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
  63 Compilation
  64 -----------
  65
  66 The OCTEON TX crypto poll mode driver can be compiled either natively on
  67 **OCTEON TX** :sup:`®` board or cross-compiled on an x86 based platform.
  68
  69 Refer :doc:`../platform/octeontx` for details about setting up the platform
  70 and building DPDK applications.
  71
  72 .. note::
  73
  74    OCTEON TX crypto PF driver needs microcode to be available at `/lib/firmware/` directory.
  75    Refer SDK documents for further information.
  76
  77 SDK and related information can be obtained from: `Cavium support site <https://support.cavium.com/>`_.
  78
  79 Execution
  80 ---------
  81
  82 The number of crypto VFs to be enabled can be controlled by setting sysfs entry,
  83 `sriov_numvfs`, for the corresponding PF driver.
  84
  85 .. code-block:: console
  86
  87         echo <num_vfs> > /sys/bus/pci/devices/<dev_bus_id>/sriov_numvfs
  88
  89 The device bus ID, `dev_bus_id`, to be used in the above step can be found out
  90 by using dpdk-devbind.py script. The OCTEON TX crypto PF device need to be
  91 identified and the corresponding device number can be used to tune various PF
  92 properties.
  93
  94
  95 Once the required VFs are enabled, dpdk-devbind.py script can be used to
  96 identify the VFs. To be accessible from DPDK, VFs need to be bound to vfio-pci
  97 driver:
  98
  99 .. code-block:: console
 100
 101         cd <dpdk directory>
 102         ./usertools/dpdk-devbind.py -u <vf device no>
 103         ./usertools/dpdk-devbind.py -b vfio-pci <vf device no>
 104
 105 Appropriate huge page need to be setup in order to run the DPDK example
 106 applications.
 107
 108 .. code-block:: console
 109
 110    dpdk-hugepages.py --setup 4G --pagesize 512M
 111
 112 Example applications can now be executed with crypto operations offloaded to
 113 OCTEON TX crypto PMD.
 114
 115 .. code-block:: console
 116
 117         ./build/ipsec-secgw --log-level=8 -c 0xff -- -P -p 0x3 -u 0x2 --config
 118         "(1,0,0),(0,0,0)" -f ep1.cfg
 119
 120 Testing
 121 -------
 122
 123 The symmetric crypto operations on OCTEON TX crypto PMD may be verified by running the test
 124 application:
 125
 126 .. code-block:: console
 127
 128         ./dpdk-test
 129         RTE>>cryptodev_octeontx_autotest
 130
 131 The asymmetric crypto operations on OCTEON TX crypto PMD may be verified by running the test
 132 application:
 133
 134 .. code-block:: console
 135
 136         ./dpdk-test
 137         RTE>>cryptodev_octeontx_asym_autotest
 138
 139 Limitations
 140 -----------
 141
 142 Multiple lcores may not operate on the same crypto queue pair. The lcore that
 143 enqueues to a queue pair is the one that must dequeue from it.