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.

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
4	4xxx	qat_4xxx	4940	4941
4	401xx	qat_4xxx	4942	4943
5	420xx	qat_420xx	4946	4947

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: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 is available in the /lib/firmware directory by running the below commands:

ls /lib/firmware/qat_4xxx.bin*
ls /lib/firmware/qat_4xxx_mmp.bin*

The output will look like one of the following:

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

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

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
sudo cp qat_4xxx*.bin /lib/firmware
rm ./qat_4xxx*.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).

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

Lastly, verify the 4xxx kernel driver is bound to each Intel^® QAT Physical Function (PF) by running one of the following commands, depending on your device id:

echo `(lspci -vvv  -d 8086:4940 && lspci -vvv -d 8086:4942 && 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
Important

If you are not getting any results from the above command, it means the 4xxx 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: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

The intel_iommu parameter must be enabled. Verify this setting is enabled by running the following command:

cat /proc/cmdline | grep intel_iommu=on

If intel_iommu is 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.
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"
Reboot the system.
sudo shutdown -r now