1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2017 Intel Corporation.
6 #ifndef _RTE_EVENT_ETH_RX_ADAPTER_
7 #define _RTE_EVENT_ETH_RX_ADAPTER_
12 * RTE Event Ethernet Rx Adapter
14 * An eventdev-based packet processing application enqueues/dequeues mbufs
15 * to/from the event device. Packet flow from the ethernet device to the event
16 * device can be accomplished using either HW or SW mechanisms depending on the
17 * platform and the particular combination of ethernet and event devices. The
18 * event ethernet Rx adapter provides common APIs to configure the packet flow
19 * from the ethernet devices to event devices across both these transfer
22 * The adapter uses a 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 ethernet device and the event device.
26 * The ethernet Rx event adapter's functions are:
27 * - rte_event_eth_rx_adapter_create_ext()
28 * - rte_event_eth_rx_adapter_create()
29 * - rte_event_eth_rx_adapter_create_with_params()
30 * - rte_event_eth_rx_adapter_free()
31 * - rte_event_eth_rx_adapter_queue_add()
32 * - rte_event_eth_rx_adapter_queue_del()
33 * - rte_event_eth_rx_adapter_start()
34 * - rte_event_eth_rx_adapter_stop()
35 * - rte_event_eth_rx_adapter_stats_get()
36 * - rte_event_eth_rx_adapter_stats_reset()
37 * - rte_event_eth_rx_adapter_queue_conf_get()
38 * - rte_event_eth_rx_adapter_queue_stats_get()
39 * - rte_event_eth_rx_adapter_queue_stats_reset()
40 * - rte_event_eth_rx_adapter_event_port_get()
42 * The application creates an ethernet to event adapter using
43 * rte_event_eth_rx_adapter_create_ext() or rte_event_eth_rx_adapter_create()
44 * or rte_event_eth_rx_adapter_create_with_params() functions.
45 * The adapter needs to know which ethernet rx queues to poll for mbufs as well
46 * as event device parameters such as the event queue identifier, event
47 * priority and scheduling type that the adapter should use when constructing
48 * events. The rte_event_eth_rx_adapter_queue_add() function is provided for
50 * The servicing weight parameter in the rte_event_eth_rx_adapter_queue_conf
51 * is applicable when the Rx adapter uses a service core function and is
52 * intended to provide application control of the frequency of polling ethernet
53 * device receive queues, for example, the application may want to poll higher
54 * priority queues with a higher frequency but at the same time not starve
55 * lower priority queues completely. If this parameter is zero and the receive
56 * interrupt is enabled when configuring the device, the receive queue is
57 * interrupt driven; else, the queue is assigned a servicing weight of one.
59 * The application can start/stop the adapter using the
60 * rte_event_eth_rx_adapter_start() and the rte_event_eth_rx_adapter_stop()
61 * functions. If the adapter uses a rte_service function, then the application
62 * is also required to assign a core to the service function and control the
63 * service core using the rte_service APIs. The
64 * rte_event_eth_rx_adapter_service_id_get() function can be used to retrieve
65 * the service function ID of the adapter in this case.
67 * For SW based packet transfers, i.e., when the
68 * RTE_EVENT_ETH_RX_ADAPTER_CAP_INTERNAL_PORT is not set in the adapter's
69 * capabilities flags for a particular ethernet device, the service function
70 * temporarily enqueues events to an event buffer before batch enqueuing these
71 * to the event device. If the buffer fills up, the service function stops
72 * dequeuing packets from the ethernet device. The application may want to
73 * monitor the buffer fill level and instruct the service function to
74 * selectively buffer events. The application may also use some other
75 * criteria to decide which packets should enter the event device even when
76 * the event buffer fill level is low or may want to enqueue packets to an
77 * internal event port. The rte_event_eth_rx_adapter_cb_register() function
78 * allows the application to register a callback that selects which packets are
79 * enqueued to the event device by the SW adapter. The callback interface is
80 * event based so the callback can also modify the event data if it needs to.
89 #include <rte_service.h>
91 #include "rte_eventdev.h"
93 #define RTE_EVENT_ETH_RX_ADAPTER_MAX_INSTANCE 32
95 /* struct rte_event_eth_rx_adapter_queue_conf flags definitions */
96 #define RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID 0x1
97 /**< This flag indicates the flow identifier is valid
98 * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags
100 #define RTE_EVENT_ETH_RX_ADAPTER_QUEUE_EVENT_VECTOR 0x2
101 /**< This flag indicates that mbufs arriving on the queue need to be vectorized
102 * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags
106 * Adapter configuration structure that the adapter configuration callback
107 * function is expected to fill out
108 * @see rte_event_eth_rx_adapter_conf_cb
110 struct rte_event_eth_rx_adapter_conf {
111 uint8_t event_port_id;
112 /**< Event port identifier, the adapter enqueues mbuf events to this
116 /**< The adapter can return early if it has processed at least
117 * max_nb_rx mbufs. This isn't treated as a requirement; batching may
118 * cause the adapter to process more than max_nb_rx mbufs.
123 * Function type used for adapter configuration callback. The callback is
124 * used to fill in members of the struct rte_event_eth_rx_adapter_conf, this
125 * callback is invoked when creating a SW service for packet transfer from
126 * ethdev queues to the event device. The SW service is created within the
127 * rte_event_eth_rx_adapter_queue_add() function if SW based packet transfers
128 * from ethdev queues to the event device are required.
131 * Adapter identifier.
134 * Event device identifier.
137 * Structure that needs to be populated by this callback.
140 * Argument to the callback. This is the same as the conf_arg passed to the
141 * rte_event_eth_rx_adapter_create_ext().
143 typedef int (*rte_event_eth_rx_adapter_conf_cb) (uint8_t id, uint8_t dev_id,
144 struct rte_event_eth_rx_adapter_conf *conf,
148 * Rx queue configuration structure
150 struct rte_event_eth_rx_adapter_queue_conf {
151 uint32_t rx_queue_flags;
152 /**< Flags for handling received packets
153 * @see RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID
155 uint16_t servicing_weight;
156 /**< Relative polling frequency of ethernet receive queue when the
157 * adapter uses a service core function for ethernet to event device
158 * transfers. If it is set to zero, the Rx queue is interrupt driven
159 * (unless rx queue interrupts are not enabled for the ethernet
164 * The values from the following event fields will be used when
165 * queuing mbuf events:
166 * - event_queue_id: Targeted event queue ID for received packets.
167 * - event_priority: Event priority of packets from this Rx queue in
168 * the event queue relative to other events.
169 * - sched_type: Scheduling type for packets from this Rx queue.
170 * - flow_id: If the RTE_ETH_RX_EVENT_ADAPTER_QUEUE_FLOW_ID_VALID bit
171 * is set in rx_queue_flags, this flow_id is used for all
172 * packets received from this queue. Otherwise the flow ID
173 * is set to the RSS hash of the src and dst IPv4/6
176 * The event adapter sets ev.event_type to RTE_EVENT_TYPE_ETHDEV in the
181 * Indicates the maximum number for mbufs to combine and form a vector.
183 * @see rte_event_eth_rx_adapter_vector_limits::min_vector_sz
184 * @see rte_event_eth_rx_adapter_vector_limits::max_vector_sz
185 * Valid when RTE_EVENT_ETH_RX_ADAPTER_QUEUE_EVENT_VECTOR flag is set in
186 * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags
188 uint64_t vector_timeout_ns;
190 * Indicates the maximum number of nanoseconds to wait for receiving
191 * mbufs. Should be within vectorization limits of the
193 * @see rte_event_eth_rx_adapter_vector_limits::min_vector_ns
194 * @see rte_event_eth_rx_adapter_vector_limits::max_vector_ns
195 * Valid when RTE_EVENT_ETH_RX_ADAPTER_QUEUE_EVENT_VECTOR flag is set in
196 * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags
198 struct rte_mempool *vector_mp;
200 * Indicates the mempool that should be used for allocating
201 * rte_event_vector container.
202 * Should be created by using `rte_event_vector_pool_create`.
203 * Valid when RTE_EVENT_ETH_RX_ADAPTER_QUEUE_EVENT_VECTOR flag is set in
204 * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags.
206 uint16_t event_buf_size;
207 /**< event buffer size for this queue */
211 * A structure used to retrieve statistics for an
212 * eth rx adapter queue.
214 struct rte_event_eth_rx_adapter_queue_stats {
215 uint64_t rx_event_buf_count;
216 /**< Rx event buffered count */
217 uint64_t rx_event_buf_size;
218 /**< Rx event buffer size */
219 uint64_t rx_poll_count;
220 /**< Receive queue poll count */
222 /**< Received packet count */
224 /**< Received packet dropped count */
228 * A structure used to retrieve statistics for an eth rx adapter instance.
230 struct rte_event_eth_rx_adapter_stats {
231 uint64_t rx_poll_count;
232 /**< Receive queue poll count */
234 /**< Received packet count */
235 uint64_t rx_enq_count;
236 /**< Eventdev enqueue count */
237 uint64_t rx_enq_retry;
238 /**< Eventdev enqueue retry count */
240 /**< Received packet dropped count */
241 uint64_t rx_enq_start_ts;
242 /**< Rx enqueue start timestamp */
243 uint64_t rx_enq_block_cycles;
244 /**< Cycles for which the service is blocked by the event device,
245 * i.e, the service fails to enqueue to the event device.
247 uint64_t rx_enq_end_ts;
248 /**< Latest timestamp at which the service is unblocked
249 * by the event device. The start, end timestamps and
250 * block cycles can be used to compute the percentage of
251 * cycles the service is blocked by the event device.
253 uint64_t rx_intr_packets;
254 /**< Received packet count for interrupt mode Rx queues */
255 uint64_t rx_event_buf_count;
256 /**< Rx event buffered count */
257 uint64_t rx_event_buf_size;
258 /**< Rx event buffer size */
262 * A structure used to retrieve eth rx adapter vector limits.
264 struct rte_event_eth_rx_adapter_vector_limits {
266 /**< Minimum vector limit configurable.
267 * @see rte_event_eth_rx_adapter_event_vector_config::vector_sz
270 /**< Maximum vector limit configurable.
271 * @see rte_event_eth_rx_adapter_event_vector_config::vector_sz
274 /**< True if the size configured should be in log2.
275 * @see rte_event_eth_rx_adapter_event_vector_config::vector_sz
277 uint64_t min_timeout_ns;
278 /**< Minimum vector timeout configurable.
279 * @see rte_event_eth_rx_adapter_event_vector_config::vector_timeout_ns
281 uint64_t max_timeout_ns;
282 /**< Maximum vector timeout configurable.
283 * @see rte_event_eth_rx_adapter_event_vector_config::vector_timeout_ns
288 * A structure to hold adapter config params
290 struct rte_event_eth_rx_adapter_params {
291 uint16_t event_buf_size;
292 /**< size of event buffer for the adapter.
293 * This value is rounded up for better buffer utilization
296 bool use_queue_event_buf;
297 /**< flag to indicate that event buffer is separate for each queue */
302 * Callback function invoked by the SW adapter before it continues
303 * to process events. The callback is passed the size of the enqueue
304 * buffer in the SW adapter and the occupancy of the buffer. The
305 * callback can use these values to decide which events are
306 * enqueued to the event device by the SW adapter. The callback may
307 * also enqueue events internally using its own event port. The SW
308 * adapter populates the event information based on the Rx queue
309 * configuration in the adapter. The callback can modify the this event
310 * information for the events to be enqueued by the SW adapter.
312 * The callback return value is the number of events from the
313 * beginning of the event array that are to be enqueued by
314 * the SW adapter. It is the callback's responsibility to arrange
315 * these events at the beginning of the array, if these events are
316 * not contiguous in the original array. The *nb_dropped* parameter is
317 * a pointer to the number of events dropped by the callback, this
318 * number is used by the adapter to indicate the number of dropped packets
319 * as part of its statistics.
322 * Port identifier of the Ethernet device.
324 * Receive queue index.
325 * @param enqueue_buf_size
326 * Total enqueue buffer size.
327 * @param enqueue_buf_count
328 * Event count in enqueue buffer.
332 * Event array length.
335 * @param[out] nb_dropped
336 * Packets dropped by callback.
338 * - The number of events to be enqueued by the SW adapter.
340 typedef uint16_t (*rte_event_eth_rx_adapter_cb_fn)(uint16_t eth_dev_id,
342 uint32_t enqueue_buf_size,
343 uint32_t enqueue_buf_count,
344 struct rte_event *ev,
347 uint16_t *nb_dropped);
350 * Create a new ethernet Rx event adapter with the specified identifier.
353 * The identifier of the ethernet Rx event adapter.
356 * The identifier of the device to configure.
359 * Callback function that fills in members of a
360 * struct rte_event_eth_rx_adapter_conf struct passed into
364 * Argument that is passed to the conf_cb function.
368 * - <0: Error code on failure
370 int rte_event_eth_rx_adapter_create_ext(uint8_t id, uint8_t dev_id,
371 rte_event_eth_rx_adapter_conf_cb conf_cb,
375 * Create a new ethernet Rx event adapter with the specified identifier.
376 * This function uses an internal configuration function that creates an event
377 * port. This default function reconfigures the event device with an
378 * additional event port and setups up the event port using the port_config
379 * parameter passed into this function. In case the application needs more
380 * control in configuration of the service, it should use the
381 * rte_event_eth_rx_adapter_create_ext() version.
384 * The identifier of the ethernet Rx event adapter.
387 * The identifier of the device to configure.
390 * Argument of type *rte_event_port_conf* that is passed to the conf_cb
395 * - <0: Error code on failure
397 int rte_event_eth_rx_adapter_create(uint8_t id, uint8_t dev_id,
398 struct rte_event_port_conf *port_config);
401 * This is a variant of rte_event_eth_rx_adapter_create() with additional
402 * adapter params specified in ``struct rte_event_eth_rx_adapter_params``.
405 * The identifier of the ethernet Rx event adapter.
408 * The identifier of the event device to configure.
411 * Argument of type *rte_event_port_conf* that is passed to the conf_cb
415 * Pointer to struct rte_event_eth_rx_adapter_params.
416 * In case of NULL, default values are used.
420 * - <0: Error code on failure
423 int rte_event_eth_rx_adapter_create_with_params(uint8_t id, uint8_t dev_id,
424 struct rte_event_port_conf *port_config,
425 struct rte_event_eth_rx_adapter_params *rxa_params);
428 * Free an event adapter
431 * Adapter identifier.
435 * - <0: Error code on failure, If the adapter still has Rx queues
436 * added to it, the function returns -EBUSY.
438 int rte_event_eth_rx_adapter_free(uint8_t id);
441 * Add receive queue to an event adapter. After a queue has been
442 * added to the event adapter, the result of the application calling
443 * rte_eth_rx_burst(eth_dev_id, rx_queue_id, ..) is undefined.
446 * Adapter identifier.
449 * Port identifier of Ethernet device.
452 * Ethernet device receive queue index.
453 * If rx_queue_id is -1, then all Rx queues configured for
454 * the device are added. If the ethdev Rx queues can only be
455 * connected to a single event queue then rx_queue_id is
457 * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ
460 * Additional configuration structure of type *rte_event_eth_rx_adapter_conf*
463 * - 0: Success, Receive queue added correctly.
464 * - <0: Error code on failure.
465 * - (-EIO) device reconfiguration and restart error. The adapter reconfigures
466 * the event device with an additional port if it is required to use a service
467 * function for packet transfer from the ethernet device to the event device.
468 * If the device had been started before this call, this error code indicates
469 * an error in restart following an error in reconfiguration, i.e., a
470 * combination of the two error codes.
472 int rte_event_eth_rx_adapter_queue_add(uint8_t id,
475 const struct rte_event_eth_rx_adapter_queue_conf *conf);
478 * Delete receive queue from an event adapter.
481 * Adapter identifier.
484 * Port identifier of Ethernet device.
487 * Ethernet device receive queue index.
488 * If rx_queue_id is -1, then all Rx queues configured for
489 * the device are deleted. If the ethdev Rx queues can only be
490 * connected to a single event queue then rx_queue_id is
492 * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ
495 * - 0: Success, Receive queue deleted correctly.
496 * - <0: Error code on failure.
498 int rte_event_eth_rx_adapter_queue_del(uint8_t id, uint16_t eth_dev_id,
499 int32_t rx_queue_id);
502 * Start ethernet Rx event adapter
505 * Adapter identifier.
508 * - 0: Success, Adapter started correctly.
509 * - <0: Error code on failure.
512 * The eventdev to which the event_eth_rx_adapter is connected needs to
513 * be started before calling rte_event_eth_rx_adapter_start().
515 int rte_event_eth_rx_adapter_start(uint8_t id);
518 * Stop ethernet Rx event adapter
521 * Adapter identifier.
524 * - 0: Success, Adapter started correctly.
525 * - <0: Error code on failure.
527 int rte_event_eth_rx_adapter_stop(uint8_t id);
530 * Retrieve statistics for an adapter
533 * Adapter identifier.
536 * A pointer to structure used to retrieve statistics for an adapter.
539 * - 0: Success, retrieved successfully.
540 * - <0: Error code on failure.
542 int rte_event_eth_rx_adapter_stats_get(uint8_t id,
543 struct rte_event_eth_rx_adapter_stats *stats);
546 * Reset statistics for an adapter.
549 * Adapter identifier.
552 * - 0: Success, statistics reset successfully.
553 * - <0: Error code on failure.
555 int rte_event_eth_rx_adapter_stats_reset(uint8_t id);
558 * Retrieve the service ID of an adapter. If the adapter doesn't use
559 * a rte_service function, this function returns -ESRCH.
562 * Adapter identifier.
564 * @param [out] service_id
565 * A pointer to a uint32_t, to be filled in with the service id.
569 * - <0: Error code on failure, if the adapter doesn't use a rte_service
570 * function, this function returns -ESRCH.
572 int rte_event_eth_rx_adapter_service_id_get(uint8_t id, uint32_t *service_id);
575 * Register callback to process Rx packets, this is supported for
576 * SW based packet transfers.
577 * @see rte_event_eth_rx_cb_fn
580 * Adapter identifier.
582 * Port identifier of Ethernet device.
589 * - <0: Error code on failure.
591 int rte_event_eth_rx_adapter_cb_register(uint8_t id, uint16_t eth_dev_id,
592 rte_event_eth_rx_adapter_cb_fn cb_fn,
596 * Retrieve vector limits for a given event dev and eth dev pair.
597 * @see rte_event_eth_rx_adapter_vector_limits
600 * Event device identifier.
602 * Port identifier of the ethernet device.
603 * @param [out] limits
604 * A pointer to rte_event_eth_rx_adapter_vector_limits structure that has to
609 * - <0: Error code on failure.
611 int rte_event_eth_rx_adapter_vector_limits_get(
612 uint8_t dev_id, uint16_t eth_port_id,
613 struct rte_event_eth_rx_adapter_vector_limits *limits);
616 * Retrieve Rx queue config information.
619 * Adapter identifier.
622 * Port identifier of Ethernet device.
625 * Ethernet device receive queue index.
627 * @param[out] queue_conf
628 * Pointer to struct rte_event_eth_rx_adapter_queue_conf
631 * - 0: Success, Receive queue added correctly.
632 * - <0: Error code on failure.
635 int rte_event_eth_rx_adapter_queue_conf_get(uint8_t id,
637 uint16_t rx_queue_id,
638 struct rte_event_eth_rx_adapter_queue_conf *queue_conf);
641 * Retrieve Rx queue statistics.
644 * Adapter identifier.
647 * Port identifier of Ethernet device.
650 * Ethernet device receive queue index.
653 * Pointer to struct rte_event_eth_rx_adapter_queue_stats
656 * - 0: Success, queue buffer stats retrieved.
657 * - <0: Error code on failure.
661 rte_event_eth_rx_adapter_queue_stats_get(uint8_t id,
663 uint16_t rx_queue_id,
664 struct rte_event_eth_rx_adapter_queue_stats *stats);
667 * Reset Rx queue statistics.
670 * Adapter identifier.
673 * Port identifier of Ethernet device.
676 * Ethernet device receive queue index.
679 * - 0: Success, queue buffer stats retrieved.
680 * - <0: Error code on failure.
684 rte_event_eth_rx_adapter_queue_stats_reset(uint8_t id,
686 uint16_t rx_queue_id);
689 * Retrieve the event port ID of an adapter. If the adapter doesn't use
690 * a rte_service function, this function returns -ESRCH.
693 * Adapter identifier.
695 * @param [out] event_port_id
696 * A pointer to a uint8_t, to be filled in with the port id.
700 * - <0: Error code on failure, if the adapter doesn't use a rte_service
701 * function, this function returns -ESRCH.
705 rte_event_eth_rx_adapter_event_port_get(uint8_t id, uint8_t *event_port_id);
710 #endif /* _RTE_EVENT_ETH_RX_ADAPTER_ */