doc/guides/cryptodevs/mrvl.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2017 Semihalf. All rights reserved.
   3     All rights reserved.
   4
   5     Redistribution and use in source and binary forms, with or without
   6     modification, are permitted provided that the following conditions
   7     are met:
   8
   9       * Redistributions of source code must retain the above copyright
  10         notice, this list of conditions and the following disclaimer.
  11       * Redistributions in binary form must reproduce the above copyright
  12         notice, this list of conditions and the following disclaimer in
  13         the documentation and/or other materials provided with the
  14         distribution.
  15       * Neither the name of Semihalf nor the names of its
  16         contributors may be used to endorse or promote products derived
  17         from this software without specific prior written permission.
  18
  19     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31 MRVL Crypto Poll Mode Driver
  32 ============================
  33
  34 The MRVL CRYPTO PMD (**librte_crypto_mrvl_pmd**) provides poll mode crypto driver
  35 support by utilizing MUSDK library, which provides cryptographic operations
  36 acceleration by using Security Acceleration Engine (EIP197) directly from
  37 user-space with minimum overhead and high performance.
  38
  39 Features
  40 --------
  41
  42 MRVL CRYPTO PMD has support for:
  43
  44 * Symmetric crypto
  45 * Sym operation chaining
  46 * AES CBC (128)
  47 * AES CBC (192)
  48 * AES CBC (256)
  49 * AES CTR (128)
  50 * AES CTR (192)
  51 * AES CTR (256)
  52 * 3DES CBC
  53 * 3DES CTR
  54 * MD5
  55 * MD5 HMAC
  56 * SHA1
  57 * SHA1 HMAC
  58 * SHA256
  59 * SHA256 HMAC
  60 * SHA384
  61 * SHA384 HMAC
  62 * SHA512
  63 * SHA512 HMAC
  64 * AES GCM (128)
  65
  66 Limitations
  67 -----------
  68
  69 * Hardware only supports scenarios where ICV (digest buffer) is placed just
  70   after the authenticated data. Other placement will result in error.
  71
  72 * Before running crypto test suite it is advised to increase limit of
  73   opened files:
  74
  75   .. code-block:: console
  76
  77      ulimit -n 20000
  78
  79 Installation
  80 ------------
  81
  82 MRVL CRYPTO PMD driver compilation is disabled by default due to external dependencies.
  83 Currently there are two driver specific compilation options in
  84 ``config/common_base`` available:
  85
  86 - ``CONFIG_RTE_LIBRTE_MRVL_CRYPTO`` (default ``n``)
  87
  88     Toggle compilation of the librte_pmd_mrvl driver.
  89
  90 - ``CONFIG_RTE_LIBRTE_MRVL_CRYPTO_DEBUG`` (default ``n``)
  91
  92     Toggle display of debugging messages.
  93
  94 During compilation external MUSDK library, which provides direct access
  95 to Marvell's EIP197 cryptographic engine, is necessary. Library sources are
  96 available `here <https://github.com/MarvellEmbeddedProcessors/musdk-marvell/tree/musdk-armada-17.08>`__.
  97
  98 Alternatively, prebuilt library can be downloaded from
  99 `Marvell Extranet <https://extranet.marvell.com>`_. Once approval has been
 100 granted, library can be found by typing ``musdk`` in the search box.
 101
 102 For MUSDK library build instructions please refer to ``doc/musdk_get_started.txt``
 103 in library sources directory.
 104
 105 MUSDK requires out of tree kernel modules to work. Kernel tree needed to build
 106 them is available
 107 `here <https://github.com/MarvellEmbeddedProcessors/linux-marvell/tree/linux-4.4.52-armada-17.08>`__.
 108
 109 Initialization
 110 --------------
 111
 112 After successfully building MRVL CRYPTO PMD, the following modules need to be
 113 loaded:
 114
 115 .. code-block:: console
 116
 117    insmod musdk_uio.ko
 118    insmod mvpp2x_sysfs.ko
 119    insmod mv_pp_uio.ko
 120    insmod mv_sam_uio.ko
 121    insmod crypto_safexcel.ko
 122
 123 - `musdk_uio.ko`, `mv_pp2_uio.ko` and `mv_sam_uio.ko` are distributed together with MUSDK library.
 124 - `crypto_safexcel.ko` is an in-kernel module.
 125 - `mvpp2x_sysfs.ko` can be build from sources available `here <https://github.com/MarvellEmbeddedProcessors/mvpp2x-marvell/tree/mvpp2x-armada-17.08>`__.
 126
 127 The following parameters (all optional) are exported by the driver:
 128
 129 * max_nb_queue_pairs: maximum number of queue pairs in the device (8 by default).
 130 * max_nb_sessions: maximum number of sessions that can be created (2048 by default).
 131 * socket_id: socket on which to allocate the device resources on.
 132
 133 l2fwd-crypto example application can be used to verify MRVL CRYPTO PMD
 134 operation:
 135
 136 .. code-block:: console
 137
 138    ./l2fwd-crypto --vdev=net_mrvl,iface=eth0 --vdev=crypto_mrvl -- \
 139      --cipher_op ENCRYPT --cipher_algo aes-cbc \
 140      --cipher_key 00:01:02:03:04:05:06:07:08:09:0a:0b:0c:0d:0e:0f  \
 141      --auth_op GENERATE --auth_algo sha1-hmac \
 142      --auth_key 10:11:12:13:14:15:16:17:18:19:1a:1b:1c:1d:1e:1f
 143
 144 Example output:
 145
 146 .. code-block:: console
 147
 148    [...]
 149    AAD: at [0x7f253ceb80], len=
 150    P ID 0 configuration ----
 151    Port mode               : KR
 152    MAC status              : disabled
 153    Link status             : link up
 154    Port speed              : 10G
 155    Port duplex             : full
 156    Port: Egress enable tx_port_num=16 qmap=0x1
 157    PORT: Port0 - link
 158    P ID 0 configuration ----
 159    Port mode               : KR
 160    MAC status              : disabled
 161    Link status             : link down
 162    Port speed              : 10G
 163    Port duplex             : full
 164    Port: Egress enable tx_port_num=16 qmap=0x1
 165    Port 0, MAC address: 00:50:43:02:21:20
 166
 167
 168    Checking link statusdone
 169    Port 0 Link Up - speed 0 Mbps - full-duplex
 170    Lcore 0: RX port 0
 171    Allocated session pool on socket 0
 172    eip197: 0:0 registers: paddr: 0xf2880000, vaddr: 0x0x7f56a80000
 173    DMA buffer (131136 bytes) for CDR #0 allocated: paddr = 0xb0585e00, vaddr = 0x7f09384e00
 174    DMA buffer (131136 bytes) for RDR #0 allocated: paddr = 0xb05a5f00, vaddr = 0x7f093a4f00
 175    DMA buffers allocated for 2049 operations. Tokens - 256 bytes
 176    Lcore 0: cryptodev 0
 177    L2FWD: lcore 1 has nothing to do
 178    L2FWD: lcore 2 has nothing to do
 179    L2FWD: lcore 3 has nothing to do
 180    L2FWD: entering main loop on lcore 0
 181    L2FWD:  -- lcoreid=0 portid=0
 182    L2FWD:  -- lcoreid=0 cryptoid=0
 183    Options:-
 184    nportmask: ffffffff
 185    ports per lcore: 1
 186    refresh period : 10000
 187    single lcore mode: disabled
 188    stats_printing: enabled
 189    sessionless crypto: disabled
 190
 191    Crypto chain: Input --> Encrypt --> Auth generate --> Output
 192
 193    ---- Cipher information ---
 194    Algorithm: aes-cbc
 195    Cipher key: at [0x7f56db4e80], len=16
 196    00000000: 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F | ................
 197    IV: at [0x7f56db4b80], len=16
 198    00000000: 20 F0 63 0E 45 EB 2D 84 72 D4 13 6E 36 B5 AF FE |  .c.E.-.r..n6...
 199
 200    ---- Authentication information ---
 201    Algorithm: sha1-hmac
 202    Auth key: at [0x7f56db4d80], len=16
 203    00000000: 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F | ................
 204    IV: at [0x7f56db4a80], len=0
 205    AAD: at [0x7f253ceb80], len=