From 4433ced9aa4b800e36bbc2509d850f98c4e92346 Mon Sep 17 00:00:00 2001 From: Ravi Kumar Date: Mon, 19 Mar 2018 08:23:53 -0400 Subject: [PATCH] doc: add AMD CCP guide Signed-off-by: Ravi Kumar --- MAINTAINERS | 2 + doc/guides/cryptodevs/ccp.rst | 102 +++++++++++++++++++++ doc/guides/cryptodevs/features/ccp.ini | 59 ++++++++++++ doc/guides/cryptodevs/features/default.ini | 15 ++- doc/guides/cryptodevs/index.rst | 1 + doc/guides/rel_notes/release_18_05.rst | 4 +- 6 files changed, 181 insertions(+), 2 deletions(-) create mode 100644 doc/guides/cryptodevs/ccp.rst create mode 100644 doc/guides/cryptodevs/features/ccp.ini diff --git a/MAINTAINERS b/MAINTAINERS index a04ab69426..7f7d97d264 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -690,6 +690,8 @@ F: doc/guides/cryptodevs/features/default.ini AMD CCP Crypto M: Ravi Kumar F: drivers/crypto/ccp/ +F: doc/guides/cryptodevs/ccp.rst +F: doc/guides/cryptodevs/features/ccp.ini ARMv8 Crypto M: Jerin Jacob diff --git a/doc/guides/cryptodevs/ccp.rst b/doc/guides/cryptodevs/ccp.rst new file mode 100644 index 0000000000..1fcd462208 --- /dev/null +++ b/doc/guides/cryptodevs/ccp.rst @@ -0,0 +1,102 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2018 Advanced Micro Devices, Inc. All rights reserved. + +AMD CCP Poll Mode Driver +======================== + +This code provides the initial implementation of the ccp poll mode driver. +The CCP poll mode driver library (librte_pmd_ccp) implements support for +AMD’s cryptographic co-processor (CCP). The CCP PMD is a virtual crypto +poll mode driver which schedules crypto operations to one or more available +CCP hardware engines on the platform. The CCP PMD provides poll mode crypto +driver support for the following hardware accelerator devices:: + + AMD Cryptographic Co-processor (0x1456) + AMD Cryptographic Co-processor (0x1468) + +Features +-------- + +CCP crypto PMD has support for: + +Cipher algorithms: + +* ``RTE_CRYPTO_CIPHER_AES_CBC`` +* ``RTE_CRYPTO_CIPHER_AES_ECB`` +* ``RTE_CRYPTO_CIPHER_AES_CTR`` +* ``RTE_CRYPTO_CIPHER_3DES_CBC`` + +Hash algorithms: + +* ``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_MD5_HMAC`` +* ``RTE_CRYPTO_AUTH_AES_CMAC`` +* ``RTE_CRYPTO_AUTH_SHA3_224`` +* ``RTE_CRYPTO_AUTH_SHA3_224_HMAC`` +* ``RTE_CRYPTO_AUTH_SHA3_256`` +* ``RTE_CRYPTO_AUTH_SHA3_256_HMAC`` +* ``RTE_CRYPTO_AUTH_SHA3_384`` +* ``RTE_CRYPTO_AUTH_SHA3_384_HMAC`` +* ``RTE_CRYPTO_AUTH_SHA3_512`` +* ``RTE_CRYPTO_AUTH_SHA3_512_HMAC`` + +AEAD algorithms: + +* ``RTE_CRYPTO_AEAD_AES_GCM`` + +Installation +------------ + +To compile CCP PMD, it has to be enabled in the config/common_base file. +* ``CONFIG_RTE_LIBRTE_PMD_CCP=y`` + +The CCP PMD also supports computing authentication over CPU with cipher offloaded +to CCP. To enable this feature, enable following in the configuration. +* ``CONFIG_RTE_LIBRTE_PMD_CCP_CPU_AUTH=y`` + +This code was verified on Ubuntu 16.04. + +Initialization +-------------- + +Bind the CCP devices to DPDK UIO driver module before running the CCP PMD stack. +e.g. for the 0x1456 device:: + + cd to the top-level DPDK directory + modprobe uio + insmod ./build/kmod/igb_uio.ko + echo "1022 1456" > /sys/bus/pci/drivers/igb_uio/new_id + +Another way to bind the CCP devices to DPDK UIO driver is by using the ``dpdk-devbind.py`` script. +The following command assumes ``BFD`` of ``0000:09:00.2``:: + + cd to the top-level DPDK directory + ./usertools/dpdk-devbind.py -b igb_uio 0000:09:00.2 + +To verify real traffic l2fwd-crypto example can be used with following command: + +.. code-block:: console + + sudo ./build/l2fwd-crypto -l 1 -n 4 --vdev "crypto_ccp" -- -p 0x1 + --chain CIPHER_HASH --cipher_op ENCRYPT --cipher_algo AES_CBC + --cipher_key 00:01:02:03:04:05:06:07:08:09:0a:0b:0c:0d:0e:0f + --iv 00:01:02:03:04:05:06:07:08:09:0a:0b:0c:0d:0e:ff + --auth_op GENERATE --auth_algo SHA1_HMAC + --auth_key 11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11 + :11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11 + :11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11 + +Limitations +----------- + +* Chained mbufs are not supported +* MD5_HMAC is supported only if ``CONFIG_RTE_LIBRTE_PMD_CCP_CPU_AUTH=y`` is enabled in configuration diff --git a/doc/guides/cryptodevs/features/ccp.ini b/doc/guides/cryptodevs/features/ccp.ini new file mode 100644 index 0000000000..4722e135dc --- /dev/null +++ b/doc/guides/cryptodevs/features/ccp.ini @@ -0,0 +1,59 @@ +; +; Supported features of the 'ccp' crypto poll mode driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Symmetric crypto = Y +Sym operation chaining = Y +HW Accelerated = Y + +; +; Supported crypto algorithms of the 'ccp' crypto driver. +; +[Cipher] +AES CBC (128) = Y +AES CBC (192) = Y +AES CBC (256) = Y +AES ECB (128) = Y +AES ECB (192) = Y +AES ECB (256) = Y +AES CTR (128) = Y +AES CTR (192) = Y +AES CTR (256) = Y +3DES CBC = Y + +; +; Supported authentication algorithms of the 'ccp' crypto driver. +; +[Auth] +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 +AES CMAC (128) = Y +AES CMAC (192) = Y +AES CMAC (256) = Y +SHA3_224 = Y +SHA3_224 HMAC = Y +SHA3_256 = Y +SHA3_256 HMAC = Y +SHA3_384 = Y +SHA3_384 HMAC = Y +SHA3_512 = Y +SHA3_512 HMAC = Y + +; +; Supported AEAD algorithms of the 'ccp' 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 243ac7670f..42783887a5 100644 --- a/doc/guides/cryptodevs/features/default.ini +++ b/doc/guides/cryptodevs/features/default.ini @@ -28,6 +28,9 @@ NULL = AES CBC (128) = AES CBC (192) = AES CBC (256) = +AES ECB (128) = +AES ECB (192) = +AES ECB (256) = AES CTR (128) = AES CTR (192) = AES CTR (256) = @@ -62,7 +65,17 @@ AES GMAC = SNOW3G UIA2 = KASUMI F9 = ZUC EIA3 = -AES CMAC(128) = +AES CMAC (128) = +AES CMAC (192) = +AES CMAC (256) = +SHA3_224 = +SHA3_224 HMAC = +SHA3_256 = +SHA3_256 HMAC = +SHA3_384 = +SHA3_384 HMAC = +SHA3_512 = +SHA3_512 HMAC = ; ; Supported AEAD algorithms of a default crypto driver. diff --git a/doc/guides/cryptodevs/index.rst b/doc/guides/cryptodevs/index.rst index 558c92673c..8a921ddd70 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 + ccp dpaa2_sec dpaa_sec kasumi diff --git a/doc/guides/rel_notes/release_18_05.rst b/doc/guides/rel_notes/release_18_05.rst index e3a959dcce..ffb4cc339d 100644 --- a/doc/guides/rel_notes/release_18_05.rst +++ b/doc/guides/rel_notes/release_18_05.rst @@ -98,7 +98,9 @@ New Features * **Added AMD CCP Crypto PMD.** - Added the new ``ccp`` crypto driver for AMD CCP devices. + Added the new ``ccp`` crypto driver for AMD CCP devices. See the + :doc:`../cryptodevs/ccp` crypto driver guide for more details on + this new driver. * **Updated AESNI MB PMD.** -- 2.20.1