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