]>
Commit | Line | Data |
---|---|---|
11fdf7f2 TL |
1 | /* SPDX-License-Identifier: BSD-3-Clause |
2 | * Copyright(c) 2017 Intel Corporation. | |
3 | * All rights reserved. | |
4 | */ | |
5 | ||
6 | #ifndef _RTE_EVENT_ETH_RX_ADAPTER_ | |
7 | #define _RTE_EVENT_ETH_RX_ADAPTER_ | |
8 | ||
9 | /** | |
10 | * @file | |
11 | * | |
12 | * RTE Event Ethernet Rx Adapter | |
13 | * | |
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 | |
20 | * mechanisms. | |
21 | * | |
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. | |
29 | * | |
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() | |
40 | * | |
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() | |
43 | * functions. | |
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 | |
48 | * this purpose. | |
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. | |
57 | * | |
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. | |
65 | * | |
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 | |
f67539c2 | 69 | * temporarily enqueues events to an event buffer before batch enqueuing these |
11fdf7f2 | 70 | * to the event device. If the buffer fills up, the service function stops |
9f95a23c | 71 | * dequeuing packets from the ethernet device. The application may want to |
11fdf7f2 | 72 | * monitor the buffer fill level and instruct the service function to |
f67539c2 | 73 | * selectively buffer events. The application may also use some other |
11fdf7f2 | 74 | * criteria to decide which packets should enter the event device even when |
f67539c2 TL |
75 | * the event buffer fill level is low or may want to enqueue packets to an |
76 | * internal event port. The rte_event_eth_rx_adapter_cb_register() function | |
77 | * allows the application to register a callback that selects which packets are | |
78 | * enqueued to the event device by the SW adapter. The callback interface is | |
79 | * event based so the callback can also modify the event data if it needs to. | |
11fdf7f2 TL |
80 | */ |
81 | ||
82 | #ifdef __cplusplus | |
83 | extern "C" { | |
84 | #endif | |
85 | ||
86 | #include <stdint.h> | |
87 | ||
88 | #include <rte_service.h> | |
89 | ||
90 | #include "rte_eventdev.h" | |
91 | ||
92 | #define RTE_EVENT_ETH_RX_ADAPTER_MAX_INSTANCE 32 | |
93 | ||
94 | /* struct rte_event_eth_rx_adapter_queue_conf flags definitions */ | |
95 | #define RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID 0x1 | |
96 | /**< This flag indicates the flow identifier is valid | |
97 | * @see rte_event_eth_rx_adapter_queue_conf::rx_queue_flags | |
98 | */ | |
99 | ||
100 | /** | |
11fdf7f2 TL |
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 | |
104 | */ | |
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 | |
108 | * port. | |
109 | */ | |
110 | uint32_t max_nb_rx; | |
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. | |
114 | */ | |
115 | }; | |
116 | ||
117 | /** | |
11fdf7f2 TL |
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. | |
124 | * | |
125 | * @param id | |
126 | * Adapter identifier. | |
127 | * | |
128 | * @param dev_id | |
129 | * Event device identifier. | |
130 | * | |
131 | * @param [out] conf | |
132 | * Structure that needs to be populated by this callback. | |
133 | * | |
134 | * @param arg | |
135 | * Argument to the callback. This is the same as the conf_arg passed to the | |
136 | * rte_event_eth_rx_adapter_create_ext(). | |
137 | */ | |
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, | |
140 | void *arg); | |
141 | ||
142 | /** | |
11fdf7f2 TL |
143 | * Rx queue configuration structure |
144 | */ | |
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 | |
149 | */ | |
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 | |
155 | * device). | |
156 | */ | |
157 | struct rte_event ev; | |
158 | /**< | |
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 | |
169 | * addresses. | |
170 | * | |
171 | * The event adapter sets ev.event_type to RTE_EVENT_TYPE_ETHDEV in the | |
172 | * enqueued event. | |
173 | */ | |
174 | }; | |
175 | ||
176 | /** | |
11fdf7f2 TL |
177 | * A structure used to retrieve statistics for an eth rx adapter instance. |
178 | */ | |
179 | struct rte_event_eth_rx_adapter_stats { | |
180 | uint64_t rx_poll_count; | |
181 | /**< Receive queue poll count */ | |
182 | uint64_t rx_packets; | |
183 | /**< Received packet count */ | |
184 | uint64_t rx_enq_count; | |
185 | /**< Eventdev enqueue count */ | |
186 | uint64_t rx_enq_retry; | |
187 | /**< Eventdev enqueue retry count */ | |
f67539c2 TL |
188 | uint64_t rx_dropped; |
189 | /**< Received packet dropped count */ | |
11fdf7f2 TL |
190 | uint64_t rx_enq_start_ts; |
191 | /**< Rx enqueue start timestamp */ | |
192 | uint64_t rx_enq_block_cycles; | |
193 | /**< Cycles for which the service is blocked by the event device, | |
194 | * i.e, the service fails to enqueue to the event device. | |
195 | */ | |
196 | uint64_t rx_enq_end_ts; | |
197 | /**< Latest timestamp at which the service is unblocked | |
198 | * by the event device. The start, end timestamps and | |
199 | * block cycles can be used to compute the percentage of | |
200 | * cycles the service is blocked by the event device. | |
201 | */ | |
202 | uint64_t rx_intr_packets; | |
203 | /**< Received packet count for interrupt mode Rx queues */ | |
204 | }; | |
205 | ||
206 | /** | |
11fdf7f2 TL |
207 | * |
208 | * Callback function invoked by the SW adapter before it continues | |
f67539c2 | 209 | * to process events. The callback is passed the size of the enqueue |
11fdf7f2 | 210 | * buffer in the SW adapter and the occupancy of the buffer. The |
f67539c2 TL |
211 | * callback can use these values to decide which events are |
212 | * enqueued to the event device by the SW adapter. The callback may | |
213 | * also enqueue events internally using its own event port. The SW | |
214 | * adapter populates the event information based on the Rx queue | |
215 | * configuration in the adapter. The callback can modify the this event | |
216 | * information for the events to be enqueued by the SW adapter. | |
217 | * | |
218 | * The callback return value is the number of events from the | |
219 | * beginning of the event array that are to be enqueued by | |
220 | * the SW adapter. It is the callback's responsibility to arrange | |
221 | * these events at the beginning of the array, if these events are | |
222 | * not contiguous in the original array. The *nb_dropped* parameter is | |
223 | * a pointer to the number of events dropped by the callback, this | |
224 | * number is used by the adapter to indicate the number of dropped packets | |
225 | * as part of its statistics. | |
11fdf7f2 TL |
226 | * |
227 | * @param eth_dev_id | |
228 | * Port identifier of the Ethernet device. | |
229 | * @param queue_id | |
230 | * Receive queue index. | |
231 | * @param enqueue_buf_size | |
232 | * Total enqueue buffer size. | |
233 | * @param enqueue_buf_count | |
f67539c2 TL |
234 | * Event count in enqueue buffer. |
235 | * @param[in, out] ev | |
236 | * Event array. | |
237 | * @param nb_event | |
238 | * Event array length. | |
11fdf7f2 TL |
239 | * @param cb_arg |
240 | * Callback argument. | |
f67539c2 TL |
241 | * @param[out] nb_dropped |
242 | * Packets dropped by callback. | |
11fdf7f2 | 243 | * @return |
f67539c2 | 244 | * - The number of events to be enqueued by the SW adapter. |
11fdf7f2 TL |
245 | */ |
246 | typedef uint16_t (*rte_event_eth_rx_adapter_cb_fn)(uint16_t eth_dev_id, | |
247 | uint16_t queue_id, | |
248 | uint32_t enqueue_buf_size, | |
249 | uint32_t enqueue_buf_count, | |
f67539c2 TL |
250 | struct rte_event *ev, |
251 | uint16_t nb_event, | |
11fdf7f2 | 252 | void *cb_arg, |
f67539c2 | 253 | uint16_t *nb_dropped); |
11fdf7f2 TL |
254 | |
255 | /** | |
11fdf7f2 TL |
256 | * Create a new ethernet Rx event adapter with the specified identifier. |
257 | * | |
258 | * @param id | |
259 | * The identifier of the ethernet Rx event adapter. | |
260 | * | |
261 | * @param dev_id | |
262 | * The identifier of the device to configure. | |
263 | * | |
264 | * @param conf_cb | |
265 | * Callback function that fills in members of a | |
266 | * struct rte_event_eth_rx_adapter_conf struct passed into | |
267 | * it. | |
268 | * | |
269 | * @param conf_arg | |
270 | * Argument that is passed to the conf_cb function. | |
271 | * | |
272 | * @return | |
273 | * - 0: Success | |
274 | * - <0: Error code on failure | |
275 | */ | |
276 | int rte_event_eth_rx_adapter_create_ext(uint8_t id, uint8_t dev_id, | |
277 | rte_event_eth_rx_adapter_conf_cb conf_cb, | |
278 | void *conf_arg); | |
279 | ||
280 | /** | |
11fdf7f2 TL |
281 | * Create a new ethernet Rx event adapter with the specified identifier. |
282 | * This function uses an internal configuration function that creates an event | |
283 | * port. This default function reconfigures the event device with an | |
284 | * additional event port and setups up the event port using the port_config | |
285 | * parameter passed into this function. In case the application needs more | |
286 | * control in configuration of the service, it should use the | |
287 | * rte_event_eth_rx_adapter_create_ext() version. | |
288 | * | |
289 | * @param id | |
290 | * The identifier of the ethernet Rx event adapter. | |
291 | * | |
292 | * @param dev_id | |
293 | * The identifier of the device to configure. | |
294 | * | |
295 | * @param port_config | |
296 | * Argument of type *rte_event_port_conf* that is passed to the conf_cb | |
297 | * function. | |
298 | * | |
299 | * @return | |
300 | * - 0: Success | |
301 | * - <0: Error code on failure | |
302 | */ | |
303 | int rte_event_eth_rx_adapter_create(uint8_t id, uint8_t dev_id, | |
304 | struct rte_event_port_conf *port_config); | |
305 | ||
306 | /** | |
11fdf7f2 TL |
307 | * Free an event adapter |
308 | * | |
309 | * @param id | |
310 | * Adapter identifier. | |
311 | * | |
312 | * @return | |
313 | * - 0: Success | |
314 | * - <0: Error code on failure, If the adapter still has Rx queues | |
315 | * added to it, the function returns -EBUSY. | |
316 | */ | |
317 | int rte_event_eth_rx_adapter_free(uint8_t id); | |
318 | ||
319 | /** | |
11fdf7f2 TL |
320 | * Add receive queue to an event adapter. After a queue has been |
321 | * added to the event adapter, the result of the application calling | |
322 | * rte_eth_rx_burst(eth_dev_id, rx_queue_id, ..) is undefined. | |
323 | * | |
324 | * @param id | |
325 | * Adapter identifier. | |
326 | * | |
327 | * @param eth_dev_id | |
328 | * Port identifier of Ethernet device. | |
329 | * | |
330 | * @param rx_queue_id | |
331 | * Ethernet device receive queue index. | |
332 | * If rx_queue_id is -1, then all Rx queues configured for | |
333 | * the device are added. If the ethdev Rx queues can only be | |
334 | * connected to a single event queue then rx_queue_id is | |
335 | * required to be -1. | |
336 | * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ | |
337 | * | |
338 | * @param conf | |
339 | * Additional configuration structure of type *rte_event_eth_rx_adapter_conf* | |
340 | * | |
341 | * @return | |
342 | * - 0: Success, Receive queue added correctly. | |
343 | * - <0: Error code on failure. | |
344 | * - (-EIO) device reconfiguration and restart error. The adapter reconfigures | |
345 | * the event device with an additional port if it is required to use a service | |
346 | * function for packet transfer from the ethernet device to the event device. | |
347 | * If the device had been started before this call, this error code indicates | |
348 | * an error in restart following an error in reconfiguration, i.e., a | |
349 | * combination of the two error codes. | |
350 | */ | |
351 | int rte_event_eth_rx_adapter_queue_add(uint8_t id, | |
352 | uint16_t eth_dev_id, | |
353 | int32_t rx_queue_id, | |
354 | const struct rte_event_eth_rx_adapter_queue_conf *conf); | |
355 | ||
356 | /** | |
11fdf7f2 TL |
357 | * Delete receive queue from an event adapter. |
358 | * | |
359 | * @param id | |
360 | * Adapter identifier. | |
361 | * | |
362 | * @param eth_dev_id | |
363 | * Port identifier of Ethernet device. | |
364 | * | |
365 | * @param rx_queue_id | |
366 | * Ethernet device receive queue index. | |
367 | * If rx_queue_id is -1, then all Rx queues configured for | |
368 | * the device are deleted. If the ethdev Rx queues can only be | |
369 | * connected to a single event queue then rx_queue_id is | |
370 | * required to be -1. | |
371 | * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ | |
372 | * | |
373 | * @return | |
374 | * - 0: Success, Receive queue deleted correctly. | |
375 | * - <0: Error code on failure. | |
376 | */ | |
377 | int rte_event_eth_rx_adapter_queue_del(uint8_t id, uint16_t eth_dev_id, | |
378 | int32_t rx_queue_id); | |
379 | ||
380 | /** | |
11fdf7f2 TL |
381 | * Start ethernet Rx event adapter |
382 | * | |
383 | * @param id | |
384 | * Adapter identifier. | |
385 | * | |
386 | * @return | |
387 | * - 0: Success, Adapter started correctly. | |
388 | * - <0: Error code on failure. | |
9f95a23c TL |
389 | * |
390 | * @note | |
391 | * The eventdev to which the event_eth_rx_adapter is connected needs to | |
392 | * be started before calling rte_event_eth_rx_adapter_start(). | |
11fdf7f2 TL |
393 | */ |
394 | int rte_event_eth_rx_adapter_start(uint8_t id); | |
395 | ||
396 | /** | |
11fdf7f2 TL |
397 | * Stop ethernet Rx event adapter |
398 | * | |
399 | * @param id | |
400 | * Adapter identifier. | |
401 | * | |
402 | * @return | |
403 | * - 0: Success, Adapter started correctly. | |
404 | * - <0: Error code on failure. | |
405 | */ | |
406 | int rte_event_eth_rx_adapter_stop(uint8_t id); | |
407 | ||
408 | /** | |
11fdf7f2 TL |
409 | * Retrieve statistics for an adapter |
410 | * | |
411 | * @param id | |
412 | * Adapter identifier. | |
413 | * | |
414 | * @param [out] stats | |
415 | * A pointer to structure used to retrieve statistics for an adapter. | |
416 | * | |
417 | * @return | |
418 | * - 0: Success, retrieved successfully. | |
419 | * - <0: Error code on failure. | |
420 | */ | |
f67539c2 TL |
421 | int rte_event_eth_rx_adapter_stats_get(uint8_t id, |
422 | struct rte_event_eth_rx_adapter_stats *stats); | |
11fdf7f2 TL |
423 | |
424 | /** | |
11fdf7f2 TL |
425 | * Reset statistics for an adapter. |
426 | * | |
427 | * @param id | |
428 | * Adapter identifier. | |
429 | * | |
430 | * @return | |
431 | * - 0: Success, statistics reset successfully. | |
432 | * - <0: Error code on failure. | |
433 | */ | |
434 | int rte_event_eth_rx_adapter_stats_reset(uint8_t id); | |
435 | ||
436 | /** | |
11fdf7f2 TL |
437 | * Retrieve the service ID of an adapter. If the adapter doesn't use |
438 | * a rte_service function, this function returns -ESRCH. | |
439 | * | |
440 | * @param id | |
441 | * Adapter identifier. | |
442 | * | |
443 | * @param [out] service_id | |
444 | * A pointer to a uint32_t, to be filled in with the service id. | |
445 | * | |
446 | * @return | |
447 | * - 0: Success | |
448 | * - <0: Error code on failure, if the adapter doesn't use a rte_service | |
449 | * function, this function returns -ESRCH. | |
450 | */ | |
451 | int rte_event_eth_rx_adapter_service_id_get(uint8_t id, uint32_t *service_id); | |
452 | ||
453 | /** | |
11fdf7f2 TL |
454 | * Register callback to process Rx packets, this is supported for |
455 | * SW based packet transfers. | |
456 | * @see rte_event_eth_rx_cb_fn | |
457 | * | |
458 | * @param id | |
459 | * Adapter identifier. | |
460 | * @param eth_dev_id | |
461 | * Port identifier of Ethernet device. | |
462 | * @param cb_fn | |
463 | * Callback function. | |
464 | * @param cb_arg | |
465 | * Callback arg. | |
466 | * @return | |
467 | * - 0: Success | |
468 | * - <0: Error code on failure. | |
469 | */ | |
f67539c2 TL |
470 | int rte_event_eth_rx_adapter_cb_register(uint8_t id, uint16_t eth_dev_id, |
471 | rte_event_eth_rx_adapter_cb_fn cb_fn, | |
472 | void *cb_arg); | |
11fdf7f2 TL |
473 | |
474 | #ifdef __cplusplus | |
475 | } | |
476 | #endif | |
477 | #endif /* _RTE_EVENT_ETH_RX_ADAPTER_ */ |