Install the Intel® QuickAssist Technology Driver using instructions from the Getting Started Guide

Other technical collaterals of the Intel® QuickAssist Technology driver can be found in the below page.

• Intel® QuickAssist Technology

Contiguous memory driver

The Intel® QAT API requires many of the data structures (those that will be passed to the hardware) to be allocated in contiguous pinned memory in order to support DMA operations. You must either supply your own contiguous memory driver and make changes to the engine to make use of it or use one of the following drivers:

User Space DMA-able Memory (USDM) Component

The Intel® QAT Driver for QAT_HW comes with its own contiguous pinned memory driver that is compatible with the Intel® QAT OpenSSL* Engine. The USDM component is of a higher quality than the qat_contig_mem driver provided within the Intel® QAT OpenSSL* Engine, and is the preferred option. The USDM component is used by the Intel® QAT Driver itself, and also has the following additional features:

• Support for virtualization
• Support for configurable slab sizes
• Support for configurable secure freeing of memory (overwrite with zeros)
• Support for configurable slab caching
• Support for newer kernels
• Support for thread specific memory to avoid locks (QAT_HW Version 1.7 & 1.8 only)

The USDM component is located within the Intel® QAT Driver for QAT_HW source code in the following subdirectory: quickassist/utilities/libusdm_drv. As the USDM component is also used by the QAT_HW driver itself it will have already been built when the driver was built. It may also already be loaded as well, and you can check by running lsmod and looking for usdm_drv in the list. If not present it can be loaded as follows:

modprobe usdm_drv.ko

The USDM thread specific memory can be enabled in QAT_HW driver using the below configure flags in driver build which is only needed for multithreaded application for performance improvement. This is supported from version 4.20 of QAT_HW Version 1.7 driver only.

./configure --enable-icp-thread-specific-usdm --enable-128k-slab

Example contiguous memory driver - qat_contig_mem

This step is not required if using the default USDM driver above. The Intel® QAT OpenSSL* Engine comes with an example kernel space contiguous memory driver that can be used to try out operation of the engine. It is considered to be an example only and is not written to be a production quality driver. The use of the qat_contig_mem driver can be enabled using the configure option --enable-qat_hw_contig_mem that tells the build that the Intel® QAT OpenSSL* Engine should be compiled to use the qat_contig_mem component instead of the USDM memory driver above.

Building and loading the qat_contig_mem driver assumming:

• The Intel® QAT OpenSSL* Engine was cloned to its own location at the root of the drive: /.

To build/install the qat_contig_mem driver follow these steps:

cd /QAT_Engine/qat_contig_mem
make
make load
make test

The expected output from make test should be something similar to the following:

seg mapped to 0x7f9eedd6e000, virtualAddress in seg 0xffff880ac9c0c000,
length 64
Hello world!
# PASS Verify for QAT Contig Mem Test

• Verify qat_sw components are installed as described in Sofware requirements

The following example is assuming:

• The Intel® QAT OpenSSL* Engine was cloned to its own location at the root of the drive: /.
• The Intel® QAT Driver version 1.7 or 2.0 was unpacked within /QAT and using the USDM component.
• OpenSSL* 1.1.1 or 3.0 built from source is being used and installed to /usr/local/ssl.

To build and install the Intel® QAT OpenSSL* Engine:

cd /QAT_Engine
./configure \
--with-qat_hw_dir=/QAT \
--with-openssl_install_dir=/usr/local/ssl
make
make install

In the above example this will create the file qatengine.so and copy it to /usr/local/ssl/lib/engines-1.1.

For building QAT Engine against qatlib(intree driver) from source which is installed to default location "/usr/local" use --with-qat_hw_dir=/usr/local or provide the path that is used in the prefix to build qatlib.

If qatlib is installed via RPM then -with-qat_hw_dir is not needed as qatengine automatically picks qatlib libraries and header from default location /usr/lib64.

The following example is assuming:

• The Intel® QAT OpenSSL* Engine was cloned to its own location at the root of the drive: /.
• The Intel® QAT Driver was unpacked within /QAT and using the USDM component.
• Prebuilt OpenSSL* (both library and devel RPM packages) are installed in the system and the OpenSSL* version is in the 1.1.1 or 3.0 series.

To build and install the Intel® QAT OpenSSL* Engine:

cd /QAT_Engine
./configure  --with-qat_hw_dir=/QAT
make
make install

In the above example this will create the file qatengine.so and copy it to the engines dir of the system which can be checked using pkg-config --variable=enginesdir libcrypto.

The following example is assuming:

• The Intel® QAT OpenSSL* Engine was cloned to its own location at the root of the drive: /.
• The Intel® QAT Driver was unpacked within /QAT and using the USDM component.
• Intel® Multi-Buffer Crypto for IPsec Library was installed to the default path
• OpenSSL* 1.1.1 or 3.0 built from source is being used and installed to /usr/local/ssl.

To build and install the Intel® QAT OpenSSL* Engine:

cd /QAT_Engine
./configure \
--with-qat_hw_dir=/QAT \
--enable-qat_sw \
--with-openssl_install_dir=/usr/local/ssl
make
make install

• In the above example this will create the file qatengine.so and copy it to /usr/local/ssl/lib/engines-1.1.
• AES-GCM operations are handled by qat_sw
• Other cryptographic operations are handled by qat_hw

The following example is assuming:

• The Intel® QAT OpenSSL* Engine was cloned to its own location at the root of the drive: /.
• The Intel® Crypto Multi-buffer library was installed to the default path (/usr/local).
• The Intel® Multi-Buffer crypto for IPsec Library was installed to its default path (/usr/). (Optional if QAT SW AES-GCM support is not needed).
• Prebuilt OpenSSL* 1.1.1 or 3.0 from the system is used.

To build and install the Intel® QAT OpenSSL* Engine with QAT Software support:

cd /QAT_Engine
./configure --enable-qat_sw
make
make install

In the above example, --disable-qat_hw needs to be provided if the system has qatlib installed. Note : --enable-qat_sw checks crypto_mb and IPSec_MB libraries in its respective default path (/usr/local/lib and /usr/lib) or in the path provided in the config flag --with-qat_sw_crypto_mb_install_dir (for crypto_mb) and --with-qat_sw_ipsec_mb_install_dir (for ipsec_mb). If any of the libraries is not installed then their corresponding algorithm support is disabled (crypto_mb library for PKE algorithms and IPSec_mb library for AES-GCM).

Progressive Lock (plock) optimization in QAT Engine provides an alternative to pthread's rwlock as in Haproxy. This plock is an alternative to read/write locks in the pthread library and optimizes read/write locking with a series of atomic operations and there will be no more syscalls in case of contention. The benefit of plock is that it saves lot of CPU and improves performance with higher number of threads for multithread applications. In case of Haproxy, this can directly enabled in the Haproxy build with addition build flag "USE_PTHREAD_EMULATION=1".

Build Flag to enable plock optimization

QAT Engine generates dynamic libraries and currently enables Plock by preloading.

• When compiling the qat engine, add the compilation option --enable-qat_plock, and the libplock.so will be generated. eg: ./configure --enable-qat_sw --enable-qat_plock --with-openssl_install_dir=${OPENSSL_INSTALL_DIR}
• Set the environment variable ‘LD_PRELOAD’ to use the plock optimization. eg: export LD_PRELOAD = ${OPENSSL_INSTALL_DIR}/lib/engine-1.1/libplock.so Note: The LD_PRELOAD must be set before launching the multithread Appliaction.