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