1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2018 Intel Corporation.
5 #ifndef _RTE_EVENT_ETH_TX_ADAPTER_
6 #define _RTE_EVENT_ETH_TX_ADAPTER_
11 * RTE Event Ethernet Tx Adapter
13 * The event ethernet Tx adapter provides configuration and data path APIs
14 * for the ethernet transmit stage of an event driven packet processing
15 * application. These APIs abstract the implementation of the transmit stage
16 * and allow the application to use eventdev PMD support or a common
19 * In the common implementation, the application enqueues mbufs to the adapter
20 * which runs as a rte_service function. The service function dequeues events
21 * from its event port and transmits the mbufs referenced by these events.
23 * The ethernet Tx event adapter APIs are:
25 * - rte_event_eth_tx_adapter_create()
26 * - rte_event_eth_tx_adapter_create_ext()
27 * - rte_event_eth_tx_adapter_free()
28 * - rte_event_eth_tx_adapter_start()
29 * - rte_event_eth_tx_adapter_stop()
30 * - rte_event_eth_tx_adapter_queue_add()
31 * - rte_event_eth_tx_adapter_queue_del()
32 * - rte_event_eth_tx_adapter_stats_get()
33 * - rte_event_eth_tx_adapter_stats_reset()
34 * - rte_event_eth_tx_adapter_enqueue()
35 * - rte_event_eth_tx_adapter_event_port_get()
36 * - rte_event_eth_tx_adapter_service_id_get()
38 * The application creates the adapter using
39 * rte_event_eth_tx_adapter_create() or rte_event_eth_tx_adapter_create_ext().
41 * The adapter will use the common implementation when the eventdev PMD
42 * does not have the #RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT capability.
43 * The common implementation uses an event port that is created using the port
44 * configuration parameter passed to rte_event_eth_tx_adapter_create(). The
45 * application can get the port identifier using
46 * rte_event_eth_tx_adapter_event_port_get() and must link an event queue to
49 * If the eventdev PMD has the #RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT
50 * flags set, Tx adapter events should be enqueued using the
51 * rte_event_eth_tx_adapter_enqueue() function, else the application should
52 * use rte_event_enqueue_burst().
54 * Transmit queues can be added and deleted from the adapter using
55 * rte_event_eth_tx_adapter_queue_add()/del() APIs respectively.
57 * The application can start and stop the adapter using the
58 * rte_event_eth_tx_adapter_start/stop() calls.
60 * The common adapter implementation uses an EAL service function as described
61 * before and its execution is controlled using the rte_service APIs. The
62 * rte_event_eth_tx_adapter_service_id_get()
63 * function can be used to retrieve the adapter's service function ID.
65 * The ethernet port and transmit queue index to transmit the mbuf on are
66 * specified using the mbuf port and the higher 16 bits of
67 * struct rte_mbuf::hash::sched:hi. The application should use the
68 * rte_event_eth_tx_adapter_txq_set() and rte_event_eth_tx_adapter_txq_get()
69 * functions to access the transmit queue index since it is expected that the
70 * transmit queue will be eventually defined within struct rte_mbuf and using
71 * these macros will help with minimizing application impact due to
72 * a change in how the transmit queue index is specified.
83 #include "rte_eventdev.h"
87 * @b EXPERIMENTAL: this API may change without prior notice
89 * Adapter configuration structure
91 * @see rte_event_eth_tx_adapter_create_ext
92 * @see rte_event_eth_tx_adapter_conf_cb
94 struct rte_event_eth_tx_adapter_conf {
95 uint8_t event_port_id;
96 /**< Event port identifier, the adapter service function dequeues mbuf
97 * events from this port.
98 * @see RTE_EVENT_ETH_RX_ADAPTER_CAP_INTERNAL_PORT
101 /**< The adapter can return early if it has processed at least
102 * max_nb_tx mbufs. This isn't treated as a requirement; batching may
103 * cause the adapter to process more than max_nb_tx mbufs.
109 * @b EXPERIMENTAL: this API may change without prior notice
111 * Function type used for adapter configuration callback. The callback is
112 * used to fill in members of the struct rte_event_eth_tx_adapter_conf, this
113 * callback is invoked when creating a RTE service function based
114 * adapter implementation.
117 * Adapter identifier.
119 * Event device identifier.
121 * Structure that needs to be populated by this callback.
123 * Argument to the callback. This is the same as the conf_arg passed to the
124 * rte_event_eth_tx_adapter_create_ext().
128 * - <0: Error code on failure
130 typedef int (*rte_event_eth_tx_adapter_conf_cb) (uint8_t id, uint8_t dev_id,
131 struct rte_event_eth_tx_adapter_conf *conf,
136 * @b EXPERIMENTAL: this API may change without prior notice
138 * A structure used to retrieve statistics for an ethernet Tx adapter instance.
140 struct rte_event_eth_tx_adapter_stats {
142 /**< Number of transmit retries */
144 /**< Number of packets transmitted */
146 /**< Number of packets dropped */
151 * @b EXPERIMENTAL: this API may change without prior notice
153 * Create a new ethernet Tx adapter with the specified identifier.
156 * The identifier of the ethernet Tx adapter.
158 * The event device identifier.
160 * Event port configuration, the adapter uses this configuration to
161 * create an event port if needed.
164 * - <0: Error code on failure
166 int __rte_experimental
167 rte_event_eth_tx_adapter_create(uint8_t id, uint8_t dev_id,
168 struct rte_event_port_conf *port_config);
172 * @b EXPERIMENTAL: this API may change without prior notice
174 * Create a new ethernet Tx adapter with the specified identifier.
177 * The identifier of the ethernet Tx adapter.
179 * The event device identifier.
181 * Callback function that initializes members of the
182 * struct rte_event_eth_tx_adapter_conf struct passed into
185 * Argument that is passed to the conf_cb function.
188 * - <0: Error code on failure
190 int __rte_experimental
191 rte_event_eth_tx_adapter_create_ext(uint8_t id, uint8_t dev_id,
192 rte_event_eth_tx_adapter_conf_cb conf_cb,
197 * @b EXPERIMENTAL: this API may change without prior notice
199 * Free an ethernet Tx adapter
202 * Adapter identifier.
205 * - <0: Error code on failure, If the adapter still has Tx queues
206 * added to it, the function returns -EBUSY.
208 int __rte_experimental
209 rte_event_eth_tx_adapter_free(uint8_t id);
213 * @b EXPERIMENTAL: this API may change without prior notice
215 * Start ethernet Tx adapter
218 * Adapter identifier.
220 * - 0: Success, Adapter started correctly.
221 * - <0: Error code on failure.
223 int __rte_experimental
224 rte_event_eth_tx_adapter_start(uint8_t id);
228 * @b EXPERIMENTAL: this API may change without prior notice
230 * Stop ethernet Tx adapter
233 * Adapter identifier.
236 * - <0: Error code on failure.
238 int __rte_experimental
239 rte_event_eth_tx_adapter_stop(uint8_t id);
243 * @b EXPERIMENTAL: this API may change without prior notice
245 * Add a Tx queue to the adapter.
246 * A queue value of -1 is used to indicate all
247 * queues within the device.
250 * Adapter identifier.
252 * Ethernet Port Identifier.
256 * - 0: Success, Queues added successfully.
257 * - <0: Error code on failure.
259 int __rte_experimental
260 rte_event_eth_tx_adapter_queue_add(uint8_t id,
266 * @b EXPERIMENTAL: this API may change without prior notice
268 * Delete a Tx queue from the adapter.
269 * A queue value of -1 is used to indicate all
270 * queues within the device, that have been added to this
274 * Adapter identifier.
276 * Ethernet Port Identifier.
280 * - 0: Success, Queues deleted successfully.
281 * - <0: Error code on failure.
283 int __rte_experimental
284 rte_event_eth_tx_adapter_queue_del(uint8_t id,
290 * @b EXPERIMENTAL: this API may change without prior notice
292 * Set Tx queue in the mbuf. This queue is used by the adapter
293 * to transmit the mbuf.
296 * Pointer to the mbuf.
300 static __rte_always_inline void __rte_experimental
301 rte_event_eth_tx_adapter_txq_set(struct rte_mbuf *pkt, uint16_t queue)
303 uint16_t *p = (uint16_t *)&pkt->hash.sched.hi;
309 * @b EXPERIMENTAL: this API may change without prior notice
311 * Retrieve Tx queue from the mbuf.
314 * Pointer to the mbuf.
316 * Tx queue identifier.
318 * @see rte_event_eth_tx_adapter_txq_set()
320 static __rte_always_inline uint16_t __rte_experimental
321 rte_event_eth_tx_adapter_txq_get(struct rte_mbuf *pkt)
323 uint16_t *p = (uint16_t *)&pkt->hash.sched.hi;
329 * @b EXPERIMENTAL: this API may change without prior notice
331 * Retrieve the adapter event port. The adapter creates an event port if
332 * the #RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT is not set in the
333 * ethernet Tx capabilities of the event device.
336 * Adapter Identifier.
337 * @param[out] event_port_id
338 * Event port pointer.
341 * - <0: Error code on failure.
343 int __rte_experimental
344 rte_event_eth_tx_adapter_event_port_get(uint8_t id, uint8_t *event_port_id);
347 * Enqueue a burst of events objects or an event object supplied in *rte_event*
348 * structure on an event device designated by its *dev_id* through the event
349 * port specified by *port_id*. This function is supported if the eventdev PMD
350 * has the #RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT capability flag set.
352 * The *nb_events* parameter is the number of event objects to enqueue which are
353 * supplied in the *ev* array of *rte_event* structure.
355 * The rte_event_eth_tx_adapter_enqueue() function returns the number of
356 * events objects it actually enqueued. A return value equal to *nb_events*
357 * means that all event objects have been enqueued.
360 * The identifier of the device.
362 * The identifier of the event port.
364 * Points to an array of *nb_events* objects of type *rte_event* structure
365 * which contain the event object enqueue operations to be processed.
367 * The number of event objects to enqueue, typically number of
368 * rte_event_port_enqueue_depth() available for this port.
371 * The number of event objects actually enqueued on the event device. The
372 * return value can be less than the value of the *nb_events* parameter when
373 * the event devices queue is full or if invalid parameters are specified in a
374 * *rte_event*. If the return value is less than *nb_events*, the remaining
375 * events at the end of ev[] are not consumed and the caller has to take care
376 * of them, and rte_errno is set accordingly. Possible errno values include:
377 * - -EINVAL The port ID is invalid, device ID is invalid, an event's queue
378 * ID is invalid, or an event's sched type doesn't match the
379 * capabilities of the destination queue.
380 * - -ENOSPC The event port was backpressured and unable to enqueue
381 * one or more events. This error code is only applicable to
384 static inline uint16_t __rte_experimental
385 rte_event_eth_tx_adapter_enqueue(uint8_t dev_id,
387 struct rte_event ev[],
390 const struct rte_eventdev *dev = &rte_eventdevs[dev_id];
392 #ifdef RTE_LIBRTE_EVENTDEV_DEBUG
393 if (dev_id >= RTE_EVENT_MAX_DEVS ||
394 !rte_eventdevs[dev_id].attached) {
399 if (port_id >= dev->data->nb_ports) {
404 return dev->txa_enqueue(dev->data->ports[port_id], ev, nb_events);
409 * @b EXPERIMENTAL: this API may change without prior notice
411 * Retrieve statistics for an adapter
414 * Adapter identifier.
416 * A pointer to structure used to retrieve statistics for an adapter.
418 * - 0: Success, statistics retrieved successfully.
419 * - <0: Error code on failure.
421 int __rte_experimental
422 rte_event_eth_tx_adapter_stats_get(uint8_t id,
423 struct rte_event_eth_tx_adapter_stats *stats);
427 * @b EXPERIMENTAL: this API may change without prior notice
429 * Reset statistics for an adapter.
432 * Adapter identifier.
434 * - 0: Success, statistics reset successfully.
435 * - <0: Error code on failure.
437 int __rte_experimental
438 rte_event_eth_tx_adapter_stats_reset(uint8_t id);
442 * @b EXPERIMENTAL: this API may change without prior notice
444 * Retrieve the service ID of an adapter. If the adapter doesn't use
445 * a rte_service function, this function returns -ESRCH.
448 * Adapter identifier.
449 * @param [out] service_id
450 * A pointer to a uint32_t, to be filled in with the service id.
453 * - <0: Error code on failure, if the adapter doesn't use a rte_service
454 * function, this function returns -ESRCH.
456 int __rte_experimental
457 rte_event_eth_tx_adapter_service_id_get(uint8_t id, uint32_t *service_id);
462 #endif /* _RTE_EVENT_ETH_TX_ADAPTER_ */