diff options
Diffstat (limited to 'doc/guides/cryptodevs')
| -rw-r--r-- | doc/guides/cryptodevs/aesni_mb.rst | 1 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/caam_jr.rst | 150 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/features/caam_jr.ini | 46 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/features/default.ini | 4 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/features/mvsam.ini | 12 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/features/octeontx.ini | 62 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/features/qat.ini | 4 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/index.rst | 2 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/mvsam.rst | 147 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/octeontx.rst | 127 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/overview.rst | 2 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/qat.rst | 200 |
12 files changed, 600 insertions, 157 deletions
diff --git a/doc/guides/cryptodevs/aesni_mb.rst b/doc/guides/cryptodevs/aesni_mb.rst index c2929500..63e060d7 100644 --- a/doc/guides/cryptodevs/aesni_mb.rst +++ b/doc/guides/cryptodevs/aesni_mb.rst @@ -44,6 +44,7 @@ Hash algorithms: AEAD algorithms: * RTE_CRYPTO_AEAD_AES_CCM +* RTE_CRYPTO_AEAD_AES_GCM Limitations ----------- diff --git a/doc/guides/cryptodevs/caam_jr.rst b/doc/guides/cryptodevs/caam_jr.rst new file mode 100644 index 00000000..e87ff091 --- /dev/null +++ b/doc/guides/cryptodevs/caam_jr.rst @@ -0,0 +1,150 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright 2018 NXP + + +NXP CAAM JOB RING (caam_jr) +=========================== + +The caam_jr PMD provides poll mode crypto driver support for NXP SEC 4.x+ (CAAM) +hardware accelerator. More information is available at: + +`NXP Cryptographic Acceleration Technology <https://www.nxp.com/applications/solutions/internet-of-things/secure-things/network-security-technology/cryptographic-acceleration-technology:NETWORK_SECURITY_CRYPTOG>`_. + +Architecture +------------ + +SEC is the SOC's security engine, which serves as NXP's latest cryptographic +acceleration and offloading hardware. It combines functions previously +implemented in separate modules to create a modular and scalable acceleration +and assurance engine. It also implements block encryption algorithms, stream +cipher algorithms, hashing algorithms, public key algorithms, run-time +integrity checking, and a hardware random number generator. SEC performs +higher-level cryptographic operations than previous NXP cryptographic +accelerators. This provides significant improvement to system level performance. + +SEC HW accelerator above 4.x+ version are also known as CAAM. + +caam_jr PMD is one of DPAA drivers which uses uio interface to interact with +Linux kernel for configure and destroy the device instance (ring). + + +Implementation +-------------- + +SEC provides platform assurance by working with SecMon, which is a companion +logic block that tracks the security state of the SOC. SEC is programmed by +means of descriptors (not to be confused with frame descriptors (FDs)) that +indicate the operations to be performed and link to the message and +associated data. SEC incorporates two DMA engines to fetch the descriptors, +read the message data, and write the results of the operations. The DMA +engine provides a scatter/gather capability so that SEC can read and write +data scattered in memory. SEC may be configured by means of software for +dynamic changes in byte ordering. The default configuration for this version +of SEC is little-endian mode. + +Note that one physical Job Ring represent one caam_jr device. + +Features +-------- + +The CAAM_JR PMD has support for: + +Cipher algorithms: + +* ``RTE_CRYPTO_CIPHER_3DES_CBC`` +* ``RTE_CRYPTO_CIPHER_AES128_CBC`` +* ``RTE_CRYPTO_CIPHER_AES192_CBC`` +* ``RTE_CRYPTO_CIPHER_AES256_CBC`` +* ``RTE_CRYPTO_CIPHER_AES128_CTR`` +* ``RTE_CRYPTO_CIPHER_AES192_CTR`` +* ``RTE_CRYPTO_CIPHER_AES256_CTR`` + +Hash algorithms: + +* ``RTE_CRYPTO_AUTH_SHA1_HMAC`` +* ``RTE_CRYPTO_AUTH_SHA224_HMAC`` +* ``RTE_CRYPTO_AUTH_SHA256_HMAC`` +* ``RTE_CRYPTO_AUTH_SHA384_HMAC`` +* ``RTE_CRYPTO_AUTH_SHA512_HMAC`` +* ``RTE_CRYPTO_AUTH_MD5_HMAC`` + +AEAD algorithms: + +* ``RTE_CRYPTO_AEAD_AES_GCM`` + +Supported DPAA SoCs +-------------------- + +* LS1046A/LS1026A +* LS1043A/LS1023A +* LS1028A +* LS1012A + +Limitations +----------- + +* Hash followed by Cipher mode is not supported +* Only supports the session-oriented API implementation (session-less APIs are not supported). + +Prerequisites +------------- + +caam_jr driver has following dependencies are not part of DPDK and must be installed separately: + +* **NXP Linux SDK** + + NXP Linux software development kit (SDK) includes support for the family + of QorIQ® ARM-Architecture-based system on chip (SoC) processors + and corresponding boards. + + It includes the Linux board support packages (BSPs) for NXP SoCs, + a fully operational tool chain, kernel and board specific modules. + + SDK and related information can be obtained from: `NXP QorIQ SDK <http://www.nxp.com/products/software-and-tools/run-time-software/linux-sdk/linux-sdk-for-qoriq-processors:SDKLINUX>`_. + +Currently supported by DPDK: + +* NXP SDK **18.09+**. +* Supported architectures: **arm64 LE**. + +* Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup the basic DPDK environment. + +Pre-Installation Configuration +------------------------------ + +Config File Options +~~~~~~~~~~~~~~~~~~~ + +The following options can be modified in the ``config`` file +to enable caam_jr PMD. + +Please note that enabling debugging options may affect system performance. + +* ``CONFIG_RTE_LIBRTE_PMD_CAAM_JR`` (default ``n``) + By default it is only enabled in common_linuxapp config. + Toggle compilation of the ``librte_pmd_caam_jr`` driver. + +* ``CONFIG_RTE_LIBRTE_PMD_CAAM_JR_BE`` (default ``n``) + By default it is disabled. + It can be used when the underlying hardware supports the CAAM in BE mode. + e.g. LS1043A, LS1046A supports CAAM in BE mode. + BE mode is enabled by default in defconfig-arm64-dpaa-linuxapp-gcc. + +Installations +------------- +To compile the caam_jr PMD for Linux arm64 gcc target, run the +following ``make`` command: + +.. code-block:: console + + cd <DPDK-source-directory> + make config T=arm64-armv8a-linuxapp-gcc install + +Enabling logs +------------- + +For enabling logs, use the following EAL parameter: + +.. code-block:: console + + ./your_crypto_application <EAL args> --log-level=pmd.crypto.caam,<level> diff --git a/doc/guides/cryptodevs/features/caam_jr.ini b/doc/guides/cryptodevs/features/caam_jr.ini new file mode 100644 index 00000000..68f8d819 --- /dev/null +++ b/doc/guides/cryptodevs/features/caam_jr.ini @@ -0,0 +1,46 @@ +; +; Supported features of the 'caam_jr' crypto driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Symmetric crypto = Y +Sym operation chaining = Y +HW Accelerated = Y +Protocol offload = Y +In Place SGL = Y +OOP SGL In SGL Out = Y +OOP SGL In LB Out = Y +OOP LB In SGL Out = Y +OOP LB In LB Out = Y + +; +; Supported crypto algorithms of the 'dpaa2_sec' crypto driver. +; +[Cipher] +AES CBC (128) = Y +AES CBC (192) = Y +AES CBC (256) = Y +AES CTR (128) = Y +AES CTR (192) = Y +AES CTR (256) = Y +3DES CBC = Y + +; +; Supported authentication algorithms of the 'dpaa2_sec' crypto driver. +; +[Auth] +MD5 HMAC = Y +SHA1 HMAC = Y +SHA224 HMAC = Y +SHA256 HMAC = Y +SHA384 HMAC = Y +SHA512 HMAC = Y + +; +; Supported AEAD algorithms of the 'dpaa2_sec' crypto driver. +; +[AEAD] +AES GCM (128) = Y +AES GCM (192) = Y +AES GCM (256) = Y diff --git a/doc/guides/cryptodevs/features/default.ini b/doc/guides/cryptodevs/features/default.ini index 92a7ccf3..810da0d7 100644 --- a/doc/guides/cryptodevs/features/default.ini +++ b/doc/guides/cryptodevs/features/default.ini @@ -38,9 +38,13 @@ AES ECB (256) = AES CTR (128) = AES CTR (192) = AES CTR (256) = +AES XTS (128) = +AES XTS (192) = +AES XTS (256) = AES DOCSIS BPI = 3DES CBC = 3DES CTR = +3DES ECB = DES CBC = DES DOCSIS BPI = SNOW3G UEA2 = diff --git a/doc/guides/cryptodevs/features/mvsam.ini b/doc/guides/cryptodevs/features/mvsam.ini index b7c105af..0cc90a53 100644 --- a/doc/guides/cryptodevs/features/mvsam.ini +++ b/doc/guides/cryptodevs/features/mvsam.ini @@ -5,17 +5,24 @@ [Features] Symmetric crypto = Y Sym operation chaining = Y +HW Accelerated = Y +OOP SGL In LB Out = Y +OOP LB In LB Out = Y ; ; Supported crypto algorithms of a default crypto driver. ; [Cipher] +NULL = Y AES CBC (128) = Y AES CBC (192) = Y AES CBC (256) = Y AES CTR (128) = Y AES CTR (192) = Y AES CTR (256) = Y +AES ECB (128) = Y +AES ECB (192) = Y +AES ECB (256) = Y 3DES CBC = Y 3DES CTR = Y @@ -23,10 +30,13 @@ AES CTR (256) = Y ; Supported authentication algorithms of a default crypto driver. ; [Auth] +NULL = Y MD5 = Y MD5 HMAC = Y SHA1 = Y SHA1 HMAC = Y +SHA224 = Y +SHA224 HMAC = Y SHA256 = Y SHA256 HMAC = Y SHA384 = Y @@ -40,3 +50,5 @@ AES GMAC = Y ; [AEAD] AES GCM (128) = Y +AES GCM (192) = Y +AES GCM (256) = Y diff --git a/doc/guides/cryptodevs/features/octeontx.ini b/doc/guides/cryptodevs/features/octeontx.ini new file mode 100644 index 00000000..307ab88c --- /dev/null +++ b/doc/guides/cryptodevs/features/octeontx.ini @@ -0,0 +1,62 @@ +; +; Supported features of the 'octeontx' crypto driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Symmetric crypto = Y +Sym operation chaining = Y +HW Accelerated = Y +In Place SGL = Y +OOP SGL In LB Out = Y +OOP SGL In SGL Out = Y + +; +; Supported crypto algorithms of 'octeontx' crypto driver. +; +[Cipher] +NULL = Y +3DES CBC = Y +3DES ECB = Y +AES CBC (128) = Y +AES CBC (192) = Y +AES CBC (256) = Y +AES CTR (128) = Y +AES CTR (192) = Y +AES CTR (256) = Y +AES XTS (128) = Y +AES XTS (256) = Y +DES CBC = Y +KASUMI F8 = Y +SNOW3G UEA2 = Y +ZUC EEA3 = Y + +; +; Supported authentication algorithms of 'octeontx' crypto driver. +; +[Auth] +NULL = Y +AES GMAC = Y +KASUMI F9 = Y +MD5 = Y +MD5 HMAC = Y +SHA1 = Y +SHA1 HMAC = Y +SHA224 = Y +SHA224 HMAC = Y +SHA256 = Y +SHA256 HMAC = Y +SHA384 = Y +SHA384 HMAC = Y +SHA512 = Y +SHA512 HMAC = Y +SNOW3G UIA2 = Y +ZUC EIA3 = Y + +; +; Supported AEAD algorithms of 'octeontx' crypto driver. +; +[AEAD] +AES GCM (128) = Y +AES GCM (192) = Y +AES GCM (256) = Y diff --git a/doc/guides/cryptodevs/features/qat.ini b/doc/guides/cryptodevs/features/qat.ini index 29d865e0..4f15ee0e 100644 --- a/doc/guides/cryptodevs/features/qat.ini +++ b/doc/guides/cryptodevs/features/qat.ini @@ -48,6 +48,7 @@ SNOW3G UIA2 = Y KASUMI F9 = Y AES XCBC MAC = Y ZUC EIA3 = Y +AES CMAC (128) = Y ; ; Supported AEAD algorithms of the 'qat' crypto driver. @@ -56,3 +57,6 @@ ZUC EIA3 = Y AES GCM (128) = Y AES GCM (192) = Y AES GCM (256) = Y +AES CCM (128) = Y +AES CCM (192) = Y +AES CCM (256) = Y diff --git a/doc/guides/cryptodevs/index.rst b/doc/guides/cryptodevs/index.rst index e9928a4e..83610e64 100644 --- a/doc/guides/cryptodevs/index.rst +++ b/doc/guides/cryptodevs/index.rst @@ -13,10 +13,12 @@ Crypto Device Drivers aesni_mb aesni_gcm armv8 + caam_jr ccp dpaa2_sec dpaa_sec kasumi + octeontx openssl mvsam null diff --git a/doc/guides/cryptodevs/mvsam.rst b/doc/guides/cryptodevs/mvsam.rst index fd418c26..7acae19b 100644 --- a/doc/guides/cryptodevs/mvsam.rst +++ b/doc/guides/cryptodevs/mvsam.rst @@ -37,32 +37,50 @@ support by utilizing MUSDK library, which provides cryptographic operations acceleration by using Security Acceleration Engine (EIP197) directly from user-space with minimum overhead and high performance. +Detailed information about SoCs that use MVSAM crypto driver can be obtained here: + +* https://www.marvell.com/embedded-processors/armada-70xx/ +* https://www.marvell.com/embedded-processors/armada-80xx/ +* https://www.marvell.com/embedded-processors/armada-3700/ + + Features -------- MVSAM CRYPTO PMD has support for: -* Symmetric crypto -* Sym operation chaining -* AES CBC (128) -* AES CBC (192) -* AES CBC (256) -* AES CTR (128) -* AES CTR (192) -* AES CTR (256) -* 3DES CBC -* 3DES CTR -* MD5 -* MD5 HMAC -* SHA1 -* SHA1 HMAC -* SHA256 -* SHA256 HMAC -* SHA384 -* SHA384 HMAC -* SHA512 -* SHA512 HMAC -* AES GCM (128) +Cipher algorithms: + +* ``RTE_CRYPTO_CIPHER_NULL`` +* ``RTE_CRYPTO_CIPHER_AES_CBC`` +* ``RTE_CRYPTO_CIPHER_AES_CTR`` +* ``RTE_CRYPTO_CIPHER_AES_ECB`` +* ``RTE_CRYPTO_CIPHER_3DES_CBC`` +* ``RTE_CRYPTO_CIPHER_3DES_CTR`` +* ``RTE_CRYPTO_CIPHER_3DES_ECB`` + +Hash algorithms: + +* ``RTE_CRYPTO_AUTH_NULL`` +* ``RTE_CRYPTO_AUTH_MD5`` +* ``RTE_CRYPTO_AUTH_MD5_HMAC`` +* ``RTE_CRYPTO_AUTH_SHA1`` +* ``RTE_CRYPTO_AUTH_SHA1_HMAC`` +* ``RTE_CRYPTO_AUTH_SHA224`` +* ``RTE_CRYPTO_AUTH_SHA224_HMAC`` +* ``RTE_CRYPTO_AUTH_SHA256`` +* ``RTE_CRYPTO_AUTH_SHA256_HMAC`` +* ``RTE_CRYPTO_AUTH_SHA384`` +* ``RTE_CRYPTO_AUTH_SHA384_HMAC`` +* ``RTE_CRYPTO_AUTH_SHA512`` +* ``RTE_CRYPTO_AUTH_SHA512_HMAC`` +* ``RTE_CRYPTO_AUTH_AES_GMAC`` + +AEAD algorithms: + +* ``RTE_CRYPTO_AEAD_AES_GCM`` + +For supported feature flags please consult :doc:`overview`. Limitations ----------- @@ -77,25 +95,18 @@ MVSAM CRYPTO PMD driver compilation is disabled by default due to external depen Currently there are two driver specific compilation options in ``config/common_base`` available: -- ``CONFIG_RTE_LIBRTE_MVSAM_CRYPTO`` (default ``n``) +- ``CONFIG_RTE_LIBRTE_PMD_MVSAM_CRYPTO`` (default: ``n``) Toggle compilation of the librte_pmd_mvsam driver. -- ``CONFIG_RTE_LIBRTE_MVSAM_CRYPTO_DEBUG`` (default ``n``) - - Toggle display of debugging messages. - -For a list of prerequisites please refer to `Prerequisites` section in -:ref:`MVPP2 Poll Mode Driver <mvpp2_poll_mode_driver>` guide. - MVSAM CRYPTO PMD requires MUSDK built with EIP197 support thus following extra option must be passed to the library configuration script: .. code-block:: console - --enable-sam + --enable-sam [--enable-sam-statistics] [--enable-sam-debug] -For `crypto_safexcel.ko` module build instructions please refer +For instructions how to build required kernel modules please refer to `doc/musdk_get_started.txt`. Initialization @@ -106,17 +117,15 @@ loaded: .. code-block:: console - insmod musdk_uio.ko - insmod mvpp2x_sysfs.ko - insmod mv_pp_uio.ko + insmod musdk_cma.ko + insmod crypto_safexcel.ko rings=0,0 insmod mv_sam_uio.ko - insmod crypto_safexcel.ko The following parameters (all optional) are exported by the driver: -* max_nb_queue_pairs: maximum number of queue pairs in the device (8 by default). -* max_nb_sessions: maximum number of sessions that can be created (2048 by default). -* socket_id: socket on which to allocate the device resources on. +- ``max_nb_queue_pairs``: maximum number of queue pairs in the device (default: 8 - A8K, 4 - A7K/A3K). +- ``max_nb_sessions``: maximum number of sessions that can be created (default: 2048). +- ``socket_id``: socket on which to allocate the device resources on. l2fwd-crypto example application can be used to verify MVSAM CRYPTO PMD operation: @@ -129,65 +138,3 @@ operation: --auth_op GENERATE --auth_algo sha1-hmac \ --auth_key 10:11:12:13:14:15:16:17:18:19:1a:1b:1c:1d:1e:1f -Example output: - -.. code-block:: console - - [...] - AAD: at [0x7f253ceb80], len= - P ID 0 configuration ---- - Port mode : KR - MAC status : disabled - Link status : link up - Port speed : 10G - Port duplex : full - Port: Egress enable tx_port_num=16 qmap=0x1 - PORT: Port0 - link - P ID 0 configuration ---- - Port mode : KR - MAC status : disabled - Link status : link down - Port speed : 10G - Port duplex : full - Port: Egress enable tx_port_num=16 qmap=0x1 - Port 0, MAC address: 00:50:43:02:21:20 - - - Checking link statusdone - Port 0 Link Up - speed 0 Mbps - full-duplex - Lcore 0: RX port 0 - Allocated session pool on socket 0 - eip197: 0:0 registers: paddr: 0xf2880000, vaddr: 0x0x7f56a80000 - DMA buffer (131136 bytes) for CDR #0 allocated: paddr = 0xb0585e00, vaddr = 0x7f09384e00 - DMA buffer (131136 bytes) for RDR #0 allocated: paddr = 0xb05a5f00, vaddr = 0x7f093a4f00 - DMA buffers allocated for 2049 operations. Tokens - 256 bytes - Lcore 0: cryptodev 0 - L2FWD: lcore 1 has nothing to do - L2FWD: lcore 2 has nothing to do - L2FWD: lcore 3 has nothing to do - L2FWD: entering main loop on lcore 0 - L2FWD: -- lcoreid=0 portid=0 - L2FWD: -- lcoreid=0 cryptoid=0 - Options:- - nportmask: ffffffff - ports per lcore: 1 - refresh period : 10000 - single lcore mode: disabled - stats_printing: enabled - sessionless crypto: disabled - - Crypto chain: Input --> Encrypt --> Auth generate --> Output - - ---- Cipher information --- - Algorithm: aes-cbc - Cipher key: at [0x7f56db4e80], len=16 - 00000000: 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F | ................ - IV: at [0x7f56db4b80], len=16 - 00000000: 20 F0 63 0E 45 EB 2D 84 72 D4 13 6E 36 B5 AF FE | .c.E.-.r..n6... - - ---- Authentication information --- - Algorithm: sha1-hmac - Auth key: at [0x7f56db4d80], len=16 - 00000000: 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F | ................ - IV: at [0x7f56db4a80], len=0 - AAD: at [0x7f253ceb80], len= diff --git a/doc/guides/cryptodevs/octeontx.rst b/doc/guides/cryptodevs/octeontx.rst new file mode 100644 index 00000000..660e980c --- /dev/null +++ b/doc/guides/cryptodevs/octeontx.rst @@ -0,0 +1,127 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2018 Cavium, Inc + +Cavium OCTEON TX Crypto Poll Mode Driver +======================================== + +The OCTEON TX crypto poll mode driver provides support for offloading +cryptographic operations to cryptographic accelerator units on +**OCTEON TX** :sup:`®` family of processors (CN8XXX). The OCTEON TX crypto +poll mode driver enqueues the crypto request to this accelerator and dequeues +the response once the operation is completed. + +Supported Algorithms +-------------------- + +Cipher Algorithms +~~~~~~~~~~~~~~~~~ + +* ``RTE_CRYPTO_CIPHER_NULL`` +* ``RTE_CRYPTO_CIPHER_3DES_CBC`` +* ``RTE_CRYPTO_CIPHER_3DES_ECB`` +* ``RTE_CRYPTO_CIPHER_AES_CBC`` +* ``RTE_CRYPTO_CIPHER_AES_CTR`` +* ``RTE_CRYPTO_CIPHER_AES_XTS`` +* ``RTE_CRYPTO_CIPHER_DES_CBC`` +* ``RTE_CRYPTO_CIPHER_KASUMI_F8`` +* ``RTE_CRYPTO_CIPHER_SNOW3G_UEA2`` +* ``RTE_CRYPTO_CIPHER_ZUC_EEA3`` + +Hash Algorithms +~~~~~~~~~~~~~~~ + +* ``RTE_CRYPTO_AUTH_NULL`` +* ``RTE_CRYPTO_AUTH_AES_GMAC`` +* ``RTE_CRYPTO_AUTH_KASUMI_F9`` +* ``RTE_CRYPTO_AUTH_MD5`` +* ``RTE_CRYPTO_AUTH_MD5_HMAC`` +* ``RTE_CRYPTO_AUTH_SHA1`` +* ``RTE_CRYPTO_AUTH_SHA1_HMAC`` +* ``RTE_CRYPTO_AUTH_SHA224`` +* ``RTE_CRYPTO_AUTH_SHA224_HMAC`` +* ``RTE_CRYPTO_AUTH_SHA256`` +* ``RTE_CRYPTO_AUTH_SHA256_HMAC`` +* ``RTE_CRYPTO_AUTH_SHA384`` +* ``RTE_CRYPTO_AUTH_SHA384_HMAC`` +* ``RTE_CRYPTO_AUTH_SHA512`` +* ``RTE_CRYPTO_AUTH_SHA512_HMAC`` +* ``RTE_CRYPTO_AUTH_SNOW3G_UIA2`` +* ``RTE_CRYPTO_AUTH_ZUC_EIA3`` + +AEAD Algorithms +~~~~~~~~~~~~~~~ + +* ``RTE_CRYPTO_AEAD_AES_GCM`` + +Compilation +----------- + +The **OCTEON TX** :sup:`®` board must be running the linux kernel based on +sdk-6.2.0 patch 3. In this, the OCTEON TX crypto PF driver is already built in. + +For compiling the OCTEON TX crypto poll mode driver, please check if the +CONFIG_RTE_LIBRTE_PMD_OCTEONTX_CRYPTO setting is set to `y` in +config/common_base file. + +* ``CONFIG_RTE_LIBRTE_PMD_OCTEONTX_CRYPTO=y`` + +The following are the steps to compile the OCTEON TX crypto poll mode driver: + +.. code-block:: console + + cd <dpdk directory> + make config T=arm64-thunderx-linuxapp-gcc + make + +The example applications can be compiled using the following: + +.. code-block:: console + + cd <dpdk directory> + export RTE_SDK=$PWD + export RTE_TARGET=build + cd examples/<application> + make + +Execution +--------- + +The number of crypto VFs to be enabled can be controlled by setting sysfs entry, +`sriov_numvfs`, for the corresponding PF driver. + +.. code-block:: console + + echo <num_vfs> > /sys/bus/pci/devices/<dev_bus_id>/sriov_numvfs + +The device bus ID, `dev_bus_id`, to be used in the above step can be found out +by using dpdk-devbind.py script. The OCTEON TX crypto PF device need to be +identified and the corresponding device number can be used to tune various PF +properties. + + +Once the required VFs are enabled, dpdk-devbind.py script can be used to +identify the VFs. To be accessible from DPDK, VFs need to be bound to vfio-pci +driver: + +.. code-block:: console + + cd <dpdk directory> + ./usertools/dpdk-devbind.py -u <vf device no> + ./usertools/dpdk-devbind.py -b vfio-pci <vf device no> + +Appropriate huge page need to be setup in order to run the DPDK example +applications. + +.. code-block:: console + + echo 8 > /sys/kernel/mm/hugepages/hugepages-524288kB/nr_hugepages + mkdir /mnt/huge + mount -t hugetlbfs nodev /mnt/huge + +Example applications can now be executed with crypto operations offloaded to +OCTEON TX crypto PMD. + +.. code-block:: console + + ./build/ipsec-secgw --log-level=8 -c 0xff -- -P -p 0x3 -u 0x2 --config + "(1,0,0),(0,0,0)" -f ep1.cfg diff --git a/doc/guides/cryptodevs/overview.rst b/doc/guides/cryptodevs/overview.rst index 3f776f07..607e758d 100644 --- a/doc/guides/cryptodevs/overview.rst +++ b/doc/guides/cryptodevs/overview.rst @@ -33,7 +33,7 @@ Supported Feature Flags scatter-gathered styled buffers. - "OOP LB In LB Out" feature flag stands for - "Out-of-place Linear Buffers Input, Scatter-gather list Output", + "Out-of-place Linear Buffers Input, Linear Buffers Output", which means that Out-of-place operation is supported, with linear input and output buffers. diff --git a/doc/guides/cryptodevs/qat.rst b/doc/guides/cryptodevs/qat.rst index bdc58eb2..b2dfeb00 100644 --- a/doc/guides/cryptodevs/qat.rst +++ b/doc/guides/cryptodevs/qat.rst @@ -4,17 +4,30 @@ Intel(R) QuickAssist (QAT) Crypto Poll Mode Driver ================================================== -The QAT PMD provides poll mode crypto driver support for the following +QAT documentation consists of three parts: + +* Details of the symmetric crypto service below. +* Details of the `compression service <http://dpdk.org/doc/guides/compressdevs/qat_comp.html>`_ + in the compressdev drivers section. +* Details of building the common QAT infrastructure and the PMDs to support the + above services. See :ref:`building_qat` below. + + +Symmetric Crypto Service on QAT +------------------------------- + +The QAT crypto PMD provides poll mode crypto driver support for the following hardware accelerator devices: * ``Intel QuickAssist Technology DH895xCC`` * ``Intel QuickAssist Technology C62x`` * ``Intel QuickAssist Technology C3xxx`` * ``Intel QuickAssist Technology D15xx`` +* ``Intel QuickAssist Technology C4xxx`` Features --------- +~~~~~~~~ The QAT PMD has support for: @@ -50,14 +63,16 @@ Hash algorithms: * ``RTE_CRYPTO_AUTH_KASUMI_F9`` * ``RTE_CRYPTO_AUTH_AES_GMAC`` * ``RTE_CRYPTO_AUTH_ZUC_EIA3`` +* ``RTE_CRYPTO_AUTH_AES_CMAC`` Supported AEAD algorithms: * ``RTE_CRYPTO_AEAD_AES_GCM`` +* ``RTE_CRYPTO_AEAD_AES_CCM`` Limitations ------------ +~~~~~~~~~~~ * Only supports the session-oriented API implementation (session-less APIs are not supported). * SNOW 3G (UEA2), KASUMI (F8) and ZUC (EEA3) supported only if cipher length and offset fields are byte-multiple. @@ -69,104 +84,155 @@ Limitations Extra notes on KASUMI F9 ------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~ When using KASUMI F9 authentication algorithm, the input buffer must be -constructed according to the 3GPP KASUMI specifications (section 4.4, page 13): -`<http://cryptome.org/3gpp/35201-900.pdf>`_. -Input buffer has to have COUNT (4 bytes), FRESH (4 bytes), MESSAGE and DIRECTION (1 bit) -concatenated. After the DIRECTION bit, a single '1' bit is appended, followed by -between 0 and 7 '0' bits, so that the total length of the buffer is multiple of 8 bits. -Note that the actual message can be any length, specified in bits. +constructed according to the +`3GPP KASUMI specification <http://cryptome.org/3gpp/35201-900.pdf>`_ +(section 4.4, page 13). The input buffer has to have COUNT (4 bytes), +FRESH (4 bytes), MESSAGE and DIRECTION (1 bit) concatenated. After the DIRECTION +bit, a single '1' bit is appended, followed by between 0 and 7 '0' bits, so that +the total length of the buffer is multiple of 8 bits. Note that the actual +message can be any length, specified in bits. Once this buffer is passed this way, when creating the crypto operation, -length of data to authenticate (op.sym.auth.data.length) must be the length +length of data to authenticate "op.sym.auth.data.length" must be the length of all the items described above, including the padding at the end. -Also, offset of data to authenticate (op.sym.auth.data.offset) +Also, offset of data to authenticate "op.sym.auth.data.offset" must be such that points at the start of the COUNT bytes. -Building the DPDK QAT cryptodev PMD ------------------------------------ +.. _building_qat: + +Building PMDs on QAT +-------------------- + +A QAT device can host multiple acceleration services: + +* symmetric cryptography +* data compression -To enable QAT crypto in DPDK, follow the instructions for modifying the compile-time -configuration file as described `here <http://dpdk.org/doc/guides/linux_gsg/build_dpdk.html>`_. +These services are provided to DPDK applications via PMDs which register to +implement the corresponding cryptodev and compressdev APIs. The PMDs use +common QAT driver code which manages the QAT PCI device. They also depend on a +QAT kernel driver being installed on the platform, see :ref:`qat_kernel` below. -Quick instructions are as follows: +Configuring and Building the DPDK QAT PMDs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +Further information on configuring, building and installing DPDK is described +`here <http://dpdk.org/doc/guides/linux_gsg/build_dpdk.html>`_. + + +Quick instructions for QAT cryptodev PMD are as follows: .. code-block:: console cd to the top-level DPDK directory - make config T=x86_64-native-linuxapp-gcc - sed -i 's,\(CONFIG_RTE_LIBRTE_PMD_QAT\)=n,\1=y,' build/.config + make defconfig sed -i 's,\(CONFIG_RTE_LIBRTE_PMD_QAT_SYM\)=n,\1=y,' build/.config make +Quick instructions for QAT compressdev PMD are as follows: -.. _qat_kernel_installation: +.. code-block:: console -Dependency on the QAT kernel driver ------------------------------------ + cd to the top-level DPDK directory + make defconfig + make -To use the QAT PMD an SRIOV-enabled QAT kernel driver is required. The VF -devices created and initialised by this driver will be used by the QAT PMD. -Instructions for installation are below, but first an explanation of the -relationships between the PF/VF devices and the PMDs visible to -DPDK applications. +Build Configuration +~~~~~~~~~~~~~~~~~~~ +These are the build configuration options affecting QAT, and their default values: -Acceleration services - cryptography and compression - are provided to DPDK -applications via PMDs which register to implement the corresponding -cryptodev and compressdev APIs. +.. code-block:: console -Each QuickAssist VF device can expose one cryptodev PMD and/or one compressdev PMD. -These QAT PMDs share the same underlying device and pci-mgmt code, but are -enumerated independently on their respective APIs and appear as independent -devices to applications. + CONFIG_RTE_LIBRTE_PMD_QAT=y + CONFIG_RTE_LIBRTE_PMD_QAT_SYM=n + CONFIG_RTE_PMD_QAT_MAX_PCI_DEVICES=48 + CONFIG_RTE_PMD_QAT_COMP_SGL_MAX_SEGMENTS=16 -.. Note:: +CONFIG_RTE_LIBRTE_PMD_QAT must be enabled for any QAT PMD to be built. - Each VF can only be used by one DPDK process. It is not possible to share - the same VF across multiple processes, even if these processes are using - different acceleration services. +The QAT cryptodev PMD has an external dependency on libcrypto, so is not +built by default. CONFIG_RTE_LIBRTE_PMD_QAT_SYM should be enabled to build it. - Conversely one DPDK process can use one or more QAT VFs and can expose both - cryptodev and compressdev instances on each of those VFs. +The QAT compressdev PMD has no external dependencies, so needs no configuration +options and is built by default. +The number of VFs per PF varies - see table below. If multiple QAT packages are +installed on a platform then CONFIG_RTE_PMD_QAT_MAX_PCI_DEVICES should be +adjusted to the number of VFs which the QAT common code will need to handle. +Note, there is a separate config item for max cryptodevs CONFIG_RTE_CRYPTO_MAX_DEVS, +if necessary this should be adjusted to handle the total of QAT and other devices +which the process will use. + +QAT allocates internal structures to handle SGLs. For the compression service +CONFIG_RTE_PMD_QAT_COMP_SGL_MAX_SEGMENTS can be changed if more segments are needed. +An extra (max_inflight_ops x 16) bytes per queue_pair will be used for every increment. Device and driver naming ------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~ * The qat cryptodev driver name is "crypto_qat". - The rte_cryptodev_devices_get() returns the devices exposed by this driver. + The "rte_cryptodev_devices_get()" returns the devices exposed by this driver. * Each qat crypto device has a unique name, in format - <pci bdf>_<service>, e.g. "0000:41:01.0_qat_sym". - This name can be passed to rte_cryptodev_get_dev_id() to get the device_id. + "<pci bdf>_<service>", e.g. "0000:41:01.0_qat_sym". + This name can be passed to "rte_cryptodev_get_dev_id()" to get the device_id. .. Note:: - The qat crypto driver name is passed to the dpdk-test-crypto-perf tool in the -devtype parameter. + The qat crypto driver name is passed to the dpdk-test-crypto-perf tool in the "-devtype" parameter. The qat crypto device name is in the format of the slave parameter passed to the crypto scheduler. -* The qat compressdev driver name is "comp_qat". +* The qat compressdev driver name is "compress_qat". The rte_compressdev_devices_get() returns the devices exposed by this driver. * Each qat compression device has a unique name, in format <pci bdf>_<service>, e.g. "0000:41:01.0_qat_comp". This name can be passed to rte_compressdev_get_dev_id() to get the device_id. +.. _qat_kernel: + +Dependency on the QAT kernel driver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To use QAT an SRIOV-enabled QAT kernel driver is required. The VF +devices created and initialised by this driver will be used by the QAT PMDs. + +Instructions for installation are below, but first an explanation of the +relationships between the PF/VF devices and the PMDs visible to +DPDK applications. + +Each QuickAssist PF device exposes a number of VF devices. Each VF device can +enable one cryptodev PMD and/or one compressdev PMD. +These QAT PMDs share the same underlying device and pci-mgmt code, but are +enumerated independently on their respective APIs and appear as independent +devices to applications. + +.. Note:: + + Each VF can only be used by one DPDK process. It is not possible to share + the same VF across multiple processes, even if these processes are using + different acceleration services. + + Conversely one DPDK process can use one or more QAT VFs and can expose both + cryptodev and compressdev instances on each of those VFs. + Available kernel drivers ------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~ Kernel drivers for each device are listed in the following table. Scroll right -to check that the driver and device supports the servic you require. +to check that the driver and device supports the service you require. .. _table_qat_pmds_drivers: @@ -190,6 +256,8 @@ to check that the driver and device supports the servic you require. +-----+----------+---------------+---------------+------------+--------+------+--------+--------+-----------+-------------+ | 2 | D15xx | p | qat_d15xx | d15xx | 6f54 | 1 | 6f55 | 16 | Yes | No | +-----+----------+---------------+---------------+------------+--------+------+--------+--------+-----------+-------------+ + | 3 | C4xxx | p | qat_c4xxx | c4xxx | 18a0 | 1 | 18a1 | 128 | Yes | No | + +-----+----------+---------------+---------------+------------+--------+------+--------+--------+-----------+-------------+ The ``Driver`` column indicates either the Linux kernel version in which @@ -203,7 +271,7 @@ If you are running on a kernel which includes a driver for your device, see Installation using kernel.org driver ------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The examples below are based on the C62x device, if you have a different device use the corresponding values in the above table. @@ -274,7 +342,7 @@ To complete the installation follow the instructions in Installation using 01.org QAT driver ------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Download the latest QuickAssist Technology Driver from `01.org <https://01.org/packet-processing/intel%C2%AE-quickassist-technology-drivers-and-patches>`_. @@ -368,12 +436,12 @@ To complete the installation - follow instructions in `Binding the available VFs Binding the available VFs to the DPDK UIO driver ------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Unbind the VFs from the stock driver so they can be bound to the uio driver. For an Intel(R) QuickAssist Technology DH895xCC device -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The unbind command below assumes ``BDFs`` of ``03:01.00-03:04.07``, if your VFs are different adjust the unbind command below:: @@ -386,7 +454,7 @@ VFs are different adjust the unbind command below:: done For an Intel(R) QuickAssist Technology C62x device -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The 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``, if your VFs are different @@ -406,7 +474,7 @@ adjust the unbind command below:: done For Intel(R) QuickAssist Technology C3xxx or D15xx device -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The unbind command below assumes ``BDFs`` of ``01:01.00-01:02.07``, if your VFs are different adjust the unbind command below:: @@ -419,7 +487,7 @@ VFs are different adjust the unbind command below:: done Bind to the DPDK uio driver -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^ Install the DPDK igb_uio driver, bind the VF PCI Device id to it and use lspci to confirm the VF devices are now in use by igb_uio kernel driver, @@ -438,9 +506,29 @@ Another way to bind the VFs to the DPDK UIO driver is by using the cd to the top-level DPDK directory ./usertools/dpdk-devbind.py -b igb_uio 0000:03:01.1 +Testing +~~~~~~~ + +QAT crypto PMD can be tested by running the test application:: + + make defconfig + make test-build -j + cd ./build/app + ./test -l1 -n1 -w <your qat bdf> + RTE>>cryptodev_qat_autotest + +QAT compression PMD can be tested by running the test application:: + + make defconfig + sed -i 's,\(CONFIG_RTE_COMPRESSDEV_TEST\)=n,\1=y,' build/.config + make test-build -j + cd ./build/app + ./test -l1 -n1 -w <your qat bdf> + RTE>>compressdev_autotest + Debugging ----------------------------------------- +~~~~~~~~~ There are 2 sets of trace available via the dynamic logging feature: |