api: sched: add cache stashing

Enable possibility to configure cache stashing at schedule group, priority
and/or queue levels. Stashing data of to-be-scheduled events and queues
may improve performance in some workloads.

For the moment, the cache stashing configuration is instantiated as
hints. Implementation can utilize the information according to its
capabilities.

Signed-off-by: Tuomas Taipale <[email protected]>

include/odp/api/spec/queue_types.h

@@ -291,6 +291,18 @@ typedef struct odp_queue_param_t {
 	  * default size. The default value is 0. */
 	uint32_t size;
 
+	/** Queue specific cache stashing hints
+	  *
+	  * Depending on the implementation, configuring these may improve
+	  * performance. Overrides any group or priority specific configuration
+	  * completely for this queue. By default, all entries are disabled
+	  * (see odp_cache_stash_region_t::l2::enable and
+	  * odp_cache_stash_region_t::l3::enable).
+	  *
+	  * For PLAIN queues, the parameter is ignored and stashing
+	  * disabled. */
+	odp_cache_stash_config_t cache_stash_hints;
+
 } odp_queue_param_t;
 
 /**

include/odp/api/spec/schedule.h

@@ -1,6 +1,6 @@
 /* SPDX-License-Identifier: BSD-3-Clause
  * Copyright (c) 2013-2018 Linaro Limited
- * Copyright (c) 2024 Nokia
+ * Copyright (c) 2024-2025 Nokia
  */
 
 /**
@@ -340,6 +340,34 @@ int odp_schedule_capability(odp_schedule_capability_t *capa);
  */
 odp_schedule_group_t odp_schedule_group_create(const char *name,
 					       const odp_thrmask_t *mask);
+/**
+ * Initialize schedule group parameters
+ *
+ * Initialize an odp_schedule_group_param_t to its default values.
+ *
+ * @param[out] param  Pointer to parameter structure
+ */
+void odp_schedule_group_param_init(odp_schedule_group_param_t *param);
+
+/**
+ * Schedule group create with parameters
+ *
+ * Otherwise like odp_schedule_group_create() but additionally accepts a set of
+ * parameters.
+ *
+ * @param name    Name of the schedule group or NULL. Maximum string length is
+ *                ODP_SCHED_GROUP_NAME_LEN, including the null character.
+ * @param mask    Thread mask
+ * @param param   Schedule group parameters
+ *
+ * @return Schedule group handle
+ * @retval ODP_SCHED_GROUP_INVALID on failure
+ *
+ * @see odp_schedule_group_create
+ */
+odp_schedule_group_t odp_schedule_group_create2(const char *name,
+						const odp_thrmask_t *mask,
+						const odp_schedule_group_param_t *param);
 
 /**
  * Schedule group destroy

include/odp/api/spec/schedule_types.h

@@ -1,6 +1,6 @@
 /* SPDX-License-Identifier: BSD-3-Clause
  * Copyright (c) 2015-2018 Linaro Limited
- * Copyright (c) 2023 Nokia
+ * Copyright (c) 2023-2025 Nokia
  */
 
 /**
@@ -307,6 +307,127 @@ typedef struct odp_schedule_config_t {
 
 } odp_schedule_config_t;
 
+/**
+ * Region specific cache stashing configuration
+ *
+ * Region specific cache stashing configuration for different cache levels.
+ * Application can, for example, configure caching of certain portions of a
+ * region to L2 while configuring another portion to be cached to L3 or
+ * alternatively caching to both levels by configuring overlapping offsets and
+ * byte counts.
+ */
+typedef struct odp_cache_stash_region_t {
+	/** L2 cache stashing */
+	struct {
+		/** Enable or disable cache stashing for level */
+		odp_bool_t enable;
+
+		/** Offset into a region to start caching from */
+		uint32_t offset;
+
+		/** Length in bytes to cache
+		 *
+		 *  Depending on the implementation, this might be rounded up
+		 *  to a more suitable boundary.
+		 */
+		uint32_t len;
+
+	} l2;
+
+	/** L3 cache stashing */
+	struct {
+		/** Enable or disable cache stashing for level */
+		odp_bool_t enable;
+
+		/** Offset into a region to start caching from */
+		uint32_t offset;
+
+		/** Length in bytes to cache
+		 *
+		 *  Depending on the implementation, this might be rounded up
+		 *  to a more suitable boundary.
+		 */
+		uint32_t len;
+
+	} l3;
+
+} odp_cache_stash_region_t;
+
+/**
+ * Cache stashing configuration
+ *
+ * Cache stashing configuration for different data regions.
+ */
+typedef struct odp_cache_stash_config_t {
+	/** Cache stashing for event metadata */
+	odp_cache_stash_region_t event_metadata;
+
+	/** Cache stashing for event data */
+	odp_cache_stash_region_t event_data;
+
+	/** Cache stashing for event user area */
+	odp_cache_stash_region_t event_user_area;
+
+	/** Cache stashing for queue context region */
+	odp_cache_stash_region_t queue_context;
+
+} odp_cache_stash_config_t;
+
+/**
+ * Priority specific cache stashing configuration
+ */
+typedef struct odp_cache_stash_prio_config_t {
+	/** Priority level for applying this cache stashing configuration to */
+	odp_schedule_prio_t  prio;
+
+	/** Cache stashing configuration */
+	odp_cache_stash_config_t config;
+
+} odp_cache_stash_prio_config_t;
+
+/**
+ * Schedule group parameters
+ */
+typedef struct odp_schedule_group_param_t {
+	/** Group specific cache stashing hints
+	 *
+	 *  Depending on the implementation, configuring these may improve
+	 *  performance.
+	 */
+	struct {
+		/** Common group specific cache stashing hints
+		 *
+		 *  Configures cache stashing for each priority and queue under
+		 *  the group. By default, all entries are disabled (see
+		 *  odp_cache_stash_region_t::l2::enable and
+		 *  odp_cache_stash_region_t::l3::enable).
+		 */
+		odp_cache_stash_config_t common;
+
+		/** Priority specific cache stashing hints
+		 *
+		 *  Configures priority specific cache stashing. If 'common' is
+		 *  defined, overrides completely the configuration for the
+		 *  given priority.
+		 */
+		struct {
+			/** Number of entries in 'prio' array
+			 *
+			 *  By default 0.
+			 */
+			uint32_t num;
+
+			/** Pointer to 'num' entries of priority specific
+			 *  configuration
+			 */
+			const odp_cache_stash_prio_config_t *prio;
+
+		};
+
+	} cache_stash_hints;
+
+} odp_schedule_group_param_t;
+
 /**
  * Schedule group information
  */