rte_event_eth_tx_adapter.h

       Generated automatically by Doxygen for DPDK from the source code.

DPDK                                             Version 24.11.2                   rte_event_eth_tx_adapter.h(3)

       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.

intrte_event_eth_tx_adapter_create(uint8_tid,uint8_tdev_id,structrte_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_portsisautomaticallyincremented,andeventdeviceisreconfiguredwithadditionaleventportduringserviceinitialization.Thiseventdevicereconfigurelogicalsoincrementstherte_event_dev_config::nb_single_link_event_port_queuesparameteriftheadaptereventportconfigisoftypeRTE_EVENT_PORT_CFG_SINGLE_LINK.

       Application   no   longer   needs   to   account   for   the   rte_event_dev_config::nb_event_portsandrte_event_dev_config::nb_single_link_event_port_queuesparametersrequiredforethTxadapterineventdeviceconfigurewhentheadapteriscreatedwiththisAPI.Parametersid 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

   intrte_event_eth_tx_adapter_create_ext(uint8_tid,uint8_tdev_id,rte_event_eth_tx_adapter_conf_cbconf_cb,void*conf_arg)
       Create a new ethernet Tx adapter with the specified identifier.

       Parametersid 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

   intrte_event_eth_tx_adapter_free(uint8_tid)
       Free an ethernet Tx adapter

       Parametersid Adapter identifier.

       Returns

           • 0: Success

           • <0: Error code on failure, If the adapter still has Tx queues added to  it,  the  function  returns
             -EBUSY.

   intrte_event_eth_tx_adapter_start(uint8_tid)
       Start ethernet Tx adapter

       Parametersid Adapter identifier.

       Returns

           • 0: Success, Adapter started correctly.

           • <0: Error code on failure.

   intrte_event_eth_tx_adapter_stop(uint8_tid)
       Stop ethernet Tx adapter

       Parametersid Adapter identifier.

       Returns

           • 0: Success.

           • <0: Error code on failure.

   intrte_event_eth_tx_adapter_queue_add(uint8_tid,uint16_teth_dev_id,int32_tqueue)
       Add a Tx queue to the adapter. A queue value of -1 is used to indicate all queues within the device.

       Parametersid Adapter identifier.
           eth_dev_id Ethernet Port Identifier.
           queue Tx queue index.

       Returns

           • 0: Success, Queues added successfully.

           • <0: Error code on failure.

   intrte_event_eth_tx_adapter_queue_del(uint8_tid,uint16_teth_dev_id,int32_tqueue)
       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.

       Parametersid 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_inlinevoidrte_event_eth_tx_adapter_txq_set(structrte_mbuf*pkt,uint16_tqueue)[static]
       Set Tx queue in the mbuf. This queue is used by the adapter to transmit the mbuf.

       Parameterspkt Pointer to the mbuf.
           queue Tx queue index.

       Definition at line 318 of file rte_event_eth_tx_adapter.h.

   static__rte_always_inlineuint16_trte_event_eth_tx_adapter_txq_get(structrte_mbuf*pkt)[static]
       Retrieve Tx queue from the mbuf.

       Parameterspkt Pointer to the mbuf.

       Returns
           Tx queue identifier.

       Seealsorte_event_eth_tx_adapter_txq_set()

       Definition at line 334 of file rte_event_eth_tx_adapter.h.

   intrte_event_eth_tx_adapter_event_port_get(uint8_tid,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.

       Parametersid Adapter Identifier.
           event_port_id Event port pointer.

       Returns

           • 0: Success.

           • <0: Error code on failure.

   staticuint16_trte_event_eth_tx_adapter_enqueue(uint8_tdev_id,uint8_tport_id,structrte_eventev[],uint16_tnb_events,constuint8_tflags)[inline],[static]
       Enqueue  a  burst of events objects or an event object supplied in rte_eventstructureonaneventdevicedesignatedbyitsdev_idthroughtheeventportspecifiedbyport_id.ThisfunctionissupportediftheeventdevPMDhastheRTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORTcapabilityflagset.

       The  nb_events  parameter is the number of event objects to enqueue which are supplied in the ev array of
       rte_eventstructure.

       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.

       Parametersdev_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_eventstructurewhichcontaintheeventobjectenqueueoperationstobeprocessed.nb_eventsThenumberofeventobjectstoenqueue,typicallynumberofrte_event_port_attr_get(...RTE_EVENT_PORT_ATTR_ENQ_DEPTH...)availableforthisport.flagsRTE_EVENT_ETH_TX_ADAPTER_ENQUEUE_flags.RTE_EVENT_ETH_TX_ADAPTER_ENQUEUE_SAME_DESTsignifiesthatallthepacketswhichareenqueuedaredestinedforthesameEthernetport&Txqueue.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.Ifthereturnvalueislessthannb_events,theremainingeventsattheendofev[]arenotconsumedandthecallerhastotakecareofthem,andrte_errnoissetaccordingly.Possibleerrnovaluesinclude:

           • 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.

   intrte_event_eth_tx_adapter_stats_get(uint8_tid,structrte_event_eth_tx_adapter_stats*stats)
       Retrieve statistics for an adapter

       Parametersid 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.

   intrte_event_eth_tx_adapter_stats_reset(uint8_tid)
       Reset statistics for an adapter.

       Parametersid Adapter identifier.

       Returns

           • 0: Success, statistics reset successfully.

           • <0: Error code on failure.

   intrte_event_eth_tx_adapter_service_id_get(uint8_tid,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.

       Parametersid 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.

   intrte_event_eth_tx_adapter_instance_get(uint16_teth_dev_id,uint16_ttx_queue_id,uint8_t*txa_inst_id)
       Get TX adapter instance id for TX queue

       Parameterseth_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

   intrte_event_eth_tx_adapter_queue_start(uint16_teth_dev_id,uint16_ttx_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 <eth_dev_id, tx_queue_id> after calling rte_event_eth_tx_adapter_queue_stop().

       Seealsorte_event_eth_tx_adapter_queue_stopUsecase:
       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.

       Parameterseth_dev_id Port identifier of Ethernet device.
           tx_queue_id Ethernet device transmit queue index.

       Returns

           • 0: Success

           • <0: Error code on failure

   intrte_event_eth_tx_adapter_queue_stop(uint16_teth_dev_id,uint16_ttx_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.

       Seealsorte_event_eth_tx_adapter_queue_startParameterseth_dev_id Port identifier of Ethernet device.
           tx_queue_id Ethernet device transmit queue index.

       Returns

           • 0: Success

           • <0: Error code on failure

   __rte_experimentalintrte_event_eth_tx_adapter_runtime_params_init(structrte_event_eth_tx_adapter_runtime_params*txa_params)
       Initialize the adapter runtime configuration parameters with default values

       Parameterstxa_params A pointer to structure of type struct rte_event_eth_tx_adapter_runtime_paramsReturns

           • 0: Success

           • <0: Error code on failure

   __rte_experimentalintrte_event_eth_tx_adapter_runtime_params_set(uint8_tid,structrte_event_eth_tx_adapter_runtime_params*params)
       Set the runtime configuration parameters for adapter.

       Parametersid 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_experimentalintrte_event_eth_tx_adapter_runtime_params_get(uint8_tid,structrte_event_eth_tx_adapter_runtime_params*params)
       Get the runtime configuration parameters of adapter.

       Parametersid 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

#defineRTE_EVENT_ETH_TX_ADAPTER_ENQUEUE_SAME_DEST0x1
       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.

       rte_event_eth_tx_adapter.h

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

   DataStructures
       struct rte_event_eth_tx_adapter_conf
       struct rte_event_eth_tx_adapter_runtime_params
       struct rte_event_eth_tx_adapter_statsMacros
       #define RTE_EVENT_ETH_TX_ADAPTER_ENQUEUE_SAME_DEST   0x1

   Typedefstypedef 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)

typedefint(*rte_event_eth_tx_adapter_conf_cb)(uint8_tid,uint8_tdev_id,structrte_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.

       Parametersid 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.