doc/guides/cryptodevs/cnxk.rst

   1 .. SPDX-License-Identifier: BSD-3-Clause
   2    Copyright(c) 2021 Marvell.
   3
   4 Marvell cnxk Crypto Poll Mode Driver
   5 ====================================
   6
   7 The cnxk crypto poll mode driver provides support for offloading
   8 cryptographic operations to cryptographic accelerator units on the
   9 **Marvell OCTEON cnxk** SoC family.
  10
  11 The cnxk crypto PMD code is organized into different sets of files.
  12 The file names starting with cn9k and cn10k provides support for CN9XX
  13 and CN10XX respectively. The common code between the SoCs is present
  14 in file names starting with cnxk.
  15
  16 More information about OCTEON cnxk SoCs may be obtained from `<https://www.marvell.com>`_
  17
  18 Supported OCTEON cnxk SoCs
  19 --------------------------
  20
  21 - CN9XX
  22 - CN10XX
  23
  24 Features
  25 --------
  26
  27 The OCTEON cnxk crypto PMD has support for:
  28
  29 Symmetric Crypto Algorithms
  30 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  31
  32 Cipher algorithms:
  33
  34 * ``RTE_CRYPTO_CIPHER_NULL``
  35 * ``RTE_CRYPTO_CIPHER_3DES_CBC``
  36 * ``RTE_CRYPTO_CIPHER_3DES_ECB``
  37 * ``RTE_CRYPTO_CIPHER_AES_CBC``
  38 * ``RTE_CRYPTO_CIPHER_AES_CTR``
  39 * ``RTE_CRYPTO_CIPHER_AES_XTS``
  40 * ``RTE_CRYPTO_CIPHER_DES_CBC``
  41 * ``RTE_CRYPTO_CIPHER_KASUMI_F8``
  42 * ``RTE_CRYPTO_CIPHER_SNOW3G_UEA2``
  43 * ``RTE_CRYPTO_CIPHER_ZUC_EEA3``
  44
  45 Hash algorithms:
  46
  47 * ``RTE_CRYPTO_AUTH_NULL``
  48 * ``RTE_CRYPTO_AUTH_AES_GMAC``
  49 * ``RTE_CRYPTO_AUTH_KASUMI_F9``
  50 * ``RTE_CRYPTO_AUTH_MD5``
  51 * ``RTE_CRYPTO_AUTH_MD5_HMAC``
  52 * ``RTE_CRYPTO_AUTH_SHA1``
  53 * ``RTE_CRYPTO_AUTH_SHA1_HMAC``
  54 * ``RTE_CRYPTO_AUTH_SHA224``
  55 * ``RTE_CRYPTO_AUTH_SHA224_HMAC``
  56 * ``RTE_CRYPTO_AUTH_SHA256``
  57 * ``RTE_CRYPTO_AUTH_SHA256_HMAC``
  58 * ``RTE_CRYPTO_AUTH_SHA384``
  59 * ``RTE_CRYPTO_AUTH_SHA384_HMAC``
  60 * ``RTE_CRYPTO_AUTH_SHA512``
  61 * ``RTE_CRYPTO_AUTH_SHA512_HMAC``
  62 * ``RTE_CRYPTO_AUTH_SNOW3G_UIA2``
  63 * ``RTE_CRYPTO_AUTH_ZUC_EIA3``
  64 * ``RTE_CRYPTO_AUTH_AES_CMAC``
  65
  66 AEAD algorithms:
  67
  68 * ``RTE_CRYPTO_AEAD_AES_GCM``
  69 * ``RTE_CRYPTO_AEAD_CHACHA20_POLY1305``
  70
  71 Asymmetric Crypto Algorithms
  72 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  73
  74 * ``RTE_CRYPTO_ASYM_XFORM_RSA``
  75 * ``RTE_CRYPTO_ASYM_XFORM_MODEX``
  76
  77 Installation
  78 ------------
  79
  80 The OCTEON cnxk crypto PMD may be compiled natively on an OCTEON cnxk platform
  81 or cross-compiled on an x86 platform.
  82
  83 Refer to :doc:`../platform/cnxk` for instructions to build your DPDK
  84 application.
  85
  86 .. note::
  87
  88    The OCTEON cnxk crypto PMD uses services from the kernel mode OCTEON cnxk
  89    crypto PF driver in linux. This driver is included in the OCTEON TX SDK.
  90
  91 Initialization
  92 --------------
  93
  94 ``CN9K Initialization``
  95
  96 List the CPT PF devices available on cn9k platform:
  97
  98 .. code-block:: console
  99
 100     lspci -d:a0fd
 101
 102 ``a0fd`` is the CPT PF device id. You should see output similar to:
 103
 104 .. code-block:: console
 105
 106     0002:10:00.0 Class 1080: Device 177d:a0fd
 107
 108 Set ``sriov_numvfs`` on the CPT PF device, to create a VF:
 109
 110 .. code-block:: console
 111
 112     echo 1 > /sys/bus/pci/devices/0002:10:00.0/sriov_numvfs
 113
 114 Bind the CPT VF device to the vfio_pci driver:
 115
 116 .. code-block:: console
 117
 118     cd <dpdk directory>
 119     ./usertools/dpdk-devbind.py -u 0002:10:00.1
 120     ./usertools/dpdk-devbind.py -b vfio-pci 0002:10.00.1
 121
 122 .. note::
 123
 124     * For CN98xx SoC, it is recommended to use even and odd DBDF VFs to achieve
 125       higher performance as even VF uses one crypto engine and odd one uses
 126       another crypto engine.
 127
 128     * Ensure that sufficient huge pages are available for your application::
 129
 130          dpdk-hugepages.py --setup 4G --pagesize 512M
 131
 132       Refer to :ref:`linux_gsg_hugepages` for more details.
 133
 134 ``CN10K Initialization``
 135
 136 List the CPT PF devices available on cn10k platform:
 137
 138 .. code-block:: console
 139
 140     lspci -d:a0f2
 141
 142 ``a0f2`` is the CPT PF device id. You should see output similar to:
 143
 144 .. code-block:: console
 145
 146     0002:20:00.0 Class 1080: Device 177d:a0f2
 147
 148 Set ``sriov_numvfs`` on the CPT PF device, to create a VF:
 149
 150 .. code-block:: console
 151
 152     echo 1 > /sys/bus/pci/devices/0002:20:00.0/sriov_numvfs
 153
 154 Bind the CPT VF device to the vfio_pci driver:
 155
 156 .. code-block:: console
 157
 158     cd <dpdk directory>
 159     ./usertools/dpdk-devbind.py -u 0002:20:00.1
 160     ./usertools/dpdk-devbind.py -b vfio-pci 0002:20:00.1
 161
 162 Runtime Config Options
 163 ----------------------
 164
 165 - ``Maximum queue pairs limit`` (default ``63``)
 166
 167    The number of maximum queue pairs supported by the device, can be limited
 168    during runtime by using ``max_qps_limit`` ``devargs`` parameter.
 169
 170    For example::
 171
 172       -a 0002:20:00.1,max_qps_limit=4
 173
 174    With the above configuration, the number of maximum queue pairs supported
 175    by the device is limited to 4.
 176
 177 Debugging Options
 178 -----------------
 179
 180 .. _table_octeon_cnxk_crypto_debug_options:
 181
 182 .. table:: OCTEON cnxk crypto PMD debug options
 183
 184     +---+------------+-------------------------------------------------------+
 185     | # | Component  | EAL log command                                       |
 186     +===+============+=======================================================+
 187     | 1 | CPT        | --log-level='pmd\.crypto\.cnxk,8'                     |
 188     +---+------------+-------------------------------------------------------+
 189
 190 Testing
 191 -------
 192
 193 The symmetric crypto operations on OCTEON cnxk crypto PMD may be verified by
 194 running the test application:
 195
 196 ``CN9K``
 197
 198 .. code-block:: console
 199
 200     ./dpdk-test
 201     RTE>>cryptodev_cn9k_autotest
 202
 203 ``CN10K``
 204
 205 .. code-block:: console
 206
 207     ./dpdk-test
 208     RTE>>cryptodev_cn10k_autotest
 209
 210 The asymmetric crypto operations on OCTEON cnxk crypto PMD may be verified by
 211 running the test application:
 212
 213 ``CN9K``
 214
 215 .. code-block:: console
 216
 217     ./dpdk-test
 218     RTE>>cryptodev_cn9k_asym_autotest
 219
 220 ``CN10K``
 221
 222 .. code-block:: console
 223
 224     ./dpdk-test
 225     RTE>>cryptodev_cn10k_asym_autotest
 226
 227 Lookaside IPsec Support
 228 -----------------------
 229
 230 The OCTEON cnxk SoCs can accelerate IPsec traffic in lookaside protocol mode,
 231 with its **cryptographic accelerator (CPT)**. ``OCTEON cnxk crypto PMD`` implements
 232 this as an ``RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL`` offload.
 233
 234 Refer to :doc:`../prog_guide/rte_security` for more details on protocol offloads.
 235
 236 This feature can be tested with ipsec-secgw sample application.
 237
 238 Supported OCTEON cnxk SoCs
 239 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 240
 241 - CN9XX
 242 - CN10XX
 243
 244 CN9XX Features supported
 245 ~~~~~~~~~~~~~~~~~~~~~~~~
 246
 247 * IPv4
 248 * IPv6
 249 * ESP
 250 * ESN
 251 * Anti-replay
 252 * Tunnel mode
 253 * Transport mode(IPv4)
 254 * UDP Encapsulation
 255
 256 AEAD algorithms
 257 +++++++++++++++
 258
 259 * AES-128/192/256-GCM
 260
 261 Cipher algorithms
 262 +++++++++++++++++
 263
 264 * NULL
 265 * AES-128/192/256-CBC
 266 * AES-128/192/256-CTR
 267
 268 Auth algorithms
 269 +++++++++++++++
 270
 271 * SHA1-HMAC
 272 * SHA256-128-HMAC
 273 * SHA384-192-HMAC
 274 * SHA512-256-HMAC
 275 * AES-XCBC-96
 276
 277 CN10XX Features supported
 278 ~~~~~~~~~~~~~~~~~~~~~~~~~
 279
 280 * IPv4
 281 * ESP
 282 * ESN
 283 * Anti-replay
 284 * Tunnel mode
 285 * Transport mode
 286 * UDP Encapsulation
 287
 288 AEAD algorithms
 289 +++++++++++++++
 290
 291 * AES-128/192/256-GCM
 292
 293 Cipher algorithms
 294 +++++++++++++++++
 295
 296 * NULL
 297 * AES-128/192/256-CBC
 298 * AES-128/192/256-CTR
 299
 300 Auth algorithms
 301 +++++++++++++++
 302
 303 * NULL
 304 * SHA1-HMAC
 305 * SHA256-128-HMAC
 306 * SHA384-192-HMAC
 307 * SHA512-256-HMAC
 308 * AES-XCBC-96