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 * AH
 256
 257 AEAD algorithms
 258 +++++++++++++++
 259
 260 * AES-128/192/256-GCM
 261
 262 Cipher algorithms
 263 +++++++++++++++++
 264
 265 * NULL
 266 * AES-128/192/256-CBC
 267 * AES-128/192/256-CTR
 268
 269 Auth algorithms
 270 +++++++++++++++
 271
 272 * SHA1-HMAC
 273 * SHA256-128-HMAC
 274 * SHA384-192-HMAC
 275 * SHA512-256-HMAC
 276 * AES-XCBC-96
 277 * AES-GMAC
 278
 279 CN10XX Features supported
 280 ~~~~~~~~~~~~~~~~~~~~~~~~~
 281
 282 * IPv4
 283 * ESP
 284 * ESN
 285 * Anti-replay
 286 * Tunnel mode
 287 * Transport mode
 288 * UDP Encapsulation
 289 * AH
 290
 291 AEAD algorithms
 292 +++++++++++++++
 293
 294 * AES-128/192/256-GCM
 295
 296 Cipher algorithms
 297 +++++++++++++++++
 298
 299 * NULL
 300 * AES-128/192/256-CBC
 301 * AES-128/192/256-CTR
 302
 303 Auth algorithms
 304 +++++++++++++++
 305
 306 * NULL
 307 * SHA1-HMAC
 308 * SHA256-128-HMAC
 309 * SHA384-192-HMAC
 310 * SHA512-256-HMAC
 311 * AES-XCBC-96
 312 * AES-GMAC