rte_event_eth_rx_adapter.h(3)

NAME
rte_event_eth_rx_adapter.h

SYNOPSIS

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

  Data Structures

struct rte_event_eth_rx_adapter_conf
struct rte_event_eth_rx_adapter_queue_conf
struct rte_event_eth_rx_adapter_queue_stats
struct rte_event_eth_rx_adapter_stats
struct rte_event_eth_rx_adapter_vector_limits
struct rte_event_eth_rx_adapter_params
struct rte_event_eth_rx_adapter_runtime_params

  Macros

#define RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID 0x1
#define RTE_EVENT_ETH_RX_ADAPTER_QUEUE_EVENT_VECTOR 0x2

  Typedefs

typedef int(* rte_event_eth_rx_adapter_conf_cb) (uint8_t id, uint8_t dev_id, struct rte_event_eth_rx_adapter_conf *conf, void *arg)
typedef uint16_t(* rte_event_eth_rx_adapter_cb_fn) (uint16_t eth_dev_id, uint16_t queue_id, uint32_t enqueue_buf_size, uint32_t enqueue_buf_count, struct rte_event *ev, uint16_t nb_event, void *cb_arg, uint16_t *nb_dropped)

  Functions

int rte_event_eth_rx_adapter_create_ext (uint8_t id, uint8_t dev_id, rte_event_eth_rx_adapter_conf_cb conf_cb, void *conf_arg)
int rte_event_eth_rx_adapter_create (uint8_t id, uint8_t dev_id, struct rte_event_port_conf *port_config)
int rte_event_eth_rx_adapter_create_with_params (uint8_t id, uint8_t dev_id, struct rte_event_port_conf *port_config, struct rte_event_eth_rx_adapter_params *rxa_params)
__rte_experimental int rte_event_eth_rx_adapter_create_ext_with_params (uint8_t id, uint8_t dev_id, rte_event_eth_rx_adapter_conf_cb conf_cb, void *conf_arg, struct rte_event_eth_rx_adapter_params *rxa_params)
int rte_event_eth_rx_adapter_free (uint8_t id)
int rte_event_eth_rx_adapter_queue_add (uint8_t id, uint16_t eth_dev_id, int32_t rx_queue_id, const struct rte_event_eth_rx_adapter_queue_conf *conf)
__rte_experimental int rte_event_eth_rx_adapter_queues_add (uint8_t id, uint16_t eth_dev_id, int32_t rx_queue_id[], const struct rte_event_eth_rx_adapter_queue_conf conf[], uint16_t nb_rx_queues)
int rte_event_eth_rx_adapter_queue_del (uint8_t id, uint16_t eth_dev_id, int32_t rx_queue_id)
int rte_event_eth_rx_adapter_start (uint8_t id)
int rte_event_eth_rx_adapter_stop (uint8_t id)
int rte_event_eth_rx_adapter_stats_get (uint8_t id, struct rte_event_eth_rx_adapter_stats *stats)
int rte_event_eth_rx_adapter_stats_reset (uint8_t id)
int rte_event_eth_rx_adapter_service_id_get (uint8_t id, uint32_t *service_id)
int rte_event_eth_rx_adapter_cb_register (uint8_t id, uint16_t eth_dev_id, rte_event_eth_rx_adapter_cb_fn cb_fn, void *cb_arg)
int rte_event_eth_rx_adapter_vector_limits_get (uint8_t dev_id, uint16_t eth_port_id, struct rte_event_eth_rx_adapter_vector_limits *limits)
int rte_event_eth_rx_adapter_queue_conf_get (uint8_t id, uint16_t eth_dev_id, uint16_t rx_queue_id, struct rte_event_eth_rx_adapter_queue_conf *queue_conf)
int rte_event_eth_rx_adapter_queue_stats_get (uint8_t id, uint16_t eth_dev_id, uint16_t rx_queue_id, struct rte_event_eth_rx_adapter_queue_stats *stats)
int rte_event_eth_rx_adapter_queue_stats_reset (uint8_t id, uint16_t eth_dev_id, uint16_t rx_queue_id)
int rte_event_eth_rx_adapter_event_port_get (uint8_t id, uint8_t *event_port_id)
int rte_event_eth_rx_adapter_instance_get (uint16_t eth_dev_id, uint16_t rx_queue_id, uint8_t *rxa_inst_id)
__rte_experimental int rte_event_eth_rx_adapter_runtime_params_init (struct rte_event_eth_rx_adapter_runtime_params *params)
__rte_experimental int rte_event_eth_rx_adapter_runtime_params_set (uint8_t id, struct rte_event_eth_rx_adapter_runtime_params *params)
__rte_experimental int rte_event_eth_rx_adapter_runtime_params_get (uint8_t id, struct rte_event_eth_rx_adapter_runtime_params *params)

