doc/guides/cryptodevs/octeontx2.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2019 Marvell International Ltd.
   3
   4
   5 Marvell OCTEON TX2 Crypto Poll Mode Driver
   6 ==========================================
   7
   8 The OCTEON TX2 crypto poll mode driver provides support for offloading
   9 cryptographic operations to cryptographic accelerator units on the
  10 **OCTEON TX2** :sup:`®` family of processors (CN9XXX).
  11
  12 More information about OCTEON TX2 SoCs may be obtained from `<https://www.marvell.com>`_
  13
  14 Features
  15 --------
  16
  17 The OCTEON TX2 crypto PMD has support for:
  18
  19 Symmetric Crypto Algorithms
  20 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  21
  22 Cipher algorithms:
  23
  24 * ``RTE_CRYPTO_CIPHER_NULL``
  25 * ``RTE_CRYPTO_CIPHER_3DES_CBC``
  26 * ``RTE_CRYPTO_CIPHER_3DES_ECB``
  27 * ``RTE_CRYPTO_CIPHER_AES_CBC``
  28 * ``RTE_CRYPTO_CIPHER_AES_CTR``
  29 * ``RTE_CRYPTO_CIPHER_AES_XTS``
  30 * ``RTE_CRYPTO_CIPHER_DES_CBC``
  31 * ``RTE_CRYPTO_CIPHER_KASUMI_F8``
  32 * ``RTE_CRYPTO_CIPHER_SNOW3G_UEA2``
  33 * ``RTE_CRYPTO_CIPHER_ZUC_EEA3``
  34
  35 Hash algorithms:
  36
  37 * ``RTE_CRYPTO_AUTH_NULL``
  38 * ``RTE_CRYPTO_AUTH_AES_GMAC``
  39 * ``RTE_CRYPTO_AUTH_KASUMI_F9``
  40 * ``RTE_CRYPTO_AUTH_MD5``
  41 * ``RTE_CRYPTO_AUTH_MD5_HMAC``
  42 * ``RTE_CRYPTO_AUTH_SHA1``
  43 * ``RTE_CRYPTO_AUTH_SHA1_HMAC``
  44 * ``RTE_CRYPTO_AUTH_SHA224``
  45 * ``RTE_CRYPTO_AUTH_SHA224_HMAC``
  46 * ``RTE_CRYPTO_AUTH_SHA256``
  47 * ``RTE_CRYPTO_AUTH_SHA256_HMAC``
  48 * ``RTE_CRYPTO_AUTH_SHA384``
  49 * ``RTE_CRYPTO_AUTH_SHA384_HMAC``
  50 * ``RTE_CRYPTO_AUTH_SHA512``
  51 * ``RTE_CRYPTO_AUTH_SHA512_HMAC``
  52 * ``RTE_CRYPTO_AUTH_SNOW3G_UIA2``
  53 * ``RTE_CRYPTO_AUTH_ZUC_EIA3``
  54
  55 AEAD algorithms:
  56
  57 * ``RTE_CRYPTO_AEAD_AES_GCM``
  58 * ``RTE_CRYPTO_AEAD_CHACHA20_POLY1305``
  59
  60 Asymmetric Crypto Algorithms
  61 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  62
  63 * ``RTE_CRYPTO_ASYM_XFORM_RSA``
  64 * ``RTE_CRYPTO_ASYM_XFORM_MODEX``
  65
  66
  67 Installation
  68 ------------
  69
  70 The OCTEON TX2 crypto PMD may be compiled natively on an OCTEON TX2 platform or
  71 cross-compiled on an x86 platform.
  72
  73 Refer to :doc:`../platform/octeontx2` for instructions to build your DPDK
  74 application.
  75
  76 .. note::
  77
  78    The OCTEON TX2 crypto PMD uses services from the kernel mode OCTEON TX2
  79    crypto PF driver in linux. This driver is included in the OCTEON TX SDK.
  80
  81 Initialization
  82 --------------
  83
  84 List the CPT PF devices available on your OCTEON TX2 platform:
  85
  86 .. code-block:: console
  87
  88     lspci -d:a0fd
  89
  90 ``a0fd`` is the CPT PF device id. You should see output similar to:
  91
  92 .. code-block:: console
  93
  94     0002:10:00.0 Class 1080: Device 177d:a0fd
  95
  96 Set ``sriov_numvfs`` on the CPT PF device, to create a VF:
  97
  98 .. code-block:: console
  99
 100     echo 1 > /sys/bus/pci/drivers/octeontx2-cpt/0002:10:00.0/sriov_numvfs
 101
 102 Bind the CPT VF device to the vfio_pci driver:
 103
 104 .. code-block:: console
 105
 106     echo '177d a0fe' > /sys/bus/pci/drivers/vfio-pci/new_id
 107     echo 0002:10:00.1 > /sys/bus/pci/devices/0002:10:00.1/driver/unbind
 108     echo 0002:10:00.1 > /sys/bus/pci/drivers/vfio-pci/bind
 109
 110 Another way to bind the VF would be to use the ``dpdk-devbind.py`` script:
 111
 112 .. code-block:: console
 113
 114     cd <dpdk directory>
 115     ./usertools/dpdk-devbind.py -u 0002:10:00.1
 116     ./usertools/dpdk-devbind.py -b vfio-pci 0002:10.00.1
 117
 118 .. note::
 119
 120     * For CN98xx SoC, it is recommended to use even and odd DBDF VFs to achieve
 121       higher performance as even VF uses one crypto engine and odd one uses
 122       another crypto engine.
 123
 124     * Ensure that sufficient huge pages are available for your application::
 125
 126          dpdk-hugepages.py --setup 4G --pagesize 512M
 127
 128       Refer to :ref:`linux_gsg_hugepages` for more details.
 129
 130 Debugging Options
 131 -----------------
 132
 133 .. _table_octeontx2_crypto_debug_options:
 134
 135 .. table:: OCTEON TX2 crypto PMD debug options
 136
 137     +---+------------+-------------------------------------------------------+
 138     | # | Component  | EAL log command                                       |
 139     +===+============+=======================================================+
 140     | 1 | CPT        | --log-level='pmd\.crypto\.octeontx2,8'                |
 141     +---+------------+-------------------------------------------------------+
 142
 143 Testing
 144 -------
 145
 146 The symmetric crypto operations on OCTEON TX2 crypto PMD may be verified by running the test
 147 application:
 148
 149 .. code-block:: console
 150
 151     ./dpdk-test
 152     RTE>>cryptodev_octeontx2_autotest
 153
 154 The asymmetric crypto operations on OCTEON TX2 crypto PMD may be verified by running the test
 155 application:
 156
 157 .. code-block:: console
 158
 159     ./dpdk-test
 160     RTE>>cryptodev_octeontx2_asym_autotest
 161
 162
 163 Lookaside IPsec Support
 164 -----------------------
 165
 166 The OCTEON TX2 SoC can accelerate IPsec traffic in lookaside protocol mode,
 167 with its **cryptographic accelerator (CPT)**. ``OCTEON TX2 crypto PMD`` implements
 168 this as an ``RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL`` offload.
 169
 170 Refer to :doc:`../prog_guide/rte_security` for more details on protocol offloads.
 171
 172 This feature can be tested with ipsec-secgw sample application.
 173
 174
 175 Features supported
 176 ~~~~~~~~~~~~~~~~~~
 177
 178 * IPv4
 179 * IPv6
 180 * ESP
 181 * Tunnel mode
 182 * Transport mode(IPv4)
 183 * ESN
 184 * Anti-replay
 185 * UDP Encapsulation
 186 * AES-128/192/256-GCM
 187 * AES-128/192/256-CBC-SHA1-HMAC
 188 * AES-128/192/256-CBC-SHA256-128-HMAC
 189
 190 Limitations
 191 -----------
 192
 193 Multiple lcores may not operate on the same crypto queue pair. The lcore that
 194 enqueues to a queue pair is the one that must dequeue from it.