System Requirements

There are some prerequisites when using QATlib. When running on newer Linux distributions many of these are taken care of.

Required BIOS parameters must be enabled.

Platform must have a 4xxx Intel^® Communication device. This includes 4xxx, 401xx, 402xx, and 420xx.

Firmware must be available for the 4xxx Intel^® Communication device.

Kernel drivers must be running and properly bound to the Intel^® QAT Physical and Virtual Functions (PF and VF).

Required Linux boot parameters must be configured.

The following sections provide the details to verify all prerequisites listed above.

BIOS Configuration

To properly use the QATlib library, the Intel VT-d and SR-IOV parameters must be enabled in the platform BIOS. Consult your platform guide for details on enabling these parameters. If using an Intel Best Known Configuration (BKC) these parameters are usually enabled by default.

The status of both parameters can be verified in the BIOS settings. Although the specific location depends on the BIOS vendor navigation menu, these parameters are usually found in the following locations:

Intel VT-d and SR-IOV parameters location in BIOS
Intel VT-d	SR-IOV
EDKII Menu -> Socket Configuration -> IIO Configuration -> Intel VT for Directed I/O (VT-d) -> Intel VT for Directed I/O	EDKII Menu -> Platform Configuration -> Miscellaneous Configuration -> SR-IOV Support

Kernel/Firmware Requirements

Refer to Kernel/Firmware Requirements for details on required kernel/firmware version.

Supported Devices

The following platforms are supported by QATlib:

Supported Platforms
GEN	Device	Kernel Module	PF Did	VF Did	FW Files
4	4xxx	qat_4xxx	4940	4941	qat_4xxx.bin qat_4xxx_mmp.bin
4	401xx	qat_4xxx	4942	4943	qat_4xxx.bin qat_4xxx_mmp.bin
4	402xx	qat_4xxx	4944	4945	qat_402xx.bin qat_402xx_mmp.bin
5	420xx	qat_420xx	4946	4947	qat_420xx.bin qat_420xx_mmp.bin

Verify the platform contains a supported 4xxx Intel^® Communications device by running the below command:

echo `(lspci -d 8086:4940 && lspci -d 8086:4941 && lspci -d 8086:4942 && lspci -d 8086:4943 && lspci -d 8086:4944 && lspci -d 8086:4945 && lspci -d 8086:4946 && lspci -d 8086:4947) | wc -l` supported devices found.

If supported 4xxx Intel^® Communications devices are found, you should get an output similar to the following:

4 supported devices found.

Firmware

Note

This step is required when running on host system. It does not apply when running in a virtual machine as the firmware is loaded on the host.

Verify the supported firmware for your platform is available in the /lib/firmware directory by running the below commands:

ls /lib/firmware/{qat_4xxx,qat_402xx,qat_420xx}.bin* 2>/dev/null
ls /lib/firmware/{qat_4xxx,qat_402xx,qat_420xx}_mmp.bin* 2>/dev/null

The output will look like:

/lib/firmware/qat_4xxx.bin
/lib/firmware/qat_4xxx_mmp.bin

Tip

If the firmware images are not present, perform the following steps:

Download the firmware files.

cd ~
wget https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git/plain/qat_4xxx.bin
wget https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git/plain/qat_4xxx_mmp.bin
wget https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git/plain/qat_402xx.bin
wget https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git/plain/qat_402xx_mmp.bin
sudo cp qat_4xxx*.bin qat_402xx*.bin /lib/firmware
rm qat_4xxx*.bin qat_402xx*.bin

Update initramfs.

sudo dracut --force
Note

dracut is not used on some distributions such as Ubuntu. The following steps can be ran instead.
sudo update-initramfs -u
sudo rmmod qat_4xxx
sudo rmmod intel_qat
sudo modprobe intel_qat
sudo modprobe qat_4xxx

Kernel Drivers

Verify the appropriate kernel drivers are loaded in the host and/or the guest system(s).

Note

Refer to Supported Devices for appropriate kernel module for your device.

Host System Kernel Drivers

When running on the host system, use the following command to verify the kernel drivers are present:

lsmod | grep qat

If the kernel drivers are found, you should get an output similar to the following:

qat_4xxx               16384  0
intel_qat             172032  1 qat_4xxx

If the kernel modules are not found, install them using the following commands:

sudo modprobe intel_qat
sudo modprobe qat_4xxx
Tip

