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. For SW based packet
25 * transfer, if the mbuf does not have a timestamp set, the adapter adds a
26 * timestamp to the mbuf using rte_get_tsc_cycles(), this provides a more
27 * accurate timestamp as compared to if the application were to set the time
28 * stamp since it avoids event device schedule latency.
30 * The ethernet Rx event adapter's functions are:
31 * - rte_event_eth_rx_adapter_create_ext()
32 * - rte_event_eth_rx_adapter_create()
33 * - rte_event_eth_rx_adapter_free()
34 * - rte_event_eth_rx_adapter_queue_add()
35 * - rte_event_eth_rx_adapter_queue_del()
36 * - rte_event_eth_rx_adapter_start()
37 * - rte_event_eth_rx_adapter_stop()
38 * - rte_event_eth_rx_adapter_stats_get()
39 * - rte_event_eth_rx_adapter_stats_reset()
41 * The application creates an ethernet to event adapter using
42 * rte_event_eth_rx_adapter_create_ext() or rte_event_eth_rx_adapter_create()
44 * The adapter needs to know which ethernet rx queues to poll for mbufs as well
45 * as event device parameters such as the event queue identifier, event
46 * priority and scheduling type that the adapter should use when constructing
47 * events. The rte_event_eth_rx_adapter_queue_add() function is provided for
49 * The servicing weight parameter in the rte_event_eth_rx_adapter_queue_conf
50 * is applicable when the Rx adapter uses a service core function and is
51 * intended to provide application control of the frequency of polling ethernet
52 * device receive queues, for example, the application may want to poll higher
53 * priority queues with a higher frequency but at the same time not starve
54 * lower priority queues completely. If this parameter is zero and the receive
55 * interrupt is enabled when configuring the device, the receive queue is
56 * interrupt driven; else, the queue is assigned a servicing weight of one.
58 * The application can start/stop the adapter using the
59 * rte_event_eth_rx_adapter_start() and the rte_event_eth_rx_adapter_stop()
60 * functions. If the adapter uses a rte_service function, then the application
61 * is also required to assign a core to the service function and control the
62 * service core using the rte_service APIs. The
63 * rte_event_eth_rx_adapter_service_id_get() function can be used to retrieve
64 * the service function ID of the adapter in this case.
66 * For SW based packet transfers, i.e., when the
67 * RTE_EVENT_ETH_RX_ADAPTER_CAP_INTERNAL_PORT is not set in the adapter's
68 * capabilities flags for a particular ethernet device, the service function
69 * temporarily enqueues mbufs to an event buffer before batch enqueueing these
70 * to the event device. If the buffer fills up, the service function stops
71 * dequeueing packets from the ethernet device. The application may want to
72 * monitor the buffer fill level and instruct the service function to
73 * selectively buffer packets. The application may also use some other
74 * criteria to decide which packets should enter the event device even when
75 * the event buffer fill level is low. The
76 * rte_event_eth_rx_adapter_cb_register() function allows the
77 * application to register a callback that selects which packets to enqueue
78 * to the event device.
81 * 1) Devices created after an instance of rte_event_eth_rx_adapter_create
82 * should be added to a new instance of the rx adapter.
91 #include <rte_service.h>
93 #include "rte_eventdev.h"
95 #define RTE_EVENT_ETH_RX_ADAPTER_MAX_INSTANCE 32
97 /* struct rte_event_eth_rx_adapter_queue_conf flags definitions */
98 #define RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID 0x1
99 /**< This flag indicates the flow identifier is valid
100 * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags
105 * @b EXPERIMENTAL: this API may change without prior notice
107 * Adapter configuration structure that the adapter configuration callback
108 * function is expected to fill out
109 * @see rte_event_eth_rx_adapter_conf_cb
111 struct rte_event_eth_rx_adapter_conf {
112 uint8_t event_port_id;
113 /**< Event port identifier, the adapter enqueues mbuf events to this
117 /**< The adapter can return early if it has processed at least
118 * max_nb_rx mbufs. This isn't treated as a requirement; batching may
119 * cause the adapter to process more than max_nb_rx mbufs.
125 * @b EXPERIMENTAL: this API may change without prior notice
127 * Function type used for adapter configuration callback. The callback is
128 * used to fill in members of the struct rte_event_eth_rx_adapter_conf, this
129 * callback is invoked when creating a SW service for packet transfer from
130 * ethdev queues to the event device. The SW service is created within the
131 * rte_event_eth_rx_adapter_queue_add() function if SW based packet transfers
132 * from ethdev queues to the event device are required.
135 * Adapter identifier.
138 * Event device identifier.
141 * Structure that needs to be populated by this callback.
144 * Argument to the callback. This is the same as the conf_arg passed to the
145 * rte_event_eth_rx_adapter_create_ext().
147 typedef int (*rte_event_eth_rx_adapter_conf_cb) (uint8_t id, uint8_t dev_id,
148 struct rte_event_eth_rx_adapter_conf *conf,
153 * @b EXPERIMENTAL: this API may change without prior notice
155 * Rx queue configuration structure
157 struct rte_event_eth_rx_adapter_queue_conf {
158 uint32_t rx_queue_flags;
159 /**< Flags for handling received packets
160 * @see RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID
162 uint16_t servicing_weight;
163 /**< Relative polling frequency of ethernet receive queue when the
164 * adapter uses a service core function for ethernet to event device
165 * transfers. If it is set to zero, the Rx queue is interrupt driven
166 * (unless rx queue interrupts are not enabled for the ethernet
171 * The values from the following event fields will be used when
172 * queuing mbuf events:
173 * - event_queue_id: Targeted event queue ID for received packets.
174 * - event_priority: Event priority of packets from this Rx queue in
175 * the event queue relative to other events.
176 * - sched_type: Scheduling type for packets from this Rx queue.
177 * - flow_id: If the RTE_ETH_RX_EVENT_ADAPTER_QUEUE_FLOW_ID_VALID bit
178 * is set in rx_queue_flags, this flow_id is used for all
179 * packets received from this queue. Otherwise the flow ID
180 * is set to the RSS hash of the src and dst IPv4/6
183 * The event adapter sets ev.event_type to RTE_EVENT_TYPE_ETHDEV in the
190 * @b EXPERIMENTAL: this API may change without prior notice
192 * A structure used to retrieve statistics for an eth rx adapter instance.
194 struct rte_event_eth_rx_adapter_stats {
195 uint64_t rx_poll_count;
196 /**< Receive queue poll count */
198 /**< Received packet count */
199 uint64_t rx_enq_count;
200 /**< Eventdev enqueue count */
201 uint64_t rx_enq_retry;
202 /**< Eventdev enqueue retry count */
203 uint64_t rx_enq_start_ts;
204 /**< Rx enqueue start timestamp */
205 uint64_t rx_enq_block_cycles;
206 /**< Cycles for which the service is blocked by the event device,
207 * i.e, the service fails to enqueue to the event device.
209 uint64_t rx_enq_end_ts;
210 /**< Latest timestamp at which the service is unblocked
211 * by the event device. The start, end timestamps and
212 * block cycles can be used to compute the percentage of
213 * cycles the service is blocked by the event device.
215 uint64_t rx_intr_packets;
216 /**< Received packet count for interrupt mode Rx queues */
221 * @b EXPERIMENTAL: this API may change without prior notice
223 * Callback function invoked by the SW adapter before it continues
224 * to process packets. The callback is passed the size of the enqueue
225 * buffer in the SW adapter and the occupancy of the buffer. The
226 * callback can use these values to decide which mbufs should be
227 * enqueued to the event device. If the return value of the callback
228 * is less than nb_mbuf then the SW adapter uses the return value to
229 * enqueue enq_mbuf[] to the event device.
232 * Port identifier of the Ethernet device.
234 * Receive queue index.
235 * @param enqueue_buf_size
236 * Total enqueue buffer size.
237 * @param enqueue_buf_count
238 * mbuf count in enqueue buffer.
245 * @param[out] enq_mbuf
246 * The adapter enqueues enq_mbuf[] if the return value of the
247 * callback is less than nb_mbuf
249 * Returns the number of mbufs should be enqueued to eventdev
251 typedef uint16_t (*rte_event_eth_rx_adapter_cb_fn)(uint16_t eth_dev_id,
253 uint32_t enqueue_buf_size,
254 uint32_t enqueue_buf_count,
255 struct rte_mbuf **mbuf,
258 struct rte_mbuf **enq_buf);
262 * @b EXPERIMENTAL: this API may change without prior notice
264 * Create a new ethernet Rx event adapter with the specified identifier.
267 * The identifier of the ethernet Rx event adapter.
270 * The identifier of the device to configure.
273 * Callback function that fills in members of a
274 * struct rte_event_eth_rx_adapter_conf struct passed into
278 * Argument that is passed to the conf_cb function.
282 * - <0: Error code on failure
284 int rte_event_eth_rx_adapter_create_ext(uint8_t id, uint8_t dev_id,
285 rte_event_eth_rx_adapter_conf_cb conf_cb,
290 * @b EXPERIMENTAL: this API may change without prior notice
292 * Create a new ethernet Rx event adapter with the specified identifier.
293 * This function uses an internal configuration function that creates an event
294 * port. This default function reconfigures the event device with an
295 * additional event port and setups up the event port using the port_config
296 * parameter passed into this function. In case the application needs more
297 * control in configuration of the service, it should use the
298 * rte_event_eth_rx_adapter_create_ext() version.
301 * The identifier of the ethernet Rx event adapter.
304 * The identifier of the device to configure.
307 * Argument of type *rte_event_port_conf* that is passed to the conf_cb
312 * - <0: Error code on failure
314 int rte_event_eth_rx_adapter_create(uint8_t id, uint8_t dev_id,
315 struct rte_event_port_conf *port_config);
319 * @b EXPERIMENTAL: this API may change without prior notice
321 * Free an event adapter
324 * Adapter identifier.
328 * - <0: Error code on failure, If the adapter still has Rx queues
329 * added to it, the function returns -EBUSY.
331 int rte_event_eth_rx_adapter_free(uint8_t id);
335 * @b EXPERIMENTAL: this API may change without prior notice
337 * Add receive queue to an event adapter. After a queue has been
338 * added to the event adapter, the result of the application calling
339 * rte_eth_rx_burst(eth_dev_id, rx_queue_id, ..) is undefined.
342 * Adapter identifier.
345 * Port identifier of Ethernet device.
348 * Ethernet device receive queue index.
349 * If rx_queue_id is -1, then all Rx queues configured for
350 * the device are added. If the ethdev Rx queues can only be
351 * connected to a single event queue then rx_queue_id is
353 * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ
356 * Additional configuration structure of type *rte_event_eth_rx_adapter_conf*
359 * - 0: Success, Receive queue added correctly.
360 * - <0: Error code on failure.
361 * - (-EIO) device reconfiguration and restart error. The adapter reconfigures
362 * the event device with an additional port if it is required to use a service
363 * function for packet transfer from the ethernet device to the event device.
364 * If the device had been started before this call, this error code indicates
365 * an error in restart following an error in reconfiguration, i.e., a
366 * combination of the two error codes.
368 int rte_event_eth_rx_adapter_queue_add(uint8_t id,
371 const struct rte_event_eth_rx_adapter_queue_conf *conf);
375 * @b EXPERIMENTAL: this API may change without prior notice
377 * Delete receive queue from an event adapter.
380 * Adapter identifier.
383 * Port identifier of Ethernet device.
386 * Ethernet device receive queue index.
387 * If rx_queue_id is -1, then all Rx queues configured for
388 * the device are deleted. If the ethdev Rx queues can only be
389 * connected to a single event queue then rx_queue_id is
391 * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ
394 * - 0: Success, Receive queue deleted correctly.
395 * - <0: Error code on failure.
397 int rte_event_eth_rx_adapter_queue_del(uint8_t id, uint16_t eth_dev_id,
398 int32_t rx_queue_id);
402 * @b EXPERIMENTAL: this API may change without prior notice
404 * Start ethernet Rx event adapter
407 * Adapter identifier.
410 * - 0: Success, Adapter started correctly.
411 * - <0: Error code on failure.
413 int rte_event_eth_rx_adapter_start(uint8_t id);
417 * @b EXPERIMENTAL: this API may change without prior notice
419 * Stop ethernet Rx event adapter
422 * Adapter identifier.
425 * - 0: Success, Adapter started correctly.
426 * - <0: Error code on failure.
428 int rte_event_eth_rx_adapter_stop(uint8_t id);
432 * @b EXPERIMENTAL: this API may change without prior notice
434 * Retrieve statistics for an adapter
437 * Adapter identifier.
440 * A pointer to structure used to retrieve statistics for an adapter.
443 * - 0: Success, retrieved successfully.
444 * - <0: Error code on failure.
446 int rte_event_eth_rx_adapter_stats_get(uint8_t id,
447 struct rte_event_eth_rx_adapter_stats *stats);
451 * @b EXPERIMENTAL: this API may change without prior notice
453 * Reset statistics for an adapter.
456 * Adapter identifier.
459 * - 0: Success, statistics reset successfully.
460 * - <0: Error code on failure.
462 int rte_event_eth_rx_adapter_stats_reset(uint8_t id);
466 * @b EXPERIMENTAL: this API may change without prior notice
468 * Retrieve the service ID of an adapter. If the adapter doesn't use
469 * a rte_service function, this function returns -ESRCH.
472 * Adapter identifier.
474 * @param [out] service_id
475 * A pointer to a uint32_t, to be filled in with the service id.
479 * - <0: Error code on failure, if the adapter doesn't use a rte_service
480 * function, this function returns -ESRCH.
482 int rte_event_eth_rx_adapter_service_id_get(uint8_t id, uint32_t *service_id);
486 * @b EXPERIMENTAL: this API may change without prior notice
488 * Register callback to process Rx packets, this is supported for
489 * SW based packet transfers.
490 * @see rte_event_eth_rx_cb_fn
493 * Adapter identifier.
495 * Port identifier of Ethernet device.
502 * - <0: Error code on failure.
504 int __rte_experimental
505 rte_event_eth_rx_adapter_cb_register(uint8_t id,
507 rte_event_eth_rx_adapter_cb_fn cb_fn,
513 #endif /* _RTE_EVENT_ETH_RX_ADAPTER_ */