1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2017 Marvell International Ltd. 3 Copyright(c) 2017 Semihalf. 4 5MVSAM Crypto Poll Mode Driver 6============================= 7 8The MVSAM CRYPTO PMD (**librte_crypto_mvsam_pmd**) provides poll mode crypto driver 9support by utilizing MUSDK library, which provides cryptographic operations 10acceleration by using Security Acceleration Engine (EIP197) directly from 11user-space with minimum overhead and high performance. 12 13Detailed information about SoCs that use MVSAM crypto driver can be obtained here: 14 15* https://www.marvell.com/embedded-processors/armada-70xx/ 16* https://www.marvell.com/embedded-processors/armada-80xx/ 17* https://www.marvell.com/embedded-processors/armada-3700/ 18 19 20Features 21-------- 22 23MVSAM CRYPTO PMD has support for: 24 25Cipher algorithms: 26 27* ``RTE_CRYPTO_CIPHER_NULL`` 28* ``RTE_CRYPTO_CIPHER_AES_CBC`` 29* ``RTE_CRYPTO_CIPHER_AES_CTR`` 30* ``RTE_CRYPTO_CIPHER_AES_ECB`` 31* ``RTE_CRYPTO_CIPHER_3DES_CBC`` 32* ``RTE_CRYPTO_CIPHER_3DES_CTR`` 33* ``RTE_CRYPTO_CIPHER_3DES_ECB`` 34 35Hash algorithms: 36 37* ``RTE_CRYPTO_AUTH_NULL`` 38* ``RTE_CRYPTO_AUTH_MD5`` 39* ``RTE_CRYPTO_AUTH_MD5_HMAC`` 40* ``RTE_CRYPTO_AUTH_SHA1`` 41* ``RTE_CRYPTO_AUTH_SHA1_HMAC`` 42* ``RTE_CRYPTO_AUTH_SHA224`` 43* ``RTE_CRYPTO_AUTH_SHA224_HMAC`` 44* ``RTE_CRYPTO_AUTH_SHA256`` 45* ``RTE_CRYPTO_AUTH_SHA256_HMAC`` 46* ``RTE_CRYPTO_AUTH_SHA384`` 47* ``RTE_CRYPTO_AUTH_SHA384_HMAC`` 48* ``RTE_CRYPTO_AUTH_SHA512`` 49* ``RTE_CRYPTO_AUTH_SHA512_HMAC`` 50* ``RTE_CRYPTO_AUTH_AES_GMAC`` 51 52AEAD algorithms: 53 54* ``RTE_CRYPTO_AEAD_AES_GCM`` 55 56For supported feature flags please consult :doc:`overview`. 57 58Limitations 59----------- 60 61* Hardware only supports scenarios where ICV (digest buffer) is placed just 62 after the authenticated data. Other placement will result in error. 63 64Installation 65------------ 66 67MVSAM CRYPTO PMD driver compilation is disabled by default due to external dependencies. 68Currently there are two driver specific compilation options in 69``config/common_base`` available: 70 71- ``CONFIG_RTE_LIBRTE_PMD_MVSAM_CRYPTO`` (default: ``n``) 72 73 Toggle compilation of the librte_pmd_mvsam driver. 74 75MVSAM CRYPTO PMD requires MUSDK built with EIP197 support thus following 76extra option must be passed to the library configuration script: 77 78.. code-block:: console 79 80 --enable-sam [--enable-sam-statistics] [--enable-sam-debug] 81 82For instructions how to build required kernel modules please refer 83to `doc/musdk_get_started.txt`. 84 85Initialization 86-------------- 87 88After successfully building MVSAM CRYPTO PMD, the following modules need to be 89loaded: 90 91.. code-block:: console 92 93 insmod musdk_cma.ko 94 insmod crypto_safexcel.ko rings=0,0 95 insmod mv_sam_uio.ko 96 97The following parameters (all optional) are exported by the driver: 98 99- ``max_nb_queue_pairs``: maximum number of queue pairs in the device (default: 8 - A8K, 4 - A7K/A3K). 100- ``max_nb_sessions``: maximum number of sessions that can be created (default: 2048). 101- ``socket_id``: socket on which to allocate the device resources on. 102 103l2fwd-crypto example application can be used to verify MVSAM CRYPTO PMD 104operation: 105 106.. code-block:: console 107 108 ./l2fwd-crypto --vdev=eth_mvpp2,iface=eth0 --vdev=crypto_mvsam -- \ 109 --cipher_op ENCRYPT --cipher_algo aes-cbc \ 110 --cipher_key 00:01:02:03:04:05:06:07:08:09:0a:0b:0c:0d:0e:0f \ 111 --auth_op GENERATE --auth_algo sha1-hmac \ 112 --auth_key 10:11:12:13:14:15:16:17:18:19:1a:1b:1c:1d:1e:1f 113 114