diff options
Diffstat (limited to 'doc/guides/cryptodevs')
| -rw-r--r-- | doc/guides/cryptodevs/aesni_gcm.rst | 13 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/aesni_mb.rst | 14 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/ccp.rst | 140 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/dpaa2_sec.rst | 32 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/dpaa_sec.rst | 34 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/features/aesni_mb.ini | 1 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/features/ccp.ini | 59 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/features/default.ini | 14 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/features/mvsam.ini (renamed from doc/guides/cryptodevs/features/mrvl.ini) | 2 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/features/virtio.ini | 26 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/index.rst | 4 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/kasumi.rst | 10 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/mvsam.rst (renamed from doc/guides/cryptodevs/mrvl.rst) | 26 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/overview.rst | 10 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/snow3g.rst | 10 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/virtio.rst | 117 | ||||
| -rw-r--r-- | doc/guides/cryptodevs/zuc.rst | 10 |
17 files changed, 460 insertions, 62 deletions
diff --git a/doc/guides/cryptodevs/aesni_gcm.rst b/doc/guides/cryptodevs/aesni_gcm.rst index ffd6ba90..01590e85 100644 --- a/doc/guides/cryptodevs/aesni_gcm.rst +++ b/doc/guides/cryptodevs/aesni_gcm.rst @@ -36,12 +36,13 @@ Installation To build DPDK with the AESNI_GCM_PMD the user is required to download the multi-buffer library from `here <https://github.com/01org/intel-ipsec-mb>`_ and compile it on their user system before building DPDK. -The latest version of the library supported by this PMD is v0.48, which -can be downloaded in `<https://github.com/01org/intel-ipsec-mb/archive/v0.48.zip>`_. +The latest version of the library supported by this PMD is v0.49, which +can be downloaded in `<https://github.com/01org/intel-ipsec-mb/archive/v0.49.zip>`_. .. code-block:: console - make + make + make install As a reference, the following table shows a mapping between the past DPDK versions and the external crypto libraries supported by them: @@ -55,7 +56,8 @@ and the external crypto libraries supported by them: ============= ================================ 16.04 - 16.11 Multi-buffer library 0.43 - 0.44 17.02 - 17.05 ISA-L Crypto v2.18 - 17.08+ Multi-buffer library 0.46+ + 17.08 - 18.02 Multi-buffer library 0.46 - 0.48 + 18.05 Multi-buffer library 0.49 ============= ================================ @@ -64,9 +66,6 @@ Initialization In order to enable this virtual crypto PMD, user must: -* Export the environmental variable AESNI_MULTI_BUFFER_LIB_PATH with the path where - the library was extracted. - * Build the multi buffer library (explained in Installation section). * Set CONFIG_RTE_LIBRTE_PMD_AESNI_GCM=y in config/common_base. diff --git a/doc/guides/cryptodevs/aesni_mb.rst b/doc/guides/cryptodevs/aesni_mb.rst index 3950daae..236828c0 100644 --- a/doc/guides/cryptodevs/aesni_mb.rst +++ b/doc/guides/cryptodevs/aesni_mb.rst @@ -38,6 +38,7 @@ Hash algorithms: * RTE_CRYPTO_HASH_SHA384_HMAC * RTE_CRYPTO_HASH_SHA512_HMAC * RTE_CRYPTO_HASH_AES_XCBC_HMAC +* RTE_CRYPTO_HASH_AES_CMAC AEAD algorithms: @@ -56,12 +57,13 @@ Installation To build DPDK with the AESNI_MB_PMD the user is required to download the multi-buffer library from `here <https://github.com/01org/intel-ipsec-mb>`_ and compile it on their user system before building DPDK. -The latest version of the library supported by this PMD is v0.48, which -can be downloaded from `<https://github.com/01org/intel-ipsec-mb/archive/v0.48.zip>`_. +The latest version of the library supported by this PMD is v0.49, which +can be downloaded from `<https://github.com/01org/intel-ipsec-mb/archive/v0.49.zip>`_. .. code-block:: console - make + make + make install As a reference, the following table shows a mapping between the past DPDK versions and the Multi-Buffer library version supported by them: @@ -77,7 +79,8 @@ and the Multi-Buffer library version supported by them: 17.02 0.44 17.05 - 17.08 0.45 - 0.48 17.11 0.47 - 0.48 - 18.02+ 0.48 + 18.02 0.48 + 18.05 0.49 ============== ============================ @@ -86,9 +89,6 @@ Initialization In order to enable this virtual crypto PMD, user must: -* Export the environmental variable AESNI_MULTI_BUFFER_LIB_PATH with the path where - the library was extracted. - * Build the multi buffer library (explained in Installation section). * Set CONFIG_RTE_LIBRTE_PMD_AESNI_MB=y in config/common_base. diff --git a/doc/guides/cryptodevs/ccp.rst b/doc/guides/cryptodevs/ccp.rst new file mode 100644 index 00000000..034d2036 --- /dev/null +++ b/doc/guides/cryptodevs/ccp.rst @@ -0,0 +1,140 @@ +.. 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 and openssl +packages have to be installed in the build environment. + +* ``CONFIG_RTE_LIBRTE_PMD_CCP=y`` + +For Ubuntu 16.04 LTS use below to install openssl in the build system: + +.. code-block:: console + + sudo apt-get install openssl + +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`` as ``0000:09:00.2``:: + + cd to the top-level DPDK directory + ./usertools/dpdk-devbind.py -b igb_uio 0000:09:00.2 + +In order to enable the ccp crypto PMD, user must set CONFIG_RTE_LIBRTE_PMD_CCP=y in config/common_base. + +To use the PMD in an application, user must: + +* Call rte_vdev_init("crypto_ccp") within the application. + +* Use --vdev="crypto_ccp" in the EAL options, which will call rte_vdev_init() internally. + +The following parameters (all optional) can be provided in the previous two calls: + +* socket_id: Specify the socket where the memory for the device is going to be allocated. + (by default, socket_id will be the socket where the core that is creating the PMD is running on). + +* max_nb_queue_pairs: Specify the maximum number of queue pairs in the device. + +* max_nb_sessions: Specify the maximum number of sessions that can be created (2048 by default). + +* ccp_auth_opt: Specify authentication operations to perform on CPU using openssl APIs. + +To validate ccp pmd, 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 + +The CCP PMD also supports computing authentication over CPU with cipher offloaded to CCP. +To enable this feature, pass an additional argument as ccp_auth_opt=1 to --vdev parameters as +following: + +.. code-block:: console + + sudo ./build/l2fwd-crypto -l 1 -n 4 --vdev "crypto_ccp,ccp_auth_opt=1" -- -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 for CPU based authentication. diff --git a/doc/guides/cryptodevs/dpaa2_sec.rst b/doc/guides/cryptodevs/dpaa2_sec.rst index 5460a92d..3ea24c8a 100644 --- a/doc/guides/cryptodevs/dpaa2_sec.rst +++ b/doc/guides/cryptodevs/dpaa2_sec.rst @@ -134,6 +134,17 @@ Supported DPAA2 SoCs * LS2088A/LS2048A * LS1088A/LS1048A +Whitelisting & Blacklisting +--------------------------- + +For blacklisting a DPAA2 SEC device, following commands can be used. + + .. code-block:: console + + <dpdk app> <EAL args> -b "fslmc:dpseci.x" -- ... + +Where x is the device object id as configured in resource container. + Limitations ----------- @@ -189,15 +200,6 @@ Please note that enabling debugging options may affect system performance. By default it is only enabled in defconfig_arm64-dpaa2-* config. Toggle compilation of the ``librte_pmd_dpaa2_sec`` driver. -* ``CONFIG_RTE_LIBRTE_DPAA2_SEC_DEBUG_INIT`` (default ``n``) - Toggle display of initialization related driver messages - -* ``CONFIG_RTE_LIBRTE_DPAA2_SEC_DEBUG_DRIVER`` (default ``n``) - Toggle display of driver runtime messages - -* ``CONFIG_RTE_LIBRTE_DPAA2_SEC_DEBUG_RX`` (default ``n``) - Toggle display of receive fast path run-time message - * ``CONFIG_RTE_DPAA2_SEC_PMD_MAX_NB_SESSIONS`` By default it is set as 2048 in defconfig_arm64-dpaa2-* config. It indicates Number of sessions to create in the session memory pool @@ -212,3 +214,15 @@ following ``make`` command: cd <DPDK-source-directory> make config T=arm64-dpaa2-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.dpaa2:<level> + +Using ``crypto.dpaa2`` as log matching criteria, all Crypto PMD logs can be +enabled which are lower than logging ``level``. diff --git a/doc/guides/cryptodevs/dpaa_sec.rst b/doc/guides/cryptodevs/dpaa_sec.rst index b98f7864..c14d6d7b 100644 --- a/doc/guides/cryptodevs/dpaa_sec.rst +++ b/doc/guides/cryptodevs/dpaa_sec.rst @@ -78,6 +78,19 @@ Supported DPAA SoCs * LS1046A/LS1026A * LS1043A/LS1023A +Whitelisting & Blacklisting +--------------------------- + +For blacklisting a DPAA device, following commands can be used. + + .. code-block:: console + + <dpdk app> <EAL args> -b "dpaa_bus:dpaa-secX" -- ... + e.g. "dpaa_bus:dpaa-sec0" + + or to disable all 4 SEC devices + -b "dpaa_sec:dpaa-sec0" -b "dpaa_sec:dpaa-sec1" -b "dpaa_sec:dpaa-sec2" -b "dpaa_sec:dpaa-sec3" + Limitations ----------- @@ -132,15 +145,6 @@ Please note that enabling debugging options may affect system performance. By default it is only enabled in defconfig_arm64-dpaa-* config. Toggle compilation of the ``librte_pmd_dpaa_sec`` driver. -* ``CONFIG_RTE_LIBRTE_DPAA_SEC_DEBUG_INIT`` (default ``n``) - Toggle display of initialization related driver messages - -* ``CONFIG_RTE_LIBRTE_DPAA_SEC_DEBUG_DRIVER`` (default ``n``) - Toggle display of driver runtime messages - -* ``CONFIG_RTE_LIBRTE_DPAA_SEC_DEBUG_RX`` (default ``n``) - Toggle display of receive fast path run-time message - * ``CONFIG_RTE_DPAA_SEC_PMD_MAX_NB_SESSIONS`` By default it is set as 2048 in defconfig_arm64-dpaa-* config. It indicates Number of sessions to create in the session memory pool @@ -155,3 +159,15 @@ following ``make`` command: cd <DPDK-source-directory> make config T=arm64-dpaa-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.dpaa:<level> + +Using ``pmd.crypto.dpaa`` as log matching criteria, all Crypto PMD logs can be +enabled which are lower than logging ``level``. diff --git a/doc/guides/cryptodevs/features/aesni_mb.ini b/doc/guides/cryptodevs/features/aesni_mb.ini index a5a45a6d..1e263c2b 100644 --- a/doc/guides/cryptodevs/features/aesni_mb.ini +++ b/doc/guides/cryptodevs/features/aesni_mb.ini @@ -37,6 +37,7 @@ SHA256 HMAC = Y SHA384 HMAC = Y SHA512 HMAC = Y AES XCBC MAC = Y +AES CMAC (128) = Y ; ; Supported AEAD algorithms of the 'aesni_mb' crypto driver. diff --git a/doc/guides/cryptodevs/features/ccp.ini b/doc/guides/cryptodevs/features/ccp.ini new file mode 100644 index 00000000..4722e135 --- /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 728ce3b7..42783887 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,6 +65,17 @@ AES GMAC = SNOW3G UIA2 = KASUMI F9 = ZUC EIA3 = +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/features/mrvl.ini b/doc/guides/cryptodevs/features/mvsam.ini index 6d2fe6aa..b7c105af 100644 --- a/doc/guides/cryptodevs/features/mrvl.ini +++ b/doc/guides/cryptodevs/features/mvsam.ini @@ -1,4 +1,4 @@ -; Supported features of the 'mrvl' crypto driver. +; Supported features of the 'mvsam' crypto driver. ; ; Refer to default.ini for the full list of available PMD features. ; diff --git a/doc/guides/cryptodevs/features/virtio.ini b/doc/guides/cryptodevs/features/virtio.ini new file mode 100644 index 00000000..168fc174 --- /dev/null +++ b/doc/guides/cryptodevs/features/virtio.ini @@ -0,0 +1,26 @@ +; Supported features of the 'virtio' crypto driver. +; +; Refer to default.ini for the full list of available PMD features. +; +[Features] +Symmetric crypto = Y +Sym operation chaining = Y + +; +; Supported crypto algorithms of the 'virtio' crypto driver. +; +[Cipher] +AES CBC (128) = Y +AES CBC (192) = Y +AES CBC (256) = Y + +; +; Supported authentication algorithms of the 'virtio' crypto driver. +; +[Auth] +SHA1 HMAC = Y + +; +; Supported AEAD algorithms of the 'virtio' crypto driver. +; +[AEAD] diff --git a/doc/guides/cryptodevs/index.rst b/doc/guides/cryptodevs/index.rst index 558c9267..e9928a4e 100644 --- a/doc/guides/cryptodevs/index.rst +++ b/doc/guides/cryptodevs/index.rst @@ -13,13 +13,15 @@ Crypto Device Drivers aesni_mb aesni_gcm armv8 + ccp dpaa2_sec dpaa_sec kasumi openssl - mrvl + mvsam null scheduler snow3g qat + virtio zuc diff --git a/doc/guides/cryptodevs/kasumi.rst b/doc/guides/cryptodevs/kasumi.rst index f56b5475..2265eee4 100644 --- a/doc/guides/cryptodevs/kasumi.rst +++ b/doc/guides/cryptodevs/kasumi.rst @@ -34,11 +34,11 @@ Installation ------------ To build DPDK with the KASUMI_PMD the user is required to download -the export controlled ``libsso_kasumi`` library, by requesting it from -`<https://networkbuilders.intel.com/network-technologies/dpdk>`_. -Once approval has been granted, the user needs to log in -`<https://networkbuilders.intel.com/dpdklogin>`_ -and click on "Kasumi Bit Stream crypto library" link, to download the library. +the export controlled ``libsso_kasumi`` library, by registering in +`Intel Resource & Design Center <https://www.intel.com/content/www/us/en/design/resource-design-center.html>`_. +Once approval has been granted, the user needs to search for +*Kasumi F8 F9 3GPP cryptographic algorithms Software Library* to download the +library or directly through this `link <https://cdrdv2.intel.com/v1/dl/getContent/575866>`_. After downloading the library, the user needs to unpack and compile it on their system before building DPDK:: diff --git a/doc/guides/cryptodevs/mrvl.rst b/doc/guides/cryptodevs/mvsam.rst index 6a0b08c5..fd418c26 100644 --- a/doc/guides/cryptodevs/mrvl.rst +++ b/doc/guides/cryptodevs/mvsam.rst @@ -29,10 +29,10 @@ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -MRVL Crypto Poll Mode Driver -============================ +MVSAM Crypto Poll Mode Driver +============================= -The MRVL CRYPTO PMD (**librte_crypto_mrvl_pmd**) provides poll mode crypto driver +The MVSAM CRYPTO PMD (**librte_crypto_mvsam_pmd**) provides poll mode crypto driver 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. @@ -40,7 +40,7 @@ user-space with minimum overhead and high performance. Features -------- -MRVL CRYPTO PMD has support for: +MVSAM CRYPTO PMD has support for: * Symmetric crypto * Sym operation chaining @@ -73,22 +73,22 @@ Limitations Installation ------------ -MRVL CRYPTO PMD driver compilation is disabled by default due to external dependencies. +MVSAM CRYPTO PMD driver compilation is disabled by default due to external dependencies. Currently there are two driver specific compilation options in ``config/common_base`` available: -- ``CONFIG_RTE_LIBRTE_MRVL_CRYPTO`` (default ``n``) +- ``CONFIG_RTE_LIBRTE_MVSAM_CRYPTO`` (default ``n``) - Toggle compilation of the librte_pmd_mrvl driver. + Toggle compilation of the librte_pmd_mvsam driver. -- ``CONFIG_RTE_LIBRTE_MRVL_CRYPTO_DEBUG`` (default ``n``) +- ``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:`MRVL Poll Mode Driver <mrvl_poll_mode_driver>` guide. +:ref:`MVPP2 Poll Mode Driver <mvpp2_poll_mode_driver>` guide. -MRVL CRYPTO PMD requires MUSDK built with EIP197 support thus following +MVSAM CRYPTO PMD requires MUSDK built with EIP197 support thus following extra option must be passed to the library configuration script: .. code-block:: console @@ -101,7 +101,7 @@ to `doc/musdk_get_started.txt`. Initialization -------------- -After successfully building MRVL CRYPTO PMD, the following modules need to be +After successfully building MVSAM CRYPTO PMD, the following modules need to be loaded: .. code-block:: console @@ -118,12 +118,12 @@ The following parameters (all optional) are exported by the driver: * 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. -l2fwd-crypto example application can be used to verify MRVL CRYPTO PMD +l2fwd-crypto example application can be used to verify MVSAM CRYPTO PMD operation: .. code-block:: console - ./l2fwd-crypto --vdev=net_mrvl,iface=eth0 --vdev=crypto_mrvl -- \ + ./l2fwd-crypto --vdev=eth_mvpp2,iface=eth0 --vdev=crypto_mvsam -- \ --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 \ --auth_op GENERATE --auth_algo sha1-hmac \ diff --git a/doc/guides/cryptodevs/overview.rst b/doc/guides/cryptodevs/overview.rst index b3cb6cae..493cd5f5 100644 --- a/doc/guides/cryptodevs/overview.rst +++ b/doc/guides/cryptodevs/overview.rst @@ -11,6 +11,16 @@ Supported Feature Flags .. include:: overview_feature_table.txt +Note, the mbuf scatter gather feature (aka chained mbufs, scatter-gather-lists +or SGLs) indicate all following combinations are supported unless otherwise called +out in the Limitations section of each PMD. + +* In place operation, input buffer as multiple segments, same buffer used for output +* Out of place operation, input buffer as single segment and output as multiple segments +* Out of place operation, input buffer as multiple segments and output as single segment +* Out of place operation, input buffer as multiple segments and output as multiple segments + + Supported Cipher Algorithms --------------------------- diff --git a/doc/guides/cryptodevs/snow3g.rst b/doc/guides/cryptodevs/snow3g.rst index 24b4f661..7cba712c 100644 --- a/doc/guides/cryptodevs/snow3g.rst +++ b/doc/guides/cryptodevs/snow3g.rst @@ -33,11 +33,11 @@ Installation ------------ To build DPDK with the SNOW3G_PMD the user is required to download -the export controlled ``libsso_snow3g`` library, by requesting it from -`<https://networkbuilders.intel.com/network-technologies/dpdk>`_. -Once approval has been granted, the user needs to log in -`<https://networkbuilders.intel.com/dpdklogin>`_ -and click on "Snow3G Bit Stream crypto library" link, to download the library. +the export controlled ``libsso_snow3g`` library, by registering in +`Intel Resource & Design Center <https://www.intel.com/content/www/us/en/design/resource-design-center.html>`_. +Once approval has been granted, the user needs to search for +*Snow3G F8 F9 3GPP cryptographic algorithms Software Library* to download the +library or directly through this `link <https://cdrdv2.intel.com/v1/dl/getContent/575867>`_. After downloading the library, the user needs to unpack and compile it on their system before building DPDK:: diff --git a/doc/guides/cryptodevs/virtio.rst b/doc/guides/cryptodevs/virtio.rst new file mode 100644 index 00000000..f3aa7c65 --- /dev/null +++ b/doc/guides/cryptodevs/virtio.rst @@ -0,0 +1,117 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2018 HUAWEI TECHNOLOGIES CO., LTD. + +Virtio Crypto Poll Mode Driver +============================== + +The virtio crypto PMD provides poll mode driver support for the virtio crypto +device. + +Features +-------- + +The virtio crypto PMD has support for: + +Cipher algorithms: + +* ``RTE_CRYPTO_CIPHER_AES_CBC`` + +Hash algorithms: + +* ``RTE_CRYPTO_AUTH_SHA1_HMAC`` + +Limitations +----------- + +* Only supports the session-oriented API implementation (session-less APIs are + not supported). +* Only supports modern mode since virtio crypto conforms to virtio-1.0. +* Only has two types of queues: data queue and control queue. These two queues + only support indirect buffers to communication with the virtio backend. +* Only supports AES_CBC cipher only algorithm and AES_CBC with HMAC_SHA1 + chaining algorithm since the vhost crypto backend only these algorithms + are supported. +* Does not support Link State interrupt. +* Does not support runtime configuration. + +Virtio crypto PMD Rx/Tx Callbacks +--------------------------------- + +Rx callbacks: + +* ``virtio_crypto_pkt_rx_burst`` + +Tx callbacks: + +* ``virtio_crypto_pkt_tx_burst`` + +Installation +------------ + +Quick instructions are as follows: + +Firstly run DPDK vhost crypto sample as a server side and build QEMU with +vhost crypto enabled. +QEMU can then be started using the following parameters: + +.. code-block:: console + + qemu-system-x86_64 \ + [...] \ + -chardev socket,id=charcrypto0,path=/path/to/your/socket \ + -object cryptodev-vhost-user,id=cryptodev0,chardev=charcrypto0 \ + -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 + [...] + +Secondly bind the uio_generic driver for the virtio-crypto device. +For example, 0000:00:04.0 is the domain, bus, device and function +number of the virtio-crypto device: + +.. code-block:: console + + modprobe uio_pci_generic + echo -n 0000:00:04.0 > /sys/bus/pci/drivers/virtio-pci/unbind + echo "1af4 1054" > /sys/bus/pci/drivers/uio_pci_generic/new_id + +Finally the front-end virtio crypto PMD driver can be installed: + +.. code-block:: console + + cd to the top-level DPDK directory + sed -i 's,\(CONFIG_RTE_LIBRTE_PMD_VIRTIO_CRYPTO\)=n,\1=y,' config/common_base + make config T=x86_64-native-linuxapp-gcc + make install T=x86_64-native-linuxapp-gcc + +Tests +----- + +The unit test cases can be tested as below: + +.. code-block:: console + + reserve enough huge pages + cd to the top-level DPDK directory + export RTE_TARGET=x86_64-native-linuxapp-gcc + export RTE_SDK=`pwd` + cd to test/test + type the command "make" to compile + run the tests with "./test" + type the command "cryptodev_virtio_autotest" to test + +The performance can be tested as below: + +.. code-block:: console + + reserve enough huge pages + cd to the top-level DPDK directory + export RTE_TARGET=x86_64-native-linuxapp-gcc + export RTE_SDK=`pwd` + cd to app/test-crypto-perf + type the command "make" to compile + run the tests with the following command: + + ./dpdk-test-crypto-perf -l 0,1 -- --devtype crypto_virtio \ + --ptest throughput --optype cipher-then-auth --cipher-algo aes-cbc \ + --cipher-op encrypt --cipher-key-sz 16 --auth-algo sha1-hmac \ + --auth-op generate --auth-key-sz 64 --digest-sz 12 \ + --total-ops 100000000 --burst-sz 64 --buffer-sz 2048 diff --git a/doc/guides/cryptodevs/zuc.rst b/doc/guides/cryptodevs/zuc.rst index e226ef9d..e3898996 100644 --- a/doc/guides/cryptodevs/zuc.rst +++ b/doc/guides/cryptodevs/zuc.rst @@ -35,11 +35,11 @@ Installation ------------ To build DPDK with the ZUC_PMD the user is required to download -the export controlled ``libsso_zuc`` library, by requesting it from -`<https://networkbuilders.intel.com/network-technologies/dpdk>`_. -Once approval has been granted, the user needs to log in -`<https://networkbuilders.intel.com/dpdklogin>`_ -and click on "ZUC Library" link, to download the library. +the export controlled ``libsso_zuc`` library, by registering in +`Intel Resource & Design Center <https://www.intel.com/content/www/us/en/design/resource-design-center.html>`_. +Once approval has been granted, the user needs to search for +*ZUC 128-EAA3 and 128-EIA3 3GPP cryptographic algorithms Software Library* to download the +library or directly through this `link <https://cdrdv2.intel.com/v1/dl/getContent/575868>`_. After downloading the library, the user needs to unpack and compile it on their system before building DPDK:: |