doc/guides/cryptodevs/mvsam.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2017 Marvell International Ltd.
   3     Copyright(c) 2017 Semihalf.
   4
   5 MVSAM Crypto Poll Mode Driver
   6 =============================
   7
   8 The MVSAM CRYPTO PMD (**librte_crypto_mvsam**) provides poll mode crypto driver
   9 support by utilizing MUSDK library, which provides cryptographic operations
  10 acceleration by using Security Acceleration Engine (EIP197) directly from
  11 user-space with minimum overhead and high performance.
  12
  13 Detailed 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
  20 Features
  21 --------
  22
  23 MVSAM CRYPTO PMD has support for:
  24
  25 Cipher 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
  35 Hash 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
  52 AEAD algorithms:
  53
  54 * ``RTE_CRYPTO_AEAD_AES_GCM``
  55
  56 For supported feature flags please consult :doc:`overview`.
  57
  58 Limitations
  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
  64 Installation
  65 ------------
  66
  67 MVSAM CRYPTO PMD requires MUSDK built with EIP197 support thus following
  68 extra option must be passed to the library configuration script:
  69
  70 .. code-block:: console
  71
  72    --enable-sam [--enable-sam-statistics] [--enable-sam-debug]
  73
  74 For instructions how to build required kernel modules please refer
  75 to `doc/musdk_get_started.txt`.
  76
  77 Initialization
  78 --------------
  79
  80 After successfully building MVSAM CRYPTO PMD, the following modules need to be
  81 loaded:
  82
  83 .. code-block:: console
  84
  85    insmod musdk_cma.ko
  86    insmod crypto_safexcel.ko rings=0,0
  87    insmod mv_sam_uio.ko
  88
  89 The following parameters (all optional) are exported by the driver:
  90
  91 - ``max_nb_queue_pairs``: maximum number of queue pairs in the device (default: 8 - A8K, 4 - A7K/A3K).
  92 - ``max_nb_sessions``: maximum number of sessions that can be created (default: 2048).
  93 - ``socket_id``: socket on which to allocate the device resources on.
  94
  95 l2fwd-crypto example application can be used to verify MVSAM CRYPTO PMD
  96 operation:
  97
  98 .. code-block:: console
  99
 100    ./dpdk-l2fwd-crypto --vdev=eth_mvpp2,iface=eth0 --vdev=crypto_mvsam -- \
 101      --cipher_op ENCRYPT --cipher_algo aes-cbc \
 102      --cipher_key 00:01:02:03:04:05:06:07:08:09:0a:0b:0c:0d:0e:0f  \
 103      --auth_op GENERATE --auth_algo sha1-hmac \
 104      --auth_key 10:11:12:13:14:15:16:17:18:19:1a:1b:1c:1d:1e:1f