| Message ID | 1508158805-5932-2-git-send-email-odpbot@yandex.ru |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [API-NEXT,v1,1/8] api: pool: relax packet pool param num | expand |
On Mon, Oct 16, 2017 at 7:59 AM, Github ODP bot <odpbot@yandex.ru> wrote: > 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: afeda4d14bb6f449cb269680cdbd56b26726eedf > ** Merge commit sha: 54f5fc670a7c125b6b0098e34e68fe3b45875069 > **/ > include/odp/api/spec/pool.h | 44 +++++++++++++++++++++++++++++++------------- > 1 file changed, 31 insertions(+), 13 deletions(-) > > diff --git a/include/odp/api/spec/pool.h b/include/odp/api/spec/pool.h > index 221798ee8..f1c8b1158 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; I'd put max_num first so that num and len are adjacent parameters for consistency with how the odp_pool_pkt_subparam_t is organized. > + > + /** 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 >
diff --git a/include/odp/api/spec/pool.h b/include/odp/api/spec/pool.h index 221798ee8..f1c8b1158 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