[PATCH v2] API: add event vectors and event aggregators

include/odp/api/spec/classification.h

@@ -1,6 +1,6 @@
 /* SPDX-License-Identifier: BSD-3-Clause
  * Copyright (c) 2014-2018 Linaro Limited
- * Copyright (c) 2021-2023 Nokia
+ * Copyright (c) 2021-2025 Nokia
  */
 
 /**
@@ -682,7 +682,13 @@ typedef struct odp_cls_cos_param {
 	/** Back Pressure configuration */
 	odp_bp_param_t bp;
 
-	/** Packet input vector configuration */
+	/** Packet input vector configuration
+	 *
+	 * Generating vectors of packets can be enabled either through this
+	 * configuration or by using event aggregators as destination queue(s).
+	 * Both options cannot be enabled simultaneously in the same ODP
+	 * application.
+	 */
 	odp_pktin_vector_config_t vector;
 
 } odp_cls_cos_param_t;

include/odp/api/spec/event_vector_types.h

@@ -1,5 +1,5 @@
 /* SPDX-License-Identifier: BSD-3-Clause
- * Copyright (c) 2024 Nokia
+ * Copyright (c) 2024-2025 Nokia
  */
 
 /**
@@ -33,6 +33,86 @@ extern "C" {
  * Invalid event vector
  */
 
+/**
+ * Event vector configuration
+ */
+typedef struct odp_event_aggregator_config_t {
+	/** Vector pool
+	 *
+	 * Pool from which to allocate event vectors. The pool must have been
+	 * created with the ODP_POOL_VECTOR type.
+	 */
+	odp_pool_t pool;
+
+	/** Maximum time to wait for events
+	 *
+	 * Maximum time in nanoseconds for an event aggregator to form an event
+	 * vector. This value should be in the range of
+	 * odp_event_aggregator_capability_t::min_tmo_ns to
+	 * odp_event_aggregator_capability_t::max_tmo_ns.
+	 *
+	 * Value of zero means there is no timeout. Events may wait aggregation
+	 * indefinitely in the aggregation queue.
+	 */
+	uint64_t max_tmo_ns;
+
+	/** Maximum number of events in vector
+	 *
+	 * Event aggregator forms an event vector event after 'max_size' events
+	 * have been collected or 'max_tmo_ns' has passed. 'max_size' value
+	 * should be in the range of odp_event_aggregator_capability_t::min_size
+	 * to odp_event_aggregator_capability_t::max_size.
+	 *
+	 * The maximum number of events a vector can hold is defined by
+	 * odp_pool_param_t::vector::max_size of the vector pool and 'max_size'
+	 * must not be greater than this value.
+	 */
+	uint32_t max_size;
+
+	/** Event type
+	 *
+	 * Event type of event aggregator. If 'event_type' is ODP_EVENT_ANY,
+	 * application is allowed to enqueue any event types, except event
+	 * vectors, to the event aggregator. Otherwise, only events of type
+	 * 'event_type' are allowed. The default value is ODP_EVENT_ANY.
+	 *
+	 * Regardless of 'event_type', an application is never allowed to
+	 * enqueue event vector or packet vector events (ODP_EVENT_VECTOR or
+	 * ODP_EVENT_PACKET_VECTOR) to a queue with event aggregation enabled
+	 * (i.e. vectors within vectors).
+	 */
+	odp_event_type_t event_type;
+
+} odp_event_aggregator_config_t;
+
+/**
+ * Event aggregator capabilities
+ */
+typedef struct odp_event_aggregator_capability_t {
+	/** Maximum number of event aggregators for this queue type */
+	uint32_t max_num_aggregators;
+
+	/** Maximum number of event aggregators per queue */
+	uint32_t max_num_aggregators_per_queue;
+
+	/** Maximum number of events that can be aggregated into an event vector */
+	uint32_t max_size;
+
+	/** Minimum number of events that can be aggregated into an event vector */
+	uint32_t min_size;
+
+	/** Maximum allowed value of odp_event_aggregator_confit_t::max_tmo_ns */
+	uint64_t max_tmo_ns;
+
+	/** Minimum time in nanoseconds for an aggregator to form an event vector.
+	 *
+	 *  odp_event_aggregator_config_t::max_tmo_ns must not be less than this
+	 *  value unless it is zero.
+	 */
+	uint64_t min_tmo_ns;
+
+} odp_event_aggregator_capability_t;
+
 /**
  * @}
  */

