api: pool: add user area content persistence capability

New `uarea_persistence` pool capability signals if implementation is
able to maintain the content of pool user areas across frees and
allocations.

In case the content can be maintained, applications could initialize all
user areas only once after pool creation and trust that the content
remains valid after freeing an event. Otherwise, user areas need
re-initialization after every allocation.

Signed-off-by: Tuomas Taipale <tuomas.taipale@nokia.com>
Acked-by: Ashwin Sekhar T K <asekhar@marvell.com>
Reviewed-by: Petri Savolainen <petri.savolainen@nokia.com>

2 files changed, 41 insertions, 1 deletions

diff --git a/include/odp/api/spec/dma_types.h b/include/odp/api/spec/dma_types.h
index 26350e998..2f9e618b7 100644
--- a/include/odp/api/spec/dma_types.h
+++ b/include/odp/api/spec/dma_types.h
@@ -1,4 +1,4 @@
-/* Copyright (c) 2021-2022, Nokia
+/* Copyright (c) 2021-2023, Nokia
  * All rights reserved.
  *
  * SPDX-License-Identifier:     BSD-3-Clause
@@ -80,6 +80,12 @@ typedef struct odp_dma_pool_capability_t {
 	/** Maximum user area size in bytes */
 	uint32_t max_uarea_size;
 
+	/** Pool user area persistence
+	 *
+	 *  See buf.uarea_persistence of odp_pool_capability_t for details
+	 *  (odp_pool_capability_t::uarea_persistence). */
+	odp_bool_t uarea_persistence;
+
 	/** Minimum size of thread local cache */
 	uint32_t min_cache_size;
 
diff --git a/include/odp/api/spec/pool_types.h b/include/odp/api/spec/pool_types.h
index cf1051a07..7f56fb937 100644
--- a/include/odp/api/spec/pool_types.h
+++ b/include/odp/api/spec/pool_types.h
@@ -209,6 +209,19 @@ typedef struct odp_pool_capability_t {
 		/** Maximum user area size in bytes */
 		uint32_t max_uarea_size;
 
+		/** Pool user area persistence
+		 *
+		 * When supported, implementation does not overwrite buffer user area
+		 * content at any point of buffer lifetime nor after freeing a buffer
+		 * back into pool.
+		 *
+		 * 0: User area content is maintained throughout regular buffer usage
+		 *    after allocation, but may be modified after free (default)
+		 * 1: User area content is maintained throughout regular buffer usage
+		 *    and additionally also after buffer is freed into the pool (between
+		 *    buffer free and allocation) */
+		odp_bool_t uarea_persistence;
+
 		/** Minimum size of thread local cache */
 		uint32_t min_cache_size;
 
@@ -288,6 +301,11 @@ typedef struct odp_pool_capability_t {
 		/** Maximum user area size in bytes */
 		uint32_t max_uarea_size;
 
+		/** Pool user area persistence
+		 *
+		 * See buf.uarea_persistence for details. */
+		odp_bool_t uarea_persistence;
+
 		/** Maximum number of subparameters
 		 *
 		 *  Maximum number of packet pool subparameters. Valid range is
@@ -318,6 +336,11 @@ typedef struct odp_pool_capability_t {
 		/** Maximum user area size in bytes */
 		uint32_t max_uarea_size;
 
+		/** Pool user area persistence
+		 *
+		 * See buf.uarea_persistence for details. */
+		odp_bool_t uarea_persistence;
+
 		/** Minimum size of thread local cache */
 		uint32_t min_cache_size;
 
@@ -345,6 +368,11 @@ typedef struct odp_pool_capability_t {
 		/** Maximum user area size in bytes */
 		uint32_t max_uarea_size;
 
+		/** Pool user area persistence
+		 *
+		 * See buf.uarea_persistence for details. */
+		odp_bool_t uarea_persistence;
+
 		/** Minimum size of thread local cache */
 		uint32_t min_cache_size;
 
@@ -713,6 +741,12 @@ typedef struct odp_pool_ext_capability_t {
 		/** Maximum user area size in bytes */
 		uint32_t max_uarea_size;
 
+		/** Pool user area persistence
+		 *
+		 *  See buf.uarea_persistence of odp_pool_capability_t for details
+		 *  (odp_pool_capability_t::uarea_persistence). */
+		odp_bool_t uarea_persistence;
+
 	} pkt;
 
 } odp_pool_ext_capability_t;