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