doc/guides/cryptodevs/qat.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2015-2016 Intel Corporation. All rights reserved.
   3
   4     Redistribution and use in source and binary forms, with or without
   5     modification, are permitted provided that the following conditions
   6     are met:
   7
   8     * Redistributions of source code must retain the above copyright
   9     notice, this list of conditions and the following disclaimer.
  10     * Redistributions in binary form must reproduce the above copyright
  11     notice, this list of conditions and the following disclaimer in
  12     the documentation and/or other materials provided with the
  13     distribution.
  14     * Neither the name of Intel Corporation nor the names of its
  15     contributors may be used to endorse or promote products derived
  16     from this software without specific prior written permission.
  17
  18     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  21     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  23     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  24     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  28     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29
  30 Intel(R) QuickAssist (QAT) Crypto Poll Mode Driver
  31 ==================================================
  32
  33 The QAT PMD provides poll mode crypto driver support for **Intel QuickAssist
  34 Technology DH895xxC**, **Intel QuickAssist Technology C62x** and
  35 **Intel QuickAssist Technology C3xxx** hardware accelerator.
  36
  37
  38 Features
  39 --------
  40
  41 The QAT PMD has support for:
  42
  43 Cipher algorithms:
  44
  45 * ``RTE_CRYPTO_CIPHER_3DES_CBC``
  46 * ``RTE_CRYPTO_CIPHER_3DES_CTR``
  47 * ``RTE_CRYPTO_CIPHER_AES128_CBC``
  48 * ``RTE_CRYPTO_CIPHER_AES192_CBC``
  49 * ``RTE_CRYPTO_CIPHER_AES256_CBC``
  50 * ``RTE_CRYPTO_CIPHER_AES128_CTR``
  51 * ``RTE_CRYPTO_CIPHER_AES192_CTR``
  52 * ``RTE_CRYPTO_CIPHER_AES256_CTR``
  53 * ``RTE_CRYPTO_CIPHER_SNOW3G_UEA2``
  54 * ``RTE_CRYPTO_CIPHER_AES_GCM``
  55 * ``RTE_CRYPTO_CIPHER_NULL``
  56 * ``RTE_CRYPTO_CIPHER_KASUMI_F8``
  57
  58 Hash algorithms:
  59
  60 * ``RTE_CRYPTO_AUTH_SHA1_HMAC``
  61 * ``RTE_CRYPTO_AUTH_SHA224_HMAC``
  62 * ``RTE_CRYPTO_AUTH_SHA256_HMAC``
  63 * ``RTE_CRYPTO_AUTH_SHA384_HMAC``
  64 * ``RTE_CRYPTO_AUTH_SHA512_HMAC``
  65 * ``RTE_CRYPTO_AUTH_AES_XCBC_MAC``
  66 * ``RTE_CRYPTO_AUTH_SNOW3G_UIA2``
  67 * ``RTE_CRYPTO_AUTH_MD5_HMAC``
  68 * ``RTE_CRYPTO_AUTH_NULL``
  69 * ``RTE_CRYPTO_AUTH_KASUMI_F9``
  70 * ``RTE_CRYPTO_AUTH_AES_GMAC``
  71
  72
  73 Limitations
  74 -----------
  75
  76 * Chained mbufs are not supported.
  77 * Hash only is not supported except SNOW 3G UIA2 and KASUMI F9.
  78 * Cipher only is not supported except SNOW 3G UEA2, KASUMI F8 and 3DES.
  79 * Only supports the session-oriented API implementation (session-less APIs are not supported).
  80 * SNOW 3G (UEA2) and KASUMI (F8) supported only if cipher length, cipher offset fields are byte-aligned.
  81 * SNOW 3G (UIA2) and KASUMI (F9) supported only if hash length, hash offset fields are byte-aligned.
  82 * No BSD support as BSD QAT kernel driver not available.
  83
  84
  85 Installation
  86 ------------
  87
  88 To use the DPDK QAT PMD an SRIOV-enabled QAT kernel driver is required. The
  89 VF devices exposed by this driver will be used by QAT PMD.
  90
  91 To enable QAT in DPDK, follow the instructions mentioned in
  92 http://dpdk.org/doc/guides/linux_gsg/build_dpdk.html
  93
  94 Quick instructions as follows:
  95
  96 .. code-block:: console
  97
  98         make config T=x86_64-native-linuxapp-gcc
  99         sed -i 's,\(CONFIG_RTE_LIBRTE_PMD_QAT\)=n,\1=y,' build/.config
 100         make
 101
 102 If you are running on kernel 4.4 or greater, see instructions for
 103 `Installation using kernel.org driver`_ below. If you are on a kernel earlier
 104 than 4.4, see `Installation using 01.org QAT driver`_.
 105
 106 For **Intel QuickAssist Technology C62x** and **Intel QuickAssist Technology C3xxx**
 107 device, kernel 4.5 or greater is needed.
 108 See instructions for `Installation using kernel.org driver`_ below.
 109
 110
 111 Installation using 01.org QAT driver
 112 ------------------------------------
 113
 114 NOTE: There is no driver available for **Intel QuickAssist Technology C62x** and
 115 **Intel QuickAssist Technology C3xxx** devices on 01.org.
 116
 117 Download the latest QuickAssist Technology Driver from `01.org
 118 <https://01.org/packet-processing/intel%C2%AE-quickassist-technology-drivers-and-patches>`_
 119 Consult the *Getting Started Guide* at the same URL for further information.
 120
 121 The steps below assume you are:
 122
 123 * Building on a platform with one ``DH895xCC`` device.
 124 * Using package ``qatmux.l.2.3.0-34.tgz``.
 125 * On Fedora21 kernel ``3.17.4-301.fc21.x86_64``.
 126
 127 In the BIOS ensure that SRIOV is enabled and VT-d is disabled.
 128
 129 Uninstall any existing QAT driver, for example by running:
 130
 131 * ``./installer.sh uninstall`` in the directory where originally installed.
 132
 133 * or ``rmmod qat_dh895xcc; rmmod intel_qat``.
 134
 135 Build and install the SRIOV-enabled QAT driver::
 136
 137     mkdir /QAT
 138     cd /QAT
 139     # copy qatmux.l.2.3.0-34.tgz to this location
 140     tar zxof qatmux.l.2.3.0-34.tgz
 141
 142     export ICP_WITHOUT_IOMMU=1
 143     ./installer.sh install QAT1.6 host
 144
 145 You can use ``cat /proc/icp_dh895xcc_dev0/version`` to confirm the driver is correctly installed.
 146 You can use ``lspci -d:443`` to confirm the bdf of the 32 VF devices are available per ``DH895xCC`` device.
 147
 148 To complete the installation - follow instructions in `Binding the available VFs to the DPDK UIO driver`_.
 149
 150 **Note**: If using a later kernel and the build fails with an error relating to ``strict_stroul`` not being available apply the following patch:
 151
 152 .. code-block:: diff
 153
 154    /QAT/QAT1.6/quickassist/utilities/downloader/Target_CoreLibs/uclo/include/linux/uclo_platform.h
 155    + #if LINUX_VERSION_CODE >= KERNEL_VERSION(3,18,5)
 156    + #define STR_TO_64(str, base, num, endPtr) {endPtr=NULL; if (kstrtoul((str), (base), (num))) printk("Error strtoull convert %s\n", str); }
 157    + #else
 158    #if LINUX_VERSION_CODE >= KERNEL_VERSION(2,6,38)
 159    #define STR_TO_64(str, base, num, endPtr) {endPtr=NULL; if (strict_strtoull((str), (base), (num))) printk("Error strtoull convert %s\n", str); }
 160    #else
 161    #if LINUX_VERSION_CODE >= KERNEL_VERSION(2,6,25)
 162    #define STR_TO_64(str, base, num, endPtr) {endPtr=NULL; strict_strtoll((str), (base), (num));}
 163    #else
 164    #define STR_TO_64(str, base, num, endPtr)                                 \
 165         do {                                                               \
 166               if (str[0] == '-')                                           \
 167               {                                                            \
 168                    *(num) = -(simple_strtoull((str+1), &(endPtr), (base))); \
 169               }else {                                                      \
 170                    *(num) = simple_strtoull((str), &(endPtr), (base));      \
 171               }                                                            \
 172         } while(0)
 173    + #endif
 174    #endif
 175    #endif
 176
 177
 178 If the build fails due to missing header files you may need to do following:
 179
 180 * ``sudo yum install zlib-devel``
 181 * ``sudo yum install openssl-devel``
 182
 183 If the build or install fails due to mismatching kernel sources you may need to do the following:
 184
 185 * ``sudo yum install kernel-headers-`uname -r```
 186 * ``sudo yum install kernel-src-`uname -r```
 187 * ``sudo yum install kernel-devel-`uname -r```
 188
 189
 190 Installation using kernel.org driver
 191 ------------------------------------
 192
 193 For **Intel QuickAssist Technology DH895xxC**:
 194
 195 Assuming you are running on at least a 4.4 kernel, you can use the stock kernel.org QAT
 196 driver to start the QAT hardware.
 197
 198 The steps below assume you are:
 199
 200 * Running DPDK on a platform with one ``DH895xCC`` device.
 201 * On a kernel at least version 4.4.
 202
 203 In BIOS ensure that SRIOV is enabled and either
 204 a) disable VT-d or
 205 b) enable VT-d and set ``"intel_iommu=on iommu=pt"`` in the grub file.
 206
 207 Ensure the QAT driver is loaded on your system, by executing::
 208
 209     lsmod | grep qat
 210
 211 You should see the following output::
 212
 213     qat_dh895xcc            5626  0
 214     intel_qat              82336  1 qat_dh895xcc
 215
 216 Next, you need to expose the Virtual Functions (VFs) using the sysfs file system.
 217
 218 First find the bdf of the physical function (PF) of the DH895xCC device::
 219
 220     lspci -d : 435
 221
 222 You should see output similar to::
 223
 224     03:00.0 Co-processor: Intel Corporation Coleto Creek PCIe Endpoint
 225
 226 Using the sysfs, enable the VFs::
 227
 228     echo 32 > /sys/bus/pci/drivers/dh895xcc/0000\:03\:00.0/sriov_numvfs
 229
 230 If you get an error, it's likely you're using a QAT kernel driver earlier than kernel 4.4.
 231
 232 To verify that the VFs are available for use - use ``lspci -d:443`` to confirm
 233 the bdf of the 32 VF devices are available per ``DH895xCC`` device.
 234
 235 To complete the installation - follow instructions in `Binding the available VFs to the DPDK UIO driver`_.
 236
 237 **Note**: If the QAT kernel modules are not loaded and you see an error like
 238     ``Failed to load MMP firmware qat_895xcc_mmp.bin`` this may be as a
 239     result of not using a distribution, but just updating the kernel directly.
 240
 241 Download firmware from the kernel firmware repo at:
 242 http://git.kernel.org/cgit/linux/kernel/git/firmware/linux-firmware.git/tree/
 243
 244 Copy qat binaries to /lib/firmware:
 245 *    ``cp qat_895xcc.bin /lib/firmware``
 246 *    ``cp qat_895xcc_mmp.bin /lib/firmware``
 247
 248 cd to your linux source root directory and start the qat kernel modules:
 249 *    ``insmod ./drivers/crypto/qat/qat_common/intel_qat.ko``
 250 *    ``insmod ./drivers/crypto/qat/qat_dh895xcc/qat_dh895xcc.ko``
 251
 252 **Note**:The following warning in /var/log/messages can be ignored:
 253     ``IOMMU should be enabled for SR-IOV to work correctly``
 254
 255 For **Intel QuickAssist Technology C62x**:
 256 Assuming you are running on at least a 4.5 kernel, you can use the stock kernel.org QAT
 257 driver to start the QAT hardware.
 258
 259 The steps below assume you are:
 260
 261 * Running DPDK on a platform with one ``C62x`` device.
 262 * On a kernel at least version 4.5.
 263
 264 In BIOS ensure that SRIOV is enabled and either
 265 a) disable VT-d or
 266 b) enable VT-d and set ``"intel_iommu=on iommu=pt"`` in the grub file.
 267
 268 Ensure the QAT driver is loaded on your system, by executing::
 269
 270     lsmod | grep qat
 271
 272 You should see the following output::
 273
 274     qat_c62x               16384  0
 275     intel_qat             122880  1 qat_c62x
 276
 277 Next, you need to expose the VFs using the sysfs file system.
 278
 279 First find the bdf of the C62x device::
 280
 281     lspci -d:37c8
 282
 283 You should see output similar to::
 284
 285     1a:00.0 Co-processor: Intel Corporation Device 37c8
 286     3d:00.0 Co-processor: Intel Corporation Device 37c8
 287     3f:00.0 Co-processor: Intel Corporation Device 37c8
 288
 289 For each c62x device there are 3 PFs.
 290 Using the sysfs, for each PF, enable the 16 VFs::
 291
 292     echo 16 > /sys/bus/pci/drivers/c6xx/0000\:1a\:00.0/sriov_numvfs
 293
 294 If you get an error, it's likely you're using a QAT kernel driver earlier than kernel 4.5.
 295
 296 To verify that the VFs are available for use - use ``lspci -d:37c9`` to confirm
 297 the bdf of the 48 VF devices are available per ``C62x`` device.
 298
 299 To complete the installation - follow instructions in `Binding the available VFs to the DPDK UIO driver`_.
 300
 301 For **Intel QuickAssist Technology C3xxx**:
 302 Assuming you are running on at least a 4.5 kernel, you can use the stock kernel.org QAT
 303 driver to start the QAT hardware.
 304
 305 The steps below assume you are:
 306
 307 * Running DPDK on a platform with one ``C3xxx`` device.
 308 * On a kernel at least version 4.5.
 309
 310 In BIOS ensure that SRIOV is enabled and either
 311 a) disable VT-d or
 312 b) enable VT-d and set ``"intel_iommu=on iommu=pt"`` in the grub file.
 313
 314 Ensure the QAT driver is loaded on your system, by executing::
 315
 316     lsmod | grep qat
 317
 318 You should see the following output::
 319
 320     qat_c3xxx               16384  0
 321     intel_qat             122880  1 qat_c3xxx
 322
 323 Next, you need to expose the Virtual Functions (VFs) using the sysfs file system.
 324
 325 First find the bdf of the physical function (PF) of the C3xxx device
 326
 327     lspci -d:19e2
 328
 329 You should see output similar to::
 330
 331     01:00.0 Co-processor: Intel Corporation Device 19e2
 332
 333 For c3xxx device there is 1 PFs.
 334 Using the sysfs, enable the 16 VFs::
 335
 336     echo 16 > /sys/bus/pci/drivers/c3xxx/0000\:01\:00.0/sriov_numvfs
 337
 338 If you get an error, it's likely you're using a QAT kernel driver earlier than kernel 4.5.
 339
 340 To verify that the VFs are available for use - use ``lspci -d:19e3`` to confirm
 341 the bdf of the 16 VF devices are available per ``C3xxx`` device.
 342 To complete the installation - follow instructions in `Binding the available VFs to the DPDK UIO driver`_.
 343
 344 Binding the available VFs to the DPDK UIO driver
 345 ------------------------------------------------
 346
 347 For **Intel(R) QuickAssist Technology DH895xcc** device:
 348 The unbind command below assumes ``bdfs`` of ``03:01.00-03:04.07``, if yours are different adjust the unbind command below::
 349
 350    cd $RTE_SDK
 351    modprobe uio
 352    insmod ./build/kmod/igb_uio.ko
 353
 354    for device in $(seq 1 4); do \
 355        for fn in $(seq 0 7); do \
 356            echo -n 0000:03:0${device}.${fn} > \
 357            /sys/bus/pci/devices/0000\:03\:0${device}.${fn}/driver/unbind; \
 358        done; \
 359    done
 360
 361    echo "8086 0443" > /sys/bus/pci/drivers/igb_uio/new_id
 362
 363 You can use ``lspci -vvd:443`` to confirm that all devices are now in use by igb_uio kernel driver.
 364
 365 For **Intel(R) QuickAssist Technology C62x** device:
 366 The unbind command below assumes ``bdfs`` of ``1a:01.00-1a:02.07``, ``3d:01.00-3d:02.07`` and ``3f:01.00-3f:02.07``,
 367 if yours are different adjust the unbind command below::
 368
 369    cd $RTE_SDK
 370    modprobe uio
 371    insmod ./build/kmod/igb_uio.ko
 372
 373    for device in $(seq 1 2); do \
 374        for fn in $(seq 0 7); do \
 375            echo -n 0000:1a:0${device}.${fn} > \
 376            /sys/bus/pci/devices/0000\:1a\:0${device}.${fn}/driver/unbind; \
 377
 378            echo -n 0000:3d:0${device}.${fn} > \
 379            /sys/bus/pci/devices/0000\:3d\:0${device}.${fn}/driver/unbind; \
 380
 381            echo -n 0000:3f:0${device}.${fn} > \
 382            /sys/bus/pci/devices/0000\:3f\:0${device}.${fn}/driver/unbind; \
 383        done; \
 384    done
 385
 386    echo "8086 37c9" > /sys/bus/pci/drivers/igb_uio/new_id
 387
 388 You can use ``lspci -vvd:37c9`` to confirm that all devices are now in use by igb_uio kernel driver.
 389
 390 For **Intel(R) QuickAssist Technology C3xxx** device:
 391 The unbind command below assumes ``bdfs`` of ``01:01.00-01:02.07``,
 392 if yours are different adjust the unbind command below::
 393
 394    cd $RTE_SDK
 395    modprobe uio
 396    insmod ./build/kmod/igb_uio.ko
 397
 398    for device in $(seq 1 2); do \
 399        for fn in $(seq 0 7); do \
 400            echo -n 0000:01:0${device}.${fn} > \
 401            /sys/bus/pci/devices/0000\:01\:0${device}.${fn}/driver/unbind; \
 402
 403        done; \
 404    done
 405
 406    echo "8086 19e3" > /sys/bus/pci/drivers/igb_uio/new_id
 407
 408 You can use ``lspci -vvd:19e3`` to confirm that all devices are now in use by igb_uio kernel driver.
 409
 410
 411 The other way to bind the VFs to the DPDK UIO driver is by using the ``dpdk-devbind.py`` script:
 412
 413 .. code-block:: console
 414
 415     cd $RTE_SDK
 416     ./tools/dpdk-devbind.py -b igb_uio 0000:03:01.1