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_pmd**) 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 driver compilation is disabled by default due to external dependencies.
  68 Currently 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
  75 MVSAM CRYPTO PMD requires MUSDK built with EIP197 support thus following
  76 extra 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
  82 For instructions how to build required kernel modules please refer
  83 to `doc/musdk_get_started.txt`.
  84
  85 Initialization
  86 --------------
  87
  88 After successfully building MVSAM CRYPTO PMD, the following modules need to be
  89 loaded:
  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
  97 The 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
 103 l2fwd-crypto example application can be used to verify MVSAM CRYPTO PMD
 104 operation:
 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