1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2015-2016 Intel Corporation. 3 4Intel(R) QuickAssist (QAT) Crypto Poll Mode Driver 5================================================== 6 7The QAT PMD provides poll mode crypto driver support for the following 8hardware accelerator devices: 9 10* ``Intel QuickAssist Technology DH895xCC`` 11* ``Intel QuickAssist Technology C62x`` 12* ``Intel QuickAssist Technology C3xxx`` 13* ``Intel QuickAssist Technology D15xx`` 14 15 16Features 17-------- 18 19The QAT PMD has support for: 20 21Cipher algorithms: 22 23* ``RTE_CRYPTO_CIPHER_3DES_CBC`` 24* ``RTE_CRYPTO_CIPHER_3DES_CTR`` 25* ``RTE_CRYPTO_CIPHER_AES128_CBC`` 26* ``RTE_CRYPTO_CIPHER_AES192_CBC`` 27* ``RTE_CRYPTO_CIPHER_AES256_CBC`` 28* ``RTE_CRYPTO_CIPHER_AES128_CTR`` 29* ``RTE_CRYPTO_CIPHER_AES192_CTR`` 30* ``RTE_CRYPTO_CIPHER_AES256_CTR`` 31* ``RTE_CRYPTO_CIPHER_SNOW3G_UEA2`` 32* ``RTE_CRYPTO_CIPHER_NULL`` 33* ``RTE_CRYPTO_CIPHER_KASUMI_F8`` 34* ``RTE_CRYPTO_CIPHER_DES_CBC`` 35* ``RTE_CRYPTO_CIPHER_AES_DOCSISBPI`` 36* ``RTE_CRYPTO_CIPHER_DES_DOCSISBPI`` 37* ``RTE_CRYPTO_CIPHER_ZUC_EEA3`` 38 39Hash algorithms: 40 41* ``RTE_CRYPTO_AUTH_SHA1_HMAC`` 42* ``RTE_CRYPTO_AUTH_SHA224_HMAC`` 43* ``RTE_CRYPTO_AUTH_SHA256_HMAC`` 44* ``RTE_CRYPTO_AUTH_SHA384_HMAC`` 45* ``RTE_CRYPTO_AUTH_SHA512_HMAC`` 46* ``RTE_CRYPTO_AUTH_AES_XCBC_MAC`` 47* ``RTE_CRYPTO_AUTH_SNOW3G_UIA2`` 48* ``RTE_CRYPTO_AUTH_MD5_HMAC`` 49* ``RTE_CRYPTO_AUTH_NULL`` 50* ``RTE_CRYPTO_AUTH_KASUMI_F9`` 51* ``RTE_CRYPTO_AUTH_AES_GMAC`` 52* ``RTE_CRYPTO_AUTH_ZUC_EIA3`` 53 54Supported AEAD algorithms: 55 56* ``RTE_CRYPTO_AEAD_AES_GCM`` 57 58 59Limitations 60----------- 61 62* Only supports the session-oriented API implementation (session-less APIs are not supported). 63* SNOW 3G (UEA2), KASUMI (F8) and ZUC (EEA3) supported only if cipher length and offset fields are byte-multiple. 64* SNOW 3G (UIA2) and ZUC (EIA3) supported only if hash length and offset fields are byte-multiple. 65* No BSD support as BSD QAT kernel driver not available. 66* ZUC EEA3/EIA3 is not supported by dh895xcc devices 67* Maximum additional authenticated data (AAD) for GCM is 240 bytes long. 68* Queue pairs are not thread-safe (that is, within a single queue pair, RX and TX from different lcores is not supported). 69 70 71Extra notes on KASUMI F9 72------------------------ 73 74When using KASUMI F9 authentication algorithm, the input buffer must be 75constructed according to the 3GPP KASUMI specifications (section 4.4, page 13): 76`<http://cryptome.org/3gpp/35201-900.pdf>`_. 77Input buffer has to have COUNT (4 bytes), FRESH (4 bytes), MESSAGE and DIRECTION (1 bit) 78concatenated. After the DIRECTION bit, a single '1' bit is appended, followed by 79between 0 and 7 '0' bits, so that the total length of the buffer is multiple of 8 bits. 80Note that the actual message can be any length, specified in bits. 81 82Once this buffer is passed this way, when creating the crypto operation, 83length of data to authenticate (op.sym.auth.data.length) must be the length 84of all the items described above, including the padding at the end. 85Also, offset of data to authenticate (op.sym.auth.data.offset) 86must be such that points at the start of the COUNT bytes. 87 88 89Building the DPDK QAT cryptodev PMD 90----------------------------------- 91 92 93To enable QAT crypto in DPDK, follow the instructions for modifying the compile-time 94configuration file as described `here <http://dpdk.org/doc/guides/linux_gsg/build_dpdk.html>`_. 95 96 97Quick instructions are as follows: 98 99.. code-block:: console 100 101 cd to the top-level DPDK directory 102 make config T=x86_64-native-linuxapp-gcc 103 sed -i 's,\(CONFIG_RTE_LIBRTE_PMD_QAT\)=n,\1=y,' build/.config 104 sed -i 's,\(CONFIG_RTE_LIBRTE_PMD_QAT_SYM\)=n,\1=y,' build/.config 105 make 106 107 108.. _qat_kernel_installation: 109 110Dependency on the QAT kernel driver 111----------------------------------- 112 113To use the QAT PMD an SRIOV-enabled QAT kernel driver is required. The VF 114devices created and initialised by this driver will be used by the QAT PMD. 115 116Instructions for installation are below, but first an explanation of the 117relationships between the PF/VF devices and the PMDs visible to 118DPDK applications. 119 120 121Acceleration services - cryptography and compression - are provided to DPDK 122applications via PMDs which register to implement the corresponding 123cryptodev and compressdev APIs. 124 125Each QuickAssist VF device can expose one cryptodev PMD and/or one compressdev PMD. 126These QAT PMDs share the same underlying device and pci-mgmt code, but are 127enumerated independently on their respective APIs and appear as independent 128devices to applications. 129 130.. Note:: 131 132 Each VF can only be used by one DPDK process. It is not possible to share 133 the same VF across multiple processes, even if these processes are using 134 different acceleration services. 135 136 Conversely one DPDK process can use one or more QAT VFs and can expose both 137 cryptodev and compressdev instances on each of those VFs. 138 139 140 141Device and driver naming 142------------------------ 143 144* The qat cryptodev driver name is "crypto_qat". 145 The rte_cryptodev_devices_get() returns the devices exposed by this driver. 146 147* Each qat crypto device has a unique name, in format 148 <pci bdf>_<service>, e.g. "0000:41:01.0_qat_sym". 149 This name can be passed to rte_cryptodev_get_dev_id() to get the device_id. 150 151.. Note:: 152 153 The qat crypto driver name is passed to the dpdk-test-crypto-perf tool in the -devtype parameter. 154 155 The qat crypto device name is in the format of the slave parameter passed to the crypto scheduler. 156 157* The qat compressdev driver name is "comp_qat". 158 The rte_compressdev_devices_get() returns the devices exposed by this driver. 159 160* Each qat compression device has a unique name, in format 161 <pci bdf>_<service>, e.g. "0000:41:01.0_qat_comp". 162 This name can be passed to rte_compressdev_get_dev_id() to get the device_id. 163 164 165Available kernel drivers 166------------------------ 167 168Kernel drivers for each device are listed in the following table. Scroll right 169to check that the driver and device supports the servic you require. 170 171 172.. _table_qat_pmds_drivers: 173 174.. table:: QAT device generations, devices and drivers 175 176 +-----+----------+---------------+---------------+------------+--------+------+--------+--------+-----------+-------------+ 177 | Gen | Device | Driver/ver | Kernel Module | Pci Driver | PF Did | #PFs | VF Did | VFs/PF | cryptodev | compressdev | 178 +=====+==========+===============+===============+============+========+======+========+========+===========+=============+ 179 | 1 | DH895xCC | linux/4.4+ | qat_dh895xcc | dh895xcc | 435 | 1 | 443 | 32 | Yes | No | 180 +-----+----------+---------------+---------------+------------+--------+------+--------+--------+-----------+-------------+ 181 | " | " | 01.org/4.2.0+ | " | " | " | " | " | " | Yes | No | 182 +-----+----------+---------------+---------------+------------+--------+------+--------+--------+-----------+-------------+ 183 | 2 | C62x | linux/4.5+ | qat_c62x | c6xx | 37c8 | 3 | 37c9 | 16 | Yes | No | 184 +-----+----------+---------------+---------------+------------+--------+------+--------+--------+-----------+-------------+ 185 | " | " | 01.org/4.2.0+ | " | " | " | " | " | " | Yes | Yes | 186 +-----+----------+---------------+---------------+------------+--------+------+--------+--------+-----------+-------------+ 187 | 2 | C3xxx | linux/4.5+ | qat_c3xxx | c3xxx | 19e2 | 1 | 19e3 | 16 | Yes | No | 188 +-----+----------+---------------+---------------+------------+--------+------+--------+--------+-----------+-------------+ 189 | " | " | 01.org/4.2.0+ | " | " | " | " | " | " | Yes | Yes | 190 +-----+----------+---------------+---------------+------------+--------+------+--------+--------+-----------+-------------+ 191 | 2 | D15xx | p | qat_d15xx | d15xx | 6f54 | 1 | 6f55 | 16 | Yes | No | 192 +-----+----------+---------------+---------------+------------+--------+------+--------+--------+-----------+-------------+ 193 194 195The ``Driver`` column indicates either the Linux kernel version in which 196support for this device was introduced or a driver available on Intel's 01.org 197website. There are both linux and 01.org kernel drivers available for some 198devices. p = release pending. 199 200If you are running on a kernel which includes a driver for your device, see 201`Installation using kernel.org driver`_ below. Otherwise see 202`Installation using 01.org QAT driver`_. 203 204 205Installation using kernel.org driver 206------------------------------------ 207 208The examples below are based on the C62x device, if you have a different device 209use the corresponding values in the above table. 210 211In BIOS ensure that SRIOV is enabled and either: 212 213* Disable VT-d or 214* Enable VT-d and set ``"intel_iommu=on iommu=pt"`` in the grub file. 215 216Check that the QAT driver is loaded on your system, by executing:: 217 218 lsmod | grep qa 219 220You should see the kernel module for your device listed, e.g.:: 221 222 qat_c62x 5626 0 223 intel_qat 82336 1 qat_c62x 224 225Next, you need to expose the Virtual Functions (VFs) using the sysfs file system. 226 227First find the BDFs (Bus-Device-Function) of the physical functions (PFs) of 228your device, e.g.:: 229 230 lspci -d:37c8 231 232You should see output similar to:: 233 234 1a:00.0 Co-processor: Intel Corporation Device 37c8 235 3d:00.0 Co-processor: Intel Corporation Device 37c8 236 3f:00.0 Co-processor: Intel Corporation Device 37c8 237 238Enable the VFs for each PF by echoing the number of VFs per PF to the pci driver:: 239 240 echo 16 > /sys/bus/pci/drivers/c6xx/0000:1a:00.0/sriov_numvfs 241 echo 16 > /sys/bus/pci/drivers/c6xx/0000:3d:00.0/sriov_numvfs 242 echo 16 > /sys/bus/pci/drivers/c6xx/0000:3f:00.0/sriov_numvfs 243 244Check that the VFs are available for use. For example ``lspci -d:37c9`` should 245list 48 VF devices available for a ``C62x`` device. 246 247To complete the installation follow the instructions in 248`Binding the available VFs to the DPDK UIO driver`_. 249 250.. Note:: 251 252 If the QAT kernel modules are not loaded and you see an error like ``Failed 253 to load MMP firmware qat_895xcc_mmp.bin`` in kernel logs, this may be as a 254 result of not using a distribution, but just updating the kernel directly. 255 256 Download firmware from the `kernel firmware repo 257 <http://git.kernel.org/cgit/linux/kernel/git/firmware/linux-firmware.git/tree/>`_. 258 259 Copy qat binaries to ``/lib/firmware``:: 260 261 cp qat_895xcc.bin /lib/firmware 262 cp qat_895xcc_mmp.bin /lib/firmware 263 264 Change to your linux source root directory and start the qat kernel modules:: 265 266 insmod ./drivers/crypto/qat/qat_common/intel_qat.ko 267 insmod ./drivers/crypto/qat/qat_dh895xcc/qat_dh895xcc.ko 268 269 270.. Note:: 271 272 If you see the following warning in ``/var/log/messages`` it can be ignored: 273 ``IOMMU should be enabled for SR-IOV to work correctly``. 274 275 276Installation using 01.org QAT driver 277------------------------------------ 278 279Download the latest QuickAssist Technology Driver from `01.org 280<https://01.org/packet-processing/intel%C2%AE-quickassist-technology-drivers-and-patches>`_. 281Consult the *Getting Started Guide* at the same URL for further information. 282 283The steps below assume you are: 284 285* Building on a platform with one ``C62x`` device. 286* Using package ``qat1.7.l.4.2.0-000xx.tar.gz``. 287* On Fedora26 kernel ``4.11.11-300.fc26.x86_64``. 288 289In the BIOS ensure that SRIOV is enabled and VT-d is disabled. 290 291Uninstall any existing QAT driver, for example by running: 292 293* ``./installer.sh uninstall`` in the directory where originally installed. 294 295 296Build and install the SRIOV-enabled QAT driver:: 297 298 mkdir /QAT 299 cd /QAT 300 301 # Copy the package to this location and unpack 302 tar zxof qat1.7.l.4.2.0-000xx.tar.gz 303 304 ./configure --enable-icp-sriov=host 305 make install 306 307You can use ``cat /sys/kernel/debug/qat<your device type and bdf>/version/fw`` to confirm the driver is correctly installed and is using firmware version 4.2.0. 308You can use ``lspci -d:37c9`` to confirm the presence of the 16 VF devices available per ``C62x`` PF. 309 310Confirm the driver is correctly installed and is using firmware version 4.2.0:: 311 312 cat /sys/kernel/debug/qat<your device type and bdf>/version/fw 313 314 315Confirm the presence of 48 VF devices - 16 per PF:: 316 317 lspci -d:37c9 318 319 320To complete the installation - follow instructions in `Binding the available VFs to the DPDK UIO driver`_. 321 322.. Note:: 323 324 If using a later kernel and the build fails with an error relating to 325 ``strict_stroul`` not being available apply the following patch: 326 327 .. code-block:: diff 328 329 /QAT/QAT1.6/quickassist/utilities/downloader/Target_CoreLibs/uclo/include/linux/uclo_platform.h 330 + #if LINUX_VERSION_CODE >= KERNEL_VERSION(3,18,5) 331 + #define STR_TO_64(str, base, num, endPtr) {endPtr=NULL; if (kstrtoul((str), (base), (num))) printk("Error strtoull convert %s\n", str); } 332 + #else 333 #if LINUX_VERSION_CODE >= KERNEL_VERSION(2,6,38) 334 #define STR_TO_64(str, base, num, endPtr) {endPtr=NULL; if (strict_strtoull((str), (base), (num))) printk("Error strtoull convert %s\n", str); } 335 #else 336 #if LINUX_VERSION_CODE >= KERNEL_VERSION(2,6,25) 337 #define STR_TO_64(str, base, num, endPtr) {endPtr=NULL; strict_strtoll((str), (base), (num));} 338 #else 339 #define STR_TO_64(str, base, num, endPtr) \ 340 do { \ 341 if (str[0] == '-') \ 342 { \ 343 *(num) = -(simple_strtoull((str+1), &(endPtr), (base))); \ 344 }else { \ 345 *(num) = simple_strtoull((str), &(endPtr), (base)); \ 346 } \ 347 } while(0) 348 + #endif 349 #endif 350 #endif 351 352 353.. Note:: 354 355 If the build fails due to missing header files you may need to do following:: 356 357 sudo yum install zlib-devel 358 sudo yum install openssl-devel 359 sudo yum install libudev-devel 360 361.. Note:: 362 363 If the build or install fails due to mismatching kernel sources you may need to do the following:: 364 365 sudo yum install kernel-headers-`uname -r` 366 sudo yum install kernel-src-`uname -r` 367 sudo yum install kernel-devel-`uname -r` 368 369 370Binding the available VFs to the DPDK UIO driver 371------------------------------------------------ 372 373Unbind the VFs from the stock driver so they can be bound to the uio driver. 374 375For an Intel(R) QuickAssist Technology DH895xCC device 376~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 377 378The unbind command below assumes ``BDFs`` of ``03:01.00-03:04.07``, if your 379VFs are different adjust the unbind command below:: 380 381 for device in $(seq 1 4); do \ 382 for fn in $(seq 0 7); do \ 383 echo -n 0000:03:0${device}.${fn} > \ 384 /sys/bus/pci/devices/0000\:03\:0${device}.${fn}/driver/unbind; \ 385 done; \ 386 done 387 388For an Intel(R) QuickAssist Technology C62x device 389~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 390 391The unbind command below assumes ``BDFs`` of ``1a:01.00-1a:02.07``, 392``3d:01.00-3d:02.07`` and ``3f:01.00-3f:02.07``, if your VFs are different 393adjust the unbind command below:: 394 395 for device in $(seq 1 2); do \ 396 for fn in $(seq 0 7); do \ 397 echo -n 0000:1a:0${device}.${fn} > \ 398 /sys/bus/pci/devices/0000\:1a\:0${device}.${fn}/driver/unbind; \ 399 400 echo -n 0000:3d:0${device}.${fn} > \ 401 /sys/bus/pci/devices/0000\:3d\:0${device}.${fn}/driver/unbind; \ 402 403 echo -n 0000:3f:0${device}.${fn} > \ 404 /sys/bus/pci/devices/0000\:3f\:0${device}.${fn}/driver/unbind; \ 405 done; \ 406 done 407 408For Intel(R) QuickAssist Technology C3xxx or D15xx device 409~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 410 411The unbind command below assumes ``BDFs`` of ``01:01.00-01:02.07``, if your 412VFs are different adjust the unbind command below:: 413 414 for device in $(seq 1 2); do \ 415 for fn in $(seq 0 7); do \ 416 echo -n 0000:01:0${device}.${fn} > \ 417 /sys/bus/pci/devices/0000\:01\:0${device}.${fn}/driver/unbind; \ 418 done; \ 419 done 420 421Bind to the DPDK uio driver 422~~~~~~~~~~~~~~~~~~~~~~~~~~~ 423 424Install the DPDK igb_uio driver, bind the VF PCI Device id to it and use lspci 425to confirm the VF devices are now in use by igb_uio kernel driver, 426e.g. for the C62x device:: 427 428 cd to the top-level DPDK directory 429 modprobe uio 430 insmod ./build/kmod/igb_uio.ko 431 echo "8086 37c9" > /sys/bus/pci/drivers/igb_uio/new_id 432 lspci -vvd:37c9 433 434 435Another way to bind the VFs to the DPDK UIO driver is by using the 436``dpdk-devbind.py`` script:: 437 438 cd to the top-level DPDK directory 439 ./usertools/dpdk-devbind.py -b igb_uio 0000:03:01.1 440 441 442Debugging 443---------------------------------------- 444 445There are 2 sets of trace available via the dynamic logging feature: 446 447* pmd.qat_dp exposes trace on the data-path. 448* pmd.qat_general exposes all other trace. 449 450pmd.qat exposes both sets of traces. 451They can be enabled using the log-level option (where 8=maximum log level) on 452the process cmdline, e.g. using any of the following:: 453 454 --log-level="pmd.qat_general,8" 455 --log-level="pmd.qat_dp,8" 456 --log-level="pmd.qat,8" 457 458.. Note:: 459 460 The global RTE_LOG_DP_LEVEL overrides data-path trace so must be set to 461 RTE_LOG_DEBUG to see all the trace. This variable is in config/rte_config.h 462 for meson build and config/common_base for gnu make. 463 Also the dynamic global log level overrides both sets of trace, so e.g. no 464 QAT trace would display in this case:: 465 466 --log-level="7" --log-level="pmd.qat_general,8" 467