doc/guides/cryptodevs/octeontx.rst

   1 .. SPDX-License-Identifier: BSD-3-Clause
   2    Copyright(c) 2018 Cavium, Inc
   3
   4 Cavium OCTEON TX Crypto Poll Mode Driver
   5 ========================================
   6
   7 The OCTEON TX crypto poll mode driver provides support for offloading
   8 cryptographic operations to cryptographic accelerator units on
   9 **OCTEON TX** :sup:`®` family of processors (CN8XXX). The OCTEON TX crypto
  10 poll mode driver enqueues the crypto request to this accelerator and dequeues
  11 the response once the operation is completed.
  12
  13 Supported Symmetric Crypto Algorithms
  14 -------------------------------------
  15
  16 Cipher Algorithms
  17 ~~~~~~~~~~~~~~~~~
  18
  19 * ``RTE_CRYPTO_CIPHER_NULL``
  20 * ``RTE_CRYPTO_CIPHER_3DES_CBC``
  21 * ``RTE_CRYPTO_CIPHER_3DES_ECB``
  22 * ``RTE_CRYPTO_CIPHER_AES_CBC``
  23 * ``RTE_CRYPTO_CIPHER_AES_CTR``
  24 * ``RTE_CRYPTO_CIPHER_AES_XTS``
  25 * ``RTE_CRYPTO_CIPHER_DES_CBC``
  26 * ``RTE_CRYPTO_CIPHER_KASUMI_F8``
  27 * ``RTE_CRYPTO_CIPHER_SNOW3G_UEA2``
  28 * ``RTE_CRYPTO_CIPHER_ZUC_EEA3``
  29
  30 Hash Algorithms
  31 ~~~~~~~~~~~~~~~
  32
  33 * ``RTE_CRYPTO_AUTH_NULL``
  34 * ``RTE_CRYPTO_AUTH_AES_GMAC``
  35 * ``RTE_CRYPTO_AUTH_KASUMI_F9``
  36 * ``RTE_CRYPTO_AUTH_MD5``
  37 * ``RTE_CRYPTO_AUTH_MD5_HMAC``
  38 * ``RTE_CRYPTO_AUTH_SHA1``
  39 * ``RTE_CRYPTO_AUTH_SHA1_HMAC``
  40 * ``RTE_CRYPTO_AUTH_SHA224``
  41 * ``RTE_CRYPTO_AUTH_SHA224_HMAC``
  42 * ``RTE_CRYPTO_AUTH_SHA256``
  43 * ``RTE_CRYPTO_AUTH_SHA256_HMAC``
  44 * ``RTE_CRYPTO_AUTH_SHA384``
  45 * ``RTE_CRYPTO_AUTH_SHA384_HMAC``
  46 * ``RTE_CRYPTO_AUTH_SHA512``
  47 * ``RTE_CRYPTO_AUTH_SHA512_HMAC``
  48 * ``RTE_CRYPTO_AUTH_SNOW3G_UIA2``
  49 * ``RTE_CRYPTO_AUTH_ZUC_EIA3``
  50
  51 AEAD Algorithms
  52 ~~~~~~~~~~~~~~~
  53
  54 * ``RTE_CRYPTO_AEAD_AES_GCM``
  55
  56 Supported Asymmetric Crypto Algorithms
  57 --------------------------------------
  58
  59 * ``RTE_CRYPTO_ASYM_XFORM_RSA``
  60 * ``RTE_CRYPTO_ASYM_XFORM_MODEX``
  61
  62 Config flags
  63 ------------
  64
  65 For compiling the OCTEON TX crypto poll mode driver, please check if the
  66 CONFIG_RTE_LIBRTE_PMD_OCTEONTX_CRYPTO setting is set to `y` in
  67 config/common_base file.
  68
  69 * ``CONFIG_RTE_LIBRTE_PMD_OCTEONTX_CRYPTO=y``
  70
  71 Compilation
  72 -----------
  73
  74 The OCTEON TX crypto poll mode driver can be compiled either natively on
  75 **OCTEON TX** :sup:`®` board or cross-compiled on an x86 based platform.
  76
  77 Refer :doc:`../platform/octeontx` for details about setting up the platform
  78 and building DPDK applications.
  79
  80 .. note::
  81
  82    OCTEON TX crypto PF driver needs microcode to be available at `/lib/firmware/` directory.
  83    Refer SDK documents for further information.
  84
  85 SDK and related information can be obtained from: `Cavium support site <https://support.cavium.com/>`_.
  86
  87 Execution
  88 ---------
  89
  90 The number of crypto VFs to be enabled can be controlled by setting sysfs entry,
  91 `sriov_numvfs`, for the corresponding PF driver.
  92
  93 .. code-block:: console
  94
  95         echo <num_vfs> > /sys/bus/pci/devices/<dev_bus_id>/sriov_numvfs
  96
  97 The device bus ID, `dev_bus_id`, to be used in the above step can be found out
  98 by using dpdk-devbind.py script. The OCTEON TX crypto PF device need to be
  99 identified and the corresponding device number can be used to tune various PF
 100 properties.
 101
 102
 103 Once the required VFs are enabled, dpdk-devbind.py script can be used to
 104 identify the VFs. To be accessible from DPDK, VFs need to be bound to vfio-pci
 105 driver:
 106
 107 .. code-block:: console
 108
 109         cd <dpdk directory>
 110         ./usertools/dpdk-devbind.py -u <vf device no>
 111         ./usertools/dpdk-devbind.py -b vfio-pci <vf device no>
 112
 113 Appropriate huge page need to be setup in order to run the DPDK example
 114 applications.
 115
 116 .. code-block:: console
 117
 118         echo 8 > /sys/kernel/mm/hugepages/hugepages-524288kB/nr_hugepages
 119         mkdir /mnt/huge
 120         mount -t hugetlbfs nodev /mnt/huge
 121
 122 Example applications can now be executed with crypto operations offloaded to
 123 OCTEON TX crypto PMD.
 124
 125 .. code-block:: console
 126
 127         ./build/ipsec-secgw --log-level=8 -c 0xff -- -P -p 0x3 -u 0x2 --config
 128         "(1,0,0),(0,0,0)" -f ep1.cfg
 129
 130 Testing
 131 -------
 132
 133 The symmetric crypto operations on OCTEON TX crypto PMD may be verified by running the test
 134 application:
 135
 136 .. code-block:: console
 137
 138         ./test
 139         RTE>>cryptodev_octeontx_autotest
 140
 141 The asymmetric crypto operations on OCTEON TX crypto PMD may be verified by running the test
 142 application:
 143
 144 .. code-block:: console
 145
 146         ./test
 147         RTE>>cryptodev_octeontx_asym_autotest