include/odp/api/spec/ipsec_types.h

@@ -1,6 +1,6 @@
 /* SPDX-License-Identifier: BSD-3-Clause
  * Copyright (c) 2016-2018 Linaro Limited
- * Copyright (c) 2022 Nokia
+ * Copyright (c) 2025 Nokia
  */
 
 /**
@@ -462,6 +462,11 @@ typedef struct odp_ipsec_config_t {
 	 * the application through the default queue and the SA destination
 	 * queues. It does not affect packets delivered through pktio
 	 * input queues.
+	 *
+	 * Generating vectors of packets can be enabled either through this
+	 * configuration or by using event aggregators as destination queue(s).
+	 * Both options cannot be enabled simultaneously in the same ODP
+	 * application.
 	 */
 	odp_pktin_vector_config_t vector;
 

include/odp/api/spec/packet_io_types.h

@@ -1,6 +1,6 @@
 /* SPDX-License-Identifier: BSD-3-Clause
  * Copyright (c) 2013-2018 Linaro Limited
- * Copyright (c) 2020-2024 Nokia
+ * Copyright (c) 2020-2025 Nokia
  */
 
 /**
@@ -303,7 +303,13 @@ typedef struct odp_pktin_queue_param_t {
 	  */
 	odp_pktin_queue_param_ovr_t *queue_param_ovr;
 
-	/** Packet input vector configuration */
+	/** Packet input vector configuration
+	 *
+	 * Generating vectors of packets can be enabled either through this
+	 * configuration or by using event aggregators as destination queue(s).
+	 * Both options cannot be enabled simultaneously in the same ODP
+	 * application.
+	 */
 	odp_pktin_vector_config_t vector;
 
 } odp_pktin_queue_param_t;

include/odp/api/spec/queue.h

@@ -1,6 +1,6 @@
 /* SPDX-License-Identifier: BSD-3-Clause
  * Copyright (c) 2013-2018 Linaro Limited
- * Copyright (c) 2023 Nokia
+ * Copyright (c) 2023-2025 Nokia
  */
 
 /**
@@ -35,6 +35,9 @@ extern "C" {
  * parameters into their default values. Default values are also used when
  * 'param' pointer is NULL.
  *
+ * 'name' and 'param' and any configuration structures pointed to by 'param'
+ * are used only during the call. They can be freed after queue creation.
+ *
  * @param name    Name of the queue or NULL. Maximum string length is
  *                ODP_QUEUE_NAME_LEN, including the null character.
  * @param param   Queue parameters. Uses defaults if NULL.
@@ -155,6 +158,50 @@ int odp_queue_context_set(odp_queue_t queue, void *context, uint32_t len);
  */
 void *odp_queue_context(odp_queue_t queue);
 
