doc/guides/cryptodevs/qat.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2015-2019 Intel Corporation.
   3
   4 Intel(R) QuickAssist (QAT) Crypto Poll Mode Driver
   5 ==================================================
   6
   7 QAT documentation consists of three parts:
   8
   9 * Details of the symmetric crypto service below.
  10 * Details of the `compression service <http://doc.dpdk.org/guides/compressdevs/qat_comp.html>`_
  11   in the compressdev drivers section.
  12 * Details of building the common QAT infrastructure and the PMDs to support the
  13   above services. See :ref:`building_qat` below.
  14
  15
  16 Symmetric Crypto Service on QAT
  17 -------------------------------
  18
  19 The QAT crypto PMD provides poll mode crypto driver support for the following
  20 hardware accelerator devices:
  21
  22 * ``Intel QuickAssist Technology DH895xCC``
  23 * ``Intel QuickAssist Technology C62x``
  24 * ``Intel QuickAssist Technology C3xxx``
  25 * ``Intel QuickAssist Technology D15xx``
  26 * ``Intel QuickAssist Technology C4xxx``
  27
  28
  29 Features
  30 ~~~~~~~~
  31
  32 The QAT PMD has support for:
  33
  34 Cipher algorithms:
  35
  36 * ``RTE_CRYPTO_CIPHER_3DES_CBC``
  37 * ``RTE_CRYPTO_CIPHER_3DES_CTR``
  38 * ``RTE_CRYPTO_CIPHER_AES128_CBC``
  39 * ``RTE_CRYPTO_CIPHER_AES192_CBC``
  40 * ``RTE_CRYPTO_CIPHER_AES256_CBC``
  41 * ``RTE_CRYPTO_CIPHER_AES128_CTR``
  42 * ``RTE_CRYPTO_CIPHER_AES192_CTR``
  43 * ``RTE_CRYPTO_CIPHER_AES256_CTR``
  44 * ``RTE_CRYPTO_CIPHER_AES_XTS``
  45 * ``RTE_CRYPTO_CIPHER_SNOW3G_UEA2``
  46 * ``RTE_CRYPTO_CIPHER_NULL``
  47 * ``RTE_CRYPTO_CIPHER_KASUMI_F8``
  48 * ``RTE_CRYPTO_CIPHER_DES_CBC``
  49 * ``RTE_CRYPTO_CIPHER_AES_DOCSISBPI``
  50 * ``RTE_CRYPTO_CIPHER_DES_DOCSISBPI``
  51 * ``RTE_CRYPTO_CIPHER_ZUC_EEA3``
  52
  53 Hash algorithms:
  54
  55 * ``RTE_CRYPTO_AUTH_SHA1_HMAC``
  56 * ``RTE_CRYPTO_AUTH_SHA224_HMAC``
  57 * ``RTE_CRYPTO_AUTH_SHA256_HMAC``
  58 * ``RTE_CRYPTO_AUTH_SHA384_HMAC``
  59 * ``RTE_CRYPTO_AUTH_SHA512_HMAC``
  60 * ``RTE_CRYPTO_AUTH_AES_XCBC_MAC``
  61 * ``RTE_CRYPTO_AUTH_SNOW3G_UIA2``
  62 * ``RTE_CRYPTO_AUTH_MD5_HMAC``
  63 * ``RTE_CRYPTO_AUTH_NULL``
  64 * ``RTE_CRYPTO_AUTH_KASUMI_F9``
  65 * ``RTE_CRYPTO_AUTH_AES_GMAC``
  66 * ``RTE_CRYPTO_AUTH_ZUC_EIA3``
  67 * ``RTE_CRYPTO_AUTH_AES_CMAC``
  68
  69 Supported AEAD algorithms:
  70
  71 * ``RTE_CRYPTO_AEAD_AES_GCM``
  72 * ``RTE_CRYPTO_AEAD_AES_CCM``
  73
  74
  75 Limitations
  76 ~~~~~~~~~~~
  77
  78 * Only supports the session-oriented API implementation (session-less APIs are not supported).
  79 * SNOW 3G (UEA2), KASUMI (F8) and ZUC (EEA3) supported only if cipher length and offset fields are byte-multiple.
  80 * SNOW 3G (UIA2) and ZUC (EIA3) supported only if hash length and offset fields are byte-multiple.
  81 * No BSD support as BSD QAT kernel driver not available.
  82 * ZUC EEA3/EIA3 is not supported by dh895xcc devices
  83 * Maximum additional authenticated data (AAD) for GCM is 240 bytes long and must be passed to the device in a buffer rounded up to the nearest block-size multiple (x16) and padded with zeros.
  84 * Queue pairs are not thread-safe (that is, within a single queue pair, RX and TX from different lcores is not supported).
  85
  86 Extra notes on KASUMI F9
  87 ~~~~~~~~~~~~~~~~~~~~~~~~
  88
  89 When using KASUMI F9 authentication algorithm, the input buffer must be
  90 constructed according to the
  91 `3GPP KASUMI specification <http://cryptome.org/3gpp/35201-900.pdf>`_
  92 (section 4.4, page 13). The input buffer has to have COUNT (4 bytes),
  93 FRESH (4 bytes), MESSAGE and DIRECTION (1 bit) concatenated. After the DIRECTION
  94 bit, a single '1' bit is appended, followed by between 0 and 7 '0' bits, so that
  95 the total length of the buffer is multiple of 8 bits. Note that the actual
  96 message can be any length, specified in bits.
  97
  98 Once this buffer is passed this way, when creating the crypto operation,
  99 length of data to authenticate "op.sym.auth.data.length" must be the length
 100 of all the items described above, including the padding at the end.
 101 Also, offset of data to authenticate "op.sym.auth.data.offset"
 102 must be such that points at the start of the COUNT bytes.
 103
 104 Asymmetric Crypto Service on QAT
 105 --------------------------------
 106
 107 The QAT Asym PMD has support for:
 108
 109 * ``Modular exponentiation``
 110 * ``Modular multiplicative inverse``
 111
 112 Limitations
 113 ~~~~~~~~~~~
 114
 115 .. _building_qat:
 116
 117 Building PMDs on QAT
 118 --------------------
 119
 120 A QAT device can host multiple acceleration services:
 121
 122 * symmetric cryptography
 123 * data compression
 124 * asymmetric cryptography
 125
 126 These services are provided to DPDK applications via PMDs which register to
 127 implement the corresponding cryptodev and compressdev APIs. The PMDs use
 128 common QAT driver code which manages the QAT PCI device. They also depend on a
 129 QAT kernel driver being installed on the platform, see :ref:`qat_kernel` below.
 130
 131
 132 Configuring and Building the DPDK QAT PMDs
 133 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 134
 135
 136 Further information on configuring, building and installing DPDK is described
 137 `here <http://doc.dpdk.org/guides/linux_gsg/build_dpdk.html>`_.
 138
 139
 140 Quick instructions for QAT cryptodev PMD are as follows:
 141
 142 .. code-block:: console
 143
 144         cd to the top-level DPDK directory
 145         make defconfig
 146         sed -i 's,\(CONFIG_RTE_LIBRTE_PMD_QAT_SYM\)=n,\1=y,' build/.config
 147         make
 148
 149 Quick instructions for QAT compressdev PMD are as follows:
 150
 151 .. code-block:: console
 152
 153         cd to the top-level DPDK directory
 154         make defconfig
 155         make
 156
 157
 158 .. _building_qat_config:
 159
 160 Build Configuration
 161 ~~~~~~~~~~~~~~~~~~~
 162
 163 These are the build configuration options affecting QAT, and their default values:
 164
 165 .. code-block:: console
 166
 167         CONFIG_RTE_LIBRTE_PMD_QAT=y
 168         CONFIG_RTE_LIBRTE_PMD_QAT_SYM=n
 169         CONFIG_RTE_PMD_QAT_MAX_PCI_DEVICES=48
 170         CONFIG_RTE_PMD_QAT_COMP_IM_BUFFER_SIZE=65536
 171
 172 CONFIG_RTE_LIBRTE_PMD_QAT must be enabled for any QAT PMD to be built.
 173
 174 The QAT cryptodev PMD has an external dependency on libcrypto, so is not
 175 built by default. CONFIG_RTE_LIBRTE_PMD_QAT_SYM should be enabled to build it.
 176
 177 The QAT compressdev PMD has no external dependencies, so needs no configuration
 178 options and is built by default.
 179
 180 The number of VFs per PF varies - see table below. If multiple QAT packages are
 181 installed on a platform then CONFIG_RTE_PMD_QAT_MAX_PCI_DEVICES should be
 182 adjusted to the number of VFs which the QAT common code will need to handle.
 183 Note, there are separate config items for max cryptodevs CONFIG_RTE_CRYPTO_MAX_DEVS
 184 and max compressdevs CONFIG_RTE_COMPRESS_MAX_DEVS, if necessary these should be
 185 adjusted to handle the total of QAT and other devices which the process will use.
 186
 187 QAT compression PMD needs intermediate buffers to support Deflate compression
 188 with Dynamic Huffman encoding. CONFIG_RTE_PMD_QAT_COMP_IM_BUFFER_SIZE
 189 specifies the size of a single buffer, the PMD will allocate a multiple of these,
 190 plus some extra space for associated meta-data. For GEN2 devices, 20 buffers are
 191 allocated while for GEN1 devices, 12 buffers are allocated, plus 1472 bytes overhead.
 192
 193 .. Note::
 194
 195         If the compressed output of a Deflate operation using Dynamic Huffman
 196         Encoding is too big to fit in an intermediate buffer, then the
 197         operation will fall back to fixed compression rather than failing the operation.
 198         To avoid this less performant case, applications should configure
 199         the intermediate buffer size to be larger than the expected input data size
 200         (compressed output size is usually unknown, so the only option is to make
 201         larger than the input size).
 202
 203
 204 Device and driver naming
 205 ~~~~~~~~~~~~~~~~~~~~~~~~
 206
 207 * The qat cryptodev driver name is "crypto_qat".
 208   The "rte_cryptodev_devices_get()" returns the devices exposed by this driver.
 209
 210 * Each qat crypto device has a unique name, in format
 211   "<pci bdf>_<service>", e.g. "0000:41:01.0_qat_sym".
 212   This name can be passed to "rte_cryptodev_get_dev_id()" to get the device_id.
 213
 214 .. Note::
 215
 216         The qat crypto driver name is passed to the dpdk-test-crypto-perf tool in the "-devtype" parameter.
 217
 218         The qat crypto device name is in the format of the slave parameter passed to the crypto scheduler.
 219
 220 * The qat compressdev driver name is "compress_qat".
 221   The rte_compressdev_devices_get() returns the devices exposed by this driver.
 222
 223 * Each qat compression device has a unique name, in format
 224   <pci bdf>_<service>, e.g. "0000:41:01.0_qat_comp".
 225   This name can be passed to rte_compressdev_get_dev_id() to get the device_id.
 226
 227 .. _qat_kernel:
 228
 229 Dependency on the QAT kernel driver
 230 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 231
 232 To use QAT an SRIOV-enabled QAT kernel driver is required. The VF
 233 devices created and initialised by this driver will be used by the QAT PMDs.
 234
 235 Instructions for installation are below, but first an explanation of the
 236 relationships between the PF/VF devices and the PMDs visible to
 237 DPDK applications.
 238
 239 Each QuickAssist PF device exposes a number of VF devices. Each VF device can
 240 enable one cryptodev PMD and/or one compressdev PMD.
 241 These QAT PMDs share the same underlying device and pci-mgmt code, but are
 242 enumerated independently on their respective APIs and appear as independent
 243 devices to applications.
 244
 245 .. Note::
 246
 247    Each VF can only be used by one DPDK process. It is not possible to share
 248    the same VF across multiple processes, even if these processes are using
 249    different acceleration services.
 250
 251    Conversely one DPDK process can use one or more QAT VFs and can expose both
 252    cryptodev and compressdev instances on each of those VFs.
 253
 254
 255 Available kernel drivers
 256 ~~~~~~~~~~~~~~~~~~~~~~~~
 257
 258 Kernel drivers for each device for each service are listed in the following table. (Scroll right
 259 to see the full table)
 260
 261
 262 .. _table_qat_pmds_drivers:
 263
 264 .. table:: QAT device generations, devices and drivers
 265
 266    +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
 267    | S   | A   | C   | Gen | Device   | Driver/ver    | Kernel Module | Pci Driver | PF Did | #PFs | VF Did | VFs/PF |
 268    +=====+=====+=====+=====+==========+===============+===============+============+========+======+========+========+
 269    | Yes | No  | No  | 1   | DH895xCC | linux/4.4+    | qat_dh895xcc  | dh895xcc   | 435    | 1    | 443    | 32     |
 270    +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
 271    | Yes | No  | No  | "   | "        | 01.org/4.2.0+ | "             | "          | "      | "    | "      | "      |
 272    +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
 273    | Yes | No  | Yes | "   | "        | 01.org/4.3.0+ | "             | "          | "      | "    | "      | "      |
 274    +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
 275    | Yes | No  | No  | 2   | C62x     | linux/4.5+    | qat_c62x      | c6xx       | 37c8   | 3    | 37c9   | 16     |
 276    +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
 277    | Yes | No  | Yes | "   | "        | 01.org/4.2.0+ | "             | "          | "      | "    | "      | "      |
 278    +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
 279    | Yes | No  | No  | 2   | C3xxx    | linux/4.5+    | qat_c3xxx     | c3xxx      | 19e2   | 1    | 19e3   | 16     |
 280    +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
 281    | Yes | No  | Yes | "   | "        | 01.org/4.2.0+ | "             | "          | "      | "    | "      | "      |
 282    +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
 283    | Yes | No  | No  | 2   | D15xx    | p             | qat_d15xx     | d15xx      | 6f54   | 1    | 6f55   | 16     |
 284    +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
 285    | Yes | No  | No  | 3   | C4xxx    | p             | qat_c4xxx     | c4xxx      | 18a0   | 1    | 18a1   | 128    |
 286    +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
 287
 288 The first 3 columns indicate the service:
 289
 290 * S = Symmetric crypto service (via cryptodev API)
 291 * A = Asymmetric crypto service  (via cryptodev API)
 292 * C = Compression service (via compressdev API)
 293
 294 The ``Driver`` column indicates either the Linux kernel version in which
 295 support for this device was introduced or a driver available on Intel's 01.org
 296 website. There are both linux in-tree and 01.org kernel drivers available for some
 297 devices. p = release pending.
 298
 299 If you are running on a kernel which includes a driver for your device, see
 300 `Installation using kernel.org driver`_ below. Otherwise see
 301 `Installation using 01.org QAT driver`_.
 302
 303
 304 Installation using kernel.org driver
 305 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 306
 307 The examples below are based on the C62x device, if you have a different device
 308 use the corresponding values in the above table.
 309
 310 In BIOS ensure that SRIOV is enabled and either:
 311
 312 * Disable VT-d or
 313 * Enable VT-d and set ``"intel_iommu=on iommu=pt"`` in the grub file.
 314
 315 Check that the QAT driver is loaded on your system, by executing::
 316
 317     lsmod | grep qa
 318
 319 You should see the kernel module for your device listed, e.g.::
 320
 321     qat_c62x               5626  0
 322     intel_qat              82336  1 qat_c62x
 323
 324 Next, you need to expose the Virtual Functions (VFs) using the sysfs file system.
 325
 326 First find the BDFs (Bus-Device-Function) of the physical functions (PFs) of
 327 your device, e.g.::
 328
 329     lspci -d:37c8
 330
 331 You should see output similar to::
 332
 333     1a:00.0 Co-processor: Intel Corporation Device 37c8
 334     3d:00.0 Co-processor: Intel Corporation Device 37c8
 335     3f:00.0 Co-processor: Intel Corporation Device 37c8
 336
 337 Enable the VFs for each PF by echoing the number of VFs per PF to the pci driver::
 338
 339      echo 16 > /sys/bus/pci/drivers/c6xx/0000:1a:00.0/sriov_numvfs
 340      echo 16 > /sys/bus/pci/drivers/c6xx/0000:3d:00.0/sriov_numvfs
 341      echo 16 > /sys/bus/pci/drivers/c6xx/0000:3f:00.0/sriov_numvfs
 342
 343 Check that the VFs are available for use. For example ``lspci -d:37c9`` should
 344 list 48 VF devices available for a ``C62x`` device.
 345
 346 To complete the installation follow the instructions in
 347 `Binding the available VFs to the DPDK UIO driver`_.
 348
 349 .. Note::
 350
 351    If the QAT kernel modules are not loaded and you see an error like ``Failed
 352    to load MMP firmware qat_895xcc_mmp.bin`` in kernel logs, this may be as a
 353    result of not using a distribution, but just updating the kernel directly.
 354
 355    Download firmware from the `kernel firmware repo
 356    <http://git.kernel.org/cgit/linux/kernel/git/firmware/linux-firmware.git/tree/>`_.
 357
 358    Copy qat binaries to ``/lib/firmware``::
 359
 360       cp qat_895xcc.bin /lib/firmware
 361       cp qat_895xcc_mmp.bin /lib/firmware
 362
 363    Change to your linux source root directory and start the qat kernel modules::
 364
 365       insmod ./drivers/crypto/qat/qat_common/intel_qat.ko
 366       insmod ./drivers/crypto/qat/qat_dh895xcc/qat_dh895xcc.ko
 367
 368
 369 .. Note::
 370
 371    If you see the following warning in ``/var/log/messages`` it can be ignored:
 372    ``IOMMU should be enabled for SR-IOV to work correctly``.
 373
 374
 375 Installation using 01.org QAT driver
 376 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 377
 378 Download the latest QuickAssist Technology Driver from `01.org
 379 <https://01.org/packet-processing/intel%C2%AE-quickassist-technology-drivers-and-patches>`_.
 380 Consult the *Getting Started Guide* at the same URL for further information.
 381
 382 The steps below assume you are:
 383
 384 * Building on a platform with one ``C62x`` device.
 385 * Using package ``qat1.7.l.4.2.0-000xx.tar.gz``.
 386 * On Fedora26 kernel ``4.11.11-300.fc26.x86_64``.
 387
 388 In the BIOS ensure that SRIOV is enabled and VT-d is disabled.
 389
 390 Uninstall any existing QAT driver, for example by running:
 391
 392 * ``./installer.sh uninstall`` in the directory where originally installed.
 393
 394
 395 Build and install the SRIOV-enabled QAT driver::
 396
 397     mkdir /QAT
 398     cd /QAT
 399
 400     # Copy the package to this location and unpack
 401     tar zxof qat1.7.l.4.2.0-000xx.tar.gz
 402
 403     ./configure --enable-icp-sriov=host
 404     make install
 405
 406 You can use ``cat /sys/kernel/debug/qat<your device type and bdf>/version/fw`` to confirm the driver is correctly installed and is using firmware version 4.2.0.
 407 You can use ``lspci -d:37c9`` to confirm the presence of the 16 VF devices available per ``C62x`` PF.
 408
 409 Confirm the driver is correctly installed and is using firmware version 4.2.0::
 410
 411     cat /sys/kernel/debug/qat<your device type and bdf>/version/fw
 412
 413
 414 Confirm the presence of 48 VF devices - 16 per PF::
 415
 416     lspci -d:37c9
 417
 418
 419 To complete the installation - follow instructions in `Binding the available VFs to the DPDK UIO driver`_.
 420
 421 .. Note::
 422
 423    If using a later kernel and the build fails with an error relating to
 424    ``strict_stroul`` not being available apply the following patch:
 425
 426    .. code-block:: diff
 427
 428       /QAT/QAT1.6/quickassist/utilities/downloader/Target_CoreLibs/uclo/include/linux/uclo_platform.h
 429       + #if LINUX_VERSION_CODE >= KERNEL_VERSION(3,18,5)
 430       + #define STR_TO_64(str, base, num, endPtr) {endPtr=NULL; if (kstrtoul((str), (base), (num))) printk("Error strtoull convert %s\n", str); }
 431       + #else
 432       #if LINUX_VERSION_CODE >= KERNEL_VERSION(2,6,38)
 433       #define STR_TO_64(str, base, num, endPtr) {endPtr=NULL; if (strict_strtoull((str), (base), (num))) printk("Error strtoull convert %s\n", str); }
 434       #else
 435       #if LINUX_VERSION_CODE >= KERNEL_VERSION(2,6,25)
 436       #define STR_TO_64(str, base, num, endPtr) {endPtr=NULL; strict_strtoll((str), (base), (num));}
 437       #else
 438       #define STR_TO_64(str, base, num, endPtr)                                 \
 439            do {                                                               \
 440                  if (str[0] == '-')                                           \
 441                  {                                                            \
 442                       *(num) = -(simple_strtoull((str+1), &(endPtr), (base))); \
 443                  }else {                                                      \
 444                       *(num) = simple_strtoull((str), &(endPtr), (base));      \
 445                  }                                                            \
 446            } while(0)
 447       + #endif
 448       #endif
 449       #endif
 450
 451
 452 .. Note::
 453
 454    If the build fails due to missing header files you may need to do following::
 455
 456       sudo yum install zlib-devel
 457       sudo yum install openssl-devel
 458       sudo yum install libudev-devel
 459
 460 .. Note::
 461
 462    If the build or install fails due to mismatching kernel sources you may need to do the following::
 463
 464       sudo yum install kernel-headers-`uname -r`
 465       sudo yum install kernel-src-`uname -r`
 466       sudo yum install kernel-devel-`uname -r`
 467
 468
 469 Binding the available VFs to the DPDK UIO driver
 470 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 471
 472 Unbind the VFs from the stock driver so they can be bound to the uio driver.
 473
 474 For an Intel(R) QuickAssist Technology DH895xCC device
 475 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 476
 477 The unbind command below assumes ``BDFs`` of ``03:01.00-03:04.07``, if your
 478 VFs are different adjust the unbind command below::
 479
 480     for device in $(seq 1 4); do \
 481         for fn in $(seq 0 7); do \
 482             echo -n 0000:03:0${device}.${fn} > \
 483             /sys/bus/pci/devices/0000\:03\:0${device}.${fn}/driver/unbind; \
 484         done; \
 485     done
 486
 487 For an Intel(R) QuickAssist Technology C62x device
 488 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 489
 490 The unbind command below assumes ``BDFs`` of ``1a:01.00-1a:02.07``,
 491 ``3d:01.00-3d:02.07`` and ``3f:01.00-3f:02.07``, if your VFs are different
 492 adjust the unbind command below::
 493
 494     for device in $(seq 1 2); do \
 495         for fn in $(seq 0 7); do \
 496             echo -n 0000:1a:0${device}.${fn} > \
 497             /sys/bus/pci/devices/0000\:1a\:0${device}.${fn}/driver/unbind; \
 498
 499             echo -n 0000:3d:0${device}.${fn} > \
 500             /sys/bus/pci/devices/0000\:3d\:0${device}.${fn}/driver/unbind; \
 501
 502             echo -n 0000:3f:0${device}.${fn} > \
 503             /sys/bus/pci/devices/0000\:3f\:0${device}.${fn}/driver/unbind; \
 504         done; \
 505     done
 506
 507 For Intel(R) QuickAssist Technology C3xxx or D15xx device
 508 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 509
 510 The unbind command below assumes ``BDFs`` of ``01:01.00-01:02.07``, if your
 511 VFs are different adjust the unbind command below::
 512
 513     for device in $(seq 1 2); do \
 514         for fn in $(seq 0 7); do \
 515             echo -n 0000:01:0${device}.${fn} > \
 516             /sys/bus/pci/devices/0000\:01\:0${device}.${fn}/driver/unbind; \
 517         done; \
 518     done
 519
 520 Bind to the DPDK uio driver
 521 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 522
 523 Install the DPDK igb_uio driver, bind the VF PCI Device id to it and use lspci
 524 to confirm the VF devices are now in use by igb_uio kernel driver,
 525 e.g. for the C62x device::
 526
 527     cd to the top-level DPDK directory
 528     modprobe uio
 529     insmod ./build/kmod/igb_uio.ko
 530     echo "8086 37c9" > /sys/bus/pci/drivers/igb_uio/new_id
 531     lspci -vvd:37c9
 532
 533
 534 Another way to bind the VFs to the DPDK UIO driver is by using the
 535 ``dpdk-devbind.py`` script::
 536
 537     cd to the top-level DPDK directory
 538     ./usertools/dpdk-devbind.py -b igb_uio 0000:03:01.1
 539
 540 Testing
 541 ~~~~~~~
 542
 543 QAT crypto PMD can be tested by running the test application::
 544
 545     make defconfig
 546     make -j
 547     cd ./build/app
 548     ./test -l1 -n1 -w <your qat bdf>
 549     RTE>>cryptodev_qat_autotest
 550
 551 QAT compression PMD can be tested by running the test application::
 552
 553     make defconfig
 554     sed -i 's,\(CONFIG_RTE_COMPRESSDEV_TEST\)=n,\1=y,' build/.config
 555     make -j
 556     cd ./build/app
 557     ./test -l1 -n1 -w <your qat bdf>
 558     RTE>>compressdev_autotest
 559
 560
 561 Debugging
 562 ~~~~~~~~~
 563
 564 There are 2 sets of trace available via the dynamic logging feature:
 565
 566 * pmd.qat_dp exposes trace on the data-path.
 567 * pmd.qat_general exposes all other trace.
 568
 569 pmd.qat exposes both sets of traces.
 570 They can be enabled using the log-level option (where 8=maximum log level) on
 571 the process cmdline, e.g. using any of the following::
 572
 573     --log-level="pmd.qat_general,8"
 574     --log-level="pmd.qat_dp,8"
 575     --log-level="pmd.qat,8"
 576
 577 .. Note::
 578
 579     The global RTE_LOG_DP_LEVEL overrides data-path trace so must be set to
 580     RTE_LOG_DEBUG to see all the trace. This variable is in config/rte_config.h
 581     for meson build and config/common_base for gnu make.
 582     Also the dynamic global log level overrides both sets of trace, so e.g. no
 583     QAT trace would display in this case::
 584
 585         --log-level="7" --log-level="pmd.qat_general,8"