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