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