Merge ODP v1.38.0.0v1.38.0.0_DPDK_19.11

Merge ODP linux-generic v1.38.0.0 into linux-dpdk.

8 files changed, 307 insertions, 19 deletions

diff --git a/include/odp/api/spec/buffer.h b/include/odp/api/spec/buffer.h
index c11a3c7b4..b739e549f 100644
--- a/include/odp/api/spec/buffer.h
+++ b/include/odp/api/spec/buffer.h
@@ -1,4 +1,5 @@
 /* Copyright (c) 2013-2018, Linaro Limited
+ * Copyright (c) 2022, Nokia
  * All rights reserved.
  *
  * SPDX-License-Identifier:     BSD-3-Clause
@@ -78,6 +79,19 @@ void *odp_buffer_addr(odp_buffer_t buf);
 uint32_t odp_buffer_size(odp_buffer_t buf);
 
 /**
+ * Buffer user area
+ *
+ * Returns pointer to the user area associated with the buffer. Size of the area is fixed
+ * and defined in buffer pool parameters.
+ *
+ * @param buf      Buffer handle
+ *
+ * @return       Pointer to the user area of the buffer
+ * @retval NULL  The buffer does not have user area
+ */
+void *odp_buffer_user_area(odp_buffer_t buf);
+
+/**
  * Check that buffer is valid
  *
  * This function can be used for debugging purposes to check if a buffer handle represents
diff --git a/include/odp/api/spec/crypto.h b/include/odp/api/spec/crypto.h
index b45731e1b..4f2961f3c 100644
--- a/include/odp/api/spec/crypto.h
+++ b/include/odp/api/spec/crypto.h
@@ -154,14 +154,23 @@ typedef enum {
 	 */
 	ODP_CIPHER_ALG_AES_EEA2,
 
-	/** Confidentiality 128-EEA3 algorithm
+	/** ZUC based confidentiality algorithm
 	 *
-	 *  ZUC-based 128-EEA3 algorithm.
+	 *  128-EEA3/128-NEA3 algorithm when key length is 128 bits.
 	 *
 	 *  IV (128 bit) should be formatted according to the ETSI/SAGE
 	 *  128-EEA3 & 128-EIA3 specification:
 	 *  COUNT || BEARER || DIRECTION || 0...0 ||
 	 *  COUNT || BEARER || DIRECTION || 0...0 ||
+	 *
+	 *  256-bit key length support is experimental and subject to
+	 *  change. The following variants may be supported:
+	 *
+	 *  - ZUC-256 with 25 byte IV (of which 184 bits are variable)
+	 *    as specified in "The ZUC-256 Stream Cipher".
+	 *  - ZUC-256 with 16 byte IV as specified in
+	 *        "An Addendum to the ZUC-256 Stream Cipher",
+	 *        https://eprint.iacr.org/2021/1439
 	 */
 	ODP_CIPHER_ALG_ZUC_EEA3,
 
