.TH "rte_event_vector_adapter.h" 3 "Version 25.11.0" "DPDK" \" -*- nroff -*- .ad l .nh .SH NAME rte_event_vector_adapter.h .SH SYNOPSIS .br .PP \fR#include \fP .br .SS "Data Structures" .in +1c .ti -1c .RI "struct \fBrte_event_vector_adapter_conf\fP" .br .ti -1c .RI "struct \fBrte_event_vector_adapter_info\fP" .br .ti -1c .RI "struct \fBrte_event_vector_adapter_stats\fP" .br .ti -1c .RI "struct \fBrte_event_vector_adapter\fP" .br .in -1c .SS "Macros" .in +1c .ti -1c .RI "#define \fBRTE_EVENT_VECTOR_ADAPTER_CAP_SOV_EOV\fP \fBRTE_BIT64\fP(0)" .br .ti -1c .RI "#define \fBRTE_EVENT_VECTOR_ENQ_SOV\fP \fBRTE_BIT64\fP(0)" .br .ti -1c .RI "#define \fBRTE_EVENT_VECTOR_ENQ_EOV\fP \fBRTE_BIT64\fP(1)" .br .ti -1c .RI "#define \fBRTE_EVENT_VECTOR_ENQ_FLUSH\fP \fBRTE_BIT64\fP(2)" .br .in -1c .SS "Typedefs" .in +1c .ti -1c .RI "\fBtypedef\fP int(* \fBrte_event_vector_adapter_port_conf_cb_t\fP) (uint8_t event_dev_id, uint8_t *event_port_id, void *conf_arg)" .br .in -1c .SS "Functions" .in +1c .ti -1c .RI "__rte_experimental struct \fBrte_event_vector_adapter\fP * \fBrte_event_vector_adapter_create\fP (const struct \fBrte_event_vector_adapter_conf\fP *conf)" .br .ti -1c .RI "__rte_experimental struct \fBrte_event_vector_adapter\fP * \fBrte_event_vector_adapter_create_ext\fP (const struct \fBrte_event_vector_adapter_conf\fP *conf, \fBrte_event_vector_adapter_port_conf_cb_t\fP conf_cb, void *conf_arg)" .br .ti -1c .RI "__rte_experimental struct \fBrte_event_vector_adapter\fP * \fBrte_event_vector_adapter_lookup\fP (uint32_t adapter_id)" .br .ti -1c .RI "__rte_experimental int \fBrte_event_vector_adapter_destroy\fP (struct \fBrte_event_vector_adapter\fP *adapter)" .br .ti -1c .RI "__rte_experimental int \fBrte_event_vector_adapter_info_get\fP (uint8_t event_dev_id, struct \fBrte_event_vector_adapter_info\fP *info)" .br .ti -1c .RI "__rte_experimental int \fBrte_event_vector_adapter_conf_get\fP (struct \fBrte_event_vector_adapter\fP *adapter, struct \fBrte_event_vector_adapter_conf\fP *conf)" .br .ti -1c .RI "__rte_experimental uint8_t \fBrte_event_vector_adapter_remaining\fP (uint8_t event_dev_id, uint8_t event_queue_id)" .br .ti -1c .RI "__rte_experimental int \fBrte_event_vector_adapter_stats_get\fP (struct \fBrte_event_vector_adapter\fP *adapter, struct \fBrte_event_vector_adapter_stats\fP *stats)" .br .ti -1c .RI "__rte_experimental int \fBrte_event_vector_adapter_stats_reset\fP (struct \fBrte_event_vector_adapter\fP *adapter)" .br .ti -1c .RI "__rte_experimental int \fBrte_event_vector_adapter_service_id_get\fP (struct \fBrte_event_vector_adapter\fP *adapter, uint32_t *service_id)" .br .ti -1c .RI "static __rte_experimental int \fBrte_event_vector_adapter_enqueue\fP (struct \fBrte_event_vector_adapter\fP *adapter, uint64_t objs[], uint16_t num_elem, uint64_t flags)" .br .in -1c .SH "Detailed Description" .PP .PP \fBWarning\fP .RS 4 \fBEXPERIMENTAL:\fP All functions in this file may be changed or removed without prior notice\&. .RE .PP Event vector adapter API\&. .PP An event vector adapter has the following working model: .PP .nf ┌──────────┐ │ Vector ├─┐ ---[1]--->│ adapter 0│ │ [1] rte_event_vector_adapter_enqueue() └──────────┘ │ ┌──────────┐ │ ┌──────────┐ │ Vector ├─┼──>│ Event │ ---[1]--->│ adapter 1│ │ │ Queue 0 │ └──────────┘ │ └──────────┘ ┌──────────┐ │ │ Vector ├─┘ ---[1]--->│ adapter n│ └──────────┘ .fi .PP .PP .IP "\(bu" 2 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\&. .IP "\(bu" 2 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 \fBRTE_EVENT_QUEUE_CFG_ALL_TYPES\fP, then the vector adapter should use the same schedule type as the event queue\&. .IP "\(bu" 2 Each vector adapter aggregates 8B objects, generates a vector event and enqueues it to the event queue with the event properties mentioned in \fBrte_event_vector_adapter_conf::ev\fP\&. .IP "\(bu" 2 After configuring the vector adapter, Application needs to use the \fBrte_event_vector_adapter_enqueue()\fP 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\&. .IP "\(bu" 2 If the vector adapter advertises the \fBRTE_EVENT_VECTOR_ADAPTER_CAP_SOV_EOV\fP capability, application can use the RTE_EVENT_VECTOR_ENQ_[S|E]OV flags to indicate the start and end of a vector event\&. .IP " \(bu" 4 When \fBRTE_EVENT_VECTOR_ENQ_SOV\fP is set, the vector adapter will flush any aggregation in-progress and start aggregating a new vector event with the enqueued objects\&. .IP " \(bu" 4 When \fBRTE_EVENT_VECTOR_ENQ_EOV\fP 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\&. .IP " \(bu" 4 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\&. .PP .IP "\(bu" 2 If the vector adapter reaches the configured vector size, it will enqueue the aggregated vector event to the event queue\&. .IP "\(bu" 2 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\&. .IP "\(bu" 2 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 \fBrte_event_vector_adapter_conf::ev_fallback\fP\&. .PP .PP 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\&. .PP When the application creates the vector adapter using the \fR\fBrte_event_vector_adapter_create()\fP\fP 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 \fR\fBrte_event_vector_adapter_create_ext()\fP\fP function\&. .PP The application can enqueue one or more objs to the vector adapter using the \fR\fBrte_event_vector_adapter_enqueue()\fP\fP function and control the aggregation using the flags\&. .PP Vector adapters report stats using the \fR\fBrte_event_vector_adapter_stats_get()\fP\fP function and reset the stats using the \fR\fBrte_event_vector_adapter_stats_reset()\fP\fP\&. .PP The application can destroy the vector adapter using the \fR\fBrte_event_vector_adapter_destroy()\fP\fP function\&. .PP Definition in file \fBrte_event_vector_adapter\&.h\fP\&. .SH "Macro Definition Documentation" .PP .SS "#define RTE_EVENT_VECTOR_ADAPTER_CAP_SOV_EOV \fBRTE_BIT64\fP(0)" Vector adapter supports Start of Vector (SOV) and End of Vector (EOV) flags in the enqueue flags\&. .PP \fBSee also\fP .RS 4 \fBRTE_EVENT_VECTOR_ENQ_SOV\fP .PP \fBRTE_EVENT_VECTOR_ENQ_EOV\fP .RE .PP .PP Definition at line \fB109\fP of file \fBrte_event_vector_adapter\&.h\fP\&. .SS "#define RTE_EVENT_VECTOR_ENQ_SOV \fBRTE_BIT64\fP(0)" Indicates the start of a vector event\&. When enqueue is called with \fBRTE_EVENT_VECTOR_ENQ_SOV\fP, the vector adapter will flush any vector aggregation in progress and start aggregating a new vector event with the enqueued objects\&. .PP \fBSee also\fP .RS 4 \fBRTE_EVENT_VECTOR_ADAPTER_CAP_SOV_EOV\fP .RE .PP .PP Definition at line \fB117\fP of file \fBrte_event_vector_adapter\&.h\fP\&. .SS "#define RTE_EVENT_VECTOR_ENQ_EOV \fBRTE_BIT64\fP(1)" Indicates the end of a vector event\&. When enqueue is called with \fBRTE_EVENT_VECTOR_ENQ_EOV\fP, the vector adapter will add the objects to any inprogress aggregation and flush the event vector\&. .PP \fBSee also\fP .RS 4 \fBRTE_EVENT_VECTOR_ADAPTER_CAP_SOV_EOV\fP .RE .PP .PP Definition at line \fB124\fP of file \fBrte_event_vector_adapter\&.h\fP\&. .SS "#define RTE_EVENT_VECTOR_ENQ_FLUSH \fBRTE_BIT64\fP(2)" Flush any in-progress vector aggregation\&. .PP Definition at line \fB130\fP of file \fBrte_event_vector_adapter\&.h\fP\&. .SH "Typedef Documentation" .PP .SS "\fBtypedef\fP 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\&. .PP Definition at line \fB245\fP of file \fBrte_event_vector_adapter\&.h\fP\&. .SH "Function Documentation" .PP .SS "__rte_experimental struct \fBrte_event_vector_adapter\fP * rte_event_vector_adapter_create (const struct \fBrte_event_vector_adapter_conf\fP * conf)" Create an event vector adapter\&. .PP 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\&. .PP \fBSee also\fP .RS 4 rte_event_vector_adapter_conf::ev::queue_id .RE .PP \fBParameters\fP .RS 4 \fIconf\fP Configuration for the event vector adapter\&. .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 Pointer to the created event vector adapter on success\&. .IP "\(bu" 2 NULL on failure with rte_errno set to the error code\&. Possible rte_errno values include: .IP " \(bu" 4 EINVAL: Invalid event device identifier specified in config\&. .IP " \(bu" 4 ENOMEM: Unable to allocate sufficient memory for adapter instances\&. .IP " \(bu" 4 ENOSPC: Maximum number of adapters already created\&. .PP .PP .RE .PP .SS "__rte_experimental struct \fBrte_event_vector_adapter\fP * rte_event_vector_adapter_create_ext (const struct \fBrte_event_vector_adapter_conf\fP * conf, \fBrte_event_vector_adapter_port_conf_cb_t\fP conf_cb, void * conf_arg)" Create an event vector adapter with the supplied callback\&. .PP 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\&. .PP \fBParameters\fP .RS 4 \fIconf\fP The event vector adapter configuration structure\&. .br \fIconf_cb\fP The port config callback function\&. .br \fIconf_arg\fP Opaque pointer to the argument for the callback function\&. .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 Pointer to the new allocated event vector adapter on success\&. .IP "\(bu" 2 NULL on error with rte_errno set appropriately Possible rte_errno values include: .IP "\(bu" 2 ERANGE: vector_timeout_ns is not in supported range\&. .IP "\(bu" 2 ENOMEM: Unable to allocate sufficient memory for adapter instances\&. .IP "\(bu" 2 EINVAL: Invalid event device identifier specified in config\&. .IP "\(bu" 2 ENOSPC: Maximum number of adapters already created\&. .PP .RE .PP .SS "__rte_experimental struct \fBrte_event_vector_adapter\fP * rte_event_vector_adapter_lookup (uint32_t adapter_id)" Lookup an event vector adapter using its identifier\&. .PP 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\&. .PP \fBParameters\fP .RS 4 \fIadapter_id\fP Identifier of the event vector adapter to look up\&. .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 Pointer to the event vector adapter on success\&. .IP "\(bu" 2 NULL if the adapter is not found\&. .PP .RE .PP .SS "__rte_experimental int rte_event_vector_adapter_destroy (struct \fBrte_event_vector_adapter\fP * adapter)" Destroy an event vector adapter\&. .PP This function releases the resources associated with the event vector adapter\&. .PP \fBParameters\fP .RS 4 \fIadapter\fP Pointer to the event vector adapter to be destroyed\&. .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 0 on success\&. .IP "\(bu" 2 Negative value on failure with rte_errno set to the error code\&. .PP .RE .PP .SS "__rte_experimental int rte_event_vector_adapter_info_get (uint8_t event_dev_id, struct \fBrte_event_vector_adapter_info\fP * info)" Get the vector info of an event vector adapter\&. .PP This function retrieves the vector info of the event vector adapter\&. .PP \fBParameters\fP .RS 4 \fIevent_dev_id\fP Event device identifier\&. .br \fIinfo\fP Pointer to the structure where the vector info will be stored\&. .RE .PP \fBReturns\fP .RS 4 0 on success, negative value on failure\&. .IP "\(bu" 2 EINVAL if the event device identifier is invalid\&. .IP "\(bu" 2 ENOTSUP if the event device does not support vector adapters\&. .PP .RE .PP .SS "__rte_experimental int rte_event_vector_adapter_conf_get (struct \fBrte_event_vector_adapter\fP * adapter, struct \fBrte_event_vector_adapter_conf\fP * conf)" Get the configuration of an event vector adapter\&. .PP This function retrieves the configuration of the event vector adapter\&. .PP \fBParameters\fP .RS 4 \fIadapter\fP Pointer to the event vector adapter\&. .br \fIconf\fP Pointer to the structure where the configuration will be stored\&. .RE .PP \fBReturns\fP .RS 4 0 on success, negative value on failure\&. .RE .PP .SS "__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\&. .PP This function retrieves the number of remaining event vector adapters available for a given event device and event queue\&. .PP \fBParameters\fP .RS 4 \fIevent_dev_id\fP Event device identifier\&. .br \fIevent_queue_id\fP Event queue identifier\&. .RE .PP \fBReturns\fP .RS 4 Number of remaining slots available for enqueuing events\&. .RE .PP .SS "__rte_experimental int rte_event_vector_adapter_stats_get (struct \fBrte_event_vector_adapter\fP * adapter, struct \fBrte_event_vector_adapter_stats\fP * stats)" Get the event vector adapter statistics\&. .PP This function retrieves the statistics of the event vector adapter\&. .PP \fBParameters\fP .RS 4 \fIadapter\fP Pointer to the event vector adapter\&. .br \fIstats\fP Pointer to the structure where the statistics will be stored\&. .RE .PP \fBReturns\fP .RS 4 0 on success, negative value on failure\&. .RE .PP .SS "__rte_experimental int rte_event_vector_adapter_stats_reset (struct \fBrte_event_vector_adapter\fP * adapter)" Reset the event vector adapter statistics\&. .PP This function resets the statistics of the event vector adapter to their default values\&. .PP \fBParameters\fP .RS 4 \fIadapter\fP Pointer to the event vector adapter whose statistics are to be reset\&. .RE .PP \fBReturns\fP .RS 4 0 on success, negative value on failure\&. .RE .PP .SS "__rte_experimental int rte_event_vector_adapter_service_id_get (struct \fBrte_event_vector_adapter\fP * 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\&. .PP \fBParameters\fP .RS 4 \fIadapter\fP A pointer to an event vector adapter\&. .br \fIservice_id\fP A pointer to a uint32_t, to be filled in with the service id\&. .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 0: Success .IP "\(bu" 2 <0: Error code on failure .IP "\(bu" 2 -ESRCH: the adapter does not require a service to operate .PP .RE .PP .SS "__rte_experimental int rte_event_vector_adapter_enqueue (struct \fBrte_event_vector_adapter\fP * adapter, uint64_t objs[], uint16_t num_elem, uint64_t flags)\fR [inline]\fP, \fR [static]\fP" Enqueue objs into the event vector adapter\&. .PP 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\&. .PP \fBParameters\fP .RS 4 \fIadapter\fP Pointer to the event vector adapter\&. .br \fIobjs\fP Array of objs to be enqueued\&. .br \fInum_elem\fP Number of objs to be enqueued\&. .br \fIflags\fP Flags to be used for the enqueue operation\&. .RE .PP \fBReturns\fP .RS 4 Number of objs enqueued on success\&. .RE .PP .PP Definition at line \fB455\fP of file \fBrte_event_vector_adapter\&.h\fP\&. .SH "Author" .PP Generated automatically by Doxygen for DPDK from the source code\&.