=============================================================================== APRIL 2025 =============================================================================== OVERVIEW ========== Intel(R) Media Transcode Accelerator provides video encoding and decoding hardware acceleration to improve efficiency and performance due to move operations from CPU to Media HW which occurs on huge amount of saving CPU cores. This README applies to Intel(R) Xeon(R) 6 SoC with Media device. =============================================================================== LICENSING ========== Software under this project is licensed by GPL-2.0-Only. Copyright (C) 2025 Intel(R) Corporation =============================================================================== Installation of Intel(R) Media Transcode Accelerator =============================================================================== 1) Requirements and dependencies Supported OS and kernels: CentOS 9 kernel 5.19 or newer Ubuntu 24.04 kernel 6.8 RHEL 9.6 kernel 5.19 or newer Intel QAT 2.2 (Intel(R) QuickAssist Technology) package NOTE: Recommended QAT package path "/src/aux_drv/qat_aux" Libraries, tools and development packages: gcc >= 10 libva >= 2.18 (2.20 recommended) libva-devel >= 2.18 (2.20 recommended) libudev-devel pciutils kernel-devel openssl-devel zlib-devel pcre-devel git autoconf automake libtool httpd-tools boost-devel libnl3-devel.x86_64 cmake pkgconf libdrm-devel nasm yasm libvpl-devel libvpl-tools libva-utils For CentOS and RHEL: dnf install dnf-plugins-core -y yum install -y libudev-devel pciutils gcc gcc-c++ openssl-devel zlib-devel pcre-devel git autoconf automake kernel-devel libtool httpd-tools boost-devel libnl3-devel.x86_64 automake cmake libtool pkgconf libdrm-devel libva-devel libvpl-devel libvpl-tools nasm yasm libva-utils For Ubuntu 24.04: apt-get install apache2 autoconf automake bison cmake diffutils dwarves findutils flex g++ gawk gcc git libboost-all-dev libdrm-dev libnl-3-dev libnl-genl-3-dev libssl-dev libtool libudev-dev libtool libudev-dev libva-dev libva-drm2 mawk nasm ncurses-base ncurses-bin pciutils pkgconf udev vainfo yasm zlib1g zlib1g-dev libvpl-dev onevpl-tools =============================================================================== 2) Installation First, make sure all the dependencies are installed in your system. ! RUN ALL COMMANDS AS ROOT ! Media FW which is included in the package (src/fw/vid.bin) should be copied into /lib/firmware (if you will run install.sh in next steps, you can skip this - the script copies FW by itself) Ensure that QAT package is under correct path (NOTE above) and all dependencies are installed. Make sure that IOMMU is enabled (intel_iommu=on,sm_on): cat /proc/cmdline To enable IOMMU do the following: Add boot line parameters "iommu=on intel_iommu=on,sm_on", for CentOS and RHEL: grubby --update-kernel=ALL --args="iommu=on intel_iommu=on,sm_on" reboot Red Hat does NOT automatically generate the signing_key.pem required for signing external kernel modules. To load Intel(R) Media Transcode Accelerator driver, make sure to generate this key manually: Go to /certs (i.e.: /usr/src/kernels/5.14.0-503.11.1.el9_5.x86_64/certs) and run: openssl req -new -x509 -newkey rsa:2048 -keyout signing_key.pem -outform PEM -out signing_key.x509 -days 365 -nodes -subj "/CN=Module Signing Key" To install Media: source setenv.sh ./install.sh uq/wqm/wqm_and_uq Recommend to use uq mode on bare metal and wqm mode on virtual machines. For virtualization SRIOV mode: ./install.sh sriov-host/sriov-guest Verify if the devices were created: ls /dev/dri/renderD128 ls /dev/dri/renderD129 (Optional) The specifics of DRM imply that renderD numbers can vary and are not necessarily always the same. To ensure that the numbers are always the same, udev rules can be used: Edit /etc/udev/rules.d/00-qat.rules file Add new rules: SUBSYSTEM=="drm", KERNEL=="renderD[0-9]*", KERNELS=="0000:01:00.0", ATTRS{vendor}=="0x8086", ATTRS{device}=="0x4946", NAME="dri/renderD128" SUBSYSTEM=="drm", KERNEL=="renderD[0-9]*", KERNELS=="0000:05:00.0", ATTRS{vendor}=="0x8086", ATTRS{device}=="0x4946", NAME="dri/renderD129 Reload the rules: sudo udevadm control --reload-rules sudo udevadm trigger =============================================================================== 3) How to remove Intel(R) Media Transcode Accelerator First uninstall Intel QAT(R) Go to "/src/aux_drv/qat_aux" Run: make uninstall Uninstall Intel(R) Media Transcode Accelerator Go to "/src/aux_drv" make uninstall # uninstall-sriov for SRIOV mode =============================================================================== Usage of Intel(R) Media Transcode Accelerator =============================================================================== 4) Basic: Intel(R) Media Transcode Accelerator allows the creation of DRM devices which are used by FFMPEG as HW acceleration. Those devices are working in two modes: UQ (User Queue) and WQM (Worker Queue Mode). The main difference between them is that UQ mode layers on top of the WQM and exist as abstract of WQM which needs memory virtualization (SVM – Shared Virtual Memory) . To select which mode should be in use export env variables: export VA_USE_WQM=1 # For WQM mode export VA_USE_WQM=0 # For UQ mode export VA_USE_SVM=1 # It's necessary for UQ mode Simple use cases: vainfo: vainfo --display drm --device /dev/dri/renderD128 FFmpeg decode: ffmpeg -hwaccel vaapi -hwaccel_device /dev/dri/renderD128 -hwaccel_output_format vaapi -i -vf 'hwdownload,format=nv12' -pix_fmt yuv420p - a supported video file (avc, av1 or hevc) (sample input file to test that use case: sample_input_files/vintage_car_1920x1080_24p_4_0_1920x1080p_71frames.264) - an uncompressed yuv file FFmpeg transcode: ffmpeg -hwaccel vaapi -init_hw_device vaapi=hw:/dev/dri/renderD128 -hwaccel_output_format vaapi -v verbose -i -an -c:v hevc_vaapi -profile:v main -rc_mode CQP -qp 14 -g 30 -slices 1 -vframes 30 -y - a supported video file (avc, av1 or hevc) (sample input file to test that use case: sample_input_files/vintage_car_1920x1080_24p_4_0_1920x1080p_71frames.264) - h265 file GStreamer encode: gst-launch-1.0 -vf filesrc location= ! rawvideoparse format=i420 width=144 height=128 ! videoconvert ! video/x-raw,format=NV12 ! vaapih264enc ! video/x-h264,profile=high ! h264parse ! filesink location= - an uncompressed yuv file (sample input file to test that use case: sample_input_files/minimum-test-144x128.yuv) - h264 file =============================================================================== 5) Virtualization (SRIOV mode): SRIOV (Single Root IOV) - This mode splits two physical Media devices up to 32 virtual devices Under "/sys/bus/pci/devices" we can see those devices. Virtualized environment: Virtual machines require wqm. Virtual machines needs to be boot with cma parameter ex. cma=4GB. 5.1) Host: In SRIOV to share a virtual device with virtualized environment like virtual machines steps below are needed: 1) Install Intel(R) Media Transcode Accelerator package with ./install.sh sriov-host 2) Unbind selected Virtual Devices with this command: echo 0000:01:00.1 > /sys/bus/pci/devices/0000\:01\:00.1/driver/unbind 3) Bind the vfio driver to Intel(R) QAT device echo 8086 4947 > /sys/bus/pci/drivers/vfio-pci/new_id 4) Run virtual environment (eg. Virtual machine by QEMU) /usr/libexec/qemu-kvm -enable-kvm -machine q35 -cpu host -m 8G -nographic -bios ./bios.fd -device vfio-pci,host=01:00.1 -smp 2 -device e1000,netdev=net0 -netdev user,id=net0,type=user,hostfwd=tcp::5559-:22 -drive format=raw,file=./os_image.img 5.2) Guest: 1) Copy Intel(R) Media Transcode Accelerator package to VM 2) Install Intel(R) Media Transcode Accelerator package with ./install.sh sriov-guest =============================================================================== 6) Quality Optimizations 6.1) Lookahead allows the encoder to analyze future frames to make better decisions about bitrate allocation, resulting in higher quality video at the same bitrate at the expense of increased latency. Depending on compression_level setting, lookahead might be enabled by default. To overwrite the default setting, please use `--lookahead option. 6.2) Improved mini GOP structure enhances the group of pictures (GOP) structure, leading to better compression efficiency and video quality. 6.3) Limitations - No AV1 Encode Support. - No Low Latency Mode: Due to the fixed GOP structure, low latency mode is not available. - No GStreamer Support. Please note, that Intel(R) Media Transcode Accelerator software stack includes optimized (patched) version of FFmpeg which is part of the Intel(R) Media Transcode Accelerator instalation package. The optimized version of FFmpeg will display "Intel(R) Media Transcode Accelerator optimized version" in its banner. =============================================================================== 7) Known Issues The current build system does not save environmental variables so for each session user need to run setenv.sh script again. Currently there is no way to switch between "SRIOV" and "Basic" mode, each time when user want to switch there is a need for uninstall of Intel(R) Media Transcode Accelerator and reinstall again in chosen mode. For complete list please refer to release notes. =============================================================================== 8) Utilization Monitor Utilization Monitor is a Python script which displays real-time utilization data for Intel(R) Media Transcode Accelerator devices. It can also save the utilization values over time as CSV which allows for creation of utilization graphs. The script is compatible with Intel(R) Xeon(R) 6 SoC systems that have correctly configured Intel(R) QuickAssist Technology 2.2 and Intel(R) Media Transcode Accelerator drivers. Usage: ./utilmon.py -i 1 -o ./util.csv Arguments: -i) telemetry interval ( 0 - 1ms, 1 - 33ms, 2 - 268ms, 3 - 1s), optional -o) path to output csv file, optional If run with no arguments, the default interval is 0 (1ms) and utilization data will not be saved to csv. This will launch Utilization Monitor which will work until closed via CTRL+C key combo. In a separate terminal instance, you can launch an encoding/decoding/transcoding task and Utilization Monitor should show real-time usage. =============================================================================== 9) Legal/Disclaimers INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL(R) PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN INTEL'S TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, INTEL ASSUMES NO LIABILITY WHATSOEVER, AND INTEL DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT. Intel(R) products are not intended for use in medical, life saving, life sustaining, critical control or safety systems, or in nuclear facility applications. Intel(R) may make changes to specifications and product descriptions at any time, without notice. (C) Intel(R) Corporation 2025 * Other names and brands may be claimed as the property of others. ===============================================================================