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 Debugging Options
 162 -----------------
 163
 164 .. _table_octeon_cnxk_crypto_debug_options:
 165
 166 .. table:: OCTEON cnxk crypto PMD debug options
 167
 168     +---+------------+-------------------------------------------------------+
 169     | # | Component  | EAL log command                                       |
 170     +===+============+=======================================================+
 171     | 1 | CPT        | --log-level='pmd\.crypto\.cnxk,8'                     |
 172     +---+------------+-------------------------------------------------------+
 173
 174 Testing
 175 -------
 176
 177 The symmetric crypto operations on OCTEON cnxk crypto PMD may be verified by
 178 running the test application:
 179
 180 ``CN9K``
 181
 182 .. code-block:: console
 183
 184     ./dpdk-test
 185     RTE>>cryptodev_cn9k_autotest
 186
 187 ``CN10K``
 188
 189 .. code-block:: console
 190
 191     ./dpdk-test
 192     RTE>>cryptodev_cn10k_autotest
 193
 194 The asymmetric crypto operations on OCTEON cnxk crypto PMD may be verified by
 195 running the test application:
 196
 197 ``CN9K``
 198
 199 .. code-block:: console
 200
 201     ./dpdk-test
 202     RTE>>cryptodev_cn9k_asym_autotest
 203
 204 ``CN10K``
 205
 206 .. code-block:: console
 207
 208     ./dpdk-test
 209     RTE>>cryptodev_cn10k_asym_autotest
 210
 211 Lookaside IPsec Support
 212 -----------------------
 213
 214 The OCTEON cnxk SoCs can accelerate IPsec traffic in lookaside protocol mode,
 215 with its **cryptographic accelerator (CPT)**. ``OCTEON cnxk crypto PMD`` implements
 216 this as an ``RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL`` offload.
 217
 218 Refer to :doc:`../prog_guide/rte_security` for more details on protocol offloads.
 219
 220 This feature can be tested with ipsec-secgw sample application.
 221
 222 Supported OCTEON cnxk SoCs
 223 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 224
 225 - CN10XX
 226
 227 Features supported
 228 ~~~~~~~~~~~~~~~~~~
 229
 230 * IPv4
 231 * ESP
 232 * Tunnel mode
 233 * AES-128/192/256-GCM
 234
 235 Limitations
 236 -----------
 237
 238 Multiple lcores may not operate on the same crypto queue pair. The lcore that
 239 enqueues to a queue pair is the one that must dequeue from it.