xref: /dpdk/doc/guides/cryptodevs/qat.rst (revision 54140461b60485941da282d8da2db2f2bc19e281) 
1..  SPDX-License-Identifier: BSD-3-Clause
2    Copyright(c) 2015-2019 Intel Corporation.
3
4Intel(R) QuickAssist (QAT) Crypto Poll Mode Driver
5==================================================
6
7QAT documentation consists of three parts:
8
9* Details of the symmetric and asymmetric crypto services below.
10* Details of the :doc:`compression service <../compressdevs/qat_comp>`
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
16Symmetric Crypto Service on QAT
17-------------------------------
18
19The QAT symmetric crypto PMD (hereafter referred to as `QAT SYM [PMD]`) provides
20poll mode crypto driver support for the following hardware accelerator devices:
21
22* ``Intel QuickAssist Technology DH895xCC``
23* ``Intel QuickAssist Technology C62x``
24* ``Intel QuickAssist Technology C3xxx``
25* ``Intel QuickAssist Technology 200xx``
26* ``Intel QuickAssist Technology D15xx``
27* ``Intel QuickAssist Technology C4xxx``
28* ``Intel QuickAssist Technology 4xxx``
29
30
31Features
32~~~~~~~~
33
34The QAT SYM PMD has support for:
35
36Cipher algorithms:
37
38* ``RTE_CRYPTO_CIPHER_3DES_CBC``
39* ``RTE_CRYPTO_CIPHER_3DES_CTR``
40* ``RTE_CRYPTO_CIPHER_AES128_CBC``
41* ``RTE_CRYPTO_CIPHER_AES192_CBC``
42* ``RTE_CRYPTO_CIPHER_AES256_CBC``
43* ``RTE_CRYPTO_CIPHER_AES128_CTR``
44* ``RTE_CRYPTO_CIPHER_AES192_CTR``
45* ``RTE_CRYPTO_CIPHER_AES256_CTR``
46* ``RTE_CRYPTO_CIPHER_AES_XTS``
47* ``RTE_CRYPTO_CIPHER_SNOW3G_UEA2``
48* ``RTE_CRYPTO_CIPHER_NULL``
49* ``RTE_CRYPTO_CIPHER_KASUMI_F8``
50* ``RTE_CRYPTO_CIPHER_DES_CBC``
51* ``RTE_CRYPTO_CIPHER_AES_DOCSISBPI``
52* ``RTE_CRYPTO_CIPHER_DES_DOCSISBPI``
53* ``RTE_CRYPTO_CIPHER_ZUC_EEA3``
54
55Hash algorithms:
56
57* ``RTE_CRYPTO_AUTH_SHA1``
58* ``RTE_CRYPTO_AUTH_SHA1_HMAC``
59* ``RTE_CRYPTO_AUTH_SHA224``
60* ``RTE_CRYPTO_AUTH_SHA224_HMAC``
61* ``RTE_CRYPTO_AUTH_SHA256``
62* ``RTE_CRYPTO_AUTH_SHA256_HMAC``
63* ``RTE_CRYPTO_AUTH_SHA384``
64* ``RTE_CRYPTO_AUTH_SHA384_HMAC``
65* ``RTE_CRYPTO_AUTH_SHA512``
66* ``RTE_CRYPTO_AUTH_SHA512_HMAC``
67* ``RTE_CRYPTO_AUTH_SHA3_224``
68* ``RTE_CRYPTO_AUTH_SHA3_256``
69* ``RTE_CRYPTO_AUTH_SHA3_384``
70* ``RTE_CRYPTO_AUTH_SHA3_512``
71* ``RTE_CRYPTO_AUTH_AES_XCBC_MAC``
72* ``RTE_CRYPTO_AUTH_SNOW3G_UIA2``
73* ``RTE_CRYPTO_AUTH_MD5_HMAC``
74* ``RTE_CRYPTO_AUTH_NULL``
75* ``RTE_CRYPTO_AUTH_KASUMI_F9``
76* ``RTE_CRYPTO_AUTH_AES_GMAC``
77* ``RTE_CRYPTO_AUTH_ZUC_EIA3``
78* ``RTE_CRYPTO_AUTH_AES_CMAC``
79* ``RTE_CRYPTO_AUTH_SM3``
80* ``RTE_CRYPTO_AUTH_SM3_HMAC``
81
82Supported AEAD algorithms:
83
84* ``RTE_CRYPTO_AEAD_AES_GCM``
85* ``RTE_CRYPTO_AEAD_AES_CCM``
86* ``RTE_CRYPTO_AEAD_CHACHA20_POLY1305``
87
88Protocol offloads:
89
90* ``RTE_SECURITY_PROTOCOL_DOCSIS``
91
92Supported Chains
93~~~~~~~~~~~~~~~~
94
95All the usual chains are supported and also some mixed chains:
96
97.. table:: Supported hash-cipher chains for wireless digest-encrypted cases
98
99   +------------------+-----------+-------------+----------+----------+
100   | Cipher algorithm | NULL AUTH | SNOW3G UIA2 | ZUC EIA3 | AES CMAC |
101   +==================+===========+=============+==========+==========+
102   | NULL CIPHER      | Y         | 2&3         | 2&3      | Y        |
103   +------------------+-----------+-------------+----------+----------+
104   | SNOW3G UEA2      | 2&3       | 1&2&3       | 2&3      | 2&3      |
105   +------------------+-----------+-------------+----------+----------+
106   | ZUC EEA3         | 2&3       | 2&3         | 2&3      | 2&3      |
107   +------------------+-----------+-------------+----------+----------+
108   | AES CTR          | 1&2&3     | 2&3         | 2&3      | Y        |
109   +------------------+-----------+-------------+----------+----------+
110
111* The combinations marked as "Y" are supported on all QAT hardware versions.
112* The combinations marked as "2&3" are supported on GEN2 and GEN3 QAT hardware only.
113* The combinations marked as "1&2&3" are supported on GEN1, GEN2 and GEN3 QAT hardware only.
114
115
116Limitations
117~~~~~~~~~~~
118
119* Only supports the session-oriented API implementation (session-less APIs are not supported).
120* SNOW 3G (UEA2), KASUMI (F8) and ZUC (EEA3) supported only if cipher length and offset fields are byte-multiple.
121* SNOW 3G (UIA2) and ZUC (EIA3) supported only if hash length and offset fields are byte-multiple.
122* No BSD support as BSD QAT kernel driver not available.
123* ZUC EEA3/EIA3 is not supported by dh895xcc devices
124* 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.
125* Queue-pairs are thread-safe on Intel CPUs but Queues are not (that is, within a single
126  queue-pair all enqueues to the TX queue must be done from one thread and all dequeues
127  from the RX queue must be done from one thread, but enqueues and dequeues may be done
128  in different threads.)
129* A GCM limitation exists, but only in the case where there are multiple
130  generations of QAT devices on a single platform.
131  To optimise performance, the GCM crypto session should be initialised for the
132  device generation to which the ops will be enqueued. Specifically if a GCM
133  session is initialised on a GEN2 device, but then attached to an op enqueued
134  to a GEN3 device, it will work but cannot take advantage of hardware
135  optimisations in the GEN3 device. And if a GCM session is initialised on a
136  GEN3 device, then attached to an op sent to a GEN1/GEN2 device, it will not be
137  enqueued to the device and will be marked as failed. The simplest way to
138  mitigate this is to use the PCI allowlist to avoid mixing devices of different
139  generations in the same process if planning to use for GCM.
140* The mixed algo feature on GEN2 is not supported by all kernel drivers. Check
141  the notes under the Available Kernel Drivers table below for specific details.
142* Out-of-place is not supported for combined Crypto-CRC DOCSIS security
143  protocol.
144* ``RTE_CRYPTO_CIPHER_DES_DOCSISBPI`` is not supported for combined Crypto-CRC
145  DOCSIS security protocol.
146* Multi-segment buffers are not supported for combined Crypto-CRC DOCSIS
147  security protocol.
148
149Extra notes on KASUMI F9
150~~~~~~~~~~~~~~~~~~~~~~~~
151
152When using KASUMI F9 authentication algorithm, the input buffer must be
153constructed according to the
154`3GPP KASUMI specification <http://cryptome.org/3gpp/35201-900.pdf>`_
155(section 4.4, page 13). The input buffer has to have COUNT (4 bytes),
156FRESH (4 bytes), MESSAGE and DIRECTION (1 bit) concatenated. After the DIRECTION
157bit, a single '1' bit is appended, followed by between 0 and 7 '0' bits, so that
158the total length of the buffer is multiple of 8 bits. Note that the actual
159message can be any length, specified in bits.
160
161Once this buffer is passed this way, when creating the crypto operation,
162length of data to authenticate "op.sym.auth.data.length" must be the length
163of all the items described above, including the padding at the end.
164Also, offset of data to authenticate "op.sym.auth.data.offset"
165must be such that points at the start of the COUNT bytes.
166
167Asymmetric Crypto Service on QAT
168--------------------------------
169
170The QAT asymmetric crypto PMD (hereafter referred to as `QAT ASYM [PMD]`) provides
171poll mode crypto driver support for the following hardware accelerator devices:
172
173* ``Intel QuickAssist Technology DH895xCC``
174* ``Intel QuickAssist Technology C62x``
175* ``Intel QuickAssist Technology C3xxx``
176* ``Intel QuickAssist Technology D15xx``
177* ``Intel QuickAssist Technology C4xxx``
178* ``Intel QuickAssist Technology 4xxx``
179* ``Intel QuickAssist Technology 401xxx``
180
181The QAT ASYM PMD has support for:
182
183* ``RTE_CRYPTO_ASYM_XFORM_MODEX``
184* ``RTE_CRYPTO_ASYM_XFORM_MODINV``
185* ``RTE_CRYPTO_ASYM_XFORM_RSA``
186* ``RTE_CRYPTO_ASYM_XFORM_ECDSA``
187* ``RTE_CRYPTO_ASYM_XFORM_ECPM``
188* ``RTE_CRYPTO_ASYM_XFORM_ECDH``
189
190Limitations
191~~~~~~~~~~~
192
193* Big integers longer than 4096 bits are not supported.
194* Queue-pairs are thread-safe on Intel CPUs but Queues are not (that is, within a single
195  queue-pair all enqueues to the TX queue must be done from one thread and all dequeues
196  from the RX queue must be done from one thread, but enqueues and dequeues may be done
197  in different threads.)
198* RSA-2560, RSA-3584 are not supported
199
200.. _building_qat:
201
202Building PMDs on QAT
203--------------------
204
205A QAT device can host multiple acceleration services:
206
207* symmetric cryptography
208* data compression
209* asymmetric cryptography
210
211These services are provided to DPDK applications via PMDs which register to
212implement the corresponding cryptodev and compressdev APIs. The PMDs use
213common QAT driver code which manages the QAT PCI device. They also depend on a
214QAT kernel driver being installed on the platform, see :ref:`qat_kernel` below.
215
216
217Configuring and Building the DPDK QAT PMDs
218~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
219
220
221Further information on configuring, building and installing DPDK is described
222:doc:`here <../linux_gsg/build_dpdk>`.
223
224.. _building_qat_config:
225
226Build Configuration
227~~~~~~~~~~~~~~~~~~~
228
229These are the build configuration options affecting QAT, and their default values:
230
231.. code-block:: console
232
233	RTE_PMD_QAT_MAX_PCI_DEVICES=48
234	RTE_PMD_QAT_COMP_IM_BUFFER_SIZE=65536
235
236Both QAT SYM PMD and QAT ASYM PMD have an external dependency on libcrypto, so are not
237built by default.
238
239Ubuntu
240
241.. code-block:: console
242
243   apt install libssl-dev
244
245RHEL
246
247.. code-block:: console
248
249   dnf install openssl-devel
250
251The QAT compressdev PMD has no external dependencies, so is built by default.
252
253The number of VFs per PF varies - see table below. If multiple QAT packages are
254installed on a platform then RTE_PMD_QAT_MAX_PCI_DEVICES should be
255adjusted to the number of VFs which the QAT common code will need to handle.
256
257.. Note::
258
259        There are separate config items (not QAT-specific) for max cryptodevs
260        RTE_CRYPTO_MAX_DEVS and max compressdevs RTE_COMPRESS_MAX_DEVS,
261        if necessary these should be adjusted to handle the total of QAT and other
262        devices which the process will use. In particular for crypto, where each
263        QAT VF may expose two crypto devices, sym and asym, it may happen that the
264        number of devices will be bigger than MAX_DEVS and the process will show an error
265        during PMD initialisation. To avoid this problem RTE_CRYPTO_MAX_DEVS may be
266        increased or -a, allow domain:bus:devid:func option may be used.
267
268
269QAT compression PMD needs intermediate buffers to support Deflate compression
270with Dynamic Huffman encoding. RTE_PMD_QAT_COMP_IM_BUFFER_SIZE
271specifies the size of a single buffer, the PMD will allocate a multiple of these,
272plus some extra space for associated meta-data. For GEN2 devices, 20 buffers are
273allocated while for GEN1 devices, 12 buffers are allocated, plus 1472 bytes overhead.
274
275.. Note::
276
277	If the compressed output of a Deflate operation using Dynamic Huffman
278	Encoding is too big to fit in an intermediate buffer, then the
279	operation will be split into smaller operations and their results will
280	be merged afterwards.
281	This is not possible if any checksum calculation was requested - in such
282	case the code falls back to fixed compression.
283	To avoid this less performant case, applications should configure
284	the intermediate buffer size to be larger than the expected input data size
285	(compressed output size is usually unknown, so the only option is to make
286	larger than the input size).
287
288
289Running QAT PMD with insecure crypto algorithms
290~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
291
292A few insecure crypto algorithms are deprecated from QAT drivers.
293This needs to be reflected in DPDK QAT PMD.
294DPDK QAT PMD has by default disabled all the insecure crypto algorithms from Gen 1, 2, 3 and 4.
295A PMD devarg is used to enable the capability.
296
297- qat_legacy_capa
298
299To use this feature the user must set the devarg on process start as a device additional devarg::
300
301  -a b1:01.2,qat_legacy_capa=1
302
303
304Running QAT PMD with minimum threshold for burst size
305~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
306
307If only a small number or packets can be enqueued. Each enqueue causes an expensive MMIO write.
308These MMIO write occurrences can be optimised by setting any of the following parameters:
309
310- qat_sym_enq_threshold
311- qat_asym_enq_threshold
312- qat_comp_enq_threshold
313
314When any of these parameters is set rte_cryptodev_enqueue_burst function will
315return 0 (thereby avoiding an MMIO) if the device is congested and number of packets
316possible to enqueue is smaller.
317To use this feature the user must set the parameter on process start as a device additional parameter::
318
319  -a 03:01.1,qat_sym_enq_threshold=32,qat_comp_enq_threshold=16
320
321All parameters can be used with the same device regardless of order. Parameters are separated
322by comma. When the same parameter is used more than once first occurrence of the parameter
323is used.
324Maximum threshold that can be set is 32.
325
326
327Running QAT PMD with Cipher-CRC offload feature
328~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
329
330Support has been added to the QAT symmetric crypto PMD for combined Cipher-CRC offload,
331primarily for the Crypto-CRC DOCSIS security protocol, on GEN2/GEN3/GEN4 QAT devices.
332
333The following devarg enables a Cipher-CRC offload capability check to determine
334if the feature is supported on the QAT device.
335
336- qat_sym_cipher_crc_enable
337
338When enabled, a capability check for the combined Cipher-CRC offload feature is triggered
339to the QAT firmware during queue pair initialization. If supported by the firmware,
340any subsequent runtime Crypto-CRC DOCSIS security protocol requests handled by the QAT PMD
341are offloaded to the QAT device by setting up the content descriptor and request accordingly.
342If not supported, the CRC is calculated by the QAT PMD using the NET CRC API.
343
344To use this feature the user must set the devarg on process start as a device additional devarg::
345
346 -a 03:01.1,qat_sym_cipher_crc_enable=1
347
348
349Running QAT PMD with Intel IPsec MB library for symmetric precomputes function
350~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
351
352The QAT PMD uses Intel IPsec MB library for partial hash calculation
353in symmetric precomputes function by default,
354the minimum required version of IPsec MB library is v1.4.
355If this version of IPsec is not met, it will fallback to use OpenSSL.
356ARM will always default to using OpenSSL
357as ARM IPsec MB does not support the necessary algorithms.
358
359
360Device and driver naming
361~~~~~~~~~~~~~~~~~~~~~~~~
362
363* The qat cryptodev symmetric crypto driver name is "crypto_qat".
364* The qat cryptodev asymmetric crypto driver name is "crypto_qat_asym".
365
366The "rte_cryptodev_devices_get()" returns the devices exposed by either of these drivers.
367
368* Each qat sym crypto device has a unique name, in format
369  "<pci bdf>_<service>", e.g. "0000:41:01.0_qat_sym".
370* Each qat asym crypto device has a unique name, in format
371  "<pci bdf>_<service>", e.g. "0000:41:01.0_qat_asym".
372  This name can be passed to "rte_cryptodev_get_dev_id()" to get the device_id.
373
374.. Note::
375
376	The cryptodev driver name is passed to the dpdk-test-crypto-perf tool in the "-devtype" parameter.
377
378	The qat crypto device name is in the format of the worker parameter passed to the crypto scheduler.
379
380* The qat compressdev driver name is "compress_qat".
381  The rte_compressdev_devices_get() returns the devices exposed by this driver.
382
383* Each qat compression device has a unique name, in format
384  <pci bdf>_<service>, e.g. "0000:41:01.0_qat_comp".
385  This name can be passed to rte_compressdev_get_dev_id() to get the device_id.
386
387.. _qat_kernel:
388
389Dependency on the QAT kernel driver
390~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
391
392To use QAT an SRIOV-enabled QAT kernel driver is required. The VF
393devices created and initialised by this driver will be used by the QAT PMDs.
394
395Instructions for installation are below, but first an explanation of the
396relationships between the PF/VF devices and the PMDs visible to
397DPDK applications.
398
399Each QuickAssist PF device exposes a number of VF devices. Each VF device can
400enable one symmetric cryptodev PMD and/or one asymmetric cryptodev PMD and/or
401one compressdev PMD.
402These QAT PMDs share the same underlying device and pci-mgmt code, but are
403enumerated independently on their respective APIs and appear as independent
404devices to applications.
405
406.. Note::
407
408   Each VF can only be used by one DPDK process. It is not possible to share
409   the same VF across multiple processes, even if these processes are using
410   different acceleration services.
411
412   Conversely one DPDK process can use one or more QAT VFs and can expose both
413   cryptodev and compressdev instances on each of those VFs.
414
415
416Available kernel drivers
417~~~~~~~~~~~~~~~~~~~~~~~~
418
419Kernel drivers for each device for each service are listed in the following table. (Scroll right
420to see the full table)
421
422
423.. _table_qat_pmds_drivers:
424
425.. table:: QAT device generations, devices and drivers
426
427   +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
428   | S   | A   | C   | Gen | Device   | Driver/ver    | Kernel Module | Pci Driver | PF Did | #PFs | VF Did | VFs/PF |
429   +=====+=====+=====+=====+==========+===============+===============+============+========+======+========+========+
430   | Yes | No  | No  | 1   | DH895xCC | linux/4.4+    | qat_dh895xcc  | dh895xcc   | 435    | 1    | 443    | 32     |
431   +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
432   | Yes | Yes | No  | "   | "        | IDZ/4.12.0+   | "             | "          | "      | "    | "      | "      |
433   +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
434   | Yes | Yes | Yes | "   | "        | IDZ/4.13.0+   | "             | "          | "      | "    | "      | "      |
435   +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
436   | Yes | No  | No  | 2   | C62x     | linux/4.5+    | qat_c62x      | c6xx       | 37c8   | 3    | 37c9   | 16     |
437   +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
438   | Yes | Yes | Yes | "   | "        | IDZ/4.12.0+   | "             | "          | "      | "    | "      | "      |
439   +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
440   | Yes | No  | No  | 2   | C3xxx    | linux/4.5+    | qat_c3xxx     | c3xxx      | 19e2   | 1    | 19e3   | 16     |
441   +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
442   | Yes | Yes | Yes | "   | "        | IDZ/4.12.0+   | "             | "          | "      | "    | "      | "      |
443   +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
444   | Yes | No  | No  | 2   | 200xx    | p             | qat_200xx     | 200xx      | 18ee   | 1    | 18ef   | 16     |
445   +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
446   | Yes | No  | No  | 2   | D15xx    | p             | qat_d15xx     | d15xx      | 6f54   | 1    | 6f55   | 16     |
447   +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
448   | Yes | Yes | No  | 3   | C4xxx    | p             | qat_c4xxx     | c4xxx      | 18a0   | 1    | 18a1   | 128    |
449   +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
450   | Yes | Yes | No  | 4   | 4xxx     | linux/5.11+   | qat_4xxx      | 4xxx       | 4940   | 4    | 4941   | 16     |
451   +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
452   | Yes | Yes | Yes | 4   | 4xxx     | linux/5.17+   | qat_4xxx      | 4xxx       | 4940   | 4    | 4941   | 16     |
453   +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
454   | Yes | No  | No  | 4   | 4xxx     | IDZ/ N/A      | qat_4xxx      | 4xxx       | 4940   | 4    | 4941   | 16     |
455   +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
456   | Yes | Yes | Yes | 4   | 401xxx   | linux/5.19+   | qat_401xxx    | 4xxx       | 4942   | 2    | 4943   | 16     |
457   +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
458   | Yes | No  | No  | 4   | 401xxx   | IDZ/ N/A      | qat_401xxx    | 4xxx       | 4942   | 2    | 4943   | 16     |
459   +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
460   | Yes | Yes | Yes | 4   | 402xx    | linux/6.4+    | qat_4xxx      | 4xxx       | 4944   | 2    | 4945   | 16     |
461   +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
462   | Yes | No  | No  | 4   | 402xx    | IDZ/ N/A      | qat_4xxx      | 4xxx       | 4944   | 2    | 4945   | 16     |
463   +-----+-----+-----+-----+----------+---------------+---------------+------------+--------+------+--------+--------+
464
465* Note: Symmetric mixed crypto algorithms feature on Gen 2 works only with IDZ driver version 4.9.0+
466
467The first 3 columns indicate the service:
468
469* S = Symmetric crypto service (via cryptodev API)
470* A = Asymmetric crypto service  (via cryptodev API)
471* C = Compression service (via compressdev API)
472
473The ``Driver`` column indicates either the Linux kernel version in which
474support for this device was introduced or a driver available on Intel Developer Zone (IDZ).
475There are both linux in-tree and IDZ kernel drivers available for some
476devices. p = release pending.
477
478If you are running on a kernel which includes a driver for your device, see
479`Installation using kernel.org driver`_ below. Otherwise see
480`Installation using IDZ QAT driver`_.
481
482.. note::
483
484   The asymmetric service is not supported by DPDK QAT PMD for the Gen 3 platform.
485   The actual crypto services enabled on the system depend
486   on QAT driver capabilities and hardware slice configuration.
487
488Installation using kernel.org driver
489~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
490
491The examples below are based on the C62x device, if you have a different device
492use the corresponding values in the above table.
493
494In BIOS ensure that SRIOV is enabled and either:
495
496* Disable VT-d or
497* Enable VT-d and set ``"intel_iommu=on iommu=pt"`` in the grub file.
498
499Check that the QAT driver is loaded on your system, by executing::
500
501    lsmod | grep qa
502
503You should see the kernel module for your device listed, e.g.::
504
505    qat_c62x               5626  0
506    intel_qat              82336  1 qat_c62x
507
508Next, you need to expose the Virtual Functions (VFs) using the sysfs file system.
509
510First find the BDFs (Bus-Device-Function) of the physical functions (PFs) of
511your device, e.g.::
512
513    lspci -d:37c8
514
515You should see output similar to::
516
517    1a:00.0 Co-processor: Intel Corporation Device 37c8
518    3d:00.0 Co-processor: Intel Corporation Device 37c8
519    3f:00.0 Co-processor: Intel Corporation Device 37c8
520
521Enable the VFs for each PF by echoing the number of VFs per PF to the pci driver::
522
523     echo 16 > /sys/bus/pci/drivers/c6xx/0000:1a:00.0/sriov_numvfs
524     echo 16 > /sys/bus/pci/drivers/c6xx/0000:3d:00.0/sriov_numvfs
525     echo 16 > /sys/bus/pci/drivers/c6xx/0000:3f:00.0/sriov_numvfs
526
527Check that the VFs are available for use. For example ``lspci -d:37c9`` should
528list 48 VF devices available for a ``C62x`` device.
529
530To complete the installation follow the instructions in
531`Binding the available VFs to the vfio-pci driver`_.
532
533.. Note::
534
535   If the QAT kernel modules are not loaded and you see an error like ``Failed
536   to load MMP firmware qat_895xcc_mmp.bin`` in kernel logs, this may be as a
537   result of not using a distribution, but just updating the kernel directly.
538
539   Download firmware from the `kernel firmware repo
540   <http://git.kernel.org/cgit/linux/kernel/git/firmware/linux-firmware.git/tree/>`_.
541
542   Copy qat binaries to ``/lib/firmware``::
543
544      cp qat_895xcc.bin /lib/firmware
545      cp qat_895xcc_mmp.bin /lib/firmware
546
547   Change to your linux source root directory and start the qat kernel modules::
548
549      insmod ./drivers/crypto/qat/qat_common/intel_qat.ko
550      insmod ./drivers/crypto/qat/qat_dh895xcc/qat_dh895xcc.ko
551
552.. Note::
553
554   If you see the following warning in ``/var/log/messages`` it can be ignored:
555   ``IOMMU should be enabled for SR-IOV to work correctly``.
556
557
558Installation using IDZ QAT driver
559~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
560
561Download the latest QuickAssist Technology Driver from `Intel Developer Zone
562<https://developer.intel.com/quickassist>`_.
563Consult the *Quick Start Guide* at the same URL for further information.
564
565The steps below assume you are:
566
567* Building on a platform with one ``C62x`` device.
568* Using package ``qat1.7.l.4.2.0-000xx.tar.gz``.
569* On Fedora26 kernel ``4.11.11-300.fc26.x86_64``.
570
571In the BIOS ensure that SRIOV is enabled and VT-d is disabled.
572
573Uninstall any existing QAT driver, for example by running:
574
575* ``./installer.sh uninstall`` in the directory where originally installed.
576
577
578Build and install the SRIOV-enabled QAT driver::
579
580    mkdir /QAT
581    cd /QAT
582
583    # Copy the package to this location and unpack
584    tar zxof qat1.7.l.4.2.0-000xx.tar.gz
585
586    ./configure --enable-icp-sriov=host
587    make install
588
589You 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.
590You can use ``lspci -d:37c9`` to confirm the presence of the 16 VF devices available per ``C62x`` PF.
591
592Confirm the driver is correctly installed and is using firmware version 4.2.0::
593
594    cat /sys/kernel/debug/qat<your device type and bdf>/version/fw
595
596
597Confirm the presence of 48 VF devices - 16 per PF::
598
599    lspci -d:37c9
600
601
602To complete the installation - follow instructions in
603`Binding the available VFs to the vfio-pci driver`_.
604
605.. Note::
606
607   If using a later kernel and the build fails with an error relating to
608   ``strict_stroul`` not being available apply the following patch:
609
610   .. code-block:: diff
611
612      /QAT/QAT1.6/quickassist/utilities/downloader/Target_CoreLibs/uclo/include/linux/uclo_platform.h
613      + #if LINUX_VERSION_CODE >= KERNEL_VERSION(3,18,5)
614      + #define STR_TO_64(str, base, num, endPtr) {endPtr=NULL; if (kstrtoul((str), (base), (num))) printk("Error strtoull convert %s\n", str); }
615      + #else
616      #if LINUX_VERSION_CODE >= KERNEL_VERSION(2,6,38)
617      #define STR_TO_64(str, base, num, endPtr) {endPtr=NULL; if (strict_strtoull((str), (base), (num))) printk("Error strtoull convert %s\n", str); }
618      #else
619      #if LINUX_VERSION_CODE >= KERNEL_VERSION(2,6,25)
620      #define STR_TO_64(str, base, num, endPtr) {endPtr=NULL; strict_strtoll((str), (base), (num));}
621      #else
622      #define STR_TO_64(str, base, num, endPtr)                                 \
623           do {                                                               \
624                 if (str[0] == '-')                                           \
625                 {                                                            \
626                      *(num) = -(simple_strtoull((str+1), &(endPtr), (base))); \
627                 }else {                                                      \
628                      *(num) = simple_strtoull((str), &(endPtr), (base));      \
629                 }                                                            \
630           } while(0)
631      + #endif
632      #endif
633      #endif
634
635
636.. Note::
637
638   If the build fails due to missing header files you may need to do following::
639
640      sudo yum install zlib-devel
641      sudo yum install openssl-devel
642      sudo yum install libudev-devel
643
644.. Note::
645
646   If the build or install fails due to mismatching kernel sources you may need to do the following::
647
648      sudo yum install kernel-headers-`uname -r`
649      sudo yum install kernel-src-`uname -r`
650      sudo yum install kernel-devel-`uname -r`
651
652.. Note::
653
654   If the build fails on newer GCC versions (such as GCC 12) with an error relating to
655   ``-lc`` not being found, apply the following patch:
656
657   .. code-block:: diff
658
659      /QAT/quickassist/lookaside/access_layer/src/Makefile
660      cd $(ICP_FINAL_OUTPUT_DIR);\
661      cmd="$(LINKER) $(LIB_SHARED_FLAGS) -o \
662        $(LIB_SHARED) $(ADDITIONAL_OBJECTS) $(ADDITIONAL_LIBS) *.o -lpthread -ludev \
663      - -Bstatic -L$(ADF_DIR)/src/build/$(ICP_OS)/$(ICP_OS_LEVEL) \
664      - -ladf_user -L$(OSAL_DIR)/src/build/$(ICP_OS)/$(ICP_OS_LEVEL)/ \
665      - -losal -Bdynamic -lc"; \
666      + -Bstatic -L$(ADF_DIR)/src/build/$(ICP_OS)/$(ICP_OS_LEVEL) \
667      + -ladf_user -L$(OSAL_DIR)/src/build/$(ICP_OS)/$(ICP_OS_LEVEL)/ \
668      + -losal -Bdynamic -L/lib/x86_64-linux-gnu/ -lc"; \
669      echo "$$cmd"; \
670      $$cmd
671
672   Followed by this patch:
673
674   .. code-block:: diff
675
676      /QAT/quickassist/build_system/build_files/OS/linux_common_user_space_rules.mk
677      @echo 'Creating shared library ${LIB_SHARED}'; \
678      cd $($(PROG_ACY)_FINAL_OUTPUT_DIR);\
679      -  echo $(LINKER) $(LIB_SHARED_FLAGS) -o $@  $(OBJECTS) $(ADDITIONAL_OBJECTS) -lc;\
680      -  $(LINKER) $(LIB_SHARED_FLAGS) -o $@  $(OBJECTS) $(ADDITIONAL_OBJECTS) -lc ;
681      +  echo $(LINKER) $(LIB_SHARED_FLAGS) -o $@  $(OBJECTS) $(ADDITIONAL_OBJECTS) \
682      +  -L/lib/x86_64-linux-gnu/ -lc;\
683      +  $(LINKER) $(LIB_SHARED_FLAGS) -o $@  $(OBJECTS) $(ADDITIONAL_OBJECTS) \
684      +  -L/lib/x86_64-linux-gnu/ -lc ;
685
686
687Binding the available VFs to the vfio-pci driver
688~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
689
690Note:
691
692* Please note that due to security issues, the usage of older DPDK igb_uio
693  driver is not recommended. This document shows how to use the more secure
694  vfio-pci driver.
695* If QAT fails to bind to vfio-pci on Linux kernel 5.9+, please see the
696  QATE-39220 and QATE-7495 issues in
697  `IDZ doc <https://cdrdv2.intel.com/v1/dl/getContent/710057?explicitVersion=true>`_
698  which details the constraint about trusted guests and add `disable_denylist=1`
699  to the vfio-pci params to use QAT. See also `this patch description <https://lkml.org/lkml/2020/7/23/1155>`_.
700
701Unbind the VFs from the stock driver so they can be bound to the vfio-pci driver.
702
703For an Intel(R) QuickAssist Technology DH895xCC device
704^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
705
706The unbind command below assumes ``BDFs`` of ``03:01.00-03:04.07``, if your
707VFs are different adjust the unbind command below::
708
709    cd to the top-level DPDK directory
710    for device in $(seq 1 4); do \
711        for fn in $(seq 0 7); do \
712            usertools/dpdk-devbind.py -u 0000:03:0${device}.${fn}; \
713        done; \
714    done
715
716For an Intel(R) QuickAssist Technology C62x device
717^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
718
719The unbind command below assumes ``BDFs`` of ``1a:01.00-1a:02.07``,
720``3d:01.00-3d:02.07`` and ``3f:01.00-3f:02.07``, if your VFs are different
721adjust the unbind command below::
722
723    cd to the top-level DPDK directory
724    for device in $(seq 1 2); do \
725        for fn in $(seq 0 7); do \
726            usertools/dpdk-devbind.py -u 0000:1a:0${device}.${fn}; \
727            usertools/dpdk-devbind.py -u 0000:3d:0${device}.${fn}; \
728            usertools/dpdk-devbind.py -u 0000:3f:0${device}.${fn}; \
729        done; \
730    done
731
732For Intel(R) QuickAssist Technology C3xxx or 200xx or D15xx device
733^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
734
735The unbind command below assumes ``BDFs`` of ``01:01.00-01:02.07``, if your
736VFs are different adjust the unbind command below::
737
738    cd to the top-level DPDK directory
739    for device in $(seq 1 2); do \
740        for fn in $(seq 0 7); do \
741            usertools/dpdk-devbind.py -u 0000:01:0${device}.${fn}; \
742        done; \
743    done
744
745Bind to the vfio-pci driver
746^^^^^^^^^^^^^^^^^^^^^^^^^^^
747
748Load the vfio-pci driver, bind the VF PCI Device id to it using the
749``dpdk-devbind.py`` script then use the ``--status`` option
750to confirm the VF devices are now in use by vfio-pci kernel driver,
751e.g. for the C62x device::
752
753    cd to the top-level DPDK directory
754    modprobe vfio-pci
755    usertools/dpdk-devbind.py -b vfio-pci 0000:03:01.1
756    usertools/dpdk-devbind.py --status
757
758Use ``modprobe vfio-pci disable_denylist=1`` from kernel 5.9 onwards.
759See note in the section `Binding the available VFs to the vfio-pci driver`_
760above.
761
762Testing
763~~~~~~~
764
765QAT SYM crypto PMD can be tested by running the test application::
766
767    cd ./<build_dir>/app/test
768    ./dpdk-test -l1 -n1 -a <your qat bdf>
769    RTE>>cryptodev_qat_autotest
770
771QAT ASYM crypto PMD can be tested by running the test application::
772
773    cd ./<build_dir>/app/test
774    ./dpdk-test -l1 -n1 -a <your qat bdf>
775    RTE>>cryptodev_qat_asym_autotest
776
777QAT compression PMD can be tested by running the test application::
778
779    cd ./<build_dir>/app/test
780    ./dpdk-test -l1 -n1 -a <your qat bdf>
781    RTE>>compressdev_autotest
782
783
784Debugging
785~~~~~~~~~
786
787There are 2 sets of trace available via the dynamic logging feature:
788
789* pmd.qat.dp exposes trace on the data-path.
790* pmd.qat.general exposes all other trace.
791
792pmd.qat exposes both sets of traces.
793They can be enabled using the log-level option (where 8=maximum log level) on
794the process cmdline, e.g. using any of the following::
795
796    --log-level="pmd.qat.general,8"
797    --log-level="pmd.qat.dp,8"
798    --log-level="pmd.qat,8"
799
800.. Note::
801
802    The global RTE_LOG_DP_LEVEL overrides data-path trace so must be set to
803    RTE_LOG_DEBUG to see all the trace. This variable is in config/rte_config.h
804    for meson build.
805    Also the dynamic global log level overrides both sets of trace, so e.g. no
806    QAT trace would display in this case::
807
808	--log-level="7" --log-level="pmd.qat.general,8"
809