Detailed Description

RTE Event Ethernet Rx Adapter

An eventdev-based packet processing application enqueues/dequeues mbufs to/from the event device. Packet flow from the ethernet device to the event device can be accomplished using either HW or SW mechanisms depending on the platform and the particular combination of ethernet and event devices. The event ethernet Rx adapter provides common APIs to configure the packet flow from the ethernet devices to event devices across both these transfer mechanisms.

The adapter uses a EAL service core function for SW based packet transfer and uses the eventdev PMD functions to configure HW based packet transfer between the ethernet device and the event device.

The ethernet Rx event adapter's functions are:

•   rte_event_eth_rx_adapter_create_ext()

•   rte_event_eth_rx_adapter_create()

•   rte_event_eth_rx_adapter_create_with_params()

•   rte_event_eth_rx_adapter_create_ext_with_params()

•   rte_event_eth_rx_adapter_free()

•   rte_event_eth_rx_adapter_queue_add()

•   rte_event_eth_rx_adapter_queue_del()

•   rte_event_eth_rx_adapter_start()

•   rte_event_eth_rx_adapter_stop()

•   rte_event_eth_rx_adapter_stats_get()

•   rte_event_eth_rx_adapter_stats_reset()

•   rte_event_eth_rx_adapter_queue_conf_get()

•   rte_event_eth_rx_adapter_queue_stats_get()

•   rte_event_eth_rx_adapter_queue_stats_reset()

•   rte_event_eth_rx_adapter_event_port_get()

•   rte_event_eth_rx_adapter_instance_get()

•   rte_event_eth_rx_adapter_runtime_params_get()

•   rte_event_eth_rx_adapter_runtime_params_init()

•   rte_event_eth_rx_adapter_runtime_params_set()

The application creates an ethernet to event adapter using rte_event_eth_rx_adapter_create_ext() or rte_event_eth_rx_adapter_create() or rte_event_eth_rx_adapter_create_with_params() or rte_event_eth_rx_adapter_create_ext_with_params() functions.

The adapter needs to know which ethernet rx queues to poll for mbufs as well as event device parameters such as the event queue identifier, event priority and scheduling type that the adapter should use when constructing events. The rte_event_eth_rx_adapter_queue_add() function is provided for this purpose. The servicing weight parameter in the rte_event_eth_rx_adapter_queue_conf is applicable when the Rx adapter uses a service core function and is intended to provide application control of the frequency of polling ethernet device receive queues, for example, the application may want to poll higher priority queues with a higher frequency but at the same time not starve lower priority queues completely. If this parameter is zero and the receive interrupt is enabled when configuring the device, the receive queue is interrupt driven; else, the queue is assigned a servicing weight of one.

The application can start/stop the adapter using the rte_event_eth_rx_adapter_start() and the rte_event_eth_rx_adapter_stop() functions. If the adapter uses a rte_service function, then the application is also required to assign a core to the service function and control the service core using the rte_service APIs. The rte_event_eth_rx_adapter_service_id_get() function can be used to retrieve the service function ID of the adapter in this case.

For SW based packet transfers, i.e., when the RTE_EVENT_ETH_RX_ADAPTER_CAP_INTERNAL_PORT is not set in the adapter's capabilities flags for a particular ethernet device, the service function temporarily enqueues events to an event buffer before batch enqueuing these to the event device. If the buffer fills up, the service function stops dequeuing packets from the ethernet device. The application may want to monitor the buffer fill level and instruct the service function to selectively buffer events. The application may also use some other criteria to decide which packets should enter the event device even when the event buffer fill level is low or may want to enqueue packets to an internal event port. The rte_event_eth_rx_adapter_cb_register() function allows the application to register a callback that selects which packets are enqueued to the event device by the SW adapter. The callback interface is event based so the callback can also modify the event data if it needs to.

Definition in file rte_event_eth_rx_adapter.h.

Macro Definition Documentation

  #define RTE_EVENT_ETH_RX_ADAPTER_QUEUE_FLOW_ID_VALID 0x1
This flag indicates the flow identifier is valid

See also
    rte_event_eth_rx_adapter_queue_conf::rx_queue_flags

Definition at line 104 of file rte_event_eth_rx_adapter.h.

  #define RTE_EVENT_ETH_RX_ADAPTER_QUEUE_EVENT_VECTOR 0x2
This flag indicates that mbufs arriving on the queue need to be vectorized

