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 45Hash 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 66AEAD algorithms: 67 68* ``RTE_CRYPTO_AEAD_AES_GCM`` 69* ``RTE_CRYPTO_AEAD_CHACHA20_POLY1305`` 70 71Asymmetric Crypto Algorithms 72~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 73 74* ``RTE_CRYPTO_ASYM_XFORM_RSA`` 75* ``RTE_CRYPTO_ASYM_XFORM_MODEX`` 76 77Installation 78------------ 79 80The OCTEON cnxk crypto PMD may be compiled natively on an OCTEON cnxk platform 81or cross-compiled on an x86 platform. 82 83Refer to :doc:`../platform/cnxk` for instructions to build your DPDK 84application. 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 91Initialization 92-------------- 93 94``CN9K Initialization`` 95 96List 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 108Set ``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 114Bind 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 136List 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 148Set ``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 154Bind 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 162Runtime 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 177Debugging 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 190Testing 191------- 192 193The symmetric crypto operations on OCTEON cnxk crypto PMD may be verified by 194running 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 210The asymmetric crypto operations on OCTEON cnxk crypto PMD may be verified by 211running 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 227Lookaside IPsec Support 228----------------------- 229 230The OCTEON cnxk SoCs can accelerate IPsec traffic in lookaside protocol mode, 231with its **cryptographic accelerator (CPT)**. ``OCTEON cnxk crypto PMD`` implements 232this as an ``RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL`` offload. 233 234Refer to :doc:`../prog_guide/rte_security` for more details on protocol offloads. 235 236This feature can be tested with ipsec-secgw sample application. 237 238Supported OCTEON cnxk SoCs 239~~~~~~~~~~~~~~~~~~~~~~~~~~ 240 241- CN9XX 242- CN10XX 243 244CN9XX 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 256AEAD algorithms 257+++++++++++++++ 258 259* AES-128/192/256-GCM 260 261Cipher algorithms 262+++++++++++++++++ 263 264* NULL 265* AES-128/192/256-CBC 266* AES-128/192/256-CTR 267 268Auth algorithms 269+++++++++++++++ 270 271* SHA1-HMAC 272* SHA256-128-HMAC 273* SHA384-192-HMAC 274* SHA512-256-HMAC 275* AES-XCBC-96 276 277CN10XX Features supported 278~~~~~~~~~~~~~~~~~~~~~~~~~ 279 280* IPv4 281* ESP 282* ESN 283* Anti-replay 284* Tunnel mode 285* Transport mode 286* UDP Encapsulation 287 288AEAD algorithms 289+++++++++++++++ 290 291* AES-128/192/256-GCM 292 293Cipher algorithms 294+++++++++++++++++ 295 296* NULL 297* AES-128/192/256-CBC 298* AES-128/192/256-CTR 299 300Auth algorithms 301+++++++++++++++ 302 303* NULL 304* SHA1-HMAC 305* SHA256-128-HMAC 306* SHA384-192-HMAC 307* SHA512-256-HMAC 308* AES-XCBC-96 309