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