diff options
Diffstat (limited to 'include/odp/api/spec')
| -rw-r--r-- | include/odp/api/spec/pool.h | 102 | ||||
| -rw-r--r-- | include/odp/api/spec/pool_types.h | 215 |
2 files changed, 315 insertions, 2 deletions
diff --git a/include/odp/api/spec/pool.h b/include/odp/api/spec/pool.h index a5ad9a3b0..6314b827c 100644 --- a/include/odp/api/spec/pool.h +++ b/include/odp/api/spec/pool.h @@ -174,6 +174,108 @@ int odp_pool_stats(odp_pool_t pool, odp_pool_stats_t *stats); 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. + * @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); + +/** * @} */ diff --git a/include/odp/api/spec/pool_types.h b/include/odp/api/spec/pool_types.h index 5e445ae38..44d9297c1 100644 --- a/include/odp/api/spec/pool_types.h +++ b/include/odp/api/spec/pool_types.h @@ -507,6 +507,204 @@ typedef struct odp_pool_param_t { } odp_pool_param_t; /** + * External memory pool population done + * + * Application uses this flag to mark the last odp_pool_ext_populate() call, which completes + * external memory pool population phase. + */ +#define ODP_POOL_POPULATE_DONE 0x1 + +/** + * External memory pool capabilities + * + * Generic fields (not specific to a pool type) contain capabilities + * of the requested pool type. + */ +typedef struct odp_pool_ext_capability_t { + /** Requested pool type + * + * Pool type from the odp_pool_ext_capability() call is recorded here for reference. */ + odp_pool_type_t type; + + /** Maximum number of pools + * + * Maximum number of external memory pools of the requested type. */ + uint32_t max_pools; + + /** Minimum size of thread local cache */ + uint32_t min_cache_size; + + /** Maximum size of thread local cache */ + uint32_t max_cache_size; + + /** Supported statistics counters */ + odp_pool_stats_opt_t stats; + + /** Packet pool capabilities */ + struct { + /** Maximum number of packet buffers */ + uint32_t max_num_buf; + + /** Maximum packet buffer size in bytes */ + uint32_t max_buf_size; + + /** ODP header size in bytes + * + * Application must reserve this many bytes from the start of a packet buffer + * for ODP implementation usage. When the value is zero, ODP implementation does + * not need header space to be reserved for it. Application will not modify this + * memory area (after buffer populate call). + */ + uint32_t odp_header_size; + + /** ODP trailer size in bytes + * + * Application must reserve this many bytes from the end of a packet buffer + * for ODP implementation usage. When the value is zero, ODP implementation does + * not need trailer space to be reserved for it. Application will not modify this + * memory area (after buffer populate call). + */ + uint32_t odp_trailer_size; + + /** Minimum packet pool memory area alignment in bytes + * + * The memory area used for a packet pool, starting from (or before) the lowest + * addressed buffer and extending to the end (or after) of the highest addressed + * buffer, must have at least this (power of two) alignment. The value is 1 when + * there is no alignment requirement. + */ + uint32_t min_mem_align; + + /** Minimum packet buffer pointer alignment in bytes + * + * Packet buffer pointers populated into a pool must be evenly divisible with + * this value. The value is 1 when there is no alignment requirement. + */ + uint32_t min_buf_align; + + /** Minimum packet headroom alignment in bytes + * + * Packet buffers populated into a pool must have their headroom start address + * evenly divisible with this value. The value is 1 when there is no alignment + * requirement. + */ + uint32_t min_head_align; + + /** Packet buffer alignment flags + * + * These flags specify additional alignment requirements for packet buffers. + * If not stated otherwise, min_buf_align and min_head_align alignment + * requirements apply also. + */ + struct { + /** Packet buffers are size aligned + * + * When set, packet buffer pointers must be aligned to the buffer size. + * For example, if the buffer size would be 2304 bytes (0x900), + * each buffer start address must be a multiple of 0x900 + * (e.g. 0x12000900, 0x12001200, 0x12004800, etc). */ + uint16_t buf_size_aligned : 1; + + }; + + /** Maximum headroom parameter value + * + * The packet pool headroom parameter may not exceed this value. + */ + uint32_t max_headroom; + + /** Maximum headroom size in bytes + * + * Any newly allocated packet will have at most this much headroom. Application + * may use this to ensure that packet buffer size is large enough to fit both + * buffer headers, headroom and data. + */ + uint32_t max_headroom_size; + + /** Maximum number of segments per packet */ + uint32_t max_segs_per_pkt; + + /** Maximum user area size in bytes */ + uint32_t max_uarea_size; + + } pkt; + +} odp_pool_ext_capability_t; + +/** + * External memory pool parameters + */ +typedef struct odp_pool_ext_param_t { + /** Pool type */ + odp_pool_type_t type; + + /** Maximum thread local cache size for the pool + * + * Valid value range is from min_cache_size to max_cache_size capability. + * The default value is implementation specific. See odp_pool_param_t (buf.cache_size) + * for more detailed documentation. + */ + uint32_t cache_size; + + /** + * Pool statistics configuration + * + * All pool statistics are disabled by default. For optimal performance, enable only those + * counters that are actually used. Counters may be read with odp_pool_stats(). + */ + odp_pool_stats_opt_t stats; + + /** Parameters for packet pools */ + struct { + /** Number of packet buffers + * + * The number of packet buffers application will populate into the pool. + * The maximum value is defined by pool capability pkt.max_num_buf. + */ + uint32_t num_buf; + + /** Packet buffer size + * + * Total buffer size in bytes including all headers, trailer, head-/tailroom + * and data. This is calculated from buffer start pointer to the end of buffer + * data area (including tailroom) or ODP trailer (see odp_trailer_size capability). + * All packet buffers application populates into the pool are of this size. + */ + uint32_t buf_size; + + /** Application header size + * + * Application reserves this many bytes for its own buffer header usage. + * The application header follows immediately the ODP buffer header + * (see odp_header_size capability). ODP implementation will not modify this + * memory area. The default value is 0. + */ + uint32_t app_header_size; + + /** User area size + * + * Per packet user area size in bytes. As with normal pools, user area location + * is ODP implementation specific. Use zero if no user area is needed. + * The maximum value is defined by pool capability pkt.max_uarea_size. + * The default value is 0. + */ + uint32_t uarea_size; + + /** Minimum headroom size + * + * Each newly allocated packet from the pool must have at least this much + * headroom in bytes. The configuration applies to both ODP packet input and + * application allocated packets. Use zero if headroom is not needed. The maximum + * value is defined by pool capability pkt.max_headroom. Implementation may + * round up the initial headroom size up to pool capability pkt.max_headroom_size. + */ + uint32_t headroom; + + } pkt; + +} odp_pool_ext_param_t; + +/** * Pool information struct * Used to get information about a pool. */ @@ -514,8 +712,21 @@ typedef struct odp_pool_info_t { /** Pool name */ const char *name; - /** Copy of pool parameters */ - odp_pool_param_t params; + /** External memory pool + * + * 0: Pool is a normal pool + * 1: Pool is an external memory pool + */ + odp_bool_t pool_ext; + + /** Pool parameters union */ + union { + /** Copy of pool parameters. This is set when pool_ext is 0. */ + odp_pool_param_t params; + + /** Copy of external memory pool parameters. This is set when pool_ext is 1. */ + odp_pool_ext_param_t pool_ext_param; + }; /** Additional info for packet pools */ struct { |