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