1 /* SPDX-License-Identifier: BSD-3-Clause
2  * Copyright(c) 2018 Intel Corporation.
3  * All rights reserved.
4  */
5 
6 #ifndef _RTE_EVENT_CRYPTO_ADAPTER_
7 #define _RTE_EVENT_CRYPTO_ADAPTER_
8 
9 /**
10  * @file
11  *
12  * RTE Event crypto adapter
13  *
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
17  * and crypto devices.
18  *
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.
25  *
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.
35  *
36  *
37  * Working model of RTE_EVENT_CRYPTO_ADAPTER_OP_NEW mode:
38  *
39  *                +--------------+         +--------------+
40  *                |              |         | Crypto stage |
41  *                | Application  |---[2]-->| + enqueue to |
42  *                |              |         |   cryptodev  |
43  *                +--------------+         +--------------+
44  *                    ^   ^                       |
45  *                    |   |                      [3]
46  *                   [6] [1]                      |
47  *                    |   |                       |
48  *                +--------------+                |
49  *                |              |                |
50  *                | Event device |                |
51  *                |              |                |
52  *                +--------------+                |
53  *                       ^                        |
54  *                       |                        |
55  *                      [5]                       |
56  *                       |                        v
57  *                +--------------+         +--------------+
58  *                |              |         |              |
59  *                |Crypto adapter|<--[4]---|  Cryptodev   |
60  *                |              |         |              |
61  *                +--------------+         +--------------+
62  *
63  *
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
70  *             processing.
71  *
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
81  * is completed.
82  *
83  *
84  * Working model of RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode:
85  *
86  *                +--------------+         +--------------+
87  *        --[1]-->|              |---[2]-->|  Application |
88  *                | Event device |         |      in      |
89  *        <--[8]--|              |<--[3]---| Ordered stage|
90  *                +--------------+         +--------------+
91  *                    ^      |
92  *                    |     [4]
93  *                   [7]     |
94  *                    |      v
95  *               +----------------+       +--------------+
96  *               |                |--[5]->|              |
97  *               | Crypto adapter |       |   Cryptodev  |
98  *               |                |<-[6]--|              |
99  *               +----------------+       +--------------+
100  *
101  *
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
107  *             (Atomic stage).
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
111  *
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.
127  *
128  *
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()
141 
142  * The application creates an instance using rte_event_crypto_adapter_create()
143  * or rte_event_crypto_adapter_create_ext().
144  *
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.
149  *
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.
153  *
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.
159  *
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).
165  */
166 
167 #ifdef __cplusplus
168 extern "C" {
169 #endif
170 
171 #include <stdint.h>
172 
173 #include "rte_eventdev.h"
174 
175 /**
176  * Crypto event adapter mode
177  */
178 enum rte_event_crypto_adapter_mode {
179 	RTE_EVENT_CRYPTO_ADAPTER_OP_NEW,
180 	/**< Start the crypto adapter in event new mode.
181 	 * @see RTE_EVENT_OP_NEW.
182 	 * Application submits crypto operations to the cryptodev.
183 	 * Adapter only dequeues the crypto completions from cryptodev
184 	 * and enqueue events to the eventdev.
185 	 */
186 	RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD,
187 	/**< Start the crypto adapter in event forward mode.
188 	 * @see RTE_EVENT_OP_FORWARD.
189 	 * Application submits crypto requests as events to the crypto
190 	 * adapter or crypto device based on
191 	 * RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD capability.
192 	 * Crypto completions are enqueued back to the eventdev by
193 	 * crypto adapter.
194 	 */
195 };
196 
197 /**
198  * Crypto event request structure will be filled by application to
199  * provide event request information to the adapter.
200  */
201 struct rte_event_crypto_request {
202 	uint8_t resv[8];
203 	/**< Overlaps with first 8 bytes of struct rte_event
204 	 * that encode the response event information. Application
205 	 * is expected to fill in struct rte_event response_info.
206 	 */
207 	uint16_t cdev_id;
208 	/**< cryptodev ID to be used */
209 	uint16_t queue_pair_id;
210 	/**< cryptodev queue pair ID to be used */
211 	uint32_t resv1;
212 	/**< Reserved bits */
213 };
214 
215 /**
216  * Crypto event metadata structure will be filled by application
217  * to provide crypto request and event response information.
218  *
219  * If crypto events are enqueued using a HW mechanism, the cryptodev
220  * PMD will use the event response information to set up the event
221  * that is enqueued back to eventdev after completion of the crypto
222  * operation. If the transfer is done by SW, event response information
223  * will be used by the adapter.
224  */
225 union rte_event_crypto_metadata {
226 	struct rte_event_crypto_request request_info;
227 	/**< Request information to be filled in by application
228 	 * for RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode.
229 	 * First 8 bytes of request_info is reserved for response_info.
230 	 */
231 	struct rte_event response_info;
232 	/**< Response information to be filled in by application
233 	 * for RTE_EVENT_CRYPTO_ADAPTER_OP_NEW and
234 	 * RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode.
235 	 */
236 };
237 
238 /**
239  * Adapter configuration structure that the adapter configuration callback
240  * function is expected to fill out
241  * @see rte_event_crypto_adapter_conf_cb
242  */
243 struct rte_event_crypto_adapter_conf {
244 	uint8_t event_port_id;
245 	/**< Event port identifier, the adapter enqueues events to this
246 	 * port and dequeues crypto request events in
247 	 * RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode.
248 	 */
249 	uint32_t max_nb;
250 	/**< The adapter can return early if it has processed at least
251 	 * max_nb crypto ops. This isn't treated as a requirement; batching
252 	 * may cause the adapter to process more than max_nb crypto ops.
253 	 */
254 };
255 
256 /**
257  * Function type used for adapter configuration callback. The callback is
258  * used to fill in members of the struct rte_event_crypto_adapter_conf, this
259  * callback is invoked when creating a SW service for packet transfer from
260  * cryptodev queue pair to the event device. The SW service is created within
261  * the rte_event_crypto_adapter_queue_pair_add() function if SW based packet
262  * transfers from cryptodev queue pair to the event device are required.
263  *
264  * @param id
265  *  Adapter identifier.
266  *
267  * @param dev_id
268  *  Event device identifier.
269  *
270  * @param conf
271  *  Structure that needs to be populated by this callback.
272  *
273  * @param arg
274  *  Argument to the callback. This is the same as the conf_arg passed to the
275  *  rte_event_crypto_adapter_create_ext().
276  */
277 typedef int (*rte_event_crypto_adapter_conf_cb) (uint8_t id, uint8_t dev_id,
278 			struct rte_event_crypto_adapter_conf *conf,
279 			void *arg);
280 
281 /**
282  * A structure used to retrieve statistics for an event crypto adapter
283  * instance.
284  */
285 
286 struct rte_event_crypto_adapter_stats {
287 	uint64_t event_poll_count;
288 	/**< Event port poll count */
289 	uint64_t event_deq_count;
290 	/**< Event dequeue count */
291 	uint64_t crypto_enq_count;
292 	/**< Cryptodev enqueue count */
293 	uint64_t crypto_enq_fail;
294 	/**< Cryptodev enqueue failed count */
295 	uint64_t crypto_deq_count;
296 	/**< Cryptodev dequeue count */
297 	uint64_t event_enq_count;
298 	/**< Event enqueue count */
299 	uint64_t event_enq_retry_count;
300 	/**< Event enqueue retry count */
301 	uint64_t event_enq_fail_count;
302 	/**< Event enqueue fail count */
303 };
304 
305 /**
306  * Create a new event crypto adapter with the specified identifier.
307  *
308  * @param id
309  *  Adapter identifier.
310  *
311  * @param dev_id
312  *  Event device identifier.
313  *
314  * @param conf_cb
315  *  Callback function that fills in members of a
316  *  struct rte_event_crypto_adapter_conf struct passed into
317  *  it.
318  *
319  * @param mode
320  *  Flag to indicate the mode of the adapter.
321  *  @see rte_event_crypto_adapter_mode
322  *
323  * @param conf_arg
324  *  Argument that is passed to the conf_cb function.
325  *
326  * @return
327  *   - 0: Success
328  *   - <0: Error code on failure
329  */
330 int
331 rte_event_crypto_adapter_create_ext(uint8_t id, uint8_t dev_id,
332 				    rte_event_crypto_adapter_conf_cb conf_cb,
333 				    enum rte_event_crypto_adapter_mode mode,
334 				    void *conf_arg);
335 
336 /**
337  * Create a new event crypto adapter with the specified identifier.
338  * This function uses an internal configuration function that creates an event
339  * port. This default function reconfigures the event device with an
340  * additional event port and set up the event port using the port_config
341  * parameter passed into this function. In case the application needs more
342  * control in configuration of the service, it should use the
343  * rte_event_crypto_adapter_create_ext() version.
344  *
345  * @param id
346  *  Adapter identifier.
347  *
348  * @param dev_id
349  *  Event device identifier.
350  *
351  * @param port_config
352  *  Argument of type *rte_event_port_conf* that is passed to the conf_cb
353  *  function.
354  *
355  * @param mode
356  *  Flag to indicate the mode of the adapter.
357  *  @see rte_event_crypto_adapter_mode
358  *
359  * @return
360  *   - 0: Success
361  *   - <0: Error code on failure
362  */
363 int
364 rte_event_crypto_adapter_create(uint8_t id, uint8_t dev_id,
365 				struct rte_event_port_conf *port_config,
366 				enum rte_event_crypto_adapter_mode mode);
367 
368 /**
369  * Free an event crypto adapter
370  *
371  * @param id
372  *  Adapter identifier.
373  *
374  * @return
375  *   - 0: Success
376  *   - <0: Error code on failure, If the adapter still has queue pairs
377  *      added to it, the function returns -EBUSY.
378  */
379 int
380 rte_event_crypto_adapter_free(uint8_t id);
381 
382 /**
383  * Add a queue pair to an event crypto adapter.
384  *
385  * @param id
386  *  Adapter identifier.
387  *
388  * @param cdev_id
389  *  Cryptodev identifier.
390  *
391  * @param queue_pair_id
392  *  Cryptodev queue pair identifier. If queue_pair_id is set -1,
393  *  adapter adds all the pre configured queue pairs to the instance.
394  *
395  * @param event
396  *  if HW supports cryptodev queue pair to event queue binding, application is
397  *  expected to fill in event information, else it will be NULL.
398  *  @see RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_QP_EV_BIND
399  *
400  * @return
401  *  - 0: Success, queue pair added correctly.
402  *  - <0: Error code on failure.
403  */
404 int
405 rte_event_crypto_adapter_queue_pair_add(uint8_t id,
406 			uint8_t cdev_id,
407 			int32_t queue_pair_id,
408 			const struct rte_event *event);
409 
410 /**
411  * Delete a queue pair from an event crypto adapter.
412  *
413  * @param id
414  *  Adapter identifier.
415  *
416  * @param cdev_id
417  *  Cryptodev identifier.
418  *
419  * @param queue_pair_id
420  *  Cryptodev queue pair identifier.
421  *
422  * @return
423  *  - 0: Success, queue pair deleted successfully.
424  *  - <0: Error code on failure.
425  */
426 int
427 rte_event_crypto_adapter_queue_pair_del(uint8_t id, uint8_t cdev_id,
428 					int32_t queue_pair_id);
429 
430 /**
431  * Start event crypto adapter
432  *
433  * @param id
434  *  Adapter identifier.
435  *
436  *
437  * @return
438  *  - 0: Success, adapter started successfully.
439  *  - <0: Error code on failure.
440  *
441  * @note
442  *  The eventdev and cryptodev to which the event_crypto_adapter is connected
443  *  needs to be started before calling rte_event_crypto_adapter_start().
444  */
445 int
446 rte_event_crypto_adapter_start(uint8_t id);
447 
448 /**
449  * Stop event crypto adapter
450  *
451  * @param id
452  *  Adapter identifier.
453  *
454  * @return
455  *  - 0: Success, adapter stopped successfully.
456  *  - <0: Error code on failure.
457  */
458 int
459 rte_event_crypto_adapter_stop(uint8_t id);
460 
461 /**
462  * Retrieve statistics for an adapter
463  *
464  * @param id
465  *  Adapter identifier.
466  *
467  * @param [out] stats
468  *  A pointer to structure used to retrieve statistics for an adapter.
469  *
470  * @return
471  *  - 0: Success, retrieved successfully.
472  *  - <0: Error code on failure.
473  */
474 int
475 rte_event_crypto_adapter_stats_get(uint8_t id,
476 				struct rte_event_crypto_adapter_stats *stats);
477 
478 /**
479  * Reset statistics for an adapter.
480  *
481  * @param id
482  *  Adapter identifier.
483  *
484  * @return
485  *  - 0: Success, statistics reset successfully.
486  *  - <0: Error code on failure.
487  */
488 int
489 rte_event_crypto_adapter_stats_reset(uint8_t id);
490 
491 /**
492  * Retrieve the service ID of an adapter. If the adapter doesn't use
493  * a rte_service function, this function returns -ESRCH.
494  *
495  * @param id
496  *  Adapter identifier.
497  *
498  * @param [out] service_id
499  *  A pointer to a uint32_t, to be filled in with the service id.
500  *
501  * @return
502  *  - 0: Success
503  *  - <0: Error code on failure, if the adapter doesn't use a rte_service
504  * function, this function returns -ESRCH.
505  */
506 int
507 rte_event_crypto_adapter_service_id_get(uint8_t id, uint32_t *service_id);
508 
509 /**
510  * Retrieve the event port of an adapter.
511  *
512  * @param id
513  *  Adapter identifier.
514  *
515  * @param [out] event_port_id
516  *  Application links its event queue to this adapter port which is used
517  *  in RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD mode.
518  *
519  * @return
520  *  - 0: Success
521  *  - <0: Error code on failure.
522  */
523 int
524 rte_event_crypto_adapter_event_port_get(uint8_t id, uint8_t *event_port_id);
525 
526 /**
527  * Enqueue a burst of crypto operations as event objects supplied in *rte_event*
528  * structure on an event crypto adapter designated by its event *dev_id* through
529  * the event port specified by *port_id*. This function is supported if the
530  * eventdev PMD has the #RTE_EVENT_CRYPTO_ADAPTER_CAP_INTERNAL_PORT_OP_FWD
531  * capability flag set.
532  *
533  * The *nb_events* parameter is the number of event objects to enqueue which are
534  * supplied in the *ev* array of *rte_event* structure.
535  *
536  * The rte_event_crypto_adapter_enqueue() function returns the number of
537  * event objects it actually enqueued. A return value equal to *nb_events*
538  * means that all event objects have been enqueued.
539  *
540  * @param dev_id
541  *  The identifier of the device.
542  * @param port_id
543  *  The identifier of the event port.
544  * @param ev
545  *  Points to an array of *nb_events* objects of type *rte_event* structure
546  *  which contain the event object enqueue operations to be processed.
547  * @param nb_events
548  *  The number of event objects to enqueue, typically number of
549  *  rte_event_port_attr_get(...RTE_EVENT_PORT_ATTR_ENQ_DEPTH...)
550  *  available for this port.
551  *
552  * @return
553  *   The number of event objects actually enqueued on the event device. The
554  *   return value can be less than the value of the *nb_events* parameter when
555  *   the event devices queue is full or if invalid parameters are specified in a
556  *   *rte_event*. If the return value is less than *nb_events*, the remaining
557  *   events at the end of ev[] are not consumed and the caller has to take care
558  *   of them, and rte_errno is set accordingly. Possible errno values include:
559  *   - EINVAL   The port ID is invalid, device ID is invalid, an event's queue
560  *              ID is invalid, or an event's sched type doesn't match the
561  *              capabilities of the destination queue.
562  *   - ENOSPC   The event port was backpressured and unable to enqueue
563  *              one or more events. This error code is only applicable to
564  *              closed systems.
565  */
566 static inline uint16_t
rte_event_crypto_adapter_enqueue(uint8_t dev_id,uint8_t port_id,struct rte_event ev[],uint16_t nb_events)567 rte_event_crypto_adapter_enqueue(uint8_t dev_id,
568 				uint8_t port_id,
569 				struct rte_event ev[],
570 				uint16_t nb_events)
571 {
572 	const struct rte_event_fp_ops *fp_ops;
573 	void *port;
574 
575 	fp_ops = &rte_event_fp_ops[dev_id];
576 	port = fp_ops->data[port_id];
577 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG
578 	if (dev_id >= RTE_EVENT_MAX_DEVS ||
579 	    port_id >= RTE_EVENT_MAX_PORTS_PER_DEV) {
580 		rte_errno = EINVAL;
581 		return 0;
582 	}
583 
584 	if (port == NULL) {
585 		rte_errno = EINVAL;
586 		return 0;
587 	}
588 #endif
589 	rte_eventdev_trace_crypto_adapter_enqueue(dev_id, port_id, ev,
590 		nb_events);
591 
592 	return fp_ops->ca_enqueue(port, ev, nb_events);
593 }
594 
595 #ifdef __cplusplus
596 }
597 #endif
598 #endif	/* _RTE_EVENT_CRYPTO_ADAPTER_ */
599