@@ -304,15 +313,24 @@ typedef enum {
 	 */
 	ODP_AUTH_ALG_AES_EIA2,
 
-	/** Integrity 128-EIA3 algorithm
+	/** ZUC-based integrity algorithm.
 	 *
-	 *  ZUC-based 128-EIA3 algorithm.
+	 *  128-EIA3/128-NIA3 algorithm when key length is 128 bits.
 	 *
 	 *  IV (128 bit) should be formatted according to the ETSI/SAGE
 	 *  128-EA3 & 128-EIA2 specification:
 	 *  COUNT || BEARER ||
 	 *  DIRECTION XOR COUNT0 || COUNT1 .. COUNT31 ||
 	 *  BEARER || 0...0 || DIRECTION || 0...0
+	 *
+	 *  256-bit key length support is experimental and subject to
+	 *  change. The following variants may be supported:
+	 *
+	 *  - ZUC-256 with 25 byte IV (of which 184 bits are variable) and
+	 *    32/64/128 bit MAC as specified in "The ZUC-256 Stream Cipher".
+	 *  - ZUC-256 with 16 byte IV and 32/64/128 bit MAC as specified in
+	 *        "An Addendum to the ZUC-256 Stream Cipher",
+	 *        https://eprint.iacr.org/2021/1439
 	 */
 	ODP_AUTH_ALG_ZUC_EIA3,
 
diff --git a/include/odp/api/spec/packet.h b/include/odp/api/spec/packet.h
index c745d29ad..a8d4caa8c 100644
--- a/include/odp/api/spec/packet.h
+++ b/include/odp/api/spec/packet.h
@@ -1492,6 +1492,31 @@ void *odp_packet_user_area(odp_packet_t pkt);
 uint32_t odp_packet_user_area_size(odp_packet_t pkt);
 
 /**
+ * Check user flag
+ *
+ * Implementation clears user flag during new packet creation (e.g. alloc and packet input)
+ * and reset. User may set the flag with odp_packet_user_flag_set(). Implementation never
+ * sets the flag, only clears it. The flag may be useful e.g. to mark when the user area
+ * content is valid.
+ *
+ * @param pkt   Packet handle
+ *
+ * @retval 0    User flag is clear
+ * @retval !0   User flag is set
+ */
+int odp_packet_user_flag(odp_packet_t pkt);
+
+/**
+ * Set user flag
+ *
+ * Set (or clear) the user flag.
+ *
+ * @param pkt   Packet handle
+ * @param val   New value for the flag. Zero clears the flag, other values set the flag.
+ */
+void odp_packet_user_flag_set(odp_packet_t pkt, int val);
+
+/**
  * Layer 2 start pointer
  *
  * Returns pointer to the start of layer 2. Optionally, outputs number of data
@@ -2213,6 +2238,44 @@ uint32_t odp_packet_vector_size(odp_packet_vector_t pktv);
 void odp_packet_vector_size_set(odp_packet_vector_t pktv, uint32_t size);
 
 /**
+ * Packet vector user area
+ *
+ * Returns pointer to the user area associated with the packet vector. Size of the area is fixed
+ * and defined in vector pool parameters.
+ *
+ * @param  pktv  Packet vector handle
+ *
+ * @return       Pointer to the user area of the packet vector
+ * @retval NULL  The packet vector does not have user area
+ */
+void *odp_packet_vector_user_area(odp_packet_vector_t pktv);
+
+/**
+ * Check user flag
+ *
+ * Implementation clears user flag during new packet vector creation (e.g. alloc and packet input)
+ * and reset. User may set the flag with odp_packet_vector_user_flag_set(). Implementation never
+ * sets the flag, only clears it. The flag may be useful e.g. to mark when the user area
+ * content is valid.
+ *
+ * @param pktv  Packet vector handle
+ *
+ * @retval 0    User flag is clear
+ * @retval !0   User flag is set
+ */
+int odp_packet_vector_user_flag(odp_packet_vector_t pktv);
+
+/**
+ * Set user flag
+ *
+ * Set (or clear) the user flag.
+ *
+ * @param pktv  Packet vector handle
+ * @param val   New value for the flag. Zero clears the flag, other values set the flag.
+ */
+void odp_packet_vector_user_flag_set(odp_packet_vector_t pktv, int val);
+
+/**
  * Check that packet vector is valid
  *
  * This function can be used for debugging purposes to check if a packet vector handle represents
diff --git a/include/odp/api/spec/pool_types.h b/include/odp/api/spec/pool_types.h
index e8026c642..9f433fba5 100644
--- a/include/odp/api/spec/pool_types.h
+++ b/include/odp/api/spec/pool_types.h
@@ -174,6 +174,9 @@ typedef struct odp_pool_capability_t {
 		 * memory size for the pool. */
 		uint32_t max_num;
 
+		/** Maximum user area size in bytes */
+		uint32_t max_uarea_size;
+
 		/** Minimum size of thread local cache */
 		uint32_t min_cache_size;
 
@@ -250,10 +253,7 @@ typedef struct odp_pool_capability_t {
 		 * memory size for the pool. */
 		uint32_t max_seg_len;
 
-		/** Maximum user area size in bytes
-		 *
-		 * The value of zero means that limited only by the available
-		 * memory size for the pool. */
+		/** Maximum user area size in bytes */
 		uint32_t max_uarea_size;
 
 		/** Maximum number of subparameters
@@ -283,6 +283,9 @@ typedef struct odp_pool_capability_t {
 		 * memory size for the pool. */
 		uint32_t max_num;
 
+		/** Maximum user area size in bytes */
+		uint32_t max_uarea_size;
+
 		/** Minimum size of thread local cache */
 		uint32_t min_cache_size;
 
@@ -304,9 +307,12 @@ typedef struct odp_pool_capability_t {
 		 * memory size for the pool. */
 		uint32_t max_num;
 
-		/** Maximum number of general types, such as odp_packet_t, in a vector. */
+		/** Maximum number of handles (such as odp_packet_t) in a vector. */
 		uint32_t max_size;
 
+		/** Maximum user area size in bytes */
+		uint32_t max_uarea_size;
+
 		/** Minimum size of thread local cache */
 		uint32_t min_cache_size;
 
@@ -344,10 +350,10 @@ typedef enum odp_pool_type_t {
 	/** Timeout pool */
 	ODP_POOL_TIMEOUT = ODP_EVENT_TIMEOUT,
 
-	/** Vector pool
+	/** Vector event pool
 	 *
-	 * The pool to hold a vector of general type such as odp_packet_t.
-	 * Each vector holds an array of generic types of the same type.
+	 * Each vector event holds an array of handles. All handles of a vector
+	 * are the same type (such as odp_packet_t).
 	 * @see ODP_EVENT_PACKET_VECTOR
 	 */
 	ODP_POOL_VECTOR,
@@ -380,6 +386,12 @@ typedef struct odp_pool_param_t {
 		 */
 		uint32_t align;
 
+		/** Minimum user area size in bytes. The maximum value is defined by
+		 *  pool capability buf.max_uarea_size. Specify as 0 if no user
+		 *  area is needed. The default value is 0.
+		 */
+		uint32_t uarea_size;
+
 		/** Maximum number of buffers cached locally per thread
 		 *
 		 *  A non-zero value allows implementation to cache buffers
@@ -454,9 +466,9 @@ typedef struct odp_pool_param_t {
 		 */
 		uint32_t seg_len;
 
-		/** User area size in bytes. The maximum value is defined by
+		/** Minimum user area size in bytes. The maximum value is defined by
 		 *  pool capability pkt.max_uarea_size. Specify as 0 if no user
-		 *  area is needed.
+		 *  area is needed. The default value is 0.
 		 */
 		uint32_t uarea_size;
 
@@ -503,6 +515,12 @@ typedef struct odp_pool_param_t {
 		/** Number of timeouts in the pool */
 		uint32_t num;
 
+		/** Minimum user area size in bytes. The maximum value is defined by
+		 *  pool capability tmo.max_uarea_size. Specify as 0 if no user
+		 *  area is needed. The default value is 0.
+		 */
+		uint32_t uarea_size;
+
 		/** Maximum number of timeouts cached locally per thread
 		 *
 		 *  See buf.cache_size documentation for details.
@@ -515,9 +533,15 @@ typedef struct odp_pool_param_t {
 		/** Number of vectors in the pool */
 		uint32_t num;
 
-		/** Maximum number of general types, such as odp_packet_t, in a vector. */
+		/** Maximum number of handles (such as odp_packet_t) in a vector. */
 		uint32_t max_size;
 
+		/** Minimum user area size in bytes. The maximum value is defined by
+		 *  pool capability vector.max_uarea_size. Specify as 0 if no user
+		 *  area is needed. The default value is 0.
+		 */
+		uint32_t uarea_size;
+
 		/** Maximum number of vectors cached locally per thread
 		 *
 		 *  See buf.cache_size documentation for details.
diff --git a/include/odp/api/spec/stash.h b/include/odp/api/spec/stash.h
index 38e388dd7..f5929c45a 100644
--- a/include/odp/api/spec/stash.h
+++ b/include/odp/api/spec/stash.h
@@ -132,6 +132,25 @@ uint64_t odp_stash_to_u64(odp_stash_t stash);
 int32_t odp_stash_put(odp_stash_t stash, const void *obj, int32_t num);
 
 /**
+ * Put batch of object handles into a stash
+ *
+ * Otherwise like odp_stash_put(), except that this function stores either all
+ * 'num' object handles or none. odp_stash_capability_t.max_put_batch defines
+ * the maximum supported batch size.
+ *
+ * @param stash  Stash handle
+ * @param obj    Points to an array of object handles to be stored.
+ *               Object handle size is specified by 'obj_size' in stash
+ *               creation parameters. The array must be 'obj_size' aligned
+ *               in memory.
+ * @param num    Number of object handles to store
+ *
+ * @return Number of object handles actually stored (0 or num)
+ * @retval <0 on failure
+ */
+int32_t odp_stash_put_batch(odp_stash_t stash, const void *obj, int32_t num);
+
+/**
  * Put 32-bit integers into a stash
  *
  * Otherwise like odp_stash_put(), except that this function operates on 32-bit
@@ -148,6 +167,23 @@ int32_t odp_stash_put(odp_stash_t stash, const void *obj, int32_t num);
 int32_t odp_stash_put_u32(odp_stash_t stash, const uint32_t val[], int32_t num);
 
 /**
+ * Put batch of 32-bit integers into a stash
+ *
+ * Otherwise like odp_stash_put_u32(), except that this function stores either
+ * all 'num' object handles or none. odp_stash_capability_t.max_put_batch
+ * defines the maximum supported batch size.
+ *
+ * @param stash  Stash handle
+ * @param val    Points to an array of 32-bit integers to be stored. The array
+ *               must be 32-bit aligned in memory.
+ * @param num    Number of integers to store
+ *
+ * @return Number of integers actually stored (0 or num)
+ * @retval <0 on failure
+ */
+int32_t odp_stash_put_u32_batch(odp_stash_t stash, const uint32_t val[], int32_t num);
+
+/**
  * Put 64-bit integers into a stash
  *
  * Otherwise like odp_stash_put(), except that this function operates on 64-bit
@@ -164,6 +200,23 @@ int32_t odp_stash_put_u32(odp_stash_t stash, const uint32_t val[], int32_t num);
 int32_t odp_stash_put_u64(odp_stash_t stash, const uint64_t val[], int32_t num);
 
 /**
+ * Put batch of 64-bit integers into a stash
+ *
+ * Otherwise like odp_stash_put_u64(), except that this function stores either
+ * all 'num' object handles or none. odp_stash_capability_t.max_put_batch
+ * defines the maximum supported batch size.
+ *
+ * @param stash  Stash handle
+ * @param val    Points to an array of 64-bit integers to be stored. The array
+ *               must be 64-bit aligned in memory.
+ * @param num    Number of integers to store
+ *
+ * @return Number of integers actually stored (0 or num)
+ * @retval <0 on failure
+ */
+int32_t odp_stash_put_u64_batch(odp_stash_t stash, const uint64_t val[], int32_t num);
+
+/**
  * Put pointers into a stash
  *
  * Otherwise like odp_stash_put(), except that this function operates on
@@ -181,6 +234,23 @@ int32_t odp_stash_put_u64(odp_stash_t stash, const uint64_t val[], int32_t num);
 int32_t odp_stash_put_ptr(odp_stash_t stash, const uintptr_t ptr[], int32_t num);
 
 /**
+ * Put batch of pointers into a stash
+ *
+ * Otherwise like odp_stash_put_ptr(), except that this function stores either
+ * all 'num' object handles or none. odp_stash_capability_t.max_put_batch
+ * defines the maximum supported batch size.
+ *
+ * @param stash  Stash handle
+ * @param ptr    Points to an array of pointers to be stored. The array must be
+ *               pointer size aligned in memory.
+ * @param num    Number of pointers to store
+ *
+ * @return Number of pointers actually stored (0 or num)
+ * @retval <0 on failure
+ */
+int32_t odp_stash_put_ptr_batch(odp_stash_t stash, const uintptr_t ptr[], int32_t num);
+
+/**
  * Get object handles from a stash
  *
  * Get previously stored object handles from the stash. Application specifies
@@ -199,6 +269,25 @@ int32_t odp_stash_put_ptr(odp_stash_t stash, const uintptr_t ptr[], int32_t num)
 int32_t odp_stash_get(odp_stash_t stash, void *obj, int32_t num);
 
 /**
+ * Get batch of object handles from a stash
+ *
+ * Otherwise like odp_stash_get(), except that this function outputs either
+ * all 'num' object handles or none. odp_stash_capability_t.max_get_batch
+ * defines the maximum supported batch size.
+ *
+ * @param      stash  Stash handle
+ * @param[out] obj    Points to an array of object handles for output.
+ *                    Object handle size is specified by 'obj_size' in stash
+ *                    creation parameters. The array must be 'obj_size' aligned
+ *                    in memory.
+ * @param      num    Number of object handles to get from the stash
+ *
+ * @return Number of object handles actually output (0 or num) to 'obj' array
+ * @retval <0 on failure
+ */
+int32_t odp_stash_get_batch(odp_stash_t stash, void *obj, int32_t num);
+
+/**
  * Get 32-bit integers from a stash
  *
  * Otherwise like odp_stash_get(), except that this function operates on 32-bit
@@ -215,6 +304,23 @@ int32_t odp_stash_get(odp_stash_t stash, void *obj, int32_t num);
 int32_t odp_stash_get_u32(odp_stash_t stash, uint32_t val[], int32_t num);
 
 /**
+ * Get batch of 32-bit integers from a stash
+ *
+ * Otherwise like odp_stash_get_u32(), except that this function outputs either
+ * all 'num' object handles or none. odp_stash_capability_t.max_get_batch
+ * defines the maximum supported batch size.
+ *
+ * @param      stash  Stash handle
+ * @param[out] val    Points to an array of 32-bit integers for output. The
+ *                    array must be 32-bit aligned in memory.
+ * @param      num    Number of integers to get from the stash
+ *
+ * @return Number of integers actually output (0 or num) to 'val' array
+ * @retval <0 on failure
+ */
+int32_t odp_stash_get_u32_batch(odp_stash_t stash, uint32_t val[], int32_t num);
+
+/**
  * Get 64-bit integers from a stash
  *
  * Otherwise like odp_stash_get(), except that this function operates on 64-bit
@@ -231,6 +337,23 @@ int32_t odp_stash_get_u32(odp_stash_t stash, uint32_t val[], int32_t num);
 int32_t odp_stash_get_u64(odp_stash_t stash, uint64_t val[], int32_t num);
 
 /**
+ * Get batch of 64-bit integers from a stash
+ *
+ * Otherwise like odp_stash_get_u64(), except that this function outputs either
+ * all 'num' object handles or none. odp_stash_capability_t.max_get_batch
+ * defines the maximum supported batch size.
+ *
+ * @param      stash  Stash handle
+ * @param[out] val    Points to an array of 64-bit integers for output. The
+ *                    array must be 64-bit aligned in memory.
+ * @param      num    Number of integers to get from the stash
+ *
+ * @return Number of integers actually output (0 or num) to 'val' array
+ * @retval <0 on failure
+ */
+int32_t odp_stash_get_u64_batch(odp_stash_t stash, uint64_t val[], int32_t num);
+
+/**
  * Get pointers from a stash
  *
  * Otherwise like odp_stash_get(), except that this function operates on
@@ -248,6 +371,23 @@ int32_t odp_stash_get_u64(odp_stash_t stash, uint64_t val[], int32_t num);
 int32_t odp_stash_get_ptr(odp_stash_t stash, uintptr_t ptr[], int32_t num);
 
 /**
+ * Get batch of pointers from a stash
+ *
+ * Otherwise like odp_stash_get_ptr(), except that this function outputs either
+ * all 'num' object handles or none. odp_stash_capability_t.max_get_batch
+ * defines the maximum supported batch size.
+ *
+ * @param      stash  Stash handle
+ * @param[out] ptr    Points to an array of pointers for output. The array must
+ *                    be pointer size aligned in memory.
+ * @param      num    Number of pointers to get from the stash
+ *
+ * @return Number of pointers actually output (0 or num) to 'ptr' array
+ * @retval <0 on failure
+ */
+int32_t odp_stash_get_ptr_batch(odp_stash_t stash, uintptr_t ptr[], int32_t num);
+
+/**
  * Flush object handles from the thread local cache
  *
  * Flushes all object handles from the thread local cache into the stash, so
diff --git a/include/odp/api/spec/stash_types.h b/include/odp/api/spec/stash_types.h
index dc966cb71..5f3e608bb 100644
--- a/include/odp/api/spec/stash_types.h
+++ b/include/odp/api/spec/stash_types.h
@@ -172,6 +172,18 @@ typedef struct odp_stash_capability_t {
 	/** Maximum size of thread local cache */
 	uint32_t max_cache_size;
 
+	/** Maximum number of object handles in batch get operations
+	 *
+	 *  At least 1 object batch size is always supported.
+	 */
+	uint32_t max_get_batch;
+
+	/** Maximum number of object handles in batch put operations
+	 *
+	 *  At least 1 object batch size is always supported.
+	 */
+	uint32_t max_put_batch;
+
 	/** Supported statistics counters */
 	odp_stash_stats_opt_t stats;
 
diff --git a/include/odp/api/spec/thread.h b/include/odp/api/spec/thread.h
index 52bd82a09..0d85b3432 100644
--- a/include/odp/api/spec/thread.h
+++ b/include/odp/api/spec/thread.h
@@ -1,4 +1,5 @@
 /* Copyright (c) 2013-2018, Linaro Limited
+ * Copyright (c) 2022, Nokia
  * All rights reserved.
  *
  * SPDX-License-Identifier:     BSD-3-Clause
@@ -33,10 +34,13 @@ extern "C" {
 /**
  * Get thread identifier
  *
- * Returns the thread identifier of the current thread. Thread ids range from 0
- * to odp_thread_count_max() - 1. The ODP thread id is assigned by
- * odp_init_local() and freed by odp_term_local(). Thread id is unique within
- * the ODP instance.
+ * Returns the ODP thread identifier of current thread. Thread IDs range from 0
+ * to odp_thread_count_max() - 1 and are unique within an ODP instance.
+ *
+ * Thread IDs are assigned by odp_init_local() and freed by odp_term_local().
+ * IDs are assigned sequentially starting from 0 in the same order threads call
+ * odp_init_local(). Thread IDs freed by odp_term_local() may be reused by
+ * following odp_init_local() calls.
  *
  * @return Thread identifier of the current thread
  */
diff --git a/include/odp/api/spec/timer.h b/include/odp/api/spec/timer.h
index b51db7dbc..edfa423e7 100644
--- a/include/odp/api/spec/timer.h
+++ b/include/odp/api/spec/timer.h
@@ -505,6 +505,19 @@ uint64_t odp_timeout_tick(odp_timeout_t tmo);
 void *odp_timeout_user_ptr(odp_timeout_t tmo);
 
 /**
+ * Timeout user area
+ *
+ * Returns pointer to the user area associated with the timeout. Size of the area is fixed
+ * and defined in timeout pool parameters.
+ *
+ * @param tmo    Timeout handle
+ *
+ * @return       Pointer to the user area of the timeout
+ * @retval NULL  The timeout does not have user area
+ */
+void *odp_timeout_user_area(odp_timeout_t tmo);
+
+/**
  * Timeout alloc
  *
  * Allocates timeout from pool. Pool must be created with ODP_POOL_TIMEOUT type.