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 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 Config flags
  57 ------------
  58
  59 For compiling the OCTEON TX crypto poll mode driver, please check if the
  60 CONFIG_RTE_LIBRTE_PMD_OCTEONTX_CRYPTO setting is set to `y` in
  61 config/common_base file.
  62
  63 * ``CONFIG_RTE_LIBRTE_PMD_OCTEONTX_CRYPTO=y``
  64
  65 Compilation
  66 -----------
  67
  68 The OCTEON TX crypto poll mode driver can be compiled either natively on
  69 **OCTEON TX** :sup:`®` board or cross-compiled on an x86 based platform.
  70
  71 Refer :doc:`../platform/octeontx` for details about setting up the platform
  72 and building DPDK applications.
  73
  74 .. note::
  75
  76    OCTEON TX crypto PF driver needs microcode to be available at `/lib/firmware/` directory.
  77    Refer SDK documents for further information.
  78
  79 SDK and related information can be obtained from: `Cavium support site <https://support.cavium.com/>`_.
  80
  81 Execution
  82 ---------
  83
  84 The number of crypto VFs to be enabled can be controlled by setting sysfs entry,
  85 `sriov_numvfs`, for the corresponding PF driver.
  86
  87 .. code-block:: console
  88
  89         echo <num_vfs> > /sys/bus/pci/devices/<dev_bus_id>/sriov_numvfs
  90
  91 The device bus ID, `dev_bus_id`, to be used in the above step can be found out
  92 by using dpdk-devbind.py script. The OCTEON TX crypto PF device need to be
  93 identified and the corresponding device number can be used to tune various PF
  94 properties.
  95
  96
  97 Once the required VFs are enabled, dpdk-devbind.py script can be used to
  98 identify the VFs. To be accessible from DPDK, VFs need to be bound to vfio-pci
  99 driver:
 100
 101 .. code-block:: console
 102
 103         cd <dpdk directory>
 104         ./usertools/dpdk-devbind.py -u <vf device no>
 105         ./usertools/dpdk-devbind.py -b vfio-pci <vf device no>
 106
 107 Appropriate huge page need to be setup in order to run the DPDK example
 108 applications.
 109
 110 .. code-block:: console
 111
 112         echo 8 > /sys/kernel/mm/hugepages/hugepages-524288kB/nr_hugepages
 113         mkdir /mnt/huge
 114         mount -t hugetlbfs nodev /mnt/huge
 115
 116 Example applications can now be executed with crypto operations offloaded to
 117 OCTEON TX crypto PMD.
 118
 119 .. code-block:: console
 120
 121         ./build/ipsec-secgw --log-level=8 -c 0xff -- -P -p 0x3 -u 0x2 --config
 122         "(1,0,0),(0,0,0)" -f ep1.cfg