Scroll to navigation

rte_event_vector_adapter.h(3) Library Functions Manual rte_event_vector_adapter.h(3)

NAME

rte_event_vector_adapter.h

SYNOPSIS

#include <rte_eventdev.h>

Data Structures


struct rte_event_vector_adapter_conf
struct rte_event_vector_adapter_info
struct rte_event_vector_adapter_stats
struct rte_event_vector_adapter

Macros


#define RTE_EVENT_VECTOR_ADAPTER_CAP_SOV_EOV RTE_BIT64(0)
#define RTE_EVENT_VECTOR_ENQ_SOV RTE_BIT64(0)
#define RTE_EVENT_VECTOR_ENQ_EOV RTE_BIT64(1)
#define RTE_EVENT_VECTOR_ENQ_FLUSH RTE_BIT64(2)

Typedefs


typedef int(* rte_event_vector_adapter_port_conf_cb_t) (uint8_t event_dev_id, uint8_t *event_port_id, void *conf_arg)

Functions


__rte_experimental struct rte_event_vector_adapter * rte_event_vector_adapter_create (const struct rte_event_vector_adapter_conf *conf)
__rte_experimental struct rte_event_vector_adapter * rte_event_vector_adapter_create_ext (const struct rte_event_vector_adapter_conf *conf, rte_event_vector_adapter_port_conf_cb_t conf_cb, void *conf_arg)
__rte_experimental struct rte_event_vector_adapter * rte_event_vector_adapter_lookup (uint32_t adapter_id)
__rte_experimental int rte_event_vector_adapter_destroy (struct rte_event_vector_adapter *adapter)
__rte_experimental int rte_event_vector_adapter_info_get (uint8_t event_dev_id, struct rte_event_vector_adapter_info *info)
__rte_experimental int rte_event_vector_adapter_conf_get (struct rte_event_vector_adapter *adapter, struct rte_event_vector_adapter_conf *conf)
__rte_experimental uint8_t rte_event_vector_adapter_remaining (uint8_t event_dev_id, uint8_t event_queue_id)
__rte_experimental int rte_event_vector_adapter_stats_get (struct rte_event_vector_adapter *adapter, struct rte_event_vector_adapter_stats *stats)
__rte_experimental int rte_event_vector_adapter_stats_reset (struct rte_event_vector_adapter *adapter)
__rte_experimental int rte_event_vector_adapter_service_id_get (struct rte_event_vector_adapter *adapter, uint32_t *service_id)
static __rte_experimental int rte_event_vector_adapter_enqueue (struct rte_event_vector_adapter *adapter, uint64_t objs[], uint16_t num_elem, uint64_t flags)

Detailed Description

Warning

EXPERIMENTAL: All functions in this file may be changed or removed without prior notice.

Event vector adapter API.

An event vector adapter has the following working model:



             ┌──────────┐


             │  Vector  ├─┐


   ---[1]--->│ adapter 0│ │  [1] rte_event_vector_adapter_enqueue()


             └──────────┘ │


             ┌──────────┐ │   ┌──────────┐


             │  Vector  ├─┼──>│  Event   │


   ---[1]--->│ adapter 1│ │   │  Queue 0 │


             └──────────┘ │   └──────────┘


             ┌──────────┐ │


             │  Vector  ├─┘


   ---[1]--->│ adapter n│


             └──────────┘
  • A vector adapter can be seen as an extension to event queue. It helps in aggregating objects and generating a vector event which is enqueued to the event queue.
  • Multiple vector adapters can be created on an event queue, each with its own unique properties such as event properties, vector size, and timeout. Note: If the target event queue doesn't support RTE_EVENT_QUEUE_CFG_ALL_TYPES, then the vector adapter should use the same schedule type as the event queue.
  • Each vector adapter aggregates 8B objects, generates a vector event and enqueues it to the event queue with the event properties mentioned in rte_event_vector_adapter_conf::ev.
  • After configuring the vector adapter, Application needs to use the rte_event_vector_adapter_enqueue() function to enqueue objects i.e., mbufs/ptrs/u64s to the vector adapter. On reaching the configured vector size or timeout, the vector adapter enqueues the event vector to the event queue. Note: Application should use the event_type and sub_event_type properly identifying the contents of vector event on dequeue.
  • If the vector adapter advertises the RTE_EVENT_VECTOR_ADAPTER_CAP_SOV_EOV capability, application can use the RTE_EVENT_VECTOR_ENQ_[S|E]OV flags to indicate the start and end of a vector event.