See also
    rte_event_eth_rx_adapter_queue_conf::rx_queue_flags

Definition at line 108 of file rte_event_eth_rx_adapter.h.

Typedef Documentation

  typedef int(* rte_event_eth_rx_adapter_conf_cb) (uint8_t id, uint8_t dev_id, struct rte_event_eth_rx_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_rx_adapter_conf, this callback is invoked when creating a SW service for packet transfer from ethdev queues to the event device. The SW service is created within the rte_event_eth_rx_adapter_queue_add() function if SW based packet transfers from ethdev queues to the event device are required.

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_rx_adapter_create_ext().

Definition at line 151 of file rte_event_eth_rx_adapter.h.

  typedef uint16_t(* rte_event_eth_rx_adapter_cb_fn) (uint16_t eth_dev_id, uint16_t queue_id, uint32_t enqueue_buf_size, uint32_t enqueue_buf_count, struct rte_event *ev, uint16_t nb_event, void *cb_arg, uint16_t *nb_dropped)
Callback function invoked by the SW adapter before it continues to process events. The callback is passed the size of the enqueue buffer in the SW adapter and the occupancy of the buffer. The callback can use these values to decide which events are enqueued to the event device by the SW adapter. The callback may also enqueue events internally using its own event port. The SW adapter populates the event information based on the Rx queue configuration in the adapter. The callback can modify the this event information for the events to be enqueued by the SW adapter.

The callback return value is the number of events from the beginning of the event array that are to be enqueued by the SW adapter. It is the callback's responsibility to arrange these events at the beginning of the array, if these events are not contiguous in the original array. The nb_dropped parameter is a pointer to the number of events dropped by the callback, this number is used by the adapter to indicate the number of dropped packets as part of its statistics.

Parameters
    eth_dev_id Port identifier of the Ethernet device.
    queue_id Receive queue index.
    enqueue_buf_size Total enqueue buffer size.
    enqueue_buf_count Event count in enqueue buffer.
    ev Event array.
    nb_event Event array length.
    cb_arg Callback argument.
    nb_dropped Packets dropped by callback.

Returns

    •   The number of events to be enqueued by the SW adapter.

Definition at line 373 of file rte_event_eth_rx_adapter.h.

Function Documentation

  int rte_event_eth_rx_adapter_create_ext (uint8_t id, uint8_t dev_id, rte_event_eth_rx_adapter_conf_cb conf_cb, void * conf_arg)
Create a new ethernet Rx event adapter with the specified identifier.

Parameters
    id The identifier of the ethernet Rx event adapter.
    dev_id The identifier of the device to configure.
    conf_cb Callback function that fills in members of a struct rte_event_eth_rx_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_rx_adapter_create (uint8_t id, uint8_t dev_id, struct rte_event_port_conf * port_config)
Create a new ethernet Rx event adapter with the specified identifier. This function uses an internal configuration function that creates an event port. This default function reconfigures the event device with an additional event port and setup the event port using the port_config parameter passed into this function. In case the application needs more control in configuration of the service, it should use the rte_event_eth_rx_adapter_create_ext() version.

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 rte_event_dev_config::nb_event_ports and rte_event_dev_config::nb_single_link_event_port_queues parameters required for eth Rx adapter in the event device configuration when the adapter is created with this API.

Parameters
    id The identifier of the ethernet Rx event adapter.
    dev_id The identifier of the device to configure.
    port_config Argument of type rte_event_port_conf that is passed to the conf_cb function.

Returns

    •   0: Success

    •   <0: Error code on failure

  int rte_event_eth_rx_adapter_create_with_params (uint8_t id, uint8_t dev_id, struct rte_event_port_conf * port_config, struct rte_event_eth_rx_adapter_params * rxa_params)
This is a variant of rte_event_eth_rx_adapter_create() with additional adapter params specified in struct rte_event_eth_rx_adapter_params.

Parameters
    id The identifier of the ethernet Rx event adapter.
    dev_id The identifier of the event device to configure.
    port_config Argument of type rte_event_port_conf that is passed to the conf_cb function.
    rxa_params Pointer to struct rte_event_eth_rx_adapter_params. In case of NULL, default values are used.

Returns

    •   0: Success

    •   <0: Error code on failure

  __rte_experimental int rte_event_eth_rx_adapter_create_ext_with_params (uint8_t id, uint8_t dev_id, rte_event_eth_rx_adapter_conf_cb conf_cb, void * conf_arg, struct rte_event_eth_rx_adapter_params * rxa_params)
This is a variant of rte_event_eth_rx_adapter_create_ext() with additional adapter params specified in struct rte_event_eth_rx_adapter_params.

Parameters
    id The identifier of the ethernet Rx event adapter.
    dev_id The identifier of the event device to configure.
    conf_cb Callback function that fills in members of a struct rte_event_eth_rx_adapter_conf struct passed into it.
    conf_arg Argument that is passed to the conf_cb function.
    rxa_params Pointer to struct rte_event_eth_rx_adapter_params. In case of NULL, default values are used.

Returns

    •   0: Success

    •   <0: Error code on failure

  int rte_event_eth_rx_adapter_free (uint8_t id)
Free an event adapter

Parameters
    id Adapter identifier.

Returns

    •   0: Success

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

  int rte_event_eth_rx_adapter_queue_add (uint8_t id, uint16_t eth_dev_id, int32_t rx_queue_id, const struct rte_event_eth_rx_adapter_queue_conf * conf)
Add receive queue to an event adapter. After a queue has been added to the event adapter, the result of the application calling rte_eth_rx_burst(eth_dev_id, rx_queue_id, ..) is undefined.

Parameters
    id Adapter identifier.
    eth_dev_id Port identifier of Ethernet device.
    rx_queue_id Ethernet device receive queue index. If rx_queue_id is -1, then all Rx queues configured for the device are added. If the ethdev Rx queues can only be connected to a single event queue then rx_queue_id is required to be -1.

See also
    RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ

Parameters
    conf Additional configuration structure of type rte_event_eth_rx_adapter_queue_conf

Returns

    •   0: Success, Receive queue added correctly.

    •   <0: Error code on failure.

    •   (-EIO) device reconfiguration and restart error. The adapter reconfigures the event device with an additional port if it is required to use a service function for packet transfer from the ethernet device to the event device. If the device had been started before this call, this error code indicates an error in restart following an error in reconfiguration, i.e., a combination of the two error codes.

  __rte_experimental int rte_event_eth_rx_adapter_queues_add (uint8_t id, uint16_t eth_dev_id, int32_t rx_queue_id[], const struct rte_event_eth_rx_adapter_queue_conf conf[], uint16_t nb_rx_queues)
Add multiple receive queues to an event adapter.

Parameters
    id Adapter identifier.
    eth_dev_id Port identifier of Ethernet device.
    rx_queue_id Array of Ethernet device receive queue indices. If nb_rx_queues is 0, then rx_queue_id is ignored.
    conf Array of additional configuration structures of type rte_event_eth_rx_adapter_queue_conf. conf[i] is used for rx_queue_id[i]. If nb_rx_queues is 0, then conf[0] is used for all Rx queues.
    nb_rx_queues Number of receive queues to add. If nb_rx_queues is 0, then all Rx queues configured for the device are added with the same configuration in conf[0].

See also
    RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ

Returns

    •   0: Success, Receive queues added correctly.

    •   <0: Error code on failure.

  int rte_event_eth_rx_adapter_queue_del (uint8_t id, uint16_t eth_dev_id, int32_t rx_queue_id)
Delete receive queue from an event adapter.

Parameters
    id Adapter identifier.
    eth_dev_id Port identifier of Ethernet device.
    rx_queue_id Ethernet device receive queue index. If rx_queue_id is -1, then all Rx queues configured for the device are deleted. If the ethdev Rx queues can only be connected to a single event queue then rx_queue_id is required to be -1.

See also
    RTE_EVENT_ETH_RX_ADAPTER_CAP_MULTI_EVENTQ

Returns

    •   0: Success, Receive queue deleted correctly.

    •   <0: Error code on failure.

  int rte_event_eth_rx_adapter_start (uint8_t id)
Start ethernet Rx event adapter

Parameters
    id Adapter identifier.

Returns

    •   0: Success, Adapter started correctly.

    •   <0: Error code on failure.

Note
    The eventdev to which the event_eth_rx_adapter is connected needs to be started before calling rte_event_eth_rx_adapter_start().

  int rte_event_eth_rx_adapter_stop (uint8_t id)
Stop ethernet Rx event adapter

Parameters
    id Adapter identifier.

Returns

    •   0: Success, Adapter started correctly.

    •   <0: Error code on failure.

  int rte_event_eth_rx_adapter_stats_get (uint8_t id, struct rte_event_eth_rx_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, retrieved successfully.

    •   <0: Error code on failure.

  int rte_event_eth_rx_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_rx_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_rx_adapter_cb_register (uint8_t id, uint16_t eth_dev_id, rte_event_eth_rx_adapter_cb_fn cb_fn, void * cb_arg)
Register callback to process Rx packets, this is supported for SW based packet transfers.

See also
    rte_event_eth_rx_cb_fn

Parameters
    id Adapter identifier.
    eth_dev_id Port identifier of Ethernet device.
    cb_fn Callback function.
    cb_arg Callback arg.

Returns

    •   0: Success

    •   <0: Error code on failure.

  int rte_event_eth_rx_adapter_vector_limits_get (uint8_t dev_id, uint16_t eth_port_id, struct rte_event_eth_rx_adapter_vector_limits * limits)
Retrieve vector limits for a given event dev and eth dev pair.

See also
    rte_event_eth_rx_adapter_vector_limits

Parameters
    dev_id Event device identifier.
    eth_port_id Port identifier of the ethernet device.
    limits A pointer to rte_event_eth_rx_adapter_vector_limits structure that has to be filled.

Returns

    •   0: Success.

    •   <0: Error code on failure.

  int rte_event_eth_rx_adapter_queue_conf_get (uint8_t id, uint16_t eth_dev_id, uint16_t rx_queue_id, struct rte_event_eth_rx_adapter_queue_conf * queue_conf)
Retrieve Rx queue config information.

Parameters
    id Adapter identifier.
    eth_dev_id Port identifier of Ethernet device.
    rx_queue_id Ethernet device receive queue index.
    queue_conf Pointer to struct rte_event_eth_rx_adapter_queue_conf

Returns

    •   0: Success, Receive queue added correctly.

    •   <0: Error code on failure.

  int rte_event_eth_rx_adapter_queue_stats_get (uint8_t id, uint16_t eth_dev_id, uint16_t rx_queue_id, struct rte_event_eth_rx_adapter_queue_stats * stats)
Retrieve Rx queue statistics.

Parameters
    id Adapter identifier.
    eth_dev_id Port identifier of Ethernet device.
    rx_queue_id Ethernet device receive queue index.
    stats Pointer to struct rte_event_eth_rx_adapter_queue_stats

Returns

    •   0: Success, queue buffer stats retrieved.

    •   <0: Error code on failure.

  int rte_event_eth_rx_adapter_queue_stats_reset (uint8_t id, uint16_t eth_dev_id, uint16_t rx_queue_id)
Reset Rx queue statistics.

Parameters
    id Adapter identifier.
    eth_dev_id Port identifier of Ethernet device.
    rx_queue_id Ethernet device receive queue index.

Returns

    •   0: Success, queue buffer stats retrieved.

    •   <0: Error code on failure.

  int rte_event_eth_rx_adapter_event_port_get (uint8_t id, uint8_t * event_port_id)
Retrieve the event port ID of an adapter. If the adapter doesn't use a rte_service function, this function returns -ESRCH.

Parameters
    id Adapter identifier.
    event_port_id A pointer to a uint8_t, to be filled in with the port 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_rx_adapter_instance_get (uint16_t eth_dev_id, uint16_t rx_queue_id, uint8_t * rxa_inst_id)
Get RX adapter instance ID for a RX queue

Parameters
    eth_dev_id Port identifier of Ethernet device.
    rx_queue_id Ethernet device receive queue index.
    rxa_inst_id Pointer to store RX adapter instance identifier. Contains valid Rx adapter instance id when return value is 0

Returns

    •   0: Success

    •   <0: Error code on failure

  __rte_experimental int rte_event_eth_rx_adapter_runtime_params_init (struct rte_event_eth_rx_adapter_runtime_params * params)
Initialize the adapter runtime configuration parameters with default values

Parameters
    params A pointer to structure of type struct rte_event_eth_rx_adapter_runtime_params

Returns

    •   0: Success

    •   <0: Error code on failure

  __rte_experimental int rte_event_eth_rx_adapter_runtime_params_set (uint8_t id, struct rte_event_eth_rx_adapter_runtime_params * params)
Set the adapter runtime configuration parameters

Parameters
    id Adapter identifier
    params A pointer to structure of type struct rte_event_eth_rx_adapter_runtime_params with configuration parameter values. The reserved fields of the structure must be initialized to zero and the valid fields need to be set appropriately. This structure can be initialized using rte_event_eth_rx_adapter_runtime_params_init() to default values or application may reset this structure and update the required fields.

Returns

    •   0: Success

    •   <0: Error code on failure

  __rte_experimental int rte_event_eth_rx_adapter_runtime_params_get (uint8_t id, struct rte_event_eth_rx_adapter_runtime_params * params)
Get the adapter runtime configuration parameters

Parameters
    id Adapter identifier
    params A pointer to structure of type struct rte_event_eth_rx_adapter_runtime_params containing valid 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.