Installation

The qatlib library can be installed by either:

• Installing from pre-built packages

• Installing from source code

Distributions such as Fedora 34+, RHEL 9.1+, CentOS 9 Stream, and Ubunutu 24.04 each include qatlib packages within their repositories.

Tip

At the time of writing this user’s guide, the steps in this section were accurate.

If any issues are encountered, refer to latest installation instructions available at the qatlib GitHub repository.

Installing from Packages

This section outlines the installation of qatlib using package managers.

Instructions cover:

• Ubuntu 24.04

• RPM (RPM Package Manager)

Ubuntu 24.04

The following steps can be used to install qatlib packages on Ubuntu 24.04.

Note

To install qatlib on older versions of Ubuntu, you must manually compile and install it from the source code.

See the Installing from Sources section for instructions on installing from source.

1. Update list of available packages and then upgrade the installed packages to their latest versions.

   sudo apt update
   sudo apt upgrade -y
   

2. Install the qatlib library by running the following command:

   sudo -E apt install -y libqat4 libqat-dev qatlib-service qatlib-examples libusdm-dev
   

Update QAT Libraries via PPA

The following commands allows users to update the qatlib version in Ubuntu24.04 using PPA (Personal Package Archive).

sudo add-apt-repository ppa:intelqat/qatlib
sudo apt update

RPM

The following steps can be used to install qatlib packages on Linux distributions such as Fedora 34+, RHEL 9.1+, or CentOS 9 Stream.

1. Install the qatlib library by running the following command:

   sudo dnf -y install qatlib
   

2. Install the qatlib-devel package by running the following command. This package is required for custom applications that call the Intel^® QAT APIs directly.

   sudo dnf -y install qatlib-devel
   

Important

If this package is not available we can build all qatlib packages from source files.

Prior to building the library, uninstall qatlib package using the following command:

sudo dnf remove qatlib

See the Installing from Sources section for instructions on installing from source.

System Updates

Note

This section is required for both on Ubunutu24.04 and RPM installations.

1. Add your user to the qat group by running the below command, and re-login to make the change effective. This is necessary for non-root users to use qat services.

   sudo usermod -a -G qat `whoami`
   sudo su -l $USER
   

2. Enable the qat service and make it persistent after reboot by running the following commands:

   sudo systemctl enable qat
   sudo systemctl start qat
   

3. Increase the amount of locked memory for your user by running the below command:

   Note

   The amount of memory depends upon the needs of your application. For example, the cpa_sample_code requires a minimum of 500MB. The following commands set the amount of locked memory to 500MB.

   sudo cp /etc/security/limits.conf /etc/security/limits.conf.qatlib_bak
   echo `whoami` - memlock 500000  | sudo tee -a /etc/security/limits.conf > /dev/null
   sudo su -l $USER
   

Installing from Sources

The following steps can be used to install the qatlib package from source.

1. Install the dependencies by running the following commands.

   For RPM-based distros:

   sudo dnf install -y gcc systemd-devel automake autoconf libtool make autoconf-archive
   sudo dnf install -y openssl-devel zlib-devel numactl-devel
   sudo dnf install -y nasm
   

   For Ubuntu and other Debian-based distros, install these dependencies:

   sudo apt-get install -y gcc libsystemd-dev automake autoconf libtool autoconf-archive
   sudo apt-get install -y libssl-dev zlib1g-dev nasm libnuma-dev
   

   Tip

   • If using CentOS 9 Stream, you may need to run the following command to install nasm:

     sudo dnf --enablerepo=crb install -y nasm
     

   • If using CentOS 8 Stream, you may need run the following command to install nasm:

     sudo dnf --enablerepo=powertools install -y nasm
     

   • If using RHEL, you may need to run the following commands to install nasm:

     sudo subscription-manager repos --enable codeready-builder-for-rhel-9-x86_64-rpms
     sudo dnf install -y nasm
     

   • If the nasm compiler is unavailable see the --disable-fast-crc-in-assembler option in the Configuration Options section.

