rte_event_..._adapter.h(3)

📦
version 25.11.3 · 11 versions
, in ubuntu resolute, ubuntu stonking

✨ NAME ✨

rte_event_eth_tx_adapter.h — bestie, you are reading page rte_event_..._adapter.h(3) from the Library Functions Manual, and it's the whole tea on the RTE Event Ethernet Tx Adapter 💖

🌸 SYNOPSIS 🌸

okay so first things first, the includes, no notes:

#include <stdint.h>
#include <rte_compat.h>
#include <rte_mbuf.h>
#include 'rte_eventdev.h'

(yes bestie, rte_eventdev.h is in single quotes in the original, we do not touch it, we respect it 💅)

🎀 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

so basically 🫶 the event ethernet Tx adapter hands you the configuration and data path APIs for the ethernet transmit stage of an event driven packet processing application. These APIs abstract away the implementation of the transmit stage and let your app use either eventdev PMD support or a common implementation. pick your fighter, both are valid.

In the common implementation, your application enqueues mbufs to the adapter, and the adapter runs as a rte_service function. That service function dequeues events from its event port and transmits the mbufs referenced by those events. it's giving pipeline, it's giving delegation 💅

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(). two doors, same hallway.

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(). Your application can grab the port identifier with rte_event_eth_tx_adapter_event_port_get() and must link an event queue to this port. don't skip that part bestie, it's not optional 😭

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 — otherwise your application should use rte_event_enqueue_burst(). iykyk ✨

Transmit queues can be added and deleted from the adapter using the 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. cute little id, very demure.

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. future-proofing, we love to see it 🦋

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. one port, one queue, one destiny, periodt 💅

Definition at line 355 of file rte_event_eth_tx_adapter.h.

🧚 Typedef Documentation 🧚

rte_event_eth_tx_adapter_conf_cb

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 the adapter configuration callback. This callback is used to fill in the members of the struct rte_event_eth_tx_adapter_conf, and it gets invoked when creating a RTE service function based adapter implementation. so it's the little setup bestie that does the paperwork 📝

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 🔥

rte_event_eth_tx_adapter_create()

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. newborn adapter, so small, so powerful 🎀

When this API is used for creating an adapter instance, rte_event_dev_config::nb_event_ports is automatically incremented, and the event device is reconfigured with an 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.

The 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 the eth Tx adapter in event device configure when the adapter is created with this API. it does the math for you, iconic behavior ✨

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

rte_event_eth_tx_adapter_create_ext()

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. this one lets you bring the callback, main character energy 😌

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

rte_event_eth_tx_adapter_free()

int rte_event_eth_tx_adapter_free (uint8_t id)

Free an ethernet Tx adapter. bye bestie, it was real 🫶

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.
ngl if you get -EBUSY it's because the adapter is still holding onto Tx queues. empty it out first 💀

rte_event_eth_tx_adapter_start()

int rte_event_eth_tx_adapter_start (uint8_t id)

Start ethernet Tx adapter. go girl, go 🚀

Parameters

  • id — Adapter identifier.

Returns

  • 0: Success, Adapter started correctly.
  • <0: Error code on failure.

rte_event_eth_tx_adapter_stop()

int rte_event_eth_tx_adapter_stop (uint8_t id)

Stop ethernet Tx adapter. nap time 🌙

Parameters

  • id — Adapter identifier.

Returns

  • 0: Success.
  • <0: Error code on failure.

rte_event_eth_tx_adapter_queue_add()

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. all of them, every single one, we're doing the whole roster 🔥

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.

rte_event_eth_tx_adapter_queue_del()

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. note the little clause there — only the ones that were actually added, we're not out here deleting strangers 💅

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.

rte_event_eth_tx_adapter_txq_set()

__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. one line, one purpose, obsessed 💖

Parameters

  • pkt — Pointer to the mbuf.
  • queue — Tx queue index.

Definition at line 318 of file rte_event_eth_tx_adapter.h.

rte_event_eth_tx_adapter_txq_get()

__rte_always_inline uint16_t rte_event_eth_tx_adapter_txq_get (struct rte_mbuf *pkt)

(static)

Retrieve Tx queue from the mbuf. the reading half of the set/get duo, together they ate 🌈

Parameters

  • pkt — Pointer to the mbuf.

Returns

Tx queue identifier.

See also

rte_event_eth_tx_adapter_txq_set()

🎀 rte_event_eth_tx_adapter_event_port_get

