xref: /dpdk/doc/guides/cryptodevs/cnxk.rst (revision d38febb08d57fec29fed27a2d12a507fc6fcdfa1) 
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
161Debugging Options
162-----------------
163
164.. _table_octeon_cnxk_crypto_debug_options:
165
166.. table:: OCTEON cnxk crypto PMD debug options
167
168    +---+------------+-------------------------------------------------------+
169    | # | Component  | EAL log command                                       |
170    +===+============+=======================================================+
171    | 1 | CPT        | --log-level='pmd\.crypto\.cnxk,8'                     |
172    +---+------------+-------------------------------------------------------+
173
174Testing
175-------
176
177The symmetric crypto operations on OCTEON cnxk crypto PMD may be verified by
178running the test application:
179
180``CN9K``
181
182.. code-block:: console
183
184    ./dpdk-test
185    RTE>>cryptodev_cn9k_autotest
186
187``CN10K``
188
189.. code-block:: console
190
191    ./dpdk-test
192    RTE>>cryptodev_cn10k_autotest
193
194The asymmetric crypto operations on OCTEON cnxk crypto PMD may be verified by
195running the test application:
196
197``CN9K``
198
199.. code-block:: console
200
201    ./dpdk-test
202    RTE>>cryptodev_cn9k_asym_autotest
203
204``CN10K``
205
206.. code-block:: console
207
208    ./dpdk-test
209    RTE>>cryptodev_cn10k_asym_autotest
210
211Lookaside IPsec Support
212-----------------------
213
214The OCTEON cnxk SoCs can accelerate IPsec traffic in lookaside protocol mode,
215with its **cryptographic accelerator (CPT)**. ``OCTEON cnxk crypto PMD`` implements
216this as an ``RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL`` offload.
217
218Refer to :doc:`../prog_guide/rte_security` for more details on protocol offloads.
219
220This feature can be tested with ipsec-secgw sample application.
221
222Supported OCTEON cnxk SoCs
223~~~~~~~~~~~~~~~~~~~~~~~~~~
224
225- CN9XX
226- CN10XX
227
228CN9XX Features supported
229~~~~~~~~~~~~~~~~~~~~~~~~
230
231* IPv4
232* ESP
233* Tunnel mode
234* UDP Encapsulation
235* AES-128/192/256-GCM
236
237CN10XX Features supported
238~~~~~~~~~~~~~~~~~~~~~~~~~
239
240* IPv4
241* ESP
242* Tunnel mode
243* Transport mode
244* UDP Encapsulation
245* AES-128/192/256-GCM
246* AES-128/192/256-CBC-SHA1-HMAC
247
248Limitations
249-----------
250
251Multiple lcores may not operate on the same crypto queue pair. The lcore that
252enqueues to a queue pair is the one that must dequeue from it.
253