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