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 Enable OCTEON TX2 crypto PMD in your config file:
  74
  75 * ``CONFIG_RTE_LIBRTE_PMD_OCTEONTX2_CRYPTO=y``
  76
  77 Refer to :doc:`../platform/octeontx2` for instructions to build your DPDK
  78 application.
  79
  80 .. note::
  81
  82    The OCTEON TX2 crypto PMD uses services from the kernel mode OCTEON TX2
  83    crypto PF driver in linux. This driver is included in the OCTEON TX SDK.
  84
  85 Initialization
  86 --------------
  87
  88 List the CPT PF devices available on your OCTEON TX2 platform:
  89
  90 .. code-block:: console
  91
  92     lspci -d:a0fd
  93
  94 ``a0fd`` is the CPT PF device id. You should see output similar to:
  95
  96 .. code-block:: console
  97
  98     0002:10:00.0 Class 1080: Device 177d:a0fd
  99
 100 Set ``sriov_numvfs`` on the CPT PF device, to create a VF:
 101
 102 .. code-block:: console
 103
 104     echo 1 > /sys/bus/pci/drivers/octeontx2-cpt/0002:10:00.0/sriov_numvfs
 105
 106 Bind the CPT VF device to the vfio_pci driver:
 107
 108 .. code-block:: console
 109
 110     echo '177d a0fe' > /sys/bus/pci/drivers/vfio-pci/new_id
 111     echo 0002:10:00.1 > /sys/bus/pci/devices/0002:10:00.1/driver/unbind
 112     echo 0002:10:00.1 > /sys/bus/pci/drivers/vfio-pci/bind
 113
 114 Another way to bind the VF would be to use the ``dpdk-devbind.py`` script:
 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     Ensure that sufficient huge pages are available for your application::
 125
 126         echo 8 > /sys/kernel/mm/hugepages/hugepages-524288kB/nr_hugepages
 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     ./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     ./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 * AES-128/192/256-GCM