| Message ID | 20170628102734.26332-1-petri.savolainen@linaro.org |
|---|---|
| State | New |
| Headers | show |
On Wed, Jun 28, 2017 at 5:27 AM, Petri Savolainen <petri.savolainen@linaro.org> wrote: > Added packet pool parameters for more fine grained pool > configuration. The basic usage of the parameters is not changed, > except that implementation may now round up 'num' by default. > Application can limit the round up with new 'max_num' parameter. > Another new parameter (opt) allows application give hints and > requirements about e.g. memory to be used for a pool (or parts > of the pool). > > Additionally, pool configuration may be extended with a table of > num/len/opt values. This gives application more flexibility to > specify requirements for various packet sizes. > > For example, the new specification allows to create this kind of > pool: > > ^ > | > max_num | - - - - - - - - > | > | * > NUM | * * > | * * * > | o * * * * > | o * * * * * > +---------------> > LEN > > o == small number of short packets into fast memory > * == all other packets into DDR > > Signed-off-by: Petri Savolainen <petri.savolainen@linaro.org> > --- > include/odp/api/spec/pool.h | 140 +++++++++++++++++++++++++++++++++++++++----- > 1 file changed, 126 insertions(+), 14 deletions(-) > > diff --git a/include/odp/api/spec/pool.h b/include/odp/api/spec/pool.h > index 6fc5b6b4..ae3aa2b1 100644 > --- a/include/odp/api/spec/pool.h > +++ b/include/odp/api/spec/pool.h > @@ -41,6 +41,9 @@ extern "C" { > * Maximum pool name length in chars including null char > */ > > +/** Maximum number of packet pool subparameters */ > +#define ODP_POOL_PKT_SUB_MAX 7 This should still be defined by the implementation, not the spec. Fine for the spec to reference it, but not to define it. > + > /** > * Pool capabilities > */ > @@ -127,6 +130,12 @@ typedef struct odp_pool_capability_t { > * The value of zero means that limited only by the available > * memory size for the pool. */ > uint32_t max_uarea_size; > + > + /** Maximum number of subparameters > + * > + * Maximum number of packet pool subparameters. Valid range is > + * 0 ... ODP_POOL_PKT_SUB_MAX. */ > + uint8_t max_num_sub; > } pkt; > > /** Timeout pool capabilities */ > @@ -156,6 +165,32 @@ typedef struct odp_pool_capability_t { > int odp_pool_capability(odp_pool_capability_t *capa); > > /** > + * Pool memory type > + */ > +typedef enum odp_pool_mem_type_t { > + /** Default memory type. Typically, this is the main memory (DRAM). */ > + ODP_POOL_MEM_DEFAULT = 0, > + > + /** Fast on chip memory. Some implementations may have a restricted > + * amount of chip internal memory that may be used for pools. It's > + * faster to access (higher bandwidth and lower latency) from CPUs > + * and accelerators than the default memory. */ > + ODP_POOL_MEM_ON_CHIP ON_CHIP seems a better name choice than the previous FAST, but this still seems premature. In particular, since we're not defining any odp_pool_capability() relating to this how is the application to make a portable decision about how to use this feature? Again, I suggest we remove odp_pool_mem_type_t from this proposed change and revisit this when we have a more comprehensive NUMA strategy/proposal in place. > + > +} odp_pool_mem_type_t; > + > +/** > + * Additional options for packet pool creation > + */ > +typedef struct odp_pool_pkt_opt_t { > + /** Pool memory type. This is a hint which memory type should be used > + * for a pool or a subset of a pool. Implementation may ignore the > + * hint, if e.g. it has only one type of memory. */ > + odp_pool_mem_type_t mem_type; > + > +} odp_pool_pkt_opt_t; If we delete mem_type for now, this is empty so it should also be deleted for now. > + > +/** > * Pool parameters > * Used to communicate pool creation options. > * @note A single thread may not be able to allocate all 'num' elements > @@ -185,35 +220,96 @@ 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. */ > + /** The minimum number of packets that are packet length > + * 'len' bytes or smaller. The maximum value is defined > + * by pool capability pkt.max_num. An implementation > + * may round up the value, as long as the 'max_num' > + * parameter below is not violated. > + */ > 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. */ > + /** The minimum packet length that at least 'num' > + * packets are required. The maximum value is defined > + * by pool capability pkt.max_len. Use 0 for default. > + */ > uint32_t len; > > + /** Packet pool options > + * > + * Options contain additional hints and requirements, > + * which quide implementation e.g. to select correct > + * memory type for the pool. > + */ > + odp_pool_pkt_opt_t opt; > + > + /** Number of subparameters > + * > + * The number of subparameter table (pkt.sub[]) entries > + * filled in. Subparameters continue pool configuration > + * after the three parameters ('num', 'len' and 'opt'). > + * above. The maximum value is defined by pool > + * capability pkt.max_num_sub. The default value is 0. > + */ > + uint8_t num_sub; > + > /** Maximum packet length that will be allocated from > the pool. The maximum value is defined by pool > capability pkt.max_len. Use 0 for default (the > pool maximum). */ > uint32_t max_len; > > + /** 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 for no requirement for maximum number. > + * The default value is 0. > + */ > + uint32_t max_num; > + > /** Minimum number of packet data bytes that are stored > - in the first segment of a packet. The maximum value > - is defined by pool capability pkt.max_seg_len. > - Use 0 for default. */ > + * in the first segment of a packet. The maximum value > + * is defined by pool capability pkt.max_seg_len. > + * Use equal value with 'max_len' to ensure that all > + * packets are single segment. Use 0 for default. > + */ > uint32_t seg_len; > > /** 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. */ > uint32_t uarea_size; > + > + /** Packet pool subparameters > + * > + * This table gives more fine grained requirements for > + * pool configuration. The table continues from > + * num/len/opt specification above. Therefore, > + * pkt.sub[0].len must be greater than pkt.len, and > + * pkt.sub[0].num refers to packet lengths between > + * pkt.len + 1 and pkt.sub[0].len. > + * > + * Table enties must be ordered by the packet length. > + * A number of packets figure (pkt.sub[N].num) refers > + * to packet lengths between pkt.sub[N-1].len + 1 and > + * pkt.sub[N].len. Each number of packets requirement > + * may be rounded up, as long as the 'max_num' > + * parameter is not violated. A pool fulfills each > + * num/len requirement separately (when there are no > + * other allocations from the pool). > + */ > + struct { > + /** Number of packets */ > + uint32_t num; > + > + /** Packet length in bytes */ > + uint32_t len; > + > + /** Packet pool options */ > + odp_pool_pkt_opt_t opt; > + > + } sub[ODP_POOL_PKT_SUB_MAX]; > } pkt; > > /** Parameters for timeout pools */ > @@ -278,8 +374,24 @@ odp_pool_t odp_pool_lookup(const char *name); > * Used to get information about a pool. > */ > typedef struct odp_pool_info_t { > - const char *name; /**< pool name */ > - odp_pool_param_t params; /**< pool parameters */ > + /** Pool name */ > + const char *name; > + > + /** Copy of the pool parameters */ > + odp_pool_param_t params; > + > + /** Packet pool info */ > + struct { > + /** Maximum number of packets of any length > + * > + * This many packets in maximum can be allocated from the pool. > + * Application can use this e.g. to prepare enough per packet > + * contexts. > + */ > + uint32_t max_num; > + > + } pkt; > + > } odp_pool_info_t; > > /** > -- > 2.13.0 >
diff --git a/include/odp/api/spec/pool.h b/include/odp/api/spec/pool.h index 6fc5b6b4..ae3aa2b1 100644 --- a/include/odp/api/spec/pool.h +++ b/include/odp/api/spec/pool.h @@ -41,6 +41,9 @@ extern "C" { * Maximum pool name length in chars including null char */ +/** Maximum number of packet pool subparameters */ +#define ODP_POOL_PKT_SUB_MAX 7 + /** * Pool capabilities */ @@ -127,6 +130,12 @@ typedef struct odp_pool_capability_t { * The value of zero means that limited only by the available * memory size for the pool. */ uint32_t max_uarea_size; + + /** Maximum number of subparameters + * + * Maximum number of packet pool subparameters. Valid range is + * 0 ... ODP_POOL_PKT_SUB_MAX. */ + uint8_t max_num_sub; } pkt; /** Timeout pool capabilities */ @@ -156,6 +165,32 @@ typedef struct odp_pool_capability_t { int odp_pool_capability(odp_pool_capability_t *capa); /** + * Pool memory type + */ +typedef enum odp_pool_mem_type_t { + /** Default memory type. Typically, this is the main memory (DRAM). */ + ODP_POOL_MEM_DEFAULT = 0, + + /** Fast on chip memory. Some implementations may have a restricted + * amount of chip internal memory that may be used for pools. It's + * faster to access (higher bandwidth and lower latency) from CPUs + * and accelerators than the default memory. */ + ODP_POOL_MEM_ON_CHIP + +} odp_pool_mem_type_t; + +/** + * Additional options for packet pool creation + */ +typedef struct odp_pool_pkt_opt_t { + /** Pool memory type. This is a hint which memory type should be used + * for a pool or a subset of a pool. Implementation may ignore the + * hint, if e.g. it has only one type of memory. */ + odp_pool_mem_type_t mem_type; + +} odp_pool_pkt_opt_t; + +/** * Pool parameters * Used to communicate pool creation options. * @note A single thread may not be able to allocate all 'num' elements @@ -185,35 +220,96 @@ 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. */ + /** The minimum number of packets that are packet length + * 'len' bytes or smaller. The maximum value is defined + * by pool capability pkt.max_num. An implementation + * may round up the value, as long as the 'max_num' + * parameter below is not violated. + */ 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. */ + /** The minimum packet length that at least 'num' + * packets are required. The maximum value is defined + * by pool capability pkt.max_len. Use 0 for default. + */ uint32_t len; + /** Packet pool options + * + * Options contain additional hints and requirements, + * which quide implementation e.g. to select correct + * memory type for the pool. + */ + odp_pool_pkt_opt_t opt; + + /** Number of subparameters + * + * The number of subparameter table (pkt.sub[]) entries + * filled in. Subparameters continue pool configuration + * after the three parameters ('num', 'len' and 'opt'). + * above. The maximum value is defined by pool + * capability pkt.max_num_sub. The default value is 0. + */ + uint8_t num_sub; + /** Maximum packet length that will be allocated from the pool. The maximum value is defined by pool capability pkt.max_len. Use 0 for default (the pool maximum). */ uint32_t max_len; + /** 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 for no requirement for maximum number. + * The default value is 0. + */ + uint32_t max_num; + /** Minimum number of packet data bytes that are stored - in the first segment of a packet. The maximum value - is defined by pool capability pkt.max_seg_len. - Use 0 for default. */ + * in the first segment of a packet. The maximum value + * is defined by pool capability pkt.max_seg_len. + * Use equal value with 'max_len' to ensure that all + * packets are single segment. Use 0 for default. + */ uint32_t seg_len; /** 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. */ uint32_t uarea_size; + + /** Packet pool subparameters + * + * This table gives more fine grained requirements for + * pool configuration. The table continues from + * num/len/opt specification above. Therefore, + * pkt.sub[0].len must be greater than pkt.len, and + * pkt.sub[0].num refers to packet lengths between + * pkt.len + 1 and pkt.sub[0].len. + * + * Table enties must be ordered by the packet length. + * A number of packets figure (pkt.sub[N].num) refers + * to packet lengths between pkt.sub[N-1].len + 1 and + * pkt.sub[N].len. Each number of packets requirement + * may be rounded up, as long as the 'max_num' + * parameter is not violated. A pool fulfills each + * num/len requirement separately (when there are no + * other allocations from the pool). + */ + struct { + /** Number of packets */ + uint32_t num; + + /** Packet length in bytes */ + uint32_t len; + + /** Packet pool options */ + odp_pool_pkt_opt_t opt; + + } sub[ODP_POOL_PKT_SUB_MAX]; } pkt; /** Parameters for timeout pools */ @@ -278,8 +374,24 @@ odp_pool_t odp_pool_lookup(const char *name); * Used to get information about a pool. */ typedef struct odp_pool_info_t { - const char *name; /**< pool name */ - odp_pool_param_t params; /**< pool parameters */ + /** Pool name */ + const char *name; + + /** Copy of the pool parameters */ + odp_pool_param_t params; + + /** Packet pool info */ + struct { + /** Maximum number of packets of any length + * + * This many packets in maximum can be allocated from the pool. + * Application can use this e.g. to prepare enough per packet + * contexts. + */ + uint32_t max_num; + + } pkt; + } odp_pool_info_t; /**
Added packet pool parameters for more fine grained pool configuration. The basic usage of the parameters is not changed, except that implementation may now round up 'num' by default. Application can limit the round up with new 'max_num' parameter. Another new parameter (opt) allows application give hints and requirements about e.g. memory to be used for a pool (or parts of the pool). Additionally, pool configuration may be extended with a table of num/len/opt values. This gives application more flexibility to specify requirements for various packet sizes. For example, the new specification allows to create this kind of pool: ^ | max_num | - - - - - - - - | | * NUM | * * | * * * | o * * * * | o * * * * * +---------------> LEN o == small number of short packets into fast memory * == all other packets into DDR Signed-off-by: Petri Savolainen <petri.savolainen@linaro.org> --- include/odp/api/spec/pool.h | 140 +++++++++++++++++++++++++++++++++++++++----- 1 file changed, 126 insertions(+), 14 deletions(-) -- 2.13.0