summaryrefslogtreecommitdiffstats
path: root/doc/guides/cryptodevs
diff options
context:
space:
mode:
authorLuca Boccassi <luca.boccassi@gmail.com>2018-11-01 11:59:50 +0000
committerLuca Boccassi <luca.boccassi@gmail.com>2018-11-01 12:00:19 +0000
commit8d01b9cd70a67cdafd5b965a70420c3bd7fb3f82 (patch)
tree208e3bc33c220854d89d010e3abf720a2e62e546 /doc/guides/cryptodevs
parentb63264c8342e6a1b6971c79550d2af2024b6a4de (diff)
New upstream version 18.11-rc1upstream/18.11-rc1
Change-Id: Iaa71986dd6332e878d8f4bf493101b2bbc6313bb Signed-off-by: Luca Boccassi <luca.boccassi@gmail.com>
Diffstat (limited to 'doc/guides/cryptodevs')
-rw-r--r--doc/guides/cryptodevs/aesni_mb.rst1
-rw-r--r--doc/guides/cryptodevs/caam_jr.rst150
-rw-r--r--doc/guides/cryptodevs/features/caam_jr.ini46
-rw-r--r--doc/guides/cryptodevs/features/default.ini4
-rw-r--r--doc/guides/cryptodevs/features/mvsam.ini12
-rw-r--r--doc/guides/cryptodevs/features/octeontx.ini62
-rw-r--r--doc/guides/cryptodevs/features/qat.ini4
-rw-r--r--doc/guides/cryptodevs/index.rst2
-rw-r--r--doc/guides/cryptodevs/mvsam.rst147
-rw-r--r--doc/guides/cryptodevs/octeontx.rst127
-rw-r--r--doc/guides/cryptodevs/overview.rst2
-rw-r--r--doc/guides/cryptodevs/qat.rst200
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: