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 Installation
  72 ------------
  73
  74 To enable QAT in DPDK, follow the instructions for modifying the compile-time
  75 configuration file as described `here <http://dpdk.org/doc/guides/linux_gsg/build_dpdk.html>`_.
  76
  77 Quick instructions are as follows:
  78
  79 .. code-block:: console
  80
  81         cd to the top-level DPDK directory
  82         make config T=x86_64-native-linuxapp-gcc
  83         sed -i 's,\(CONFIG_RTE_LIBRTE_PMD_QAT\)=n,\1=y,' build/.config
  84         make
  85
  86 To use the DPDK QAT PMD an SRIOV-enabled QAT kernel driver is required. The VF
  87 devices exposed by this driver will be used by the QAT PMD. The devices and
  88 available kernel drivers and device ids are :
  89
  90 .. _table_qat_pmds_drivers:
  91
  92 .. table:: QAT device generations, devices and drivers
  93
  94    +-----+----------+--------+---------------+------------+--------+------+--------+--------+
  95    | Gen | Device   | Driver | Kernel Module | Pci Driver | PF Did | #PFs | Vf Did | VFs/PF |
  96    +=====+==========+========+===============+============+========+======+========+========+
  97    | 1   | DH895xCC | 01.org | icp_qa_al     | n/a        | 435    | 1    | 443    | 32     |
  98    +-----+----------+--------+---------------+------------+--------+------+--------+--------+
  99    | 1   | DH895xCC | 4.4+   | qat_dh895xcc  | dh895xcc   | 435    | 1    | 443    | 32     |
 100    +-----+----------+--------+---------------+------------+--------+------+--------+--------+
 101    | 2   | C62x     | 4.5+   | qat_c62x      | c6xx       | 37c8   | 3    | 37c9   | 16     |
 102    +-----+----------+--------+---------------+------------+--------+------+--------+--------+
 103    | 2   | C3xxx    | 4.5+   | qat_c3xxx     | c3xxx      | 19e2   | 1    | 19e3   | 16     |
 104    +-----+----------+--------+---------------+------------+--------+------+--------+--------+
 105    | 2   | D15xx    | p      | qat_d15xx     | d15xx      | 6f54   | 1    | 6f55   | 16     |
 106    +-----+----------+--------+---------------+------------+--------+------+--------+--------+
 107
 108
 109 The ``Driver`` column indicates either the Linux kernel version in which
 110 support for this device was introduced or a driver available on Intel's 01.org
 111 website. There are both linux and 01.org kernel drivers available for some
 112 devices. p = release pending.
 113
 114 If you are running on a kernel which includes a driver for your device, see
 115 `Installation using kernel.org driver`_ below. Otherwise see
 116 `Installation using 01.org QAT driver`_.
 117
 118
 119 Installation using kernel.org driver
 120 ------------------------------------
 121
 122 The examples below are based on the C62x device, if you have a different device
 123 use the corresponding values in the above table.
 124
 125 In BIOS ensure that SRIOV is enabled and either:
 126
 127 * Disable VT-d or
 128 * Enable VT-d and set ``"intel_iommu=on iommu=pt"`` in the grub file.
 129
 130 Check that the QAT driver is loaded on your system, by executing::
 131
 132     lsmod | grep qa
 133
 134 You should see the kernel module for your device listed, e.g.::
 135
 136     qat_c62x               5626  0
 137     intel_qat              82336  1 qat_c62x
 138
 139 Next, you need to expose the Virtual Functions (VFs) using the sysfs file system.
 140
 141 First find the BDFs (Bus-Device-Function) of the physical functions (PFs) of
 142 your device, e.g.::
 143
 144     lspci -d:37c8
 145
 146 You should see output similar to::
 147
 148     1a:00.0 Co-processor: Intel Corporation Device 37c8
 149     3d:00.0 Co-processor: Intel Corporation Device 37c8
 150     3f:00.0 Co-processor: Intel Corporation Device 37c8
 151
 152 Enable the VFs for each PF by echoing the number of VFs per PF to the pci driver::
 153
 154      echo 16 > /sys/bus/pci/drivers/c6xx/0000:1a:00.0/sriov_numvfs
 155      echo 16 > /sys/bus/pci/drivers/c6xx/0000:3d:00.0/sriov_numvfs
 156      echo 16 > /sys/bus/pci/drivers/c6xx/0000:3f:00.0/sriov_numvfs
 157
 158 Check that the VFs are available for use. For example ``lspci -d:37c9`` should
 159 list 48 VF devices available for a ``C62x`` device.
 160
 161 To complete the installation follow the instructions in
 162 `Binding the available VFs to the DPDK UIO driver`_.
 163
 164 .. Note::
 165
 166    If the QAT kernel modules are not loaded and you see an error like ``Failed
 167    to load MMP firmware qat_895xcc_mmp.bin`` in kernel logs, this may be as a
 168    result of not using a distribution, but just updating the kernel directly.
 169
 170    Download firmware from the `kernel firmware repo
 171    <http://git.kernel.org/cgit/linux/kernel/git/firmware/linux-firmware.git/tree/>`_.
 172
 173    Copy qat binaries to ``/lib/firmware``::
 174
 175       cp qat_895xcc.bin /lib/firmware
 176       cp qat_895xcc_mmp.bin /lib/firmware
 177
 178    Change to your linux source root directory and start the qat kernel modules::
 179
 180       insmod ./drivers/crypto/qat/qat_common/intel_qat.ko
 181       insmod ./drivers/crypto/qat/qat_dh895xcc/qat_dh895xcc.ko
 182
 183
 184 .. Note::
 185
 186    If you see the following warning in ``/var/log/messages`` it can be ignored:
 187    ``IOMMU should be enabled for SR-IOV to work correctly``.
 188
 189
 190 Installation using 01.org QAT driver
 191 ------------------------------------
 192
 193 Download the latest QuickAssist Technology Driver from `01.org
 194 <https://01.org/packet-processing/intel%C2%AE-quickassist-technology-drivers-and-patches>`_.
 195 Consult the *Getting Started Guide* at the same URL for further information.
 196
 197 The steps below assume you are:
 198
 199 * Building on a platform with one ``DH895xCC`` device.
 200 * Using package ``qatmux.l.2.3.0-34.tgz``.
 201 * On Fedora21 kernel ``3.17.4-301.fc21.x86_64``.
 202
 203 In the BIOS ensure that SRIOV is enabled and VT-d is disabled.
 204
 205 Uninstall any existing QAT driver, for example by running:
 206
 207 * ``./installer.sh uninstall`` in the directory where originally installed.
 208
 209 * or ``rmmod qat_dh895xcc; rmmod intel_qat``.
 210
 211 Build and install the SRIOV-enabled QAT driver::
 212
 213     mkdir /QAT
 214     cd /QAT
 215
 216     # Copy qatmux.l.2.3.0-34.tgz to this location
 217     tar zxof qatmux.l.2.3.0-34.tgz
 218
 219     export ICP_WITHOUT_IOMMU=1
 220     ./installer.sh install QAT1.6 host
 221
 222 You can use ``cat /proc/icp_dh895xcc_dev0/version`` to confirm the driver is correctly installed.
 223 You can use ``lspci -d:443`` to confirm the  of the 32 VF devices available per ``DH895xCC`` device.
 224
 225 To complete the installation - follow instructions in `Binding the available VFs to the DPDK UIO driver`_.
 226
 227 .. Note::
 228
 229    If using a later kernel and the build fails with an error relating to
 230    ``strict_stroul`` not being available apply the following patch:
 231
 232    .. code-block:: diff
 233
 234       /QAT/QAT1.6/quickassist/utilities/downloader/Target_CoreLibs/uclo/include/linux/uclo_platform.h
 235       + #if LINUX_VERSION_CODE >= KERNEL_VERSION(3,18,5)
 236       + #define STR_TO_64(str, base, num, endPtr) {endPtr=NULL; if (kstrtoul((str), (base), (num))) printk("Error strtoull convert %s\n", str); }
 237       + #else
 238       #if LINUX_VERSION_CODE >= KERNEL_VERSION(2,6,38)
 239       #define STR_TO_64(str, base, num, endPtr) {endPtr=NULL; if (strict_strtoull((str), (base), (num))) printk("Error strtoull convert %s\n", str); }
 240       #else
 241       #if LINUX_VERSION_CODE >= KERNEL_VERSION(2,6,25)
 242       #define STR_TO_64(str, base, num, endPtr) {endPtr=NULL; strict_strtoll((str), (base), (num));}
 243       #else
 244       #define STR_TO_64(str, base, num, endPtr)                                 \
 245            do {                                                               \
 246                  if (str[0] == '-')                                           \
 247                  {                                                            \
 248                       *(num) = -(simple_strtoull((str+1), &(endPtr), (base))); \
 249                  }else {                                                      \
 250                       *(num) = simple_strtoull((str), &(endPtr), (base));      \
 251                  }                                                            \
 252            } while(0)
 253       + #endif
 254       #endif
 255       #endif
 256
 257
 258 .. Note::
 259
 260    If the build fails due to missing header files you may need to do following::
 261
 262       sudo yum install zlib-devel
 263       sudo yum install openssl-devel
 264
 265 .. Note::
 266
 267    If the build or install fails due to mismatching kernel sources you may need to do the following::
 268
 269       sudo yum install kernel-headers-`uname -r`
 270       sudo yum install kernel-src-`uname -r`
 271       sudo yum install kernel-devel-`uname -r`
 272
 273
 274 Binding the available VFs to the DPDK UIO driver
 275 ------------------------------------------------
 276
 277 Unbind the VFs from the stock driver so they can be bound to the uio driver.
 278
 279 For an Intel(R) QuickAssist Technology DH895xCC device
 280 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 281
 282 The unbind command below assumes ``BDFs`` of ``03:01.00-03:04.07``, if your
 283 VFs are different adjust the unbind command below::
 284
 285     for device in $(seq 1 4); do \
 286         for fn in $(seq 0 7); do \
 287             echo -n 0000:03:0${device}.${fn} > \
 288             /sys/bus/pci/devices/0000\:03\:0${device}.${fn}/driver/unbind; \
 289         done; \
 290     done
 291
 292 For an Intel(R) QuickAssist Technology C62x device
 293 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 294
 295 The unbind command below assumes ``BDFs`` of ``1a:01.00-1a:02.07``,
 296 ``3d:01.00-3d:02.07`` and ``3f:01.00-3f:02.07``, if your VFs are different
 297 adjust the unbind command below::
 298
 299     for device in $(seq 1 2); do \
 300         for fn in $(seq 0 7); do \
 301             echo -n 0000:1a:0${device}.${fn} > \
 302             /sys/bus/pci/devices/0000\:1a\:0${device}.${fn}/driver/unbind; \
 303
 304             echo -n 0000:3d:0${device}.${fn} > \
 305             /sys/bus/pci/devices/0000\:3d\:0${device}.${fn}/driver/unbind; \
 306
 307             echo -n 0000:3f:0${device}.${fn} > \
 308             /sys/bus/pci/devices/0000\:3f\:0${device}.${fn}/driver/unbind; \
 309         done; \
 310     done
 311
 312 For Intel(R) QuickAssist Technology C3xxx or D15xx device
 313 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 314
 315 The unbind command below assumes ``BDFs`` of ``01:01.00-01:02.07``, if your
 316 VFs are different adjust the unbind command below::
 317
 318     for device in $(seq 1 2); do \
 319         for fn in $(seq 0 7); do \
 320             echo -n 0000:01:0${device}.${fn} > \
 321             /sys/bus/pci/devices/0000\:01\:0${device}.${fn}/driver/unbind; \
 322         done; \
 323     done
 324
 325 Bind to the DPDK uio driver
 326 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 327
 328 Install the DPDK igb_uio driver, bind the VF PCI Device id to it and use lspci
 329 to confirm the VF devices are now in use by igb_uio kernel driver,
 330 e.g. for the C62x device::
 331
 332     cd to the top-level DPDK directory
 333     modprobe uio
 334     insmod ./build/kmod/igb_uio.ko
 335     echo "8086 37c9" > /sys/bus/pci/drivers/igb_uio/new_id
 336     lspci -vvd:37c9
 337
 338
 339 Another way to bind the VFs to the DPDK UIO driver is by using the
 340 ``dpdk-devbind.py`` script::
 341
 342     cd to the top-level DPDK directory
 343     ./usertools/dpdk-devbind.py -b igb_uio 0000:03:01.1
 344
 345
 346 Extra notes on KASUMI F9
 347 ------------------------
 348
 349 When using KASUMI F9 authentication algorithm, the input buffer must be
 350 constructed according to the 3GPP KASUMI specifications (section 4.4, page 13):
 351 `<http://cryptome.org/3gpp/35201-900.pdf>`_.
 352 Input buffer has to have COUNT (4 bytes), FRESH (4 bytes), MESSAGE and DIRECTION (1 bit)
 353 concatenated. After the DIRECTION bit, a single '1' bit is appended, followed by
 354 between 0 and 7 '0' bits, so that the total length of the buffer is multiple of 8 bits.
 355 Note that the actual message can be any length, specified in bits.
 356
 357 Once this buffer is passed this way, when creating the crypto operation,
 358 length of data to authenticate (op.sym.auth.data.length) must be the length
 359 of all the items described above, including the padding at the end.
 360 Also, offset of data to authenticate (op.sym.auth.data.offset)
 361 must be such that points at the start of the COUNT bytes.