•
When RTE_EVENT_VECTOR_ENQ_SOV is set, the vector adapter will flush any aggregation in-progress and start aggregating a new vector event with the enqueued objects.
•
When RTE_EVENT_VECTOR_ENQ_EOV is set, the vector adapter will add the objects enqueued to the in-progress aggregation and enqueue the vector event to the event queue, even if configured vector size or timeout is not reached.
•
If both flags are set, the vector adapter will flush any aggregation in progress and enqueue the objects as a new vector event to the event queue.
  • If the vector adapter reaches the configured vector size, it will enqueue the aggregated vector event to the event queue.
  • If the vector adapter reaches the configured vector timeout, it will flush the aggregated objects as a vector event if the minimum vector size is reached, if not it will enqueue the objs as single events to the event queue.
  • If the vector adapter is unable to aggregate the objs into a vector event, it will enqueue the objs as single events to the event queue with the event properties mentioned in rte_event_vector_adapter_conf::ev_fallback.

Before using the vector adapter, the application has to create and configure an event device and based on the event device capability it might require creating an additional event port.

When the application creates the vector adapter using the rte_event_vector_adapter_create() function, the event device driver capabilities are checked. If an in-built port is absent, the application uses the default function to create a new event port. For finer control over event port creation, the application should use the rte_event_vector_adapter_create_ext() function.

The application can enqueue one or more objs to the vector adapter using the rte_event_vector_adapter_enqueue() function and control the aggregation using the flags.

Vector adapters report stats using the rte_event_vector_adapter_stats_get() function and reset the stats using the rte_event_vector_adapter_stats_reset().

The application can destroy the vector adapter using the rte_event_vector_adapter_destroy() function.

Definition in file rte_event_vector_adapter.h.

Macro Definition Documentation

#define RTE_EVENT_VECTOR_ADAPTER_CAP_SOV_EOV RTE_BIT64(0)

Vector adapter supports Start of Vector (SOV) and End of Vector (EOV) flags in the enqueue flags.

See also

RTE_EVENT_VECTOR_ENQ_SOV

RTE_EVENT_VECTOR_ENQ_EOV

Definition at line 109 of file rte_event_vector_adapter.h.

#define RTE_EVENT_VECTOR_ENQ_SOV RTE_BIT64(0)

Indicates the start of a vector event. When enqueue is called with RTE_EVENT_VECTOR_ENQ_SOV, the vector adapter will flush any vector aggregation in progress and start aggregating a new vector event with the enqueued objects.

See also

RTE_EVENT_VECTOR_ADAPTER_CAP_SOV_EOV

Definition at line 117 of file rte_event_vector_adapter.h.

#define RTE_EVENT_VECTOR_ENQ_EOV RTE_BIT64(1)

Indicates the end of a vector event. When enqueue is called with RTE_EVENT_VECTOR_ENQ_EOV, the vector adapter will add the objects to any inprogress aggregation and flush the event vector.

See also

RTE_EVENT_VECTOR_ADAPTER_CAP_SOV_EOV

Definition at line 124 of file rte_event_vector_adapter.h.

#define RTE_EVENT_VECTOR_ENQ_FLUSH RTE_BIT64(2)

Flush any in-progress vector aggregation.

Definition at line 130 of file rte_event_vector_adapter.h.

Typedef Documentation

typedef int(* rte_event_vector_adapter_port_conf_cb_t) (uint8_t event_dev_id, uint8_t *event_port_id, void *conf_arg)

Callback function type for producer port creation.

Definition at line 245 of file rte_event_vector_adapter.h.

Function Documentation

__rte_experimental struct rte_event_vector_adapter * rte_event_vector_adapter_create (const struct rte_event_vector_adapter_conf * conf)

Create an event vector adapter.

This function creates an event vector adapter based on the provided configuration. The adapter can be used to combine multiple mbufs/ptrs/u64s into a single vector event, i.e., rte_event_vector, which is then enqueued to the event queue provided.

See also

rte_event_vector_adapter_conf::ev::queue_id

Parameters

conf Configuration for the event vector adapter.

Returns

  • Pointer to the created event vector adapter on success.
  • NULL on failure with rte_errno set to the error code. Possible rte_errno values include:
•
EINVAL: Invalid event device identifier specified in config.
•
ENOMEM: Unable to allocate sufficient memory for adapter instances.
•
ENOSPC: Maximum number of adapters already created.

__rte_experimental struct rte_event_vector_adapter * rte_event_vector_adapter_create_ext (const struct rte_event_vector_adapter_conf * conf, rte_event_vector_adapter_port_conf_cb_t conf_cb, void * conf_arg)

Create an event vector adapter with the supplied callback.

This function can be used to have a more granular control over the event vector adapter creation. If a built-in port is absent, then the function uses the callback provided to create and get the port id to be used as a producer port.