2. Uninstall existing libraries and clean-up (if upgrading from a previous version of qatlib) the environment.

   Note

   • These make commands should be run using the Makefiles that were generated by the original call to the configure script.

   • There is no need to call the ./configure script before uninstall and clean-up. If it is ever called again it must be called with exactly the same options as were originally used so whatever was installed can be correctly cleaned up.

   To uninstall:

   cd ~/qatlib
   sudo make samples-uninstall
   sudo systemctl stop qat
   sudo make uninstall
   

   To clean-up:

   sudo make clean
   sudo make distclean
   

3. Clone the qatlib repository into ~/qatlib (i.e. current home directory) by running the below commands:

   cd ~
   git clone https://github.com/intel/qatlib.git
   

4. Configure the qatlib driver by running the following commands:

   cd qatlib
   ./autogen.sh
   

   A complete list of configuration options are listed Configuration Options section or can be obtained by running the following command:

   ./configure --help
   

   By default, libraries are installed into /usr/local/lib , however, use the ./configure flag --prefix=<path> to point to /usr/lib or /usr/lib64/ .

   Important

   By default the shared library files are placed in /usr/local/lib. Depending on your distribution, this directory may not be in the library path that ldconfig uses.

   This directory can be included by either adding entry to the file /etc/ld.so.conf or creating a file usr-local.conf (or name of your choice) in the /etc/ld.so.conf.d directory.

   Important

   With some OS distributions such as Ubuntu, the directory for qat.service is in a different location.

   To address potential issues, include additional configuration option: systemdsystemunitdir.

   Configure step would look like:

   ./configure --enable-service systemdsystemunitdir=/lib/systemd/system/ --prefix=/usr
   

   To run in Managed Mode, enable the qat service. This can be done automatically with the following command:

   ./configure --enable-service --prefix=/usr
   

   To run in Standalone Mode, disable the qat service. This is often preferable when running in containers to avoid dependency on systemd. This can be done with the following command:

   ./configure --enable-systemd=no --prefix=/usr
   

5. Build and install the qatlib library by running the following commands:

   make -j
   sudo make install
   

   If the service was not configured to start automatically using the --enable-service configuration option, then the service will need to be started. To start the qat service and make it persistent after reboot, use the following commands:

   sudo systemctl enable qat
   sudo systemctl start qat
   

6. Verify the qat service was started by running the below command:

   systemctl status qat
   

   The output should look like the following:

   qat.service - QAT service
   Loaded: loaded (/usr/lib/systemd/system/qat.service; enabled; preset: disabled)
   Active: active (running) since Sat 2023-05-13 12:08:26 PDT; 8s ago
   Main PID: 1266135 (qatmgr)
      Tasks: 1 (limit: 1643873)
   Memory: 7.0M
      CPU: 1.832s
   CGroup: /system.slice/qat.service
            └─1266135 /usr/local/sbin/qatmgr --policy=0
   
   May 13 12:08:17 SPR-QUANTA-Server-01 qat_init.sh[1264066]: /usr/local/sbin/qat_init.sh, device 0000:e8:00.0 configured with services: dc
   May 13 12:08:17 SPR-QUANTA-Server-01 qat_init.sh[1264066]: /usr/local/sbin/qat_init.sh, device 0000:ed:00.0 configured with services: dc
   May 13 12:08:17 SPR-QUANTA-Server-01 qat_init.sh[1264066]: /usr/local/sbin/qat_init.sh, device 0000:f2:00.0 configured with services: dc
   May 13 12:08:17 SPR-QUANTA-Server-01 qat_init.sh[1264066]: /usr/local/sbin/qat_init.sh, device 0000:f7:00.0 configured with services: dc
   May 13 12:08:26 SPR-QUANTA-Server-01 systemd[1]: Started QAT service.
   

7. Add your user to the qat group by running the below command, and re-login to make the change effective. This is necessary for non-root users to use qat services.

   sudo usermod -a -G qat `whoami`
   sudo su -l $USER
   

8. Increase the amount of locked memory for your user by running the below command:

   Note

   The amount of memory depends upon the needs of your application. For example, the cpa_sample_code requires a minimum of 500MB. The following commands set the amount of locked memory to 500MB.

   sudo cp /etc/security/limits.conf /etc/security/limits.conf.qatlib_bak
   echo `whoami` - memlock 500000  | sudo tee -a /etc/security/limits.conf > /dev/null
   sudo su -l $USER
   