(quick callback to the entry above it, bestie — that one lives at 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)

Grab the adapter's event port, periodt. Little fun fact: the adapter spins up an event port all on its own if RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT is not set in the event device's ethernet Tx capabilities. iykyk.

Parameters 🌸

  • id — the Adapter Identifier.
  • event_port_id — Event port pointer.

Returns 💖

  • 0: slay, success.
  • <0: error code, it flopped.

🔥 rte_event_eth_tx_adapter_enqueue

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] — yes bestie, it's a static inline, it lives in your header.

This one enqueues a whole burst of event objects — or just one, whatever — supplied in a rte_event structure, onto an event device you point at with its dev_id, through the event port you name with port_id. It's only supported if the eventdev PMD has the RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT capability flag set — no cap flag, no dice.

The nb_events parameter is literally just how many event objects you wanna enqueue, and they're handed to it in the ev array of rte_event structures.

rte_event_eth_tx_adapter_enqueue() tells you how many event objects it actually enqueued (iconic of it). If the return value equals nb_events, every single one made it in. 💅

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, and those contain the event object enqueue operations to be processed.
  • nb_events — The number of event objects to enqueue, typically the 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. And 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. And heads up — this can come back less than nb_events when the event device's queue is full, or if invalid parameters got 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 it's on you to take care of them, plus rte_errno gets 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. 📍

🦋 rte_event_eth_tx_adapter_stats_get

int rte_event_eth_tx_adapter_stats_get(uint8_t id,
    struct rte_event_eth_tx_adapter_stats *stats)

Retrieve statistics for an adapter. The receipts, bestie. 🧾✨

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.

🍓 rte_event_eth_tx_adapter_stats_reset

int rte_event_eth_tx_adapter_stats_reset(uint8_t id)

Reset statistics for an adapter — clean slate energy. 🧼

Parameters

  • id — Adapter identifier.

Returns

  • 0: Success, statistics reset successfully.
  • <0: Error code on failure.

🌈 rte_event_eth_tx_adapter_service_id_get

int rte_event_eth_tx_adapter_service_id_get(uint8_t id, uint32_t *service_id)

Retrieve the service ID of an adapter. And if the adapter doesn't use a rte_service function, this function returns -ESRCH. Them's the rules.

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 — and again, if the adapter doesn't use a rte_service function, this function returns -ESRCH.

👑 rte_event_eth_tx_adapter_instance_get

int rte_event_eth_tx_adapter_instance_get(uint16_t eth_dev_id,
    uint16_t tx_queue_id, uint8_t *txa_inst_id)

Get the TX adapter instance id for a 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. It contains a valid Tx adapter instance id when the return value is 0.

Returns

  • 0: Success
  • <0: Error code on failure

💅 rte_event_eth_tx_adapter_queue_start

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 exists so that the application can resume enqueueing packets that reference packets for <eth_dev_id, tx_queue_id> 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 the application stopping ethdev Tx queues and the adapter being completely unaware of it. With these APIs, the application can call the stop API to notify the adapter that the corresponding ethdev Tx queue is stopped, and any in-flight packets are freed by the adapter dataplane code. The adapter queue stop API is called before stopping the ethdev Tx queue. Then, when the ethdev Tx queue is enabled, the application can notify the adapter to resume processing of the packets for that queue by calling the start API. The ethdev Tx queue is started before calling the 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

🌸 rte_event_eth_tx_adapter_queue_stop

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. So yeah, that's a real thing that happens — not a drill.

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_event_eth_tx_adapter_runtime_params_init

__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. ⚠️ __rte_experimental, bestie — experimental API, vibe with caution.

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_event_eth_tx_adapter_runtime_params_set

__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 the adapter. Also __rte_experimental. ⚠️

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. You can init this structure with rte_event_eth_tx_adapter_runtime_params_init() API to default values, or the application may reset this structure and update the required fields itself.

Returns

  • 0: Success
  • <0: Error code on failure

💀 rte_event_eth_tx_adapter_runtime_params_get

__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 the adapter. Yep, __rte_experimental again. ⚠️

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 the return value is 0.

Returns

  • 0: Success
  • <0: Error code on failure

💖 Author

Generated automatically by Doxygen for DPDK from the source code. (so literally no human to thank, it's giving robot authorship 🫶)

aaaand that's the whole page, no cap. This was DPDK, Version 25.11.3, page rte_event_..._adapter.h(3) — go forth and enqueue responsibly, bestie. 💅✨🌈

📦 where this page comes from