From f4eed1292f375765fd461be7f296d171f029ed5b Mon Sep 17 00:00:00 2001 From: Hemant Agrawal Date: Tue, 16 Oct 2018 18:18:57 +0530 Subject: [PATCH] doc: add CAAM JR guide add caam jr driver details, supported features and algorithms in the document. release note and MAINTAINERS are also updated. Signed-off-by: Hemant Agrawal Acked-by: Akhil Goyal --- MAINTAINERS | 2 + doc/guides/cryptodevs/caam_jr.rst | 150 +++++++++++++++++++++ doc/guides/cryptodevs/features/caam_jr.ini | 46 +++++++ doc/guides/cryptodevs/index.rst | 1 + doc/guides/rel_notes/release_18_11.rst | 5 + 5 files changed, 204 insertions(+) create mode 100644 doc/guides/cryptodevs/caam_jr.rst create mode 100644 doc/guides/cryptodevs/features/caam_jr.ini diff --git a/MAINTAINERS b/MAINTAINERS index 9de01189a0..3079c187e5 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -855,6 +855,8 @@ NXP CAAM JR M: Gagandeep Singh M: Hemant Agrawal F: drivers/crypto/caam_jr/ +F: doc/guides/cryptodevs/caam_jr.rst +F: doc/guides/cryptodevs/features/caam_jr.ini NXP DPAA_SEC M: Akhil Goyal diff --git a/doc/guides/cryptodevs/caam_jr.rst b/doc/guides/cryptodevs/caam_jr.rst new file mode 100644 index 0000000000..e87ff09155 --- /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 `_. + +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 `_. + +Currently supported by DPDK: + +* NXP SDK **18.09+**. +* Supported architectures: **arm64 LE**. + +* Follow the DPDK :ref:`Getting Started Guide for Linux ` 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 + make config T=arm64-armv8a-linuxapp-gcc install + +Enabling logs +------------- + +For enabling logs, use the following EAL parameter: + +.. code-block:: console + + ./your_crypto_application --log-level=pmd.crypto.caam, diff --git a/doc/guides/cryptodevs/features/caam_jr.ini b/doc/guides/cryptodevs/features/caam_jr.ini new file mode 100644 index 0000000000..68f8d81956 --- /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/index.rst b/doc/guides/cryptodevs/index.rst index bd15885376..83610e64fe 100644 --- a/doc/guides/cryptodevs/index.rst +++ b/doc/guides/cryptodevs/index.rst @@ -13,6 +13,7 @@ Crypto Device Drivers aesni_mb aesni_gcm armv8 + caam_jr ccp dpaa2_sec dpaa_sec diff --git a/doc/guides/rel_notes/release_18_11.rst b/doc/guides/rel_notes/release_18_11.rst index 465ec21e34..3d5a34ed98 100644 --- a/doc/guides/rel_notes/release_18_11.rst +++ b/doc/guides/rel_notes/release_18_11.rst @@ -154,6 +154,11 @@ New Features The AESNI MB PMD has been updated with additional support for AES-GCM algorithm support. +* **Added NXP CAAM JR PMD.** + + Added the new caam job ring driver for NXP platforms. See the + "NXP CAAM JOB RING (caam_jr)" document for more details on this new driver. + * **Added Event Ethernet Tx Adapter.** Added event ethernet Tx adapter library that provides configuration and -- 2.20.1