--- name: "rte_event_eth_tx_adapter.h" section: "3" platform: "linux" package: "dpdk-doc" version: "24.11.4-0+deb13u1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/rte_event_eth_tx_adapter.h" --- # rte\_event\_eth\_tx\_adapter.h(3) ## NAME rte\_event\_eth\_tx\_adapter.h ## SYNOPSIS `#include `\ `#include `\ `#include `\ `#include 'rte_eventdev.h'`\ ### Data Structures struct **rte\_event\_eth\_tx\_adapter\_conf**\ struct **rte\_event\_eth\_tx\_adapter\_runtime\_params**\ struct **rte\_event\_eth\_tx\_adapter\_stats**\ ### Macros \#define **RTE\_EVENT\_ETH\_TX\_ADAPTER\_ENQUEUE\_SAME\_DEST** 0x1\ ### Typedefs **typedef** int(\* **rte\_event\_eth\_tx\_adapter\_conf\_cb**) (uint8\_t id, uint8\_t dev\_id, struct **rte\_event\_eth\_tx\_adapter\_conf** \*conf, void \*arg)\ ### Functions int **rte\_event\_eth\_tx\_adapter\_create** (uint8\_t id, uint8\_t dev\_id, struct **rte\_event\_port\_conf** \*port\_config)\ int **rte\_event\_eth\_tx\_adapter\_create\_ext** (uint8\_t id, uint8\_t dev\_id, **rte\_event\_eth\_tx\_adapter\_conf\_cb** conf\_cb, void \*conf\_arg)\ int **rte\_event\_eth\_tx\_adapter\_free** (uint8\_t id)\ int **rte\_event\_eth\_tx\_adapter\_start** (uint8\_t id)\ int **rte\_event\_eth\_tx\_adapter\_stop** (uint8\_t id)\ int **rte\_event\_eth\_tx\_adapter\_queue\_add** (uint8\_t id, uint16\_t eth\_dev\_id, int32\_t queue)\ int **rte\_event\_eth\_tx\_adapter\_queue\_del** (uint8\_t id, uint16\_t eth\_dev\_id, int32\_t queue)\ static **\_\_rte\_always\_inline** void **rte\_event\_eth\_tx\_adapter\_txq\_set** (struct **rte\_mbuf** \*pkt, uint16\_t queue)\ static **\_\_rte\_always\_inline** uint16\_t **rte\_event\_eth\_tx\_adapter\_txq\_get** (struct **rte\_mbuf** \*pkt)\ int **rte\_event\_eth\_tx\_adapter\_event\_port\_get** (uint8\_t id, uint8\_t \*event\_port\_id)\ static uint16\_t **rte\_event\_eth\_tx\_adapter\_enqueue** (uint8\_t dev\_id, uint8\_t port\_id, struct **rte\_event** ev\[\], uint16\_t nb\_events, const uint8\_t flags)\ int **rte\_event\_eth\_tx\_adapter\_stats\_get** (uint8\_t id, struct **rte\_event\_eth\_tx\_adapter\_stats** \*stats)\ int **rte\_event\_eth\_tx\_adapter\_stats\_reset** (uint8\_t id)\ int **rte\_event\_eth\_tx\_adapter\_service\_id\_get** (uint8\_t id, uint32\_t \*service\_id)\ int **rte\_event\_eth\_tx\_adapter\_instance\_get** (uint16\_t eth\_dev\_id, uint16\_t tx\_queue\_id, uint8\_t \*txa\_inst\_id)\ int **rte\_event\_eth\_tx\_adapter\_queue\_start** (uint16\_t eth\_dev\_id, uint16\_t tx\_queue\_id)\ int **rte\_event\_eth\_tx\_adapter\_queue\_stop** (uint16\_t eth\_dev\_id, uint16\_t tx\_queue\_id)\ \_\_rte\_experimental int **rte\_event\_eth\_tx\_adapter\_runtime\_params\_init** (struct **rte\_event\_eth\_tx\_adapter\_runtime\_params** \*txa\_params)\ \_\_rte\_experimental int **rte\_event\_eth\_tx\_adapter\_runtime\_params\_set** (uint8\_t id, struct **rte\_event\_eth\_tx\_adapter\_runtime\_params** \*params)\ \_\_rte\_experimental int **rte\_event\_eth\_tx\_adapter\_runtime\_params\_get** (uint8\_t id, struct **rte\_event\_eth\_tx\_adapter\_runtime\_params** \*params)\ ## Detailed Description RTE Event Ethernet Tx Adapter The event ethernet Tx adapter provides configuration and data path APIs for the ethernet transmit stage of an event driven packet processing application. These APIs abstract the implementation of the transmit stage and allow the application to use eventdev PMD support or a common implementation. In the common implementation, the application enqueues mbufs to the adapter which runs as a rte\_service function. The service function dequeues events from its event port and transmits the mbufs referenced by these events. The ethernet Tx event adapter APIs are: - • **rte\_event\_eth\_tx\_adapter\_create()** - • **rte\_event\_eth\_tx\_adapter\_create\_ext()** - • **rte\_event\_eth\_tx\_adapter\_free()** - • **rte\_event\_eth\_tx\_adapter\_start()** - • **rte\_event\_eth\_tx\_adapter\_stop()** - • **rte\_event\_eth\_tx\_adapter\_queue\_add()** - • **rte\_event\_eth\_tx\_adapter\_queue\_del()** - • **rte\_event\_eth\_tx\_adapter\_stats\_get()** - • **rte\_event\_eth\_tx\_adapter\_stats\_reset()** - • **rte\_event\_eth\_tx\_adapter\_enqueue()** - • **rte\_event\_eth\_tx\_adapter\_event\_port\_get()** - • **rte\_event\_eth\_tx\_adapter\_service\_id\_get()** - • **rte\_event\_eth\_tx\_adapter\_instance\_get()** - • **rte\_event\_eth\_tx\_adapter\_queue\_start()** - • **rte\_event\_eth\_tx\_adapter\_queue\_stop()** - • **rte\_event\_eth\_tx\_adapter\_runtime\_params\_get()** - • **rte\_event\_eth\_tx\_adapter\_runtime\_params\_init()** - • **rte\_event\_eth\_tx\_adapter\_runtime\_params\_set()** The application creates the adapter using **rte\_event\_eth\_tx\_adapter\_create()** or **rte\_event\_eth\_tx\_adapter\_create\_ext()**. The adapter will use the common implementation when the eventdev PMD does not have the **RTE\_EVENT\_ETH\_TX\_ADAPTER\_CAP\_INTERNAL\_PORT** capability. The common implementation uses an event port that is created using the port configuration parameter passed to **rte\_event\_eth\_tx\_adapter\_create()**. The application can get the port identifier using **rte\_event\_eth\_tx\_adapter\_event\_port\_get()** and must link an event queue to this port. If the eventdev PMD has the **RTE\_EVENT\_ETH\_TX\_ADAPTER\_CAP\_INTERNAL\_PORT** flags set, Tx adapter events should be enqueued using the **rte\_event\_eth\_tx\_adapter\_enqueue()** function, else the application should use **rte\_event\_enqueue\_burst()**. Transmit queues can be added and deleted from the adapter using **rte\_event\_eth\_tx\_adapter\_queue\_add()**/del() APIs respectively. The application can start and stop the adapter using the rte\_event\_eth\_tx\_adapter\_start/stop() calls. The common adapter implementation uses an EAL service function as described before and its execution is controlled using the rte\_service APIs. The **rte\_event\_eth\_tx\_adapter\_service\_id\_get()** function can be used to retrieve the adapter's service function ID. The ethernet port and transmit queue index to transmit the mbuf on are specified using the mbuf port struct rte\_mbuf::hash::txadapter:txq. The application should use the **rte\_event\_eth\_tx\_adapter\_txq\_set()** and **rte\_event\_eth\_tx\_adapter\_txq\_get()** functions to access the transmit queue index, using these macros will help with minimizing application impact due to a change in how the transmit queue index is specified. Definition in file **rte\_event\_eth\_tx\_adapter.h**. ## Macro Definition Documentation ### #define RTE\_EVENT\_ETH\_TX\_ADAPTER\_ENQUEUE\_SAME\_DEST 0x1 This flag is used when all the packets enqueued in the tx adapter are destined for the same Ethernet port & Tx queue. Definition at line **358** of file **rte\_event\_eth\_tx\_adapter.h**. ## Typedef Documentation ### typedef int(\* rte\_event\_eth\_tx\_adapter\_conf\_cb) (uint8\_t id, uint8\_t dev\_id, struct rte\_event\_eth\_tx\_adapter\_conf \*conf, void \*arg) Function type used for adapter configuration callback. The callback is used to fill in members of the struct **rte\_event\_eth\_tx\_adapter\_conf**, this callback is invoked when creating a RTE service function based adapter implementation. **Parameters** *id* Adapter identifier. \ *dev\_id* Event device identifier. \ *conf* Structure that needs to be populated by this callback. \ *arg* Argument to the callback. This is the same as the conf\_arg passed to the **rte\_event\_eth\_tx\_adapter\_create\_ext()**. **Returns** - • 0: Success - • \<0: Error code on failure Definition at line **160** of file **rte\_event\_eth\_tx\_adapter.h**. ## Function Documentation ### int rte\_event\_eth\_tx\_adapter\_create (uint8\_t id, uint8\_t dev\_id, struct rte\_event\_port\_conf \* port\_config) Create a new ethernet Tx adapter with the specified identifier. When this API is used for creating adapter instance, **rte\_event\_dev\_config::nb\_event\_ports is automatically incremented, and event device is reconfigured with additional event port during service initialization. This event device reconfigure logic also increments the rte\_event\_dev\_config::nb\_single\_link\_event\_port\_queues parameter if the adapter event port config is of type** `RTE_EVENT_PORT_CFG_SINGLE_LINK`**.** **Application no longer needs to account for the rte\_event\_dev\_config::nb\_event\_ports and rte\_event\_dev\_config::nb\_single\_link\_event\_port\_queues parameters required for eth Tx adapter in event device configure when the adapter is created with this API.** **Parameters** *id* **The identifier of the ethernet Tx adapter.** \ *dev\_id* **The event device identifier.** \ *port\_config* **Event port configuration, the adapter uses this configuration to create an event port if needed.** **Returns** - • **0: Success** - • **\<0: Error code on failure** ### int rte\_event\_eth\_tx\_adapter\_create\_ext (uint8\_t id, uint8\_t dev\_id, rte\_event\_eth\_tx\_adapter\_conf\_cb conf\_cb, void \* conf\_arg) **Create a new ethernet Tx adapter with the specified identifier.** **Parameters** *id* **The identifier of the ethernet Tx adapter.** \ *dev\_id* **The event device identifier.** \ *conf\_cb* **Callback function that initializes members of the struct rte\_event\_eth\_tx\_adapter\_conf struct passed into it.** \ *conf\_arg* **Argument that is passed to the conf\_cb function.** **Returns** - • **0: Success** - • **\<0: Error code on failure** ### int rte\_event\_eth\_tx\_adapter\_free (uint8\_t id) **Free an ethernet Tx adapter** **Parameters** *id* **Adapter identifier.** **Returns** - • **0: Success** - • **\<0: Error code on failure, If the adapter still has Tx queues added to it, the function returns -EBUSY.** ### int rte\_event\_eth\_tx\_adapter\_start (uint8\_t id) **Start ethernet Tx adapter** **Parameters** *id* **Adapter identifier.** **Returns** - • **0: Success, Adapter started correctly.** - • **\<0: Error code on failure.** ### int rte\_event\_eth\_tx\_adapter\_stop (uint8\_t id) **Stop ethernet Tx adapter** **Parameters** *id* **Adapter identifier.** **Returns** - • **0: Success.** - • **\<0: Error code on failure.** ### int rte\_event\_eth\_tx\_adapter\_queue\_add (uint8\_t id, uint16\_t eth\_dev\_id, int32\_t queue) **Add a Tx queue to the adapter. A queue value of -1 is used to indicate all queues within the device.** **Parameters** *id* **Adapter identifier.** \ *eth\_dev\_id* **Ethernet Port Identifier.** \ *queue* **Tx queue index.** **Returns** - • **0: Success, Queues added successfully.** - • **\<0: Error code on failure.** ### int rte\_event\_eth\_tx\_adapter\_queue\_del (uint8\_t id, uint16\_t eth\_dev\_id, int32\_t queue) **Delete a Tx queue from the adapter. A queue value of -1 is used to indicate all queues within the device, that have been added to this adapter.** **Parameters** *id* **Adapter identifier.** \ *eth\_dev\_id* **Ethernet Port Identifier.** \ *queue* **Tx queue index.** **Returns** - • **0: Success, Queues deleted successfully.** - • **\<0: Error code on failure.** ### static \_\_rte\_always\_inline void rte\_event\_eth\_tx\_adapter\_txq\_set (struct rte\_mbuf \* pkt, uint16\_t queue)` [static]` **Set Tx queue in the mbuf. This queue is used by the adapter to transmit the mbuf.** **Parameters** *pkt* **Pointer to the mbuf.** \ *queue* **Tx queue index.** **Definition at line 318 of file rte\_event\_eth\_tx\_adapter.h.** ### static \_\_rte\_always\_inline uint16\_t rte\_event\_eth\_tx\_adapter\_txq\_get (struct rte\_mbuf \* pkt)` [static]` **Retrieve Tx queue from the mbuf.** **Parameters** *pkt* **Pointer to the mbuf.** **Returns** **Tx queue identifier.** **See also** **rte\_event\_eth\_tx\_adapter\_txq\_set()** **Definition at line 334 of file rte\_event\_eth\_tx\_adapter.h.** ### int rte\_event\_eth\_tx\_adapter\_event\_port\_get (uint8\_t id, uint8\_t \* event\_port\_id) **Retrieve the adapter event port. The adapter creates an event port if the RTE\_EVENT\_ETH\_TX\_ADAPTER\_CAP\_INTERNAL\_PORT is not set in the ethernet Tx capabilities of the event device.** **Parameters** *id* **Adapter Identifier.** \ *event\_port\_id* **Event port pointer.** **Returns** - • **0: Success.** - • **\<0: Error code on failure.** ### static uint16\_t rte\_event\_eth\_tx\_adapter\_enqueue (uint8\_t dev\_id, uint8\_t port\_id, struct rte\_event ev\[\], uint16\_t nb\_events, const uint8\_t flags)` [inline]`, ` [static]` **Enqueue a burst of events objects or an event object supplied in rte\_event structure on an event device designated by its** *dev\_id* **through the event port specified by** *port\_id***. This function is supported if the eventdev PMD has the RTE\_EVENT\_ETH\_TX\_ADAPTER\_CAP\_INTERNAL\_PORT capability flag set.** **The** *nb\_events* **parameter is the number of event objects to enqueue which are supplied in the** *ev* **array of rte\_event structure.** **The rte\_event\_eth\_tx\_adapter\_enqueue() function returns the number of events objects it actually enqueued. A return value equal to** *nb\_events* **means that all event objects have been enqueued.** **Parameters** *dev\_id* **The identifier of the device.** \ *port\_id* **The identifier of the event port.** \ *ev* **Points to an array of** *nb\_events* **objects of type rte\_event structure which contain the event object enqueue operations to be processed.** \ *nb\_events* **The number of event objects to enqueue, typically number of rte\_event\_port\_attr\_get(...RTE\_EVENT\_PORT\_ATTR\_ENQ\_DEPTH...) available for this port.** \ *flags* **RTE\_EVENT\_ETH\_TX\_ADAPTER\_ENQUEUE\_ flags. RTE\_EVENT\_ETH\_TX\_ADAPTER\_ENQUEUE\_SAME\_DEST signifies that all the packets which are enqueued are destined for the same Ethernet port & Tx queue.** **Returns** **The number of event objects actually enqueued on the event device. The return value can be less than the value of the** *nb\_events* **parameter when the event devices queue is full or if invalid parameters are specified in a rte\_event. If the return value is less than** *nb\_events***, the remaining events at the end of ev\[\] are not consumed and the caller has to take care of them, and rte\_errno is set accordingly. Possible errno values include:** - • **EINVAL The port ID is invalid, device ID is invalid, an event's queue ID is invalid, or an event's sched type doesn't match the capabilities of the destination queue.** - • **ENOSPC The event port was backpressured and unable to enqueue one or more events. This error code is only applicable to closed systems.** **Definition at line 404 of file rte\_event\_eth\_tx\_adapter.h.** ### int rte\_event\_eth\_tx\_adapter\_stats\_get (uint8\_t id, struct rte\_event\_eth\_tx\_adapter\_stats \* stats) **Retrieve statistics for an adapter** **Parameters** *id* **Adapter identifier.** \ *stats* **A pointer to structure used to retrieve statistics for an adapter.** **Returns** - • **0: Success, statistics retrieved successfully.** - • **\<0: Error code on failure.** ### int rte\_event\_eth\_tx\_adapter\_stats\_reset (uint8\_t id) **Reset statistics for an adapter.** **Parameters** *id* **Adapter identifier.** **Returns** - • **0: Success, statistics reset successfully.** - • **\<0: Error code on failure.** ### int rte\_event\_eth\_tx\_adapter\_service\_id\_get (uint8\_t id, uint32\_t \* service\_id) **Retrieve the service ID of an adapter. If the adapter doesn't use a rte\_service function, this function returns -ESRCH.** **Parameters** *id* **Adapter identifier.** \ *service\_id* **A pointer to a uint32\_t, to be filled in with the service id.** **Returns** - • **0: Success** - • **\<0: Error code on failure, if the adapter doesn't use a rte\_service function, this function returns -ESRCH.** ### int rte\_event\_eth\_tx\_adapter\_instance\_get (uint16\_t eth\_dev\_id, uint16\_t tx\_queue\_id, uint8\_t \* txa\_inst\_id) **Get TX adapter instance id for TX queue** **Parameters** *eth\_dev\_id* **Port identifier of Ethernet device**\ *tx\_queue\_id* **Etherdev device TX queue index**\ *txa\_inst\_id* **Pointer to TX adapter instance identifier Contains valid Tx adapter instance id when return value is 0** **Returns** - • **0: Success** - • **\<0: Error code on failure** ### int rte\_event\_eth\_tx\_adapter\_queue\_start (uint16\_t eth\_dev\_id, uint16\_t tx\_queue\_id) **Enables the adapter to start enqueueing of packets to the Tx queue.** **This function is provided so that the application can resume enqueueing packets that reference packets for \ after calling rte\_event\_eth\_tx\_adapter\_queue\_stop().** **See also** **rte\_event\_eth\_tx\_adapter\_queue\_stop** ### Use case: **The queue start/stop APIs help avoid some unexpected behavior with application stopping ethdev Tx queues and adapter being unaware of it. With these APIs, the application can call stop API to notify adapter that corresponding ethdev Tx queue is stopped and any in-flight packets are freed by adapter dataplane code. Adapter queue stop API is called before stopping the ethdev Tx queue. When ethdev Tx queue is enabled, application can notify adapter to resume processing of the packets for that queue by calling the start API. The ethdev Tx queue is started before calling adapter start API.** **Parameters** *eth\_dev\_id* **Port identifier of Ethernet device.** \ *tx\_queue\_id* **Ethernet device transmit queue index.** **Returns** - • **0: Success** - • **\<0: Error code on failure** ### int rte\_event\_eth\_tx\_adapter\_queue\_stop (uint16\_t eth\_dev\_id, uint16\_t tx\_queue\_id) **Stops the adapter runtime function from enqueueing any packets to the associated Tx queue. This API also frees any packets that may have been buffered for this queue. All inflight packets destined to the queue are freed by the adapter runtime until the queue is started again.** **See also** **rte\_event\_eth\_tx\_adapter\_queue\_start** **Parameters** *eth\_dev\_id* **Port identifier of Ethernet device.** \ *tx\_queue\_id* **Ethernet device transmit queue index.** **Returns** - • **0: Success** - • **\<0: Error code on failure** ### \_\_rte\_experimental int rte\_event\_eth\_tx\_adapter\_runtime\_params\_init (struct rte\_event\_eth\_tx\_adapter\_runtime\_params \* txa\_params) **Initialize the adapter runtime configuration parameters with default values** **Parameters** *txa\_params* **A pointer to structure of type struct rte\_event\_eth\_tx\_adapter\_runtime\_params** **Returns** - • **0: Success** - • **\<0: Error code on failure** ### \_\_rte\_experimental int rte\_event\_eth\_tx\_adapter\_runtime\_params\_set (uint8\_t id, struct rte\_event\_eth\_tx\_adapter\_runtime\_params \* params) **Set the runtime configuration parameters for adapter.** **Parameters** *id* **Adapter identifier** \ *params* **A pointer to structure of type struct rte\_event\_eth\_tx\_adapter\_runtime\_params with configuration parameter values. The reserved fields of this structure must be initialized to zero and the valid fields need to be set appropriately. This structure can be initialized using rte\_event\_eth\_tx\_adapter\_runtime\_params\_init() API to default values or application may reset this structure and update required fields.** **Returns** - • **0: Success** - • **\<0: Error code on failure** ### \_\_rte\_experimental int rte\_event\_eth\_tx\_adapter\_runtime\_params\_get (uint8\_t id, struct rte\_event\_eth\_tx\_adapter\_runtime\_params \* params) **Get the runtime configuration parameters of adapter.** **Parameters** *id* **Adapter identifier** \ *params* **A pointer to structure of type struct rte\_event\_eth\_tx\_adapter\_runtime\_params containing valid Tx adapter parameters when return value is 0.** **Returns** - • **0: Success** - • **\<0: Error code on failure** ## Author **Generated automatically by Doxygen for DPDK from the source code.**