diff options
Diffstat (limited to 'include/odp/api/spec/pool.h')
| -rw-r--r-- | include/odp/api/spec/pool.h | 432 |
1 files changed, 210 insertions, 222 deletions
diff --git a/include/odp/api/spec/pool.h b/include/odp/api/spec/pool.h index 6fc5b6b4a..32f01fb59 100644 --- a/include/odp/api/spec/pool.h +++ b/include/odp/api/spec/pool.h @@ -1,18 +1,16 @@ -/* Copyright (c) 2015, Linaro Limited - * All rights reserved. - * - * SPDX-License-Identifier: BSD-3-Clause +/* SPDX-License-Identifier: BSD-3-Clause + * Copyright (c) 2015-2018 Linaro Limited + * Copyright (c) 2020-2023 Nokia */ - /** * @file * * ODP pool */ -#ifndef ODP_API_POOL_H_ -#define ODP_API_POOL_H_ +#ifndef ODP_API_SPEC_POOL_H_ +#define ODP_API_SPEC_POOL_H_ #include <odp/visibility_begin.h> #ifdef __cplusplus @@ -20,130 +18,14 @@ extern "C" { #endif #include <odp/api/std_types.h> +#include <odp/api/pool_types.h> -/** @defgroup odp_pool ODP POOL - * Operations on a pool. +/** @addtogroup odp_pool + * Packet and buffer (event) pools. * @{ */ /** - * @typedef odp_pool_t - * ODP pool - */ - -/** - * @def ODP_POOL_INVALID - * Invalid pool - */ - -/** - * @def ODP_POOL_NAME_LEN - * Maximum pool name length in chars including null char - */ - -/** - * Pool capabilities - */ -typedef struct odp_pool_capability_t { - /** Maximum number of pools of any type */ - unsigned max_pools; - - /** Buffer pool capabilities */ - struct { - /** Maximum number of buffer pools */ - unsigned max_pools; - - /** Maximum buffer data alignment in bytes */ - uint32_t max_align; - - /** Maximum buffer data size in bytes - * - * The value of zero means that size is limited only by the - * available memory size for the pool. */ - uint32_t max_size; - - /** Maximum number of buffers of any size - * - * The value of zero means that limited only by the available - * memory size for the pool. */ - uint32_t max_num; - } buf; - - /** Packet pool capabilities */ - struct { - /** Maximum number of packet pools */ - unsigned max_pools; - - /** Maximum packet data length in bytes - * - * This defines the maximum packet data length that can be - * stored into a packet. Attempts to allocate or extend packets - * to sizes larger than this limit will fail. - * - * The value of zero means that limited only by the available - * memory size for the pool. */ - uint32_t max_len; - - /** Maximum number of packets of any length - * - * The value of zero means that limited only by the available - * memory size for the pool. */ - uint32_t max_num; - - /** Minimum packet level headroom length in bytes - * - * The minimum number of headroom bytes that newly created - * packets have by default. The default apply to both ODP - * packet input and user allocated packets.*/ - uint32_t min_headroom; - - /** Minimum packet level tailroom length in bytes - * - * The minimum number of tailroom bytes that newly created - * packets have by default. The default apply to both ODP - * packet input and user allocated packets.*/ - uint32_t min_tailroom; - - /** Maximum number of segments per packet */ - uint32_t max_segs_per_pkt; - - /** Minimum packet segment data length in bytes - * - * The user defined segment length (seg_len in - * odp_pool_param_t) will be rounded up into this value. */ - uint32_t min_seg_len; - - /** Maximum packet segment data length in bytes - * - * The user defined segment length (seg_len in odp_pool_param_t) - * must not be larger than this. - * - * The value of zero means that limited only by the available - * 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. */ - uint32_t max_uarea_size; - } pkt; - - /** Timeout pool capabilities */ - struct { - /** Maximum number of timeout pools */ - unsigned max_pools; - - /** Maximum number of timeout events in a pool - * - * The value of zero means that limited only by the available - * memory size for the pool. */ - uint32_t max_num; - } tmo; - -} odp_pool_capability_t; - -/** * Query pool capabilities * * Outputs pool capabilities on success. @@ -156,110 +38,35 @@ typedef struct odp_pool_capability_t { 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. - */ -typedef struct odp_pool_param_t { - /** Pool type */ - int type; - - /** Variant parameters for different pool types */ - union { - /** Parameters for buffer pools */ - struct { - /** Number of buffers in the pool */ - uint32_t num; - - /** Buffer size in bytes. The maximum number of bytes - application will store in each buffer. */ - uint32_t size; - - /** Minimum buffer alignment in bytes. Valid values are - powers of two. Use 0 for default alignment. - Default will always be a multiple of 8. */ - uint32_t align; - } buf; - - /** 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. */ - 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. */ - uint32_t len; - - /** 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; - - /** 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. */ - 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; - } pkt; - - /** Parameters for timeout pools */ - struct { - /** Number of timeouts in the pool */ - uint32_t num; - } tmo; - }; -} odp_pool_param_t; - -/** Packet pool*/ -#define ODP_POOL_PACKET ODP_EVENT_PACKET -/** Buffer pool */ -#define ODP_POOL_BUFFER ODP_EVENT_BUFFER -/** Timeout pool */ -#define ODP_POOL_TIMEOUT ODP_EVENT_TIMEOUT - -/** * Create a pool * * This routine is used to create a pool. The use of pool name is optional. * Unique names are not required. However, odp_pool_lookup() returns only a - * single matching pool. + * single matching pool. Use odp_pool_param_init() to initialize parameters + * into their default values. * * @param name Name of the pool or NULL. Maximum string length is - * ODP_POOL_NAME_LEN. - * @param params Pool parameters. + * ODP_POOL_NAME_LEN, including the null character. + * @param param Pool parameters. * * @return Handle of the created pool * @retval ODP_POOL_INVALID Pool could not be created */ - -odp_pool_t odp_pool_create(const char *name, odp_pool_param_t *params); +odp_pool_t odp_pool_create(const char *name, const odp_pool_param_t *param); /** * Destroy a pool previously created by odp_pool_create() * + * This routine destroys a previously created pool, and will destroy any + * internal shared memory objects associated with the pool. The pool must not + * be in use (in pktio, classifier, timer, etc.) when calling this function. + * Results are undefined if an attempt is made to destroy a pool that contains + * allocated or otherwise active buffers. + * * @param pool Handle of the pool to be destroyed * * @retval 0 Success * @retval -1 Failure - * - * @note This routine destroys a previously created pool, and will destroy any - * internal shared memory objects associated with the pool. Results are - * undefined if an attempt is made to destroy a pool that contains allocated - * or otherwise active buffers. */ int odp_pool_destroy(odp_pool_t pool); @@ -274,15 +81,6 @@ int odp_pool_destroy(odp_pool_t pool); odp_pool_t odp_pool_lookup(const char *name); /** - * Pool information struct - * 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 */ -} odp_pool_info_t; - -/** * Retrieve information about a pool * * @param pool Pool handle @@ -293,7 +91,6 @@ typedef struct odp_pool_info_t { * @retval 0 Success * @retval -1 Failure. Info could not be retrieved. */ - int odp_pool_info(odp_pool_t pool, odp_pool_info_t *info); /** @@ -307,6 +104,14 @@ int odp_pool_info(odp_pool_t pool, odp_pool_info_t *info); void odp_pool_print(odp_pool_t pool); /** + * Print debug info about all pools + * + * Print implementation defined information about all created pools to the ODP + * log. The information is intended to be used for debugging. + */ +void odp_pool_print_all(void); + +/** * Get printable value for an odp_pool_t * * @param hdl odp_pool_t handle to be printed @@ -329,6 +134,189 @@ uint64_t odp_pool_to_u64(odp_pool_t hdl); void odp_pool_param_init(odp_pool_param_t *param); /** + * Maximum pool index + * + * Return the maximum pool index. Pool indexes (e.g. returned by odp_pool_index()) + * range from zero to this maximum value. + * + * @return Maximum pool index + */ +unsigned int odp_pool_max_index(void); + +/** + * Get pool index + * + * @param pool Pool handle + * + * @return Pool index (0..odp_pool_max_index()) + * @retval <0 on failure + */ +int odp_pool_index(odp_pool_t pool); + +/** + * Read pool statistics + * + * Read statistics counters that were enabled in pool creation parameters (odp_pool_param_t.stats). + * The function writes all disabled counters to zero, except per thread counters + * (thread.cache_available[]) which have undefined values. + * + * When per thread counters are enabled, application sets 'stats.thread.first' and + * 'stats.thread.last' to select the threads ('first' <= 'last'). A single call may read statistics + * from one to #ODP_POOL_MAX_THREAD_STATS threads. Valid thread ID values range from 0 to + * odp_thread_count_max() - 1. A successful call fills the output array starting always from the + * first element 'stats.thread.cache_available[0]' (='stats.thread.first'). Unused array elements + * have undefined values. + * + * Depending on the implementation, there may be some delay until performed pool operations are + * visible in the statistics. + * + * @param pool Pool handle + * @param[in,out] stats Output buffer for counters + * + * @retval 0 on success + * @retval <0 on failure + */ +int odp_pool_stats(odp_pool_t pool, odp_pool_stats_t *stats); + +/** + * Get selected pool statistics + * + * Read the selected counters given in odp_pool_stats_opt_t bit field structure. Only counters + * included in odp_pool_stats_selected_t can be read and the selected counters must have been + * enabled during pool creation. Values of the unselected counters are undefined. Depending on the + * implementation, there may be some delay until performed pool operations are visible in the + * statistics. + * + * Depending on the implementation, this function may have higher performance compared to + * odp_pool_stats(), as only the selected set of counters is read. + * + * @param pool Pool handle + * @param[out] stats Output buffer for counters + * @param opt Bit field for selecting the counters to be read + * + * @retval 0 on success + * @retval <0 on failure + */ +int odp_pool_stats_selected(odp_pool_t pool, odp_pool_stats_selected_t *stats, + const odp_pool_stats_opt_t *opt); + +/** + * Reset statistics for pool + * + * Reset all statistics counters to zero except: odp_pool_stats_t::available, + * odp_pool_stats_t::cache_available, odp_pool_stats_t::thread::cache_available + * + * @param pool Pool handle + * + * @retval 0 on success + * @retval <0 on failure + */ +int odp_pool_stats_reset(odp_pool_t pool); + +/** + * Query capabilities of an external memory pool type + * + * Outputs pool capabilities on success. Returns failure if a bad pool type is used. When + * the requested pool type is valid but not supported, sets the value of 'max_pools' to zero. + * + * @param type Pool type + * @param[out] capa Pointer to capability structure for output + * + * @retval 0 on success + * @retval <0 on failure + */ +int odp_pool_ext_capability(odp_pool_type_t type, odp_pool_ext_capability_t *capa); + +/** + * Initialize pool params + * + * Initialize an odp_pool_ext_param_t to its default values for all fields + * based on the selected pool type. + * + * @param type Pool type + * @param param odp_pool_ext_param_t to be initialized + */ +void odp_pool_ext_param_init(odp_pool_type_t type, odp_pool_ext_param_t *param); + +/** + * Create an external memory pool + * + * This routine is used to create a pool. The use of pool name is optional. + * Unique names are not required. However, odp_pool_lookup() returns only a + * single matching pool. Use odp_pool_ext_param_init() to initialize parameters + * into their default values. + * + * @param name Name of the pool or NULL. Maximum string length is + * ODP_POOL_NAME_LEN, including the null character. + * @param param Pool parameters + * + * @return Pool handle on success + * @retval ODP_POOL_INVALID on failure + */ +odp_pool_t odp_pool_ext_create(const char *name, const odp_pool_ext_param_t *param); + +/** + * Populate external memory pool with buffer memory + * + * Populate can be called multiple times to add memory buffers into the pool. Application must + * populate the pool with the exact number of buffers specified in pool parameters. The pool is + * ready to be used for allocations only after all populate calls have returned successfully. + * Application marks the last populate call with ODP_POOL_POPULATE_DONE flag. + * + * Depending on pool usage (and ODP implementation), the memory may need to be accessible by + * HW accelerators. Application may use e.g. odp_shm_reserve() with ODP_SHM_HW_ACCESS flag to + * ensure HW access. The memory area used for one pool, starting from (or before) the lowest + * addressed buffer and extending to the end (or after) of the highest addressed buffer, must not + * overlap with the memory area used for any other pool. Pool capabilities + * (odp_pool_ext_capability_t) specify the minimum alignment of the memory area. + * + * Pool type defines memory buffer layout and where the buffer pointer (buf[N]) points + * in the layout. Pool capabilities specify requirements for buffer size, layout and + * pointer alignment. + * + * For packet pools, packet buffer layout is shown below. The packet headroom (odp_packet_head()) + * starts immediately after the application header. For a segmented packet, each segment has this + * same layout. Buffer size includes all headers, headroom, data, tailroom and trailer. + * + * @code{.unparsed} + * + * +-------------------------------+ -- -- + * buf[N] ---> | | | | + * | ODP header (optional) | > odp_header_size | + * | | | | + * +-------------------------------+ -- | + * | | | | + * | Application header (optional) | > app_header_size | + * | | | > buf_size + * +-------------------------------+ -- | + * odp_packet_head()--> | | | + * | Packet data | | + * | (headroom, data, tailroom) | | + * | | | + * | | | + * +-------------------------------+ -- | + * | | | | + * | ODP trailer (optional) | > odp_trailer_size | + * | | | | + * +-------------------------------+ -- -- + * + * @endcode + * + * @param pool External memory pool + * @param buf Buffer pointers to be populated into the pool + * @param buf_size Buffer size + * @param num Number of buffer pointers + * @param flags 0: No flags + * ODP_POOL_POPULATE_DONE: Marks the last populate call and completes the pool + * population phase + * + * @retval 0 on success + * @retval <0 on failure + */ +int odp_pool_ext_populate(odp_pool_t pool, void *buf[], uint32_t buf_size, uint32_t num, + uint32_t flags); + +/** * @} */ |