1..  SPDX-License-Identifier: BSD-3-Clause
2    Copyright(c) 2019 Marvell International Ltd.
3
4
5Marvell OCTEON TX2 Crypto Poll Mode Driver
6==========================================
7
8The OCTEON TX2 crypto poll mode driver provides support for offloading
9cryptographic operations to cryptographic accelerator units on the
10**OCTEON TX2** :sup:`®` family of processors (CN9XXX).
11
12More information about OCTEON TX2 SoCs may be obtained from `<https://www.marvell.com>`_
13
14Features
15--------
16
17The OCTEON TX2 crypto PMD has support for:
18
19Symmetric Crypto Algorithms
20~~~~~~~~~~~~~~~~~~~~~~~~~~~
21
22Cipher 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
35Hash 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
55AEAD algorithms:
56
57* ``RTE_CRYPTO_AEAD_AES_GCM``
58* ``RTE_CRYPTO_AEAD_CHACHA20_POLY1305``
59
60Asymmetric Crypto Algorithms
61~~~~~~~~~~~~~~~~~~~~~~~~~~~~
62
63* ``RTE_CRYPTO_ASYM_XFORM_RSA``
64* ``RTE_CRYPTO_ASYM_XFORM_MODEX``
65
66
67Installation
68------------
69
70The OCTEON TX2 crypto PMD may be compiled natively on an OCTEON TX2 platform or
71cross-compiled on an x86 platform.
72
73Refer to :doc:`../platform/octeontx2` for instructions to build your DPDK
74application.
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
81Initialization
82--------------
83
84List 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
96Set ``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
102Bind 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
110Another 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
126Debugging 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
139Testing
140-------
141
142The symmetric crypto operations on OCTEON TX2 crypto PMD may be verified by running the test
143application:
144
145.. code-block:: console
146
147    ./dpdk-test
148    RTE>>cryptodev_octeontx2_autotest
149
150The asymmetric crypto operations on OCTEON TX2 crypto PMD may be verified by running the test
151application:
152
153.. code-block:: console
154
155    ./dpdk-test
156    RTE>>cryptodev_octeontx2_asym_autotest
157
158
159Lookaside IPsec Support
160-----------------------
161
162The OCTEON TX2 SoC can accelerate IPsec traffic in lookaside protocol mode,
163with its **cryptographic accelerator (CPT)**. ``OCTEON TX2 crypto PMD`` implements
164this as an ``RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL`` offload.
165
166Refer to :doc:`../prog_guide/rte_security` for more details on protocol offloads.
167
168This feature can be tested with ipsec-secgw sample application.
169
170
171Features supported
172~~~~~~~~~~~~~~~~~~
173
174* IPv4
175* IPv6
176* ESP
177* Tunnel mode
178* AES-128/192/256-GCM
179