diff mbox series

[API-NEXT,v4,1/8] api: pool: relax packet pool param num

Message ID 1509091212-14398-2-git-send-email-odpbot@yandex.ru
State New
Headers show
Series [API-NEXT,v4,1/8] api: pool: relax packet pool param num | expand

Commit Message

Github ODP bot Oct. 27, 2017, 8 a.m. UTC 
From: Petri Savolainen <petri.savolainen@linaro.org>


Added packet pool parameter 'max_num', so that 'num' parameter
can be round up by the implementation. Most implementations have
a fixed segment size, and need this flexibility. For example,
when 'len' is larger than the pool segment size, there may be
e.g. 2 x 'num' segments in the poool, and thus it would be
able to allocate 2 x 'num' small packets. When application
needs to limit maximum number of packets on a pool, it can
use the new max_num param for that. Otherwise, it would leave
'max_num' to zero (== no limit).

Signed-off-by: Petri Savolainen <petri.savolainen@linaro.org>

---
/** Email created from pull request 234 (psavol:next-pool-param)
 ** https://github.com/Linaro/odp/pull/234
 ** Patch: https://github.com/Linaro/odp/pull/234.patch
 ** Base sha: d61d32590d1772b70b8dcd0d0ec44d29029d7443
 ** Merge commit sha: 436021e0a0bff8bda38fa420ebbc4545c97a7fc8
 **/
 include/odp/api/spec/pool.h | 44 +++++++++++++++++++++++++++++++-------------
 1 file changed, 31 insertions(+), 13 deletions(-)
diff mbox series

Patch

diff --git a/include/odp/api/spec/pool.h b/include/odp/api/spec/pool.h
index 35f783775..dc07851c4 100644
--- a/include/odp/api/spec/pool.h
+++ b/include/odp/api/spec/pool.h
@@ -164,10 +164,11 @@  int odp_pool_capability(odp_pool_capability_t *capa);
 
 /**
  * Pool parameters
- * Used to communicate pool creation options.
- * @note A single thread may not be able to allocate all 'num' elements
- * from the pool at any particular time, as other threads or hardware
- * blocks are allowed to keep some for caching purposes.
+ *
+ * A note for all pool types: a single thread may not be able to allocate all
+ * 'num' elements from the pool at any particular time, as implementations are
+ * allowed to store some elements (per thread and HW engine) for caching
+ * purposes.
  */
 typedef struct odp_pool_param_t {
 	/** Pool type */
@@ -192,17 +193,34 @@  typedef struct odp_pool_param_t {
 
 		/** Parameters for packet pools */
 		struct {
-			/** The number of packets that the pool must provide
-			    that are packet length 'len' bytes or smaller.
-			    The maximum value is defined by pool capability
-			    pkt.max_num. */
+			/** Minimum number of 'len' byte packets.
+			 *
+			 *  The pool must contain at least this many packets
+			 *  that are 'len' bytes or smaller. An implementation
+			 *  may round up the value, as long as the 'max_num'
+			 *  parameter below is not violated. The maximum value
+			 *  for this field is defined by pool capability
+			 *  pkt.max_num.
+			 */
 			uint32_t num;
 
-			/** Minimum packet length that the pool must provide
-			    'num' packets. The number of packets may be less
-			    than 'num' when packets are larger than 'len'.
-			    The maximum value is defined by pool capability
-			    pkt.max_len. Use 0 for default. */
+			/** Maximum number of packets.
+			 *
+			 *  This is the maximum number of packets of any length
+			 *  that can be allocated from the pool. The maximum
+			 *  value is defined by pool capability pkt.max_num.
+			 *  Use 0 when there's no requirement for the maximum
+			 *  number of packets. The default value is 0.
+			 */
+			uint32_t max_num;
+
+			/** Minimum length of 'num' packets.
+			 *
+			 *  The pool must contain at least 'num' packets up to
+			 *  this packet length (1 ... 'len' bytes). The maximum
+			 *  value for this field is defined by pool capability
+			 *  pkt.max_len. Use 0 for default.
+			 */
 			uint32_t len;
 
 			/** Maximum packet length that will be allocated from