Note

On some distros like Ubuntu, it may be necessary to set $LD_LIBRARY_PATH to point to the path that contains libusdm.so, usually /usr/local/lib. Example:

export LD_LIBRARY_PATH=/usr/local/lib

Configuration Options

Note

• After any change to ./configure flags, it is required to re-run the make and install commands.

Typical examples of how to update the configuration options are as follows:

./configure ICP_ANY_FLAG=value

or

./configure --enable-something

If it is required to use more than one flag at once use the following example:

./configure ICP_ANY_PATH=path ICP_ANY_NAME=name --enable-something

Available Configuration Options

Parameter	Description
--disable-option-checking	Ignores unrecognized configure options when run along with it.
--disable-FEATURE	Does not include FEATURE (same as --enable-FEATURE=no).
--enable-FEATURE[=ARG]	Includes FEATURE [ARG=yes].
--enable-silent-rules	Less verbose build output (undo: make V=1).
--disable-silent-rules	Verbose build output (undo: make V=0).
--enable-dependency-tracking	Does not reject slow dependency extractors.
--disable-dependency-tracking	Speeds up one-time build.
--enable-systemd	Enable systemd support. Set it to No to remove dependency on systemd (default = yes). Note: --enable-service should not be used in this case.
--disable-fast-crc-in-assembler	Force use of C code instead of faster assembler implementation of CRC for DC integrityCrc feature. Not recommended unless nasm assembler compiler is unavailable.
--enable-icp-debug	Enables debugging.
--disable-param-check	Disables parameters checking in the top-level APIs (used for performance optimization).
--disable-stats	Disables statistic collection (used for performance optimization).
--enable-icp-log-syslog	Enables debugging messages to be outputted to the system log instead of standard output.
--enable-icp-trace	Enables tracing for the Cryptography API.
--enable-dc-error-simulation	Enables Data Compression Error Simulation.
--enable-hb-error-simulation	Enables Heartbeat Error Simulation.
--enable-icp-thread-specific-usdm	USDM allocates and handles memory specific to threads (For multi-thread apps, allocated memory information will be maintained separately for each thread). [default=no]
--enable-legacy-lib-names	Enables legacy names for libraries.
--enable-service	Automatically creates the qat group and enables systemd service during installation.
--enable-legacy-algorithms	Enables deprecated legacy crypto algorithms. See the README for the list of algorithms which are deprecated by default.
--enable-icp-without-qp-submission-lock	This allows for the removal of Queue Pair (QP) submission locks and is designed to optimize performance in environments where QPs assigned to one thread are not shared by another thread. In these scenarios, the frequent invocation of mutex_lock/unlock during hardware request submissions is unnecessary and can affect performance. By enabling this flag, the locks around QP submissions are eliminated, thus reducing the cost of offload. As QPs are assigned to instances, only enable this if instances are not shared across threads, else undefined behaviour could occur.
--enable-treat-crc-from-comp-engine-as-error	When the device calculates a CRC over the uncompressed data, it usually uses the decompression engine to do the CRC calculation. In compression operation cases where the stored block is returned e.g. due to input data being incompressible, the returned CRC is calculated using the compression engine, which should give exactly the same CRC as the decompression engine would. Enabling this option causes any case where the CRC is calculated by the compression engine to be reported as a CPA_DC_E2E_NO_DECOMPRESSION error, rather than as a successful operation. Please see QAT Kernel Driver Releases & Features for firmware needed to support this feature.

Confirm Current Version

1. To confirm your current qatlib version, use one of the following:

   qatmgr -v
   

   Example return:

   qatmgr 25.08.0
   

2. Use the package versionfile:

   In the example command below, it assumes the source directory for qatlib is ~/qatlib. Update this command if source directory is something different.

   cat ~/qatlib/versionfile
   

   Example return:

   PACKAGE_TYPE=QAT_UPSTREAM
   
   PACKAGE_OS=L
   
   PACKAGE_VERSION_MAJOR_NUMBER=25
   
   PACKAGE_VERSION_MINOR_NUMBER=08
   
   PACKAGE_VERSION_PATCH_NUMBER=0
   
   PACKAGE_VERSION_BUILD_NUMBER=00028