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
  65 AEAD algorithms:
  66
  67 * ``RTE_CRYPTO_AEAD_AES_GCM``
  68 * ``RTE_CRYPTO_AEAD_CHACHA20_POLY1305``
  69
  70 Asymmetric Crypto Algorithms
  71 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  72
  73 * ``RTE_CRYPTO_ASYM_XFORM_RSA``
  74 * ``RTE_CRYPTO_ASYM_XFORM_MODEX``
  75
  76 Installation
  77 ------------
  78
  79 The OCTEON cnxk crypto PMD may be compiled natively on an OCTEON cnxk platform
  80 or cross-compiled on an x86 platform.
  81
  82 Refer to :doc:`../platform/cnxk` for instructions to build your DPDK
  83 application.
  84
  85 .. note::
  86
  87    The OCTEON cnxk crypto PMD uses services from the kernel mode OCTEON cnxk
  88    crypto PF driver in linux. This driver is included in the OCTEON TX SDK.
  89
  90 Initialization
  91 --------------
  92
  93 ``CN9K Initialization``
  94
  95 List the CPT PF devices available on cn9k platform:
  96
  97 .. code-block:: console
  98
  99     lspci -d:a0fd
 100
 101 ``a0fd`` is the CPT PF device id. You should see output similar to:
 102
 103 .. code-block:: console
 104
 105     0002:10:00.0 Class 1080: Device 177d:a0fd
 106
 107 Set ``sriov_numvfs`` on the CPT PF device, to create a VF:
 108
 109 .. code-block:: console
 110
 111     echo 1 > /sys/bus/pci/devices/0002:10:00.0/sriov_numvfs
 112
 113 Bind the CPT VF device to the vfio_pci driver:
 114
 115 .. code-block:: console
 116
 117     cd <dpdk directory>
 118     ./usertools/dpdk-devbind.py -u 0002:10:00.1
 119     ./usertools/dpdk-devbind.py -b vfio-pci 0002:10.00.1
 120
 121 .. note::
 122
 123     * For CN98xx SoC, it is recommended to use even and odd DBDF VFs to achieve
 124       higher performance as even VF uses one crypto engine and odd one uses
 125       another crypto engine.
 126
 127     * Ensure that sufficient huge pages are available for your application::
 128
 129          dpdk-hugepages.py --setup 4G --pagesize 512M
 130
 131       Refer to :ref:`linux_gsg_hugepages` for more details.
 132
 133 ``CN10K Initialization``
 134
 135 List the CPT PF devices available on cn10k platform:
 136
 137 .. code-block:: console
 138
 139     lspci -d:a0f2
 140
 141 ``a0f2`` is the CPT PF device id. You should see output similar to:
 142
 143 .. code-block:: console
 144
 145     0002:20:00.0 Class 1080: Device 177d:a0f2
 146
 147 Set ``sriov_numvfs`` on the CPT PF device, to create a VF:
 148
 149 .. code-block:: console
 150
 151     echo 1 > /sys/bus/pci/devices/0002:20:00.0/sriov_numvfs
 152
 153 Bind the CPT VF device to the vfio_pci driver:
 154
 155 .. code-block:: console
 156
 157     cd <dpdk directory>
 158     ./usertools/dpdk-devbind.py -u 0002:20:00.1
 159     ./usertools/dpdk-devbind.py -b vfio-pci 0002:20:00.1
 160
 161 Runtime Config Options
 162 ----------------------
 163
 164 - ``Maximum queue pairs limit`` (default ``63``)
 165
 166    The number of maximum queue pairs supported by the device, can be limited
 167    during runtime by using ``max_qps_limit`` ``devargs`` parameter.
 168
 169    For example::
 170
 171       -a 0002:20:00.1,max_qps_limit=4
 172
 173    With the above configuration, the number of maximum queue pairs supported
 174    by the device is limited to 4.
 175
 176 Debugging Options
 177 -----------------
 178
 179 .. _table_octeon_cnxk_crypto_debug_options:
 180
 181 .. table:: OCTEON cnxk crypto PMD debug options
 182
 183     +---+------------+-------------------------------------------------------+
 184     | # | Component  | EAL log command                                       |
 185     +===+============+=======================================================+
 186     | 1 | CPT        | --log-level='pmd\.crypto\.cnxk,8'                     |
 187     +---+------------+-------------------------------------------------------+
 188
 189 Testing
 190 -------
 191
 192 The symmetric crypto operations on OCTEON cnxk crypto PMD may be verified by
 193 running the test application:
 194
 195 ``CN9K``
 196
 197 .. code-block:: console
 198
 199     ./dpdk-test
 200     RTE>>cryptodev_cn9k_autotest
 201
 202 ``CN10K``
 203
 204 .. code-block:: console
 205
 206     ./dpdk-test
 207     RTE>>cryptodev_cn10k_autotest
 208
 209 The asymmetric crypto operations on OCTEON cnxk crypto PMD may be verified by
 210 running the test application:
 211
 212 ``CN9K``
 213
 214 .. code-block:: console
 215
 216     ./dpdk-test
 217     RTE>>cryptodev_cn9k_asym_autotest
 218
 219 ``CN10K``
 220
 221 .. code-block:: console
 222
 223     ./dpdk-test
 224     RTE>>cryptodev_cn10k_asym_autotest
 225
 226 Lookaside IPsec Support
 227 -----------------------
 228
 229 The OCTEON cnxk SoCs can accelerate IPsec traffic in lookaside protocol mode,
 230 with its **cryptographic accelerator (CPT)**. ``OCTEON cnxk crypto PMD`` implements
 231 this as an ``RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL`` offload.
 232
 233 Refer to :doc:`../prog_guide/rte_security` for more details on protocol offloads.
 234
 235 This feature can be tested with ipsec-secgw sample application.
 236
 237 Supported OCTEON cnxk SoCs
 238 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 239
 240 - CN9XX
 241 - CN10XX
 242
 243 CN9XX Features supported
 244 ~~~~~~~~~~~~~~~~~~~~~~~~
 245
 246 * IPv4
 247 * ESP
 248 * Tunnel mode
 249 * UDP Encapsulation
 250 * AES-128/192/256-GCM
 251
 252 CN10XX Features supported
 253 ~~~~~~~~~~~~~~~~~~~~~~~~~
 254
 255 * IPv4
 256 * ESP
 257 * Tunnel mode
 258 * Transport mode
 259 * UDP Encapsulation
 260 * AES-128/192/256-GCM
 261 * AES-128/192/256-CBC-SHA1-HMAC
 262
 263 Limitations
 264 -----------
 265
 266 Multiple lcores may not operate on the same crypto queue pair. The lcore that
 267 enqueues to a queue pair is the one that must dequeue from it.