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