app/testpmd: add flow table management
[dpdk.git] / doc / guides / prog_guide / event_crypto_adapter.rst
1 ..  SPDX-License-Identifier: BSD-3-Clause
2     Copyright(c) 2018 Intel Corporation. All rights reserved.
3
4 Event Crypto Adapter Library
5 ============================
6
7 The DPDK :doc:`Eventdev library <eventdev>` provides event driven
8 programming model with features to schedule events.
9 The :doc:`Cryptodev library <cryptodev_lib>` provides an interface to
10 the crypto poll mode drivers which supports different crypto operations.
11 The Event Crypto Adapter is one of the adapter which is intended to
12 bridge between the event device and the crypto device.
13
14 The packet flow from crypto device to the event device can be accomplished
15 using SW and HW based transfer mechanism.
16 The Adapter queries an eventdev PMD to determine which mechanism to be used.
17 The adapter uses an EAL service core function for SW based packet transfer
18 and uses the eventdev PMD functions to configure HW based packet transfer
19 between the crypto device and the event device. The crypto adapter uses a new
20 event type called ``RTE_EVENT_TYPE_CRYPTODEV`` to indicate the event source.
21
22 The application can choose to submit a crypto operation directly to
23 crypto device or send it to the crypto adapter via eventdev based on
24 RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD capability.
25 The first mode is known as the event new(RTE_EVENT_CRYPTO_ADAPTER_OP_NEW)
26 mode and the second as the event forward(RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD)
27 mode. The choice of mode can be specified while creating the adapter.
28 In the former mode, it is an application responsibility to enable ingress
29 packet ordering. In the latter mode, it is the adapter responsibility to
30 enable the ingress packet ordering.
31
32
33 Adapter Mode
34 ------------
35
36 RTE_EVENT_CRYPTO_ADAPTER_OP_NEW mode
37 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
38
39 In the RTE_EVENT_CRYPTO_ADAPTER_OP_NEW mode, application submits crypto
40 operations directly to crypto device. The adapter then dequeues crypto
41 completions from crypto device and enqueues them as events to the event device.
42 This mode does not ensure ingress ordering, if the application directly
43 enqueues to the cryptodev without going through crypto/atomic stage.
44 In this mode, events dequeued from the adapter will be treated as new events.
45 The application needs to specify event information (response information)
46 which is needed to enqueue an event after the crypto operation is completed.
47
48 .. _figure_event_crypto_adapter_op_new:
49
50 .. figure:: img/event_crypto_adapter_op_new.*
51
52    Working model of ``RTE_EVENT_CRYPTO_ADAPTER_OP_NEW`` mode
53
54
55 RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode
56 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
57
58 In the ``RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD`` mode, if the event PMD and crypto
59 PMD supports internal event port
60 (``RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD``), the application should
61 use ``rte_event_crypto_adapter_enqueue()`` API to enqueue crypto operations as
62 events to crypto adapter. If not, application retrieves crypto adapter's event
63 port using ``rte_event_crypto_adapter_event_port_get()`` API, links its event
64 queue to this port and starts enqueuing crypto operations as events to eventdev
65 using ``rte_event_enqueue_burst()``. The adapter then dequeues the events and
66 submits the crypto operations to the cryptodev. After the crypto operation is
67 complete, the adapter enqueues events to the event device. The application can
68 use this mode when ingress packet ordering is needed. In this mode, events
69 dequeued from the adapter will be treated as forwarded events. The application
70 needs to specify the cryptodev ID and queue pair ID (request information) needed
71 to enqueue a crypto operation in addition to the event information (response
72 information) needed to enqueue an event after the crypto operation has
73 completed.
74
75 .. _figure_event_crypto_adapter_op_forward:
76
77 .. figure:: img/event_crypto_adapter_op_forward.*
78
79    Working model of ``RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD`` mode
80
81
82 API Overview
83 ------------
84
85 This section has a brief introduction to the event crypto adapter APIs.
86 The application is expected to create an adapter which is associated with
87 a single eventdev, then add cryptodev and queue pair to the adapter instance.
88
89 Create an adapter instance
90 ~~~~~~~~~~~~~~~~~~~~~~~~~~
91
92 An adapter instance is created using ``rte_event_crypto_adapter_create()``. This
93 function is called with event device to be associated with the adapter and port
94 configuration for the adapter to setup an event port(if the adapter needs to use
95 a service function).
96
97 Adapter can be started in ``RTE_EVENT_CRYPTO_ADAPTER_OP_NEW`` or
98 ``RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD`` mode.
99
100 .. code-block:: c
101
102         int err;
103         uint8_t dev_id, id;
104         struct rte_event_dev_info dev_info;
105         struct rte_event_port_conf conf;
106         enum rte_event_crypto_adapter_mode mode;
107
108         err = rte_event_dev_info_get(id, &dev_info);
109
110         conf.new_event_threshold = dev_info.max_num_events;
111         conf.dequeue_depth = dev_info.max_event_port_dequeue_depth;
112         conf.enqueue_depth = dev_info.max_event_port_enqueue_depth;
113         mode = RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD;
114         err = rte_event_crypto_adapter_create(id, dev_id, &conf, mode);
115
116 If the application desires to have finer control of eventdev port allocation
117 and setup, it can use the ``rte_event_crypto_adapter_create_ext()`` function.
118 The ``rte_event_crypto_adapter_create_ext()`` function is passed as a callback
119 function. The callback function is invoked if the adapter needs to use a
120 service function and needs to create an event port for it. The callback is
121 expected to fill the ``struct rte_event_crypto_adapter_conf`` structure
122 passed to it.
123
124 In the ``RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD`` mode, if the event PMD and crypto
125 PMD supports internal event port
126 (``RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD``), events with crypto
127 operations should be enqueued to the crypto adapter using
128 ``rte_event_crypto_adapter_enqueue()`` API. If not, the event port created by
129 the adapter can be retrieved using ``rte_event_crypto_adapter_event_port_get()``
130 API. An application can use this event port to link with an event queue, on
131 which it enqueues events towards the crypto adapter using
132 ``rte_event_enqueue_burst()``.
133
134 .. code-block:: c
135
136         uint8_t id, evdev_id, cdev_id, crypto_ev_port_id, app_qid;
137         struct rte_event ev;
138         uint32_t cap;
139         int ret;
140
141         // Fill in event info and update event_ptr with rte_crypto_op
142         memset(&ev, 0, sizeof(ev));
143         .
144         .
145         ev.event_ptr = op;
146
147         ret = rte_event_crypto_adapter_caps_get(evdev_id, cdev_id, &cap);
148         if (cap & RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD) {
149                 ret = rte_event_crypto_adapter_enqueue(evdev_id, app_ev_port_id,
150                                                        ev, nb_events);
151         } else {
152                 ret = rte_event_crypto_adapter_event_port_get(id,
153                                                         &crypto_ev_port_id);
154                 ret = rte_event_queue_setup(evdev_id, app_qid, NULL);
155                 ret = rte_event_port_link(evdev_id, crypto_ev_port_id, &app_qid,
156                                           NULL, 1);
157                 ev.queue_id = app_qid;
158                 ret = rte_event_enqueue_burst(evdev_id, app_ev_port_id, ev,
159                                               nb_events);
160         }
161
162
163 Querying adapter capabilities
164 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
165
166 The ``rte_event_crypto_adapter_caps_get()`` function allows
167 the application to query the adapter capabilities for an eventdev and cryptodev
168 combination. This API provides whether cryptodev and eventdev are connected using
169 internal HW port or not.
170
171 .. code-block:: c
172
173         rte_event_crypto_adapter_caps_get(dev_id, cdev_id, &cap);
174
175 Adding queue pair to the adapter instance
176 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
177
178 Cryptodev device id and queue pair are created using cryptodev APIs.
179 For more information see :doc:`here  <cryptodev_lib>`.
180
181 .. code-block:: c
182
183         struct rte_cryptodev_config conf;
184         struct rte_cryptodev_qp_conf qp_conf;
185         uint8_t cdev_id = 0;
186         uint16_t qp_id = 0;
187
188         rte_cryptodev_configure(cdev_id, &conf);
189         rte_cryptodev_queue_pair_setup(cdev_id, qp_id, &qp_conf);
190
191 These cryptodev id and queue pair are added to the instance using the
192 ``rte_event_crypto_adapter_queue_pair_add()`` API.
193 The same is removed using ``rte_event_crypto_adapter_queue_pair_del()`` API.
194 If HW supports RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_QP_EV_BIND
195 capability, event information must be passed to the add API.
196
197 .. code-block:: c
198
199         uint32_t cap;
200         int ret;
201
202         ret = rte_event_crypto_adapter_caps_get(id, evdev, &cap);
203         if (cap & RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_QP_EV_BIND) {
204                 struct rte_event event;
205
206                 // Fill in event information & pass it to add API
207                 rte_event_crypto_adapter_queue_pair_add(id, cdev_id, qp_id, &event);
208         } else
209                 rte_event_crypto_adapter_queue_pair_add(id, cdev_id, qp_id, NULL);
210
211 Configure the service function
212 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
213
214 If the adapter uses a service function, the application is required to assign
215 a service core to the service function as show below.
216
217 .. code-block:: c
218
219         uint32_t service_id;
220
221         if (rte_event_crypto_adapter_service_id_get(id, &service_id) == 0)
222                 rte_service_map_lcore_set(service_id, CORE_ID);
223
224 Set event request/response information
225 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
226
227 In the RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode, the application needs
228 to specify the cryptodev ID and queue pair ID (request information) in
229 addition to the event information (response information) needed to enqueue
230 an event after the crypto operation has completed. The request and response
231 information are specified in the ``struct rte_crypto_op`` private data or
232 session's private data.
233
234 In the RTE_EVENT_CRYPTO_ADAPTER_OP_NEW mode, the application is required
235 to provide only the response information.
236
237 The SW adapter or HW PMD uses ``rte_crypto_op::sess_type`` to
238 decide whether request/response data is located in the crypto session/
239 crypto security session or at an offset in the ``struct rte_crypto_op``.
240 The ``rte_crypto_op::private_data_offset`` is used to locate the request/
241 response in the ``rte_crypto_op``.
242
243 For crypto session, ``rte_cryptodev_sym_session_set_user_data()`` API
244 will be used to set request/response data. The same data will be obtained
245 by ``rte_cryptodev_sym_session_get_user_data()`` API.  The
246 RTE_EVENT_CRYPTO_ADAPTER_CAP_SESSION_PRIVATE_DATA capability indicates
247 whether HW or SW supports this feature.
248
249 For security session, ``rte_security_session_set_private_data()`` API
250 will be used to set request/response data. The same data will be obtained
251 by ``rte_security_session_get_private_data()`` API.
252
253 For session-less it is mandatory to place the request/response data with
254 the ``rte_crypto_op``.
255
256 .. code-block:: c
257
258         union rte_event_crypto_metadata m_data;
259         struct rte_event ev;
260         struct rte_crypto_op *op;
261
262         /* Allocate & fill op structure */
263         op = rte_crypto_op_alloc();
264
265         memset(&m_data, 0, sizeof(m_data));
266         memset(&ev, 0, sizeof(ev));
267         /* Fill event information and update event_ptr to rte_crypto_op */
268         ev.event_ptr = op;
269
270         if (op->sess_type == RTE_CRYPTO_OP_WITH_SESSION) {
271                 /* Copy response information */
272                 rte_memcpy(&m_data.response_info, &ev, sizeof(ev));
273                 /* Copy request information */
274                 m_data.request_info.cdev_id = cdev_id;
275                 m_data.request_info.queue_pair_id = qp_id;
276                 /* Call set API to store private data information */
277                 rte_cryptodev_sym_session_set_user_data(
278                         op->sym->session,
279                         &m_data,
280                         sizeof(m_data));
281         } if (op->sess_type == RTE_CRYPTO_OP_SESSIONLESS) {
282                 uint32_t len = IV_OFFSET + MAXIMUM_IV_LENGTH +
283                                (sizeof(struct rte_crypto_sym_xform) * 2);
284                 op->private_data_offset = len;
285                 /* Copy response information */
286                 rte_memcpy(&m_data.response_info, &ev, sizeof(ev));
287                 /* Copy request information */
288                 m_data.request_info.cdev_id = cdev_id;
289                 m_data.request_info.queue_pair_id = qp_id;
290                 /* Store private data information along with rte_crypto_op */
291                 rte_memcpy(op + len, &m_data, sizeof(m_data));
292         }
293
294 Start the adapter instance
295 ~~~~~~~~~~~~~~~~~~~~~~~~~~
296
297 The application calls ``rte_event_crypto_adapter_start()`` to start the adapter.
298 This function calls the start callbacks of the eventdev PMDs for hardware based
299 eventdev-cryptodev connections and ``rte_service_run_state_set()`` to enable the
300 service function if one exists.
301
302 .. code-block:: c
303
304         rte_event_crypto_adapter_start(id, mode);
305
306 .. Note::
307
308          The eventdev to which the event_crypto_adapter is connected needs to
309          be started before calling rte_event_crypto_adapter_start().
310
311 Get adapter statistics
312 ~~~~~~~~~~~~~~~~~~~~~~
313
314 The  ``rte_event_crypto_adapter_stats_get()`` function reports counters defined
315 in struct ``rte_event_crypto_adapter_stats``. The received packet and
316 enqueued event counts are a sum of the counts from the eventdev PMD callbacks
317 if the callback is supported, and the counts maintained by the service function,
318 if one exists.