If the modprobe commands fail to install the kernel drivers, verify the kernel has been configured to include these modules by running the below command:
cat /boot/config-$(uname -r) | grep -i qat
You should see the following output:
CONFIG_CRYPTO_DEV_QAT=m
CONFIG_CRYPTO_DEV_QAT_DH895xCC=m
CONFIG_CRYPTO_DEV_QAT_C3XXX=m
CONFIG_CRYPTO_DEV_QAT_C62X=m
CONFIG_CRYPTO_DEV_QAT_4XXX=m
CONFIG_CRYPTO_DEV_QAT_DH895xCCVF=m
CONFIG_CRYPTO_DEV_QAT_C3XXXVF=m
CONFIG_CRYPTO_DEV_QAT_C62XVF=m
Important

For Debian-based systems like Ubuntu, QAT (QuickAssist Technology) kernel modules may be available in an additional package. Install it with:
sudo apt update
sudo apy upgrade -y
sudo apt-get install -y linux-modules-extra-$(uname -r)

Lastly, verify the appropriate kernel driver is bound to each Intel^® QAT Physical Function (PF) by running the following command:

echo `(lspci -vvv  -d 8086:4940 && lspci -vvv -d 8086:4942 && lspci -vvv -d 8086:4944 && lspci -vvv -d 8086:4946) | grep "Kernel driver"`

You should see an output similar to the following:

Kernel driver in use: 4xxx Kernel driver in use: 4xxx Kernel driver in use: 4xxx Kernel driver in use: 4xxx Kernel driver in use: 4xxx Kernel driver in use: 4xxx Kernel driver in use: 4xxx Kernel driver in use: 4xxx
Note

Refer to Supported Devices for appropriate kernel module for your device.

Important

If you are not getting any results from the above command, it means the QAT kernel driver is not bound to the Intel^® QAT PF.

This could be due to the current kernel version in the system does not support the particular Intel^® CPU SKU in your system.

Try upgrading the kernel version to 5.19+.

Guest System Kernel Drivers

When running on the guest system, use the following command to verify the kernel drivers are present:

lsmod | grep vfio_pci

If the kernel module is not found, install it using the following command:

sudo modprobe vfio_pci

Lastly, verify the vfio_pci kernel driver is bound to each Intel^® QAT Virtual Function (VF) by running the following command:

echo `(lspci -vvv  -d 8086:4941 && lspci -vvv -d 8086:4943 && lspci -vvv -d 8086:4945 && lspci -vvv -d 8086:4947) | grep "Kernel driver"`

You should see an output similar to the following:

Kernel driver in use: vfio-pci Kernel driver in use: vfio-pci Kernel driver in use: vfio-pci Kernel driver in use:

Linux Boot Parameters

There are two boot parameters that are required.

intel_iommu=on
vfio-pci.ids=[QAT VF DID]

Verify these settings are enabled by running the following command:

grep -E 'intel_iommu=on' /proc/cmdline && grep -o 'vfio-pci.ids=[^ ]*' /proc/cmdline | grep -E '8086:4941|8086:4943|8086:4945|8086:4947'

If they are not enabled, the following steps can be used to turn it on.

Instructions for Debian Based Distros

If using a Debian based distribution, run the following commands:

Open the grub file.
sudo vi /etc/default/grub
Update the GRUB_CMDLINE_LINUX line by adding intel_iommu=on.

Update the GRUB_CMDLINE_LINUX line by adding vfio-pci-ids=8086:4941.

Note

In the command above we added the 8086:4941 device id. Depending on your system, this ID could also be 8086:4943, 8086:4945, or 8086:4947.

Refer to Supported Devices section of QATlib Users Guide for additional details.
Load the changes done.
sudo update-grub
Reboot the system.
shutdown -r now

Instructions for RHEL/CentOS/Fedora

If using RHEL, CentOS or Fedora, run the following commands:

Update the kernel boot parameters.
sudo grubby --update-kernel=ALL --args="intel_iommu=on"
sudo grubby --update-kernel=ALL --args="vfio-pci.ids=8086:4941"
Note

In the command above we added the 8086:4941 device id. Depending on your system, this ID could also be 8086:4943, 8086:4945, or 8086:4947.

Refer to Supported Devices section of QATlib Users Guide for additional details.
Reboot the system.
sudo shutdown -r now