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 Compilation
  57 -----------
  58
  59 The **OCTEON TX** :sup:`®` board must be running the linux kernel based on
  60 sdk-6.2.0 patch 3. In this, the OCTEON TX crypto PF driver is already built in.
  61
  62 For compiling the OCTEON TX crypto poll mode driver, please check if the
  63 CONFIG_RTE_LIBRTE_PMD_OCTEONTX_CRYPTO setting is set to `y` in
  64 config/common_base file.
  65
  66 * ``CONFIG_RTE_LIBRTE_PMD_OCTEONTX_CRYPTO=y``
  67
  68 The following are the steps to compile the OCTEON TX crypto poll mode driver:
  69
  70 .. code-block:: console
  71
  72         cd <dpdk directory>
  73         make config T=arm64-thunderx-linuxapp-gcc
  74         make
  75
  76 The example applications can be compiled using the following:
  77
  78 .. code-block:: console
  79
  80         cd <dpdk directory>
  81         export RTE_SDK=$PWD
  82         export RTE_TARGET=build
  83         cd examples/<application>
  84         make
  85
  86 Execution
  87 ---------
  88
  89 The number of crypto VFs to be enabled can be controlled by setting sysfs entry,
  90 `sriov_numvfs`, for the corresponding PF driver.
  91
  92 .. code-block:: console
  93
  94         echo <num_vfs> > /sys/bus/pci/devices/<dev_bus_id>/sriov_numvfs
  95
  96 The device bus ID, `dev_bus_id`, to be used in the above step can be found out
  97 by using dpdk-devbind.py script. The OCTEON TX crypto PF device need to be
  98 identified and the corresponding device number can be used to tune various PF
  99 properties.
 100
 101
 102 Once the required VFs are enabled, dpdk-devbind.py script can be used to
 103 identify the VFs. To be accessible from DPDK, VFs need to be bound to vfio-pci
 104 driver:
 105
 106 .. code-block:: console
 107
 108         cd <dpdk directory>
 109         ./usertools/dpdk-devbind.py -u <vf device no>
 110         ./usertools/dpdk-devbind.py -b vfio-pci <vf device no>
 111
 112 Appropriate huge page need to be setup in order to run the DPDK example
 113 applications.
 114
 115 .. code-block:: console
 116
 117         echo 8 > /sys/kernel/mm/hugepages/hugepages-524288kB/nr_hugepages
 118         mkdir /mnt/huge
 119         mount -t hugetlbfs nodev /mnt/huge
 120
 121 Example applications can now be executed with crypto operations offloaded to
 122 OCTEON TX crypto PMD.
 123
 124 .. code-block:: console
 125
 126         ./build/ipsec-secgw --log-level=8 -c 0xff -- -P -p 0x3 -u 0x2 --config
 127         "(1,0,0),(0,0,0)" -f ep1.cfg