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.
67 * 1) Devices created after an instance of rte_event_eth_rx_adapter_create
68 * should be added to a new instance of the rx adapter.
77 #include <rte_service.h>
79 #include "rte_eventdev.h"
81 #define RTE_EVENT_ETH_RX_ADAPTER_MAX_INSTANCE 32
83 /* struct rte_event_eth_rx_adapter_queue_conf flags definitions */
84 #define RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID 0x1
85 /**< This flag indicates the flow identifier is valid
86 * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags
91 * @b EXPERIMENTAL: this API may change without prior notice
93 * Adapter configuration structure that the adapter configuration callback
94 * function is expected to fill out
95 * @see rte_event_eth_rx_adapter_conf_cb
97 struct rte_event_eth_rx_adapter_conf {
98 uint8_t event_port_id;
99 /**< Event port identifier, the adapter enqueues mbuf events to this
103 /**< The adapter can return early if it has processed at least
104 * max_nb_rx mbufs. This isn't treated as a requirement; batching may
105 * cause the adapter to process more than max_nb_rx mbufs.
111 * @b EXPERIMENTAL: this API may change without prior notice
113 * Function type used for adapter configuration callback. The callback is
114 * used to fill in members of the struct rte_event_eth_rx_adapter_conf, this
115 * callback is invoked when creating a SW service for packet transfer from
116 * ethdev queues to the event device. The SW service is created within the
117 * rte_event_eth_rx_adapter_queue_add() function if SW based packet transfers
118 * from ethdev queues to the event device are required.
121 * Adapter identifier.
124 * Event device identifier.
127 * Structure that needs to be populated by this callback.
130 * Argument to the callback. This is the same as the conf_arg passed to the
131 * rte_event_eth_rx_adapter_create_ext().
133 typedef int (*rte_event_eth_rx_adapter_conf_cb) (uint8_t id, uint8_t dev_id,
134 struct rte_event_eth_rx_adapter_conf *conf,
139 * @b EXPERIMENTAL: this API may change without prior notice
141 * Rx queue configuration structure
143 struct rte_event_eth_rx_adapter_queue_conf {
144 uint32_t rx_queue_flags;
145 /**< Flags for handling received packets
146 * @see RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID
148 uint16_t servicing_weight;
149 /**< Relative polling frequency of ethernet receive queue when the
150 * adapter uses a service core function for ethernet to event device
151 * transfers. If it is set to zero, the Rx queue is interrupt driven
152 * (unless rx queue interrupts are not enabled for the ethernet
157 * The values from the following event fields will be used when
158 * queuing mbuf events:
159 * - event_queue_id: Targeted event queue ID for received packets.
160 * - event_priority: Event priority of packets from this Rx queue in
161 * the event queue relative to other events.
162 * - sched_type: Scheduling type for packets from this Rx queue.
163 * - flow_id: If the RTE_ETH_RX_EVENT_ADAPTER_QUEUE_FLOW_ID_VALID bit
164 * is set in rx_queue_flags, this flow_id is used for all
165 * packets received from this queue. Otherwise the flow ID
166 * is set to the RSS hash of the src and dst IPv4/6
169 * The event adapter sets ev.event_type to RTE_EVENT_TYPE_ETHDEV in the
176 * @b EXPERIMENTAL: this API may change without prior notice
178 * A structure used to retrieve statistics for an eth rx adapter instance.
180 struct rte_event_eth_rx_adapter_stats {
181 uint64_t rx_poll_count;
182 /**< Receive queue poll count */
184 /**< Received packet count */
185 uint64_t rx_enq_count;
186 /**< Eventdev enqueue count */
187 uint64_t rx_enq_retry;
188 /**< Eventdev enqueue retry count */
189 uint64_t rx_enq_start_ts;
190 /**< Rx enqueue start timestamp */
191 uint64_t rx_enq_block_cycles;
192 /**< Cycles for which the service is blocked by the event device,
193 * i.e, the service fails to enqueue to the event device.
195 uint64_t rx_enq_end_ts;
196 /**< Latest timestamp at which the service is unblocked
197 * by the event device. The start, end timestamps and
198 * block cycles can be used to compute the percentage of
199 * cycles the service is blocked by the event device.
201 uint64_t rx_intr_packets;
202 /**< Received packet count for interrupt mode Rx queues */
207 * @b EXPERIMENTAL: this API may change without prior notice
209 * Create a new ethernet Rx event adapter with the specified identifier.
212 * The identifier of the ethernet Rx event adapter.
215 * The identifier of the device to configure.
218 * Callback function that fills in members of a
219 * struct rte_event_eth_rx_adapter_conf struct passed into
223 * Argument that is passed to the conf_cb function.
227 * - <0: Error code on failure
229 int rte_event_eth_rx_adapter_create_ext(uint8_t id, uint8_t dev_id,
230 rte_event_eth_rx_adapter_conf_cb conf_cb,
235 * @b EXPERIMENTAL: this API may change without prior notice
237 * Create a new ethernet Rx event adapter with the specified identifier.
238 * This function uses an internal configuration function that creates an event
239 * port. This default function reconfigures the event device with an
240 * additional event port and setups up the event port using the port_config
241 * parameter passed into this function. In case the application needs more
242 * control in configuration of the service, it should use the
243 * rte_event_eth_rx_adapter_create_ext() version.
246 * The identifier of the ethernet Rx event adapter.
249 * The identifier of the device to configure.
252 * Argument of type *rte_event_port_conf* that is passed to the conf_cb
257 * - <0: Error code on failure
259 int rte_event_eth_rx_adapter_create(uint8_t id, uint8_t dev_id,
260 struct rte_event_port_conf *port_config);
264 * @b EXPERIMENTAL: this API may change without prior notice
266 * Free an event adapter
269 * Adapter identifier.
273 * - <0: Error code on failure, If the adapter still has Rx queues
274 * added to it, the function returns -EBUSY.
276 int rte_event_eth_rx_adapter_free(uint8_t id);
280 * @b EXPERIMENTAL: this API may change without prior notice
282 * Add receive queue to an event adapter. After a queue has been
283 * added to the event adapter, the result of the application calling
284 * rte_eth_rx_burst(eth_dev_id, rx_queue_id, ..) is undefined.
287 * Adapter identifier.
290 * Port identifier of Ethernet device.
293 * Ethernet device receive queue index.
294 * If rx_queue_id is -1, then all Rx queues configured for
295 * the device are added. If the ethdev Rx queues can only be
296 * connected to a single event queue then rx_queue_id is
298 * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ
301 * Additional configuration structure of type *rte_event_eth_rx_adapter_conf*
304 * - 0: Success, Receive queue added correctly.
305 * - <0: Error code on failure.
306 * - (-EIO) device reconfiguration and restart error. The adapter reconfigures
307 * the event device with an additional port if it is required to use a service
308 * function for packet transfer from the ethernet device to the event device.
309 * If the device had been started before this call, this error code indicates
310 * an error in restart following an error in reconfiguration, i.e., a
311 * combination of the two error codes.
313 int rte_event_eth_rx_adapter_queue_add(uint8_t id,
316 const struct rte_event_eth_rx_adapter_queue_conf *conf);
320 * @b EXPERIMENTAL: this API may change without prior notice
322 * Delete receive queue from an event adapter.
325 * Adapter identifier.
328 * Port identifier of Ethernet device.
331 * Ethernet device receive queue index.
332 * If rx_queue_id is -1, then all Rx queues configured for
333 * the device are deleted. If the ethdev Rx queues can only be
334 * connected to a single event queue then rx_queue_id is
336 * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ
339 * - 0: Success, Receive queue deleted correctly.
340 * - <0: Error code on failure.
342 int rte_event_eth_rx_adapter_queue_del(uint8_t id, uint16_t eth_dev_id,
343 int32_t rx_queue_id);
347 * @b EXPERIMENTAL: this API may change without prior notice
349 * Start ethernet Rx event adapter
352 * Adapter identifier.
355 * - 0: Success, Adapter started correctly.
356 * - <0: Error code on failure.
358 int rte_event_eth_rx_adapter_start(uint8_t id);
362 * @b EXPERIMENTAL: this API may change without prior notice
364 * Stop ethernet Rx event adapter
367 * Adapter identifier.
370 * - 0: Success, Adapter started correctly.
371 * - <0: Error code on failure.
373 int rte_event_eth_rx_adapter_stop(uint8_t id);
377 * @b EXPERIMENTAL: this API may change without prior notice
379 * Retrieve statistics for an adapter
382 * Adapter identifier.
385 * A pointer to structure used to retrieve statistics for an adapter.
388 * - 0: Success, retrieved successfully.
389 * - <0: Error code on failure.
391 int rte_event_eth_rx_adapter_stats_get(uint8_t id,
392 struct rte_event_eth_rx_adapter_stats *stats);
396 * @b EXPERIMENTAL: this API may change without prior notice
398 * Reset statistics for an adapter.
401 * Adapter identifier.
404 * - 0: Success, statistics reset successfully.
405 * - <0: Error code on failure.
407 int rte_event_eth_rx_adapter_stats_reset(uint8_t id);
411 * @b EXPERIMENTAL: this API may change without prior notice
413 * Retrieve the service ID of an adapter. If the adapter doesn't use
414 * a rte_service function, this function returns -ESRCH.
417 * Adapter identifier.
419 * @param [out] service_id
420 * A pointer to a uint32_t, to be filled in with the service id.
424 * - <0: Error code on failure, if the adapter doesn't use a rte_service
425 * function, this function returns -ESRCH.
427 int rte_event_eth_rx_adapter_service_id_get(uint8_t id, uint32_t *service_id);
432 #endif /* _RTE_EVENT_ETH_RX_ADAPTER_ */