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_free()
30 * - rte_event_eth_rx_adapter_queue_add()
31 * - rte_event_eth_rx_adapter_queue_del()
32 * - rte_event_eth_rx_adapter_start()
33 * - rte_event_eth_rx_adapter_stop()
34 * - rte_event_eth_rx_adapter_stats_get()
35 * - rte_event_eth_rx_adapter_stats_reset()
37 * The application creates an ethernet to event adapter using
38 * rte_event_eth_rx_adapter_create_ext() or rte_event_eth_rx_adapter_create()
40 * The adapter needs to know which ethernet rx queues to poll for mbufs as well
41 * as event device parameters such as the event queue identifier, event
42 * priority and scheduling type that the adapter should use when constructing
43 * events. The rte_event_eth_rx_adapter_queue_add() function is provided for
45 * The servicing weight parameter in the rte_event_eth_rx_adapter_queue_conf
46 * is applicable when the Rx adapter uses a service core function and is
47 * intended to provide application control of the frequency of polling ethernet
48 * device receive queues, for example, the application may want to poll higher
49 * priority queues with a higher frequency but at the same time not starve
50 * lower priority queues completely. If this parameter is zero and the receive
51 * interrupt is enabled when configuring the device, the receive queue is
52 * interrupt driven; else, the queue is assigned a servicing weight of one.
54 * The application can start/stop the adapter using the
55 * rte_event_eth_rx_adapter_start() and the rte_event_eth_rx_adapter_stop()
56 * functions. If the adapter uses a rte_service function, then the application
57 * is also required to assign a core to the service function and control the
58 * service core using the rte_service APIs. The
59 * rte_event_eth_rx_adapter_service_id_get() function can be used to retrieve
60 * the service function ID of the adapter in this case.
62 * For SW based packet transfers, i.e., when the
63 * RTE_EVENT_ETH_RX_ADAPTER_CAP_INTERNAL_PORT is not set in the adapter's
64 * capabilities flags for a particular ethernet device, the service function
65 * temporarily enqueues events to an event buffer before batch enqueuing these
66 * to the event device. If the buffer fills up, the service function stops
67 * dequeuing packets from the ethernet device. The application may want to
68 * monitor the buffer fill level and instruct the service function to
69 * selectively buffer events. The application may also use some other
70 * criteria to decide which packets should enter the event device even when
71 * the event buffer fill level is low or may want to enqueue packets to an
72 * internal event port. The rte_event_eth_rx_adapter_cb_register() function
73 * allows the application to register a callback that selects which packets are
74 * enqueued to the event device by the SW adapter. The callback interface is
75 * event based so the callback can also modify the event data if it needs to.
84 #include <rte_service.h>
86 #include "rte_eventdev.h"
88 #define RTE_EVENT_ETH_RX_ADAPTER_MAX_INSTANCE 32
90 /* struct rte_event_eth_rx_adapter_queue_conf flags definitions */
91 #define RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID 0x1
92 /**< This flag indicates the flow identifier is valid
93 * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags
95 #define RTE_EVENT_ETH_RX_ADAPTER_QUEUE_EVENT_VECTOR 0x2
96 /**< This flag indicates that mbufs arriving on the queue need to be vectorized
97 * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags
101 * Adapter configuration structure that the adapter configuration callback
102 * function is expected to fill out
103 * @see rte_event_eth_rx_adapter_conf_cb
105 struct rte_event_eth_rx_adapter_conf {
106 uint8_t event_port_id;
107 /**< Event port identifier, the adapter enqueues mbuf events to this
111 /**< The adapter can return early if it has processed at least
112 * max_nb_rx mbufs. This isn't treated as a requirement; batching may
113 * cause the adapter to process more than max_nb_rx mbufs.
118 * Function type used for adapter configuration callback. The callback is
119 * used to fill in members of the struct rte_event_eth_rx_adapter_conf, this
120 * callback is invoked when creating a SW service for packet transfer from
121 * ethdev queues to the event device. The SW service is created within the
122 * rte_event_eth_rx_adapter_queue_add() function if SW based packet transfers
123 * from ethdev queues to the event device are required.
126 * Adapter identifier.
129 * Event device identifier.
132 * Structure that needs to be populated by this callback.
135 * Argument to the callback. This is the same as the conf_arg passed to the
136 * rte_event_eth_rx_adapter_create_ext().
138 typedef int (*rte_event_eth_rx_adapter_conf_cb) (uint8_t id, uint8_t dev_id,
139 struct rte_event_eth_rx_adapter_conf *conf,
143 * Rx queue configuration structure
145 struct rte_event_eth_rx_adapter_queue_conf {
146 uint32_t rx_queue_flags;
147 /**< Flags for handling received packets
148 * @see RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID
150 uint16_t servicing_weight;
151 /**< Relative polling frequency of ethernet receive queue when the
152 * adapter uses a service core function for ethernet to event device
153 * transfers. If it is set to zero, the Rx queue is interrupt driven
154 * (unless rx queue interrupts are not enabled for the ethernet
159 * The values from the following event fields will be used when
160 * queuing mbuf events:
161 * - event_queue_id: Targeted event queue ID for received packets.
162 * - event_priority: Event priority of packets from this Rx queue in
163 * the event queue relative to other events.
164 * - sched_type: Scheduling type for packets from this Rx queue.
165 * - flow_id: If the RTE_ETH_RX_EVENT_ADAPTER_QUEUE_FLOW_ID_VALID bit
166 * is set in rx_queue_flags, this flow_id is used for all
167 * packets received from this queue. Otherwise the flow ID
168 * is set to the RSS hash of the src and dst IPv4/6
171 * The event adapter sets ev.event_type to RTE_EVENT_TYPE_ETHDEV in the
176 struct rte_event_eth_rx_adapter_event_vector_config {
179 * Indicates the maximum number for mbufs to combine and form a vector.
181 * @see rte_event_eth_rx_adapter_vector_limits::min_vector_sz
182 * @see rte_event_eth_rx_adapter_vector_limits::max_vector_sz
183 * Valid when RTE_EVENT_ETH_RX_ADAPTER_QUEUE_EVENT_VECTOR flag is set in
184 * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags
186 uint64_t vector_timeout_ns;
188 * Indicates the maximum number of nanoseconds to wait for receiving
189 * mbufs. Should be within vectorization limits of the
191 * @see rte_event_eth_rx_adapter_vector_limits::min_vector_ns
192 * @see rte_event_eth_rx_adapter_vector_limits::max_vector_ns
193 * Valid when RTE_EVENT_ETH_RX_ADAPTER_QUEUE_EVENT_VECTOR flag is set in
194 * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags
196 struct rte_mempool *vector_mp;
198 * Indicates the mempool that should be used for allocating
199 * rte_event_vector container.
200 * Should be created by using `rte_event_vector_pool_create`.
201 * Valid when RTE_EVENT_ETH_RX_ADAPTER_QUEUE_EVENT_VECTOR flag is set in
202 * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags.
207 * A structure used to retrieve statistics for an eth rx adapter instance.
209 struct rte_event_eth_rx_adapter_stats {
210 uint64_t rx_poll_count;
211 /**< Receive queue poll count */
213 /**< Received packet count */
214 uint64_t rx_enq_count;
215 /**< Eventdev enqueue count */
216 uint64_t rx_enq_retry;
217 /**< Eventdev enqueue retry count */
219 /**< Received packet dropped count */
220 uint64_t rx_enq_start_ts;
221 /**< Rx enqueue start timestamp */
222 uint64_t rx_enq_block_cycles;
223 /**< Cycles for which the service is blocked by the event device,
224 * i.e, the service fails to enqueue to the event device.
226 uint64_t rx_enq_end_ts;
227 /**< Latest timestamp at which the service is unblocked
228 * by the event device. The start, end timestamps and
229 * block cycles can be used to compute the percentage of
230 * cycles the service is blocked by the event device.
232 uint64_t rx_intr_packets;
233 /**< Received packet count for interrupt mode Rx queues */
237 * A structure used to retrieve eth rx adapter vector limits.
239 struct rte_event_eth_rx_adapter_vector_limits {
241 /**< Minimum vector limit configurable.
242 * @see rte_event_eth_rx_adapter_event_vector_config::vector_sz
245 /**< Maximum vector limit configurable.
246 * @see rte_event_eth_rx_adapter_event_vector_config::vector_sz
249 /**< True if the size configured should be in log2.
250 * @see rte_event_eth_rx_adapter_event_vector_config::vector_sz
252 uint64_t min_timeout_ns;
253 /**< Minimum vector timeout configurable.
254 * @see rte_event_eth_rx_adapter_event_vector_config::vector_timeout_ns
256 uint64_t max_timeout_ns;
257 /**< Maximum vector timeout configurable.
258 * @see rte_event_eth_rx_adapter_event_vector_config::vector_timeout_ns
264 * Callback function invoked by the SW adapter before it continues
265 * to process events. The callback is passed the size of the enqueue
266 * buffer in the SW adapter and the occupancy of the buffer. The
267 * callback can use these values to decide which events are
268 * enqueued to the event device by the SW adapter. The callback may
269 * also enqueue events internally using its own event port. The SW
270 * adapter populates the event information based on the Rx queue
271 * configuration in the adapter. The callback can modify the this event
272 * information for the events to be enqueued by the SW adapter.
274 * The callback return value is the number of events from the
275 * beginning of the event array that are to be enqueued by
276 * the SW adapter. It is the callback's responsibility to arrange
277 * these events at the beginning of the array, if these events are
278 * not contiguous in the original array. The *nb_dropped* parameter is
279 * a pointer to the number of events dropped by the callback, this
280 * number is used by the adapter to indicate the number of dropped packets
281 * as part of its statistics.
284 * Port identifier of the Ethernet device.
286 * Receive queue index.
287 * @param enqueue_buf_size
288 * Total enqueue buffer size.
289 * @param enqueue_buf_count
290 * Event count in enqueue buffer.
294 * Event array length.
297 * @param[out] nb_dropped
298 * Packets dropped by callback.
300 * - The number of events to be enqueued by the SW adapter.
302 typedef uint16_t (*rte_event_eth_rx_adapter_cb_fn)(uint16_t eth_dev_id,
304 uint32_t enqueue_buf_size,
305 uint32_t enqueue_buf_count,
306 struct rte_event *ev,
309 uint16_t *nb_dropped);
312 * Create a new ethernet Rx event adapter with the specified identifier.
315 * The identifier of the ethernet Rx event adapter.
318 * The identifier of the device to configure.
321 * Callback function that fills in members of a
322 * struct rte_event_eth_rx_adapter_conf struct passed into
326 * Argument that is passed to the conf_cb function.
330 * - <0: Error code on failure
332 int rte_event_eth_rx_adapter_create_ext(uint8_t id, uint8_t dev_id,
333 rte_event_eth_rx_adapter_conf_cb conf_cb,
337 * Create a new ethernet Rx event 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 setups 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_eth_rx_adapter_create_ext() version.
346 * The identifier of the ethernet Rx event adapter.
349 * The identifier of the device to configure.
352 * Argument of type *rte_event_port_conf* that is passed to the conf_cb
357 * - <0: Error code on failure
359 int rte_event_eth_rx_adapter_create(uint8_t id, uint8_t dev_id,
360 struct rte_event_port_conf *port_config);
363 * Free an event adapter
366 * Adapter identifier.
370 * - <0: Error code on failure, If the adapter still has Rx queues
371 * added to it, the function returns -EBUSY.
373 int rte_event_eth_rx_adapter_free(uint8_t id);
376 * Add receive queue to an event adapter. After a queue has been
377 * added to the event adapter, the result of the application calling
378 * rte_eth_rx_burst(eth_dev_id, rx_queue_id, ..) is undefined.
381 * Adapter identifier.
384 * Port identifier of Ethernet device.
387 * Ethernet device receive queue index.
388 * If rx_queue_id is -1, then all Rx queues configured for
389 * the device are added. If the ethdev Rx queues can only be
390 * connected to a single event queue then rx_queue_id is
392 * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ
395 * Additional configuration structure of type *rte_event_eth_rx_adapter_conf*
398 * - 0: Success, Receive queue added correctly.
399 * - <0: Error code on failure.
400 * - (-EIO) device reconfiguration and restart error. The adapter reconfigures
401 * the event device with an additional port if it is required to use a service
402 * function for packet transfer from the ethernet device to the event device.
403 * If the device had been started before this call, this error code indicates
404 * an error in restart following an error in reconfiguration, i.e., a
405 * combination of the two error codes.
407 int rte_event_eth_rx_adapter_queue_add(uint8_t id,
410 const struct rte_event_eth_rx_adapter_queue_conf *conf);
413 * Delete receive queue from an event adapter.
416 * Adapter identifier.
419 * Port identifier of Ethernet device.
422 * Ethernet device receive queue index.
423 * If rx_queue_id is -1, then all Rx queues configured for
424 * the device are deleted. If the ethdev Rx queues can only be
425 * connected to a single event queue then rx_queue_id is
427 * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ
430 * - 0: Success, Receive queue deleted correctly.
431 * - <0: Error code on failure.
433 int rte_event_eth_rx_adapter_queue_del(uint8_t id, uint16_t eth_dev_id,
434 int32_t rx_queue_id);
437 * Start ethernet Rx event adapter
440 * Adapter identifier.
443 * - 0: Success, Adapter started correctly.
444 * - <0: Error code on failure.
447 * The eventdev to which the event_eth_rx_adapter is connected needs to
448 * be started before calling rte_event_eth_rx_adapter_start().
450 int rte_event_eth_rx_adapter_start(uint8_t id);
453 * Stop ethernet Rx event adapter
456 * Adapter identifier.
459 * - 0: Success, Adapter started correctly.
460 * - <0: Error code on failure.
462 int rte_event_eth_rx_adapter_stop(uint8_t id);
465 * Retrieve statistics for an adapter
468 * Adapter identifier.
471 * A pointer to structure used to retrieve statistics for an adapter.
474 * - 0: Success, retrieved successfully.
475 * - <0: Error code on failure.
477 int rte_event_eth_rx_adapter_stats_get(uint8_t id,
478 struct rte_event_eth_rx_adapter_stats *stats);
481 * Reset statistics for an adapter.
484 * Adapter identifier.
487 * - 0: Success, statistics reset successfully.
488 * - <0: Error code on failure.
490 int rte_event_eth_rx_adapter_stats_reset(uint8_t id);
493 * Retrieve the service ID of an adapter. If the adapter doesn't use
494 * a rte_service function, this function returns -ESRCH.
497 * Adapter identifier.
499 * @param [out] service_id
500 * A pointer to a uint32_t, to be filled in with the service id.
504 * - <0: Error code on failure, if the adapter doesn't use a rte_service
505 * function, this function returns -ESRCH.
507 int rte_event_eth_rx_adapter_service_id_get(uint8_t id, uint32_t *service_id);
510 * Register callback to process Rx packets, this is supported for
511 * SW based packet transfers.
512 * @see rte_event_eth_rx_cb_fn
515 * Adapter identifier.
517 * Port identifier of Ethernet device.
524 * - <0: Error code on failure.
526 int rte_event_eth_rx_adapter_cb_register(uint8_t id, uint16_t eth_dev_id,
527 rte_event_eth_rx_adapter_cb_fn cb_fn,
531 * Retrieve vector limits for a given event dev and eth dev pair.
532 * @see rte_event_eth_rx_adapter_vector_limits
535 * Event device identifier.
537 * Port identifier of the ethernet device.
538 * @param [out] limits
539 * A pointer to rte_event_eth_rx_adapter_vector_limits structure that has to
544 * - <0: Error code on failure.
547 int rte_event_eth_rx_adapter_vector_limits_get(
548 uint8_t dev_id, uint16_t eth_port_id,
549 struct rte_event_eth_rx_adapter_vector_limits *limits);
552 * Configure event vectorization for a given ethernet device queue, that has
553 * been added to a event eth Rx adapter.
556 * The identifier of the ethernet Rx event adapter.
559 * The identifier of the ethernet device.
562 * Ethernet device receive queue index.
563 * If rx_queue_id is -1, then all Rx queues configured for the ethernet device
564 * are configured with event vectorization.
567 * Event vector configuration structure.
570 * - 0: Success, Receive queue configured correctly.
571 * - <0: Error code on failure.
574 int rte_event_eth_rx_adapter_queue_event_vector_config(
575 uint8_t id, uint16_t eth_dev_id, int32_t rx_queue_id,
576 struct rte_event_eth_rx_adapter_event_vector_config *config);
581 #endif /* _RTE_EVENT_ETH_RX_ADAPTER_ */