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