Re: [PATCH v2 1/3] eventdev: introduce event vector adapter

[Jerin Jacob <jerinjacobk@gmail.com>]

On Fri, May 30, 2025 at 3:55 AM <pbhagavatula@marvell.com> wrote:
>
> From: Pavan Nikhilesh <pbhagavatula@marvell.com>
>
> The event vector adapter supports offloading creation of
> event vectors by vectorizing objects (mbufs/ptrs/u64s).
> Applications can create a vector adapter associated with
> an event queue and enqueue objects to be vectorized.
> When the vector reaches the configured size or when the timeout
> is reached, the vector adapter will enqueue the vector to the
> event queue.
>
> Signed-off-by: Pavan Nikhilesh <pbhagavatula@marvell.com>

> +* **Added eventdev vector adapter.**
> +
> +  Added the Event vector Adapter Library. This library extends the event-based
> +  model by introducing APIs that allow applications to offload creation of
> +  event vectors, thereby reducing the scheduling latency.
> +
> +  Use cases for the Event Vector Adapter include:

# This additional description is not needed in the above line, link to
event adapter programming guide
# In the programing guide and header file description, emphasis on
this feature is when CPU is event producer
# Please below some documentation improvements[1]. Please include it
in the next version.
# Series-Acked-by: Jerin Jacob <jerinj@marvell.com>
# I will merge next version and when HW PMD v1 is ready. HW PMD
version will review separately and merge after rc1.


[1]
diff --git a/doc/guides/prog_guide/eventdev/event_vector_adapter.rst
b/doc/guides/prog_guide/eventdev/event_vector_adapter.rst
index 3a36245266..9126c5d79e 100644
--- a/doc/guides/prog_guide/eventdev/event_vector_adapter.rst
+++ b/doc/guides/prog_guide/eventdev/event_vector_adapter.rst
@@ -5,14 +5,10 @@ Event Vector Adapter Library
 ============================

 The Event Vector Adapter library extends the event-driven model by introducing
-a mechanism to aggregate multiple 8B objects (e.g., mbufs, u64s) into a single
-vector event and enqueue it to an event queue, there by reducing the scheduling
-latency while preserving the ingress order and offloading vector allocation and
-aggregation to the vector adapter.
-
-@see struct rte_event_vector::mbufs
-@see struct rte_event_vector::u64s
-@see struct rte_event_vector::ptrs
+a mechanism to aggregate multiple 8B objects
+(e.g. ``rte_event_vector::mbufs``, ``rte_event_vector::u64s``) into a
single vector event
+and enqueue it to an event queue, there by reducing the scheduling
latency while preserving
+the ingress order and offloading vector allocation and aggregation to
the vector adapter.

 The Event Vector Adapter library is designed to interface with hardware or
 software implementations of vector aggregation. It queries an eventdev PMD
@@ -60,12 +56,12 @@ and configure a vector adapter and use it to
manage vector events.

 From a high level, the setup steps are:

-* rte_event_vector_adapter_create()
+* ``rte_event_vector_adapter_create()``

 And to enqueue and manage vectors:

-* rte_event_vector_adapter_enqueue()
-* rte_event_vector_adapter_stats_get()
+* ``rte_event_vector_adapter_enqueue()``
+* ``rte_event_vector_adapter_stats_get()``

 Create and Configure a Vector Adapter
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -204,7 +200,7 @@ Statistics and Cleanup
 ----------------------

 The application can retrieve statistics for the vector adapter using
-``rte_event_vector_adapter_stats_get()``:
+``rte_event_vector_adapter_stats_get()``

 .. code-block:: c

diff --git a/lib/eventdev/rte_event_vector_adapter.h
b/lib/eventdev/rte_event_vector_adapter.h
index 6b69f7ba3e..7ecaf5552b 100644
--- a/lib/eventdev/rte_event_vector_adapter.h
+++ b/lib/eventdev/rte_event_vector_adapter.h
@@ -19,24 +19,15 @@
  *
  *         ┌──────────┐
  *         │  Vector  ├─┐
- *         │ adapter0 │ │
+ *         │ adapter 0│ │
  *         └──────────┘ │
  *         ┌──────────┐ │   ┌──────────┐
  *         │  Vector  ├─┼──►│  Event   │
- *         │ adapter1 │ │   │  Queue0  │
+ *         │ adapter 1│ │   │  Queue   │
  *         └──────────┘ │   └──────────┘
  *         ┌──────────┐ │
  *         │  Vector  ├─┘
- *         │ adapter2 │
- *         └──────────┘

- *         ┌──────────┐
- *         │  Vector  ├─┐


                        - *         │ adapter0 │ │   ┌──────────┐
- *         └──────────┘ ├──►│  Event   │
- *         ┌──────────┐ │   │  Queue1  │
- *         │  Vector  ├─┘   └──────────┘
- *         │ adapter1 │
+ *         │ adapter n│
  *         └──────────┘
  *


                          * - A vector adapter can be seen as an
extension to event queue. It helps in
@@ -45,7 +36,7 @@
  *
  * - 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,
+ *   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.


                          *
@@ -61,13 +52,13 @@
  *   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
+ * - 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
+ *   * 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
+ *   * 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.
@@ -126,14 +117,14 @@ extern "C" {

 #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
+ *  #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 RTE_EVENT_VECTOR_ADAPTER_CAP_SOV_EOV
  */
 #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
+ *  #RTE_EVENT_VECTOR_ENQ_EOV, the vector adapter will add the objects
  *  to any inprogress aggregation and flush the event vector.
  *  @see RTE_EVENT_VECTOR_ADAPTER_CAP_SOV_EOV


+/**
+ * Vector adapter vector structure
+ */
 struct __rte_cache_aligned rte_event_vector_adapter {
        rte_event_vector_adapter_enqueue_t enqueue;
        /**< Pointer to driver enqueue function. */
@@ -259,14 +253,14 @@ typedef int
(*rte_event_vector_adapter_port_conf_cb_t)(uint8_t event_dev_id, uin
  * 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 rte_event_vector_adapter_conf::ev::event_queue_id.
+ * @see rte_event_vector_adapter_conf::ev::queue_id
  *


                          * @param conf
  *   Configuration for the event vector adapter.
  * @return


                          *   - 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:
+ * 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.
@@ -291,8 +285,8 @@ rte_event_vector_adapter_create(const struct
rte_event_vector_adapter_conf *conf
  *   Opaque pointer to the argument for the callback function.
  * @return
  *   - Pointer to the new allocated event vector adapter on success.
- *   - NULL on error with rte_errno set appropriately.
- *   Possible rte_errno values include:
+ *   - 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.
@@ -407,7 +401,7 @@ rte_event_vector_adapter_stats_get(struct
rte_event_vector_adapter *adapter,
                                   struct
rte_event_vector_adapter_stats *stats);



                         /**
- * @brief Reset the event vector adapter statistics.
+ * Reset the event vector adapter statistics.
  *


                          * This function resets the statistics of the
event vector adapter to their default values.
  *
> +    * Offload CPU event vector creation overhead i.e., vector allocation and
> +      aggregation.
> +    * Splitting existing vectors to classify objects into different event queues
> +      based on their properties.
> +
> +
>