doc/guides/cryptodevs/qat.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2015-2016 Intel Corporation.
   3
   4 Intel(R) QuickAssist (QAT) Crypto Poll Mode Driver
   5 ==================================================
   6
   7 The QAT PMD provides poll mode crypto driver support for the following
   8 hardware 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
  16 Features
  17 --------
  18
  19 The QAT PMD has support for:
  20
  21 Cipher 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
  39 Hash 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
  54 Supported AEAD algorithms:
  55
  56 * ``RTE_CRYPTO_AEAD_AES_GCM``
  57
  58
  59 Limitations
  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
  71 Extra notes on KASUMI F9
  72 ------------------------
  73
  74 When using KASUMI F9 authentication algorithm, the input buffer must be
  75 constructed according to the 3GPP KASUMI specifications (section 4.4, page 13):
  76 `<http://cryptome.org/3gpp/35201-900.pdf>`_.
  77 Input buffer has to have COUNT (4 bytes), FRESH (4 bytes), MESSAGE and DIRECTION (1 bit)
  78 concatenated. After the DIRECTION bit, a single '1' bit is appended, followed by
  79 between 0 and 7 '0' bits, so that the total length of the buffer is multiple of 8 bits.
  80 Note that the actual message can be any length, specified in bits.
  81
  82 Once this buffer is passed this way, when creating the crypto operation,
  83 length of data to authenticate (op.sym.auth.data.length) must be the length
  84 of all the items described above, including the padding at the end.
  85 Also, offset of data to authenticate (op.sym.auth.data.offset)
  86 must be such that points at the start of the COUNT bytes.
  87
  88
  89 Building the DPDK QAT cryptodev PMD
  90 -----------------------------------
  91
  92
  93 To enable QAT crypto in DPDK, follow the instructions for modifying the compile-time
  94 configuration file as described `here <http://dpdk.org/doc/guides/linux_gsg/build_dpdk.html>`_.
  95
  96
  97 Quick 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
 110 Dependency on the QAT kernel driver
 111 -----------------------------------
 112
 113 To use the QAT PMD an SRIOV-enabled QAT kernel driver is required. The VF
 114 devices created and initialised by this driver will be used by the QAT PMD.
 115
 116 Instructions for installation are below, but first an explanation of the
 117 relationships between the PF/VF devices and the PMDs visible to
 118 DPDK applications.
 119
 120
 121 Acceleration services - cryptography and compression - are provided to DPDK
 122 applications via PMDs which register to implement the corresponding
 123 cryptodev and compressdev APIs.
 124
 125 Each QuickAssist VF device can expose one cryptodev PMD and/or one compressdev PMD.
 126 These QAT PMDs share the same underlying device and pci-mgmt code, but are
 127 enumerated independently on their respective APIs and appear as independent
 128 devices 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
 141 Device 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
 165 Available kernel drivers
 166 ------------------------
 167
 168 Kernel drivers for each device are listed in the following table. Scroll right
 169 to 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
 195 The ``Driver`` column indicates either the Linux kernel version in which
 196 support for this device was introduced or a driver available on Intel's 01.org
 197 website. There are both linux and 01.org kernel drivers available for some
 198 devices. p = release pending.
 199
 200 If 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
 205 Installation using kernel.org driver
 206 ------------------------------------
 207
 208 The examples below are based on the C62x device, if you have a different device
 209 use the corresponding values in the above table.
 210
 211 In 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
 216 Check that the QAT driver is loaded on your system, by executing::
 217
 218     lsmod | grep qa
 219
 220 You 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
 225 Next, you need to expose the Virtual Functions (VFs) using the sysfs file system.
 226
 227 First find the BDFs (Bus-Device-Function) of the physical functions (PFs) of
 228 your device, e.g.::
 229
 230     lspci -d:37c8
 231
 232 You 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
 238 Enable 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
 244 Check that the VFs are available for use. For example ``lspci -d:37c9`` should
 245 list 48 VF devices available for a ``C62x`` device.
 246
 247 To 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
 276 Installation using 01.org QAT driver
 277 ------------------------------------
 278
 279 Download the latest QuickAssist Technology Driver from `01.org
 280 <https://01.org/packet-processing/intel%C2%AE-quickassist-technology-drivers-and-patches>`_.
 281 Consult the *Getting Started Guide* at the same URL for further information.
 282
 283 The 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
 289 In the BIOS ensure that SRIOV is enabled and VT-d is disabled.
 290
 291 Uninstall any existing QAT driver, for example by running:
 292
 293 * ``./installer.sh uninstall`` in the directory where originally installed.
 294
 295
 296 Build 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
 307 You 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.
 308 You can use ``lspci -d:37c9`` to confirm the presence of the 16 VF devices available per ``C62x`` PF.
 309
 310 Confirm 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
 315 Confirm the presence of 48 VF devices - 16 per PF::
 316
 317     lspci -d:37c9
 318
 319
 320 To 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
 370 Binding the available VFs to the DPDK UIO driver
 371 ------------------------------------------------
 372
 373 Unbind the VFs from the stock driver so they can be bound to the uio driver.
 374
 375 For an Intel(R) QuickAssist Technology DH895xCC device
 376 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 377
 378 The unbind command below assumes ``BDFs`` of ``03:01.00-03:04.07``, if your
 379 VFs 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
 388 For an Intel(R) QuickAssist Technology C62x device
 389 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 390
 391 The 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
 393 adjust 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
 408 For Intel(R) QuickAssist Technology C3xxx or D15xx device
 409 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 410
 411 The unbind command below assumes ``BDFs`` of ``01:01.00-01:02.07``, if your
 412 VFs 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
 421 Bind to the DPDK uio driver
 422 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 423
 424 Install the DPDK igb_uio driver, bind the VF PCI Device id to it and use lspci
 425 to confirm the VF devices are now in use by igb_uio kernel driver,
 426 e.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
 435 Another 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
 442 Debugging
 443 ----------------------------------------
 444
 445 There 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
 450 pmd.qat exposes both sets of traces.
 451 They can be enabled using the log-level option (where 8=maximum log level) on
 452 the 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"