xref: /dpdk/doc/guides/cryptodevs/cnxk.rst (revision ba62b473f09a93361d96e03fb6bb1b43ffdf6e9a) 
1.. SPDX-License-Identifier: BSD-3-Clause
2   Copyright(c) 2021 Marvell.
3
4Marvell cnxk Crypto Poll Mode Driver
5====================================
6
7The cnxk crypto poll mode driver provides support for offloading
8cryptographic operations to cryptographic accelerator units on the
9**Marvell OCTEON cnxk** SoC family.
10
11The cnxk crypto PMD code is organized into different sets of files.
12The file names starting with cn9k and cn10k provides support for CN9XX
13and CN10XX respectively. The common code between the SoCs is present
14in file names starting with cnxk.
15
16More information about OCTEON cnxk SoCs may be obtained from `<https://www.marvell.com>`_
17
18Supported OCTEON cnxk SoCs
19--------------------------
20
21- CN9XX
22- CN10XX
23
24Features
25--------
26
27The OCTEON cnxk crypto PMD has support for:
28
29Symmetric Crypto Algorithms
30~~~~~~~~~~~~~~~~~~~~~~~~~~~
31
32Cipher algorithms:
33
34* ``RTE_CRYPTO_CIPHER_NULL``
35* ``RTE_CRYPTO_CIPHER_3DES_CBC``
36* ``RTE_CRYPTO_CIPHER_3DES_ECB``
37* ``RTE_CRYPTO_CIPHER_AES_CBC``
38* ``RTE_CRYPTO_CIPHER_AES_CTR``
39* ``RTE_CRYPTO_CIPHER_AES_XTS``
40* ``RTE_CRYPTO_CIPHER_DES_CBC``
41* ``RTE_CRYPTO_CIPHER_KASUMI_F8``
42* ``RTE_CRYPTO_CIPHER_SNOW3G_UEA2``
43* ``RTE_CRYPTO_CIPHER_ZUC_EEA3``
44
45Hash algorithms:
46
47* ``RTE_CRYPTO_AUTH_NULL``
48* ``RTE_CRYPTO_AUTH_AES_GMAC``
49* ``RTE_CRYPTO_AUTH_KASUMI_F9``
50* ``RTE_CRYPTO_AUTH_MD5``
51* ``RTE_CRYPTO_AUTH_MD5_HMAC``
52* ``RTE_CRYPTO_AUTH_SHA1``
53* ``RTE_CRYPTO_AUTH_SHA1_HMAC``
54* ``RTE_CRYPTO_AUTH_SHA224``
55* ``RTE_CRYPTO_AUTH_SHA224_HMAC``
56* ``RTE_CRYPTO_AUTH_SHA256``
57* ``RTE_CRYPTO_AUTH_SHA256_HMAC``
58* ``RTE_CRYPTO_AUTH_SHA384``
59* ``RTE_CRYPTO_AUTH_SHA384_HMAC``
60* ``RTE_CRYPTO_AUTH_SHA512``
61* ``RTE_CRYPTO_AUTH_SHA512_HMAC``
62* ``RTE_CRYPTO_AUTH_SNOW3G_UIA2``
63* ``RTE_CRYPTO_AUTH_ZUC_EIA3``
64
65AEAD algorithms:
66
67* ``RTE_CRYPTO_AEAD_AES_GCM``
68* ``RTE_CRYPTO_AEAD_CHACHA20_POLY1305``
69
70Asymmetric Crypto Algorithms
71~~~~~~~~~~~~~~~~~~~~~~~~~~~~
72
73* ``RTE_CRYPTO_ASYM_XFORM_RSA``
74* ``RTE_CRYPTO_ASYM_XFORM_MODEX``
75
76Installation
77------------
78
79The OCTEON cnxk crypto PMD may be compiled natively on an OCTEON cnxk platform
80or cross-compiled on an x86 platform.
81
82Refer to :doc:`../platform/cnxk` for instructions to build your DPDK
83application.
84
85.. note::
86
87   The OCTEON cnxk crypto PMD uses services from the kernel mode OCTEON cnxk
88   crypto PF driver in linux. This driver is included in the OCTEON TX SDK.
89
90Initialization
91--------------
92
93``CN9K Initialization``
94
95List the CPT PF devices available on cn9k platform:
96
97.. code-block:: console
98
99    lspci -d:a0fd
100
101``a0fd`` is the CPT PF device id. You should see output similar to:
102
103.. code-block:: console
104
105    0002:10:00.0 Class 1080: Device 177d:a0fd
106
107Set ``sriov_numvfs`` on the CPT PF device, to create a VF:
108
109.. code-block:: console
110
111    echo 1 > /sys/bus/pci/devices/0002:10:00.0/sriov_numvfs
112
113Bind the CPT VF device to the vfio_pci driver:
114
115.. code-block:: console
116
117    cd <dpdk directory>
118    ./usertools/dpdk-devbind.py -u 0002:10:00.1
119    ./usertools/dpdk-devbind.py -b vfio-pci 0002:10.00.1
120
121.. note::
122
123    * For CN98xx SoC, it is recommended to use even and odd DBDF VFs to achieve
124      higher performance as even VF uses one crypto engine and odd one uses
125      another crypto engine.
126
127    * Ensure that sufficient huge pages are available for your application::
128
129         dpdk-hugepages.py --setup 4G --pagesize 512M
130
131      Refer to :ref:`linux_gsg_hugepages` for more details.
132
133``CN10K Initialization``
134
135List the CPT PF devices available on cn10k platform:
136
137.. code-block:: console
138
139    lspci -d:a0f2
140
141``a0f2`` is the CPT PF device id. You should see output similar to:
142
143.. code-block:: console
144
145    0002:20:00.0 Class 1080: Device 177d:a0f2
146
147Set ``sriov_numvfs`` on the CPT PF device, to create a VF:
148
149.. code-block:: console
150
151    echo 1 > /sys/bus/pci/devices/0002:20:00.0/sriov_numvfs
152
153Bind the CPT VF device to the vfio_pci driver:
154
155.. code-block:: console
156
157    cd <dpdk directory>
158    ./usertools/dpdk-devbind.py -u 0002:20:00.1
159    ./usertools/dpdk-devbind.py -b vfio-pci 0002:20:00.1
160
161Runtime Config Options
162----------------------
163
164- ``Maximum queue pairs limit`` (default ``63``)
165
166   The number of maximum queue pairs supported by the device, can be limited
167   during runtime by using ``max_qps_limit`` ``devargs`` parameter.
168
169   For example::
170
171      -a 0002:20:00.1,max_qps_limit=4
172
173   With the above configuration, the number of maximum queue pairs supported
174   by the device is limited to 4.
175
176Debugging Options
177-----------------
178
179.. _table_octeon_cnxk_crypto_debug_options:
180
181.. table:: OCTEON cnxk crypto PMD debug options
182
183    +---+------------+-------------------------------------------------------+
184    | # | Component  | EAL log command                                       |
185    +===+============+=======================================================+
186    | 1 | CPT        | --log-level='pmd\.crypto\.cnxk,8'                     |
187    +---+------------+-------------------------------------------------------+
188
189Testing
190-------
191
192The symmetric crypto operations on OCTEON cnxk crypto PMD may be verified by
193running the test application:
194
195``CN9K``
196
197.. code-block:: console
198
199    ./dpdk-test
200    RTE>>cryptodev_cn9k_autotest
201
202``CN10K``
203
204.. code-block:: console
205
206    ./dpdk-test
207    RTE>>cryptodev_cn10k_autotest
208
209The asymmetric crypto operations on OCTEON cnxk crypto PMD may be verified by
210running the test application:
211
212``CN9K``
213
214.. code-block:: console
215
216    ./dpdk-test
217    RTE>>cryptodev_cn9k_asym_autotest
218
219``CN10K``
220
221.. code-block:: console
222
223    ./dpdk-test
224    RTE>>cryptodev_cn10k_asym_autotest
225
226Lookaside IPsec Support
227-----------------------
228
229The OCTEON cnxk SoCs can accelerate IPsec traffic in lookaside protocol mode,
230with its **cryptographic accelerator (CPT)**. ``OCTEON cnxk crypto PMD`` implements
231this as an ``RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL`` offload.
232
233Refer to :doc:`../prog_guide/rte_security` for more details on protocol offloads.
234
235This feature can be tested with ipsec-secgw sample application.
236
237Supported OCTEON cnxk SoCs
238~~~~~~~~~~~~~~~~~~~~~~~~~~
239
240- CN9XX
241- CN10XX
242
243CN9XX Features supported
244~~~~~~~~~~~~~~~~~~~~~~~~
245
246* IPv4
247* IPv6
248* ESP
249* Tunnel mode
250* Transport mode(IPv4)
251* UDP Encapsulation
252* AES-128/192/256-GCM
253* AES-128/192/256-CBC-SHA1-HMAC
254* AES-128/192/256-CBC-SHA256-128-HMAC
255* ESN
256* Anti-replay
257
258CN10XX Features supported
259~~~~~~~~~~~~~~~~~~~~~~~~~
260
261* IPv4
262* ESP
263* Tunnel mode
264* Transport mode
265* UDP Encapsulation
266* AES-128/192/256-GCM
267* AES-128/192/256-CBC-NULL
268* AES-128/192/256-CBC-SHA1-HMAC
269