Parameters

conf The event vector adapter configuration structure.
conf_cb The port config callback function.
conf_arg Opaque pointer to the argument for the callback function.

Returns

  • Pointer to the new allocated event vector adapter on success.
  • NULL on error with rte_errno set appropriately Possible rte_errno values include:
  • ERANGE: vector_timeout_ns is not in supported range.
  • ENOMEM: Unable to allocate sufficient memory for adapter instances.
  • EINVAL: Invalid event device identifier specified in config.
  • ENOSPC: Maximum number of adapters already created.

__rte_experimental struct rte_event_vector_adapter * rte_event_vector_adapter_lookup (uint32_t adapter_id)

Lookup an event vector adapter using its identifier.

This function returns the event vector adapter based on the adapter_id. This is useful when the adapter is created in another process and the application wants to use the adapter in the current process.

Parameters

adapter_id Identifier of the event vector adapter to look up.

Returns

  • Pointer to the event vector adapter on success.
  • NULL if the adapter is not found.

__rte_experimental int rte_event_vector_adapter_destroy (struct rte_event_vector_adapter * adapter)

Destroy an event vector adapter.

This function releases the resources associated with the event vector adapter.

Parameters

adapter Pointer to the event vector adapter to be destroyed.

Returns

  • 0 on success.
  • Negative value on failure with rte_errno set to the error code.

__rte_experimental int rte_event_vector_adapter_info_get (uint8_t event_dev_id, struct rte_event_vector_adapter_info * info)

Get the vector info of an event vector adapter.

This function retrieves the vector info of the event vector adapter.

Parameters

event_dev_id Event device identifier.
info Pointer to the structure where the vector info will be stored.

Returns

0 on success, negative value on failure.
  • EINVAL if the event device identifier is invalid.
  • ENOTSUP if the event device does not support vector adapters.

__rte_experimental int rte_event_vector_adapter_conf_get (struct rte_event_vector_adapter * adapter, struct rte_event_vector_adapter_conf * conf)

Get the configuration of an event vector adapter.

This function retrieves the configuration of the event vector adapter.

Parameters

adapter Pointer to the event vector adapter.
conf Pointer to the structure where the configuration will be stored.

Returns

0 on success, negative value on failure.

__rte_experimental uint8_t rte_event_vector_adapter_remaining (uint8_t event_dev_id, uint8_t event_queue_id)

Get the remaining event vector adapters.

This function retrieves the number of remaining event vector adapters available for a given event device and event queue.

Parameters

event_dev_id Event device identifier.
event_queue_id Event queue identifier.

Returns

Number of remaining slots available for enqueuing events.

__rte_experimental int rte_event_vector_adapter_stats_get (struct rte_event_vector_adapter * adapter, struct rte_event_vector_adapter_stats * stats)

Get the event vector adapter statistics.

This function retrieves the statistics of the event vector adapter.

Parameters

adapter Pointer to the event vector adapter.
stats Pointer to the structure where the statistics will be stored.

Returns

0 on success, negative value on failure.

__rte_experimental int rte_event_vector_adapter_stats_reset (struct rte_event_vector_adapter * adapter)

Reset the event vector adapter statistics.

This function resets the statistics of the event vector adapter to their default values.

Parameters

adapter Pointer to the event vector adapter whose statistics are to be reset.

Returns

0 on success, negative value on failure.

__rte_experimental int rte_event_vector_adapter_service_id_get (struct rte_event_vector_adapter * adapter, uint32_t * service_id)

Retrieve the service ID of the event vector adapter. If the adapter doesn't use an rte_service function, this function returns -ESRCH.

Parameters

adapter A pointer to an event vector adapter.
service_id A pointer to a uint32_t, to be filled in with the service id.

Returns

  • 0: Success
  • <0: Error code on failure
  • -ESRCH: the adapter does not require a service to operate

__rte_experimental int rte_event_vector_adapter_enqueue (struct rte_event_vector_adapter * adapter, uint64_t objs[], uint16_t num_elem, uint64_t flags) [inline], [static]

Enqueue objs into the event vector adapter.

This function enqueues a specified number of objs into the event vector adapter. The objs are combined into a single vector event, i.e., rte_event_vector, which is then enqueued to the event queue configured in the adapter.

Parameters

adapter Pointer to the event vector adapter.
objs Array of objs to be enqueued.
num_elem Number of objs to be enqueued.
flags Flags to be used for the enqueue operation.

Returns

Number of objs enqueued on success.

Definition at line 455 of file rte_event_vector_adapter.h.

Author

Generated automatically by Doxygen for DPDK from the source code.

Version 25.11.0 DPDK