1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2018 Intel Corporation.
6 #ifndef _RTE_EVENT_CRYPTO_ADAPTER_
7 #define _RTE_EVENT_CRYPTO_ADAPTER_
12 * RTE Event crypto adapter
14 * Eventdev library provides couple of adapters to bridge between various
15 * components for providing new event source. The event crypto adapter is
16 * one of those adapters which is intended to bridge between event devices
19 * The crypto adapter adds support to enqueue/dequeue crypto operations to/
20 * from event device. The packet flow between crypto device and the event
21 * device can be accomplished using both SW and HW based transfer mechanisms.
22 * The adapter uses an EAL service core function for SW based packet transfer
23 * and uses the eventdev PMD functions to configure HW based packet transfer
24 * between the crypto device and the event device.
26 * The application can choose to submit a crypto operation directly to
27 * crypto device or send it to the crypto adapter via eventdev based on
28 * RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD capability.
29 * The first mode is known as the event new(RTE_EVENT_CRYPTO_ADAPTER_OP_NEW)
30 * mode and the second as the event forward(RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD)
31 * mode. The choice of mode can be specified while creating the adapter.
32 * In the former mode, it is an application responsibility to enable ingress
33 * packet ordering. In the latter mode, it is the adapter responsibility to
34 * enable the ingress packet ordering.
37 * Working model of RTE_EVENT_CRYPTO_ADAPTER_OP_NEW mode:
39 * +--------------+ +--------------+
40 * | | | Crypto stage |
41 * | Application |---[2]-->| + enqueue to |
43 * +--------------+ +--------------+
57 * +--------------+ +--------------+
59 * |Crypto adapter|<--[4]---| Cryptodev |
61 * +--------------+ +--------------+
64 * [1] Application dequeues events from the previous stage.
65 * [2] Application prepares the crypto operations.
66 * [3] Crypto operations are submitted to cryptodev by application.
67 * [4] Crypto adapter dequeues crypto completions from cryptodev.
68 * [5] Crypto adapter enqueues events to the eventdev.
69 * [6] Application dequeues from eventdev and prepare for further
72 * In the RTE_EVENT_CRYPTO_ADAPTER_OP_NEW mode, application submits crypto
73 * operations directly to crypto device. The adapter then dequeues crypto
74 * completions from crypto device and enqueue events to the event device.
75 * This mode does not ensure ingress ordering, if the application directly
76 * enqueues to cryptodev without going through crypto/atomic stage i.e.
77 * removing item [1] and [2].
78 * Events dequeued from the adapter will be treated as new events.
79 * In this mode, application needs to specify event information (response
80 * information) which is needed to enqueue an event after the crypto operation
84 * Working model of RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode:
86 * +--------------+ +--------------+
87 * --[1]-->| |---[2]-->| Application |
88 * | Event device | | in |
89 * <--[8]--| |<--[3]---| Ordered stage|
90 * +--------------+ +--------------+
95 * +----------------+ +--------------+
97 * | Crypto adapter | | Cryptodev |
99 * +----------------+ +--------------+
102 * [1] Events from the previous stage.
103 * [2] Application in ordered stage dequeues events from eventdev.
104 * [3] Application enqueues crypto operations as events to eventdev.
105 * [4] Crypto adapter dequeues event from eventdev.
106 * [5] Crypto adapter submits crypto operations to cryptodev
108 * [6] Crypto adapter dequeues crypto completions from cryptodev
109 * [7] Crypto adapter enqueues events to the eventdev
110 * [8] Events to the next stage
112 * In the RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode, if HW supports
113 * RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD capability the application
114 * can directly submit the crypto operations to the cryptodev.
115 * If not, application retrieves crypto adapter's event port using
116 * rte_event_crypto_adapter_event_port_get() API. Then, links its event
117 * queue to this port and starts enqueuing crypto operations as events
118 * to the eventdev. The adapter then dequeues the events and submits the
119 * crypto operations to the cryptodev. After the crypto completions, the
120 * adapter enqueues events to the event device.
121 * Application can use this mode, when ingress packet ordering is needed.
122 * Events dequeued from the adapter will be treated as forwarded events.
123 * In this mode, the application needs to specify the cryptodev ID
124 * and queue pair ID (request information) needed to enqueue a crypto
125 * operation in addition to the event information (response information)
126 * needed to enqueue an event after the crypto operation has completed.
129 * The event crypto adapter provides common APIs to configure the packet flow
130 * from the crypto device to event devices for both SW and HW based transfers.
131 * The crypto event adapter's functions are:
132 * - rte_event_crypto_adapter_create_ext()
133 * - rte_event_crypto_adapter_create()
134 * - rte_event_crypto_adapter_free()
135 * - rte_event_crypto_adapter_queue_pair_add()
136 * - rte_event_crypto_adapter_queue_pair_del()
137 * - rte_event_crypto_adapter_start()
138 * - rte_event_crypto_adapter_stop()
139 * - rte_event_crypto_adapter_stats_get()
140 * - rte_event_crypto_adapter_stats_reset()
142 * The applicaton creates an instance using rte_event_crypto_adapter_create()
143 * or rte_event_crypto_adapter_create_ext().
145 * Cryptodev queue pair addition/deletion is done using the
146 * rte_event_crypto_adapter_queue_pair_xxx() APIs. If HW supports
147 * RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_QP_EV_BIND capability, event
148 * information must be passed to the add API.
150 * The SW adapter or HW PMD uses rte_crypto_op::sess_type to decide whether
151 * request/response(private) data is located in the crypto/security session
152 * or at an offset in the rte_crypto_op.
154 * For session-based operations, the set and get API provides a mechanism for
155 * an application to store and retrieve the data information stored
156 * along with the crypto session.
157 * The RTE_EVENT_CRYPTO_ADAPTER_CAP_SESSION_PRIVATE_DATA capability indicates
158 * whether HW or SW supports this feature.
160 * For session-less mode, the adapter gets the private data information placed
161 * along with the ``struct rte_crypto_op``.
162 * The rte_crypto_op::private_data_offset provides an offset to locate the
163 * request/response information in the rte_crypto_op. This offset is counted
164 * from the start of the rte_crypto_op including initialization vector (IV).
173 #include "rte_eventdev.h"
177 * @b EXPERIMENTAL: this enum may change without prior notice
179 * Crypto event adapter mode
181 enum rte_event_crypto_adapter_mode {
182 RTE_EVENT_CRYPTO_ADAPTER_OP_NEW,
183 /**< Start the crypto adapter in event new mode.
184 * @see RTE_EVENT_OP_NEW.
185 * Application submits crypto operations to the cryptodev.
186 * Adapter only dequeues the crypto completions from cryptodev
187 * and enqueue events to the eventdev.
189 RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD,
190 /**< Start the crypto adapter in event forward mode.
191 * @see RTE_EVENT_OP_FORWARD.
192 * Application submits crypto requests as events to the crypto
193 * adapter or crypto device based on
194 * RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD capability.
195 * Crypto completions are enqueued back to the eventdev by
202 * @b EXPERIMENTAL: this structure may change without prior notice
204 * Crypto event request structure will be filled by application to
205 * provide event request information to the adapter.
207 struct rte_event_crypto_request {
209 /**< Overlaps with first 8 bytes of struct rte_event
210 * that encode the response event information. Application
211 * is expected to fill in struct rte_event response_info.
214 /**< cryptodev ID to be used */
215 uint16_t queue_pair_id;
216 /**< cryptodev queue pair ID to be used */
218 /**< Reserved bits */
223 * @b EXPERIMENTAL: this structure may change without prior notice
225 * Crypto event metadata structure will be filled by application
226 * to provide crypto request and event response information.
228 * If crypto events are enqueued using a HW mechanism, the cryptodev
229 * PMD will use the event response information to set up the event
230 * that is enqueued back to eventdev after completion of the crypto
231 * operation. If the transfer is done by SW, event response information
232 * will be used by the adapter.
234 union rte_event_crypto_metadata {
235 struct rte_event_crypto_request request_info;
236 /**< Request information to be filled in by application
237 * for RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode.
239 struct rte_event response_info;
240 /**< Response information to be filled in by application
241 * for RTE_EVENT_CRYPTO_ADAPTER_OP_NEW and
242 * RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode.
248 * @b EXPERIMENTAL: this structure may change without prior notice
250 * Adapter configuration structure that the adapter configuration callback
251 * function is expected to fill out
252 * @see rte_event_crypto_adapter_conf_cb
254 struct rte_event_crypto_adapter_conf {
255 uint8_t event_port_id;
256 /**< Event port identifier, the adapter enqueues events to this
257 * port and dequeues crypto request events in
258 * RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode.
261 /**< The adapter can return early if it has processed at least
262 * max_nb crypto ops. This isn't treated as a requirement; batching
263 * may cause the adapter to process more than max_nb crypto ops.
269 * @b EXPERIMENTAL: this API may change without prior notice
271 * Function type used for adapter configuration callback. The callback is
272 * used to fill in members of the struct rte_event_crypto_adapter_conf, this
273 * callback is invoked when creating a SW service for packet transfer from
274 * cryptodev queue pair to the event device. The SW service is created within
275 * the rte_event_crypto_adapter_queue_pair_add() function if SW based packet
276 * transfers from cryptodev queue pair to the event device are required.
279 * Adapter identifier.
282 * Event device identifier.
285 * Structure that needs to be populated by this callback.
288 * Argument to the callback. This is the same as the conf_arg passed to the
289 * rte_event_crypto_adapter_create_ext().
291 typedef int (*rte_event_crypto_adapter_conf_cb) (uint8_t id, uint8_t dev_id,
292 struct rte_event_crypto_adapter_conf *conf,
297 * @b EXPERIMENTAL: this structure may change without prior notice
299 * A structure used to retrieve statistics for an event crypto adapter
303 struct rte_event_crypto_adapter_stats {
304 uint64_t event_poll_count;
305 /**< Event port poll count */
306 uint64_t event_deq_count;
307 /**< Event dequeue count */
308 uint64_t crypto_enq_count;
309 /**< Cryptodev enqueue count */
310 uint64_t crypto_enq_fail;
311 /**< Cryptodev enqueue failed count */
312 uint64_t crypto_deq_count;
313 /**< Cryptodev dequeue count */
314 uint64_t event_enq_count;
315 /**< Event enqueue count */
316 uint64_t event_enq_retry_count;
317 /**< Event enqueue retry count */
318 uint64_t event_enq_fail_count;
319 /**< Event enqueue fail count */
324 * @b EXPERIMENTAL: this API may change without prior notice
326 * Create a new event crypto adapter with the specified identifier.
329 * Adapter identifier.
332 * Event device identifier.
335 * Callback function that fills in members of a
336 * struct rte_event_crypto_adapter_conf struct passed into
340 * Flag to indicate the mode of the adapter.
341 * @see rte_event_crypto_adapter_mode
344 * Argument that is passed to the conf_cb function.
348 * - <0: Error code on failure
350 int __rte_experimental
351 rte_event_crypto_adapter_create_ext(uint8_t id, uint8_t dev_id,
352 rte_event_crypto_adapter_conf_cb conf_cb,
353 enum rte_event_crypto_adapter_mode mode,
358 * @b EXPERIMENTAL: this API may change without prior notice
360 * Create a new event crypto adapter with the specified identifier.
361 * This function uses an internal configuration function that creates an event
362 * port. This default function reconfigures the event device with an
363 * additional event port and set up the event port using the port_config
364 * parameter passed into this function. In case the application needs more
365 * control in configuration of the service, it should use the
366 * rte_event_crypto_adapter_create_ext() version.
369 * Adapter identifier.
372 * Event device identifier.
375 * Argument of type *rte_event_port_conf* that is passed to the conf_cb
379 * Flag to indicate the mode of the adapter.
380 * @see rte_event_crypto_adapter_mode
384 * - <0: Error code on failure
386 int __rte_experimental
387 rte_event_crypto_adapter_create(uint8_t id, uint8_t dev_id,
388 struct rte_event_port_conf *port_config,
389 enum rte_event_crypto_adapter_mode mode);
393 * @b EXPERIMENTAL: this API may change without prior notice
395 * Free an event crypto adapter
398 * Adapter identifier.
402 * - <0: Error code on failure, If the adapter still has queue pairs
403 * added to it, the function returns -EBUSY.
405 int __rte_experimental
406 rte_event_crypto_adapter_free(uint8_t id);
410 * @b EXPERIMENTAL: this API may change without prior notice
412 * Add a queue pair to an event crypto adapter.
415 * Adapter identifier.
418 * Cryptodev identifier.
420 * @param queue_pair_id
421 * Cryptodev queue pair identifier. If queue_pair_id is set -1,
422 * adapter adds all the pre configured queue pairs to the instance.
425 * if HW supports cryptodev queue pair to event queue binding, application is
426 * expected to fill in event information, else it will be NULL.
427 * @see RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_QP_EV_BIND
430 * - 0: Success, queue pair added correctly.
431 * - <0: Error code on failure.
433 int __rte_experimental
434 rte_event_crypto_adapter_queue_pair_add(uint8_t id,
436 int32_t queue_pair_id,
437 const struct rte_event *event);
441 * @b EXPERIMENTAL: this API may change without prior notice
443 * Delete a queue pair from an event crypto adapter.
446 * Adapter identifier.
449 * Cryptodev identifier.
451 * @param queue_pair_id
452 * Cryptodev queue pair identifier.
455 * - 0: Success, queue pair deleted successfully.
456 * - <0: Error code on failure.
458 int __rte_experimental
459 rte_event_crypto_adapter_queue_pair_del(uint8_t id, uint8_t cdev_id,
460 int32_t queue_pair_id);
464 * @b EXPERIMENTAL: this API may change without prior notice
466 * Start event crypto adapter
469 * Adapter identifier.
473 * - 0: Success, adapter started successfully.
474 * - <0: Error code on failure.
476 int __rte_experimental
477 rte_event_crypto_adapter_start(uint8_t id);
481 * @b EXPERIMENTAL: this API may change without prior notice
483 * Stop event crypto adapter
486 * Adapter identifier.
489 * - 0: Success, adapter stopped successfully.
490 * - <0: Error code on failure.
492 int __rte_experimental
493 rte_event_crypto_adapter_stop(uint8_t id);
497 * @b EXPERIMENTAL: this API may change without prior notice
499 * Retrieve statistics for an adapter
502 * Adapter identifier.
505 * A pointer to structure used to retrieve statistics for an adapter.
508 * - 0: Success, retrieved successfully.
509 * - <0: Error code on failure.
511 int __rte_experimental
512 rte_event_crypto_adapter_stats_get(uint8_t id,
513 struct rte_event_crypto_adapter_stats *stats);
517 * @b EXPERIMENTAL: this API may change without prior notice
519 * Reset statistics for an adapter.
522 * Adapter identifier.
525 * - 0: Success, statistics reset successfully.
526 * - <0: Error code on failure.
528 int __rte_experimental
529 rte_event_crypto_adapter_stats_reset(uint8_t id);
533 * @b EXPERIMENTAL: this API may change without prior notice
535 * Retrieve the service ID of an adapter. If the adapter doesn't use
536 * a rte_service function, this function returns -ESRCH.
539 * Adapter identifier.
541 * @param [out] service_id
542 * A pointer to a uint32_t, to be filled in with the service id.
546 * - <0: Error code on failure, if the adapter doesn't use a rte_service
547 * function, this function returns -ESRCH.
549 int __rte_experimental
550 rte_event_crypto_adapter_service_id_get(uint8_t id, uint32_t *service_id);
554 * @b EXPERIMENTAL: this API may change without prior notice
556 * Retrieve the event port of an adapter.
559 * Adapter identifier.
561 * @param [out] event_port_id
562 * Application links its event queue to this adapter port which is used
563 * in RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode.
567 * - <0: Error code on failure.
569 int __rte_experimental
570 rte_event_crypto_adapter_event_port_get(uint8_t id, uint8_t *event_port_id);
575 #endif /* _RTE_EVENT_CRYPTO_ADAPTER_ */