+/**
+ * Get a queue handle of an event aggregator associated with a queue
+ *
+ * Returns a queue handle that can be used to refer to an event aggregator
+ * associated with this queue. Unless otherwise noted, the returned queue
+ * handle can be used in all contexts where queue handles are used.
+ * In particular, the queue handle can be used in odp_queue_enq() to
+ * enqueue events through an event aggregator to the underlying queue.
+ * Similarly, the queue handle can be given to packet I/O, classifier,
+ * crypto and IPsec to have the generated events be enqueued by ODP through
+ * the event aggregator.
+ *
+ * This function does not create a new queue but merely returns a reference
+ * to an aggregator queue which has the same life time as the underlying
+ * queue. The underlying queue must not be destroyed as long as any of its
+ * aggregators is in use. The aggregator queue gets destroyed when the
+ * underlying queue gets destroyed. An aggregator queue handle must not
+ * be passed to odp_queue_destroy().
+ *
+ * The aggregator queues have the same enq_mode as the underlying queue.
+ *
+ * The returned queue handle cannot be used for dequeuing events. It must
+ * not be passed to odp_queue_deq() or similar.
+ *
+ * The returned queue handle must not be passed to any of the
+ * odp_queue_context* or odp_queue_sched* functions and is never returned
+ * by odp_queue_lookup().
+ *
+ * 'aggr_index' refers to the aggregator configured with the same index
+ * in odp_queue_param_t::aggregator.
+ *
+ * If 'aggr_index' is greater than odp_queue_param_t::num_aggregators,
+ * ODP_QUEUE_INVALID is returned.
+ *
+ * @param queue       Queue handle
+ * @param aggr_index  Index of the event aggregator
+ *
+ * @return event aggregator queue handle
+ * @retval ODP_QUEUE_INVALID on failure
+ *
+ * @see odp_queue_create()
+ */
+odp_queue_t odp_queue_aggregator(odp_queue_t queue, uint32_t aggr_index);
+
 /**
  * Enqueue an event to a queue
  *

include/odp/api/spec/queue_types.h

@@ -1,5 +1,6 @@
 /* SPDX-License-Identifier: BSD-3-Clause
  * Copyright (c) 2018 Linaro Limited
+ * Copyright (c) 2024-2025 Nokia
  */
 
 /**
@@ -16,6 +17,7 @@
 extern "C" {
 #endif
 
+#include <odp/api/event_vector_types.h>
 #include <odp/api/schedule_types.h>
 
 /** @defgroup odp_queue ODP QUEUE
@@ -52,7 +54,17 @@ typedef enum odp_queue_type_t {
 	  * Scheduled queues are connected to the scheduler. Application must
 	  * not dequeue events directly from these queues but use the scheduler
 	  * instead. */
-	ODP_QUEUE_TYPE_SCHED
+	ODP_QUEUE_TYPE_SCHED,
+
+	/** Aggregator queue
+	  *
+	  * Aggregator queues are connected to an underlyig plain or scheduled
+	  * queue. They cannot be created directly but through the creation
+	  * of the underlying queue. Application must not dequeue events
+	  * directly from these queues.
+	  */
+	ODP_QUEUE_TYPE_AGGREGATOR,
+
 } odp_queue_type_t;
 
 /**
@@ -214,6 +226,9 @@ typedef struct odp_queue_capability_t {
 
 		} waitfree;
 
+		/** Event vector generation capabilities */
+		odp_event_aggregator_capability_t aggregator;
+
 	} plain;
 
 } odp_queue_capability_t;
@@ -291,6 +306,28 @@ typedef struct odp_queue_param_t {
 	  * default size. The default value is 0. */
 	uint32_t size;
 
+	/** Number of event aggregators
+	  *
+	  * Event aggregators are queues which try to aggregate multiple
+	  * events into vector events before enqueuing the events or vector
+	  * events to this queue. When at least one event aggregator is
+	  * configured, event can be enqueued directly using the queue
+	  * handle of this queue or indirectly through an event aggregator
+	  * using the queue handle of the event aggregator (see
+	  * odp_queue_aggregator_get()).
+	  *
+	  * When >= 1, configuration must be provided for each aggregator
+	  * through the 'aggregator' array.
+	  */
+	uint32_t num_aggregators;
+
+	/** Event aggregator configuration parameters
+	  *
+	  * When 'num_aggregators' is non-zero, 'aggregator' must point to
+	  * an array of size 'num_aggregators'.
+	  */
+	const odp_event_aggregator_config_t *aggregator;
+
 } odp_queue_param_t;
 
 /**

include/odp/api/spec/schedule_types.h

@@ -13,6 +13,7 @@
 #define ODP_API_SPEC_SCHEDULE_TYPES_H_
 #include <odp/visibility_begin.h>
 
+#include <odp/api/event_vector_types.h>
 #include <odp/api/std_types.h>
 #include <odp/api/thrmask.h>
 
@@ -242,6 +243,9 @@ typedef struct odp_schedule_capability_t {
 	 *  does nothing. */
 	odp_support_t order_wait;
 
+	/** Event aggregator capabilities for scheduled queues */
+	odp_event_aggregator_capability_t vector;
+
 } odp_schedule_capability_t;
 
 /**