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     Ensure that sufficient huge pages are available for your application::
 121
 122         echo 8 > /sys/kernel/mm/hugepages/hugepages-524288kB/nr_hugepages
 123
 124     Refer to :ref:`linux_gsg_hugepages` for more details.
 125
 126 Debugging Options
 127 -----------------
 128
 129 .. _table_octeontx2_crypto_debug_options:
 130
 131 .. table:: OCTEON TX2 crypto PMD debug options
 132
 133     +---+------------+-------------------------------------------------------+
 134     | # | Component  | EAL log command                                       |
 135     +===+============+=======================================================+
 136     | 1 | CPT        | --log-level='pmd\.crypto\.octeontx2,8'                |
 137     +---+------------+-------------------------------------------------------+
 138
 139 Testing
 140 -------
 141
 142 The symmetric crypto operations on OCTEON TX2 crypto PMD may be verified by running the test
 143 application:
 144
 145 .. code-block:: console
 146
 147     ./dpdk-test
 148     RTE>>cryptodev_octeontx2_autotest
 149
 150 The asymmetric crypto operations on OCTEON TX2 crypto PMD may be verified by running the test
 151 application:
 152
 153 .. code-block:: console
 154
 155     ./dpdk-test
 156     RTE>>cryptodev_octeontx2_asym_autotest
 157
 158
 159 Lookaside IPsec Support
 160 -----------------------
 161
 162 The OCTEON TX2 SoC can accelerate IPsec traffic in lookaside protocol mode,
 163 with its **cryptographic accelerator (CPT)**. ``OCTEON TX2 crypto PMD`` implements
 164 this as an ``RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL`` offload.
 165
 166 Refer to :doc:`../prog_guide/rte_security` for more details on protocol offloads.
 167
 168 This feature can be tested with ipsec-secgw sample application.
 169
 170
 171 Features supported
 172 ~~~~~~~~~~~~~~~~~~
 173
 174 * IPv4
 175 * IPv6
 176 * ESP
 177 * Tunnel mode
 178 * AES-128/192/256-GCM