ODP POOL

API Description

Packet and buffer (event) pools.

Data Structures
union	odp_pool_stats_opt_t
	Pool statistics counters options. More...
struct	odp_pool_stats_t
	Pool statistics counters. More...
struct	odp_pool_stats_selected_t
	Pool statistics counters. More...
struct	odp_pool_capability_t
	Pool capabilities. More...
struct	odp_pool_pkt_subparam_t
	Packet pool subparameters. More...
struct	odp_pool_param_t
	Pool parameters. More...
struct	odp_pool_ext_capability_t
	External memory pool capabilities. More...
struct	odp_pool_ext_param_t
	External memory pool parameters. More...
struct	odp_pool_info_t
	Pool information struct Used to get information about a pool. More...

Macros
#define	ODP_POOL_INVALID   ((odp_pool_t)0)
	Invalid pool.
#define	ODP_POOL_NAME_LEN   32
	Maximum pool name length, including the null character.
#define	ODP_POOL_MAX_THREAD_STATS   128
	Maximum number of per thread statistics a single odp_pool_stats() call can read.
#define	ODP_POOL_MAX_SUBPARAMS   7
	Maximum number of packet pool subparameters.
#define	ODP_POOL_POPULATE_DONE   0x1
	External memory pool population done. More...

Typedefs
typedef _odp_abi_pool_t *	odp_pool_t
	ODP pool.
typedef union odp_pool_stats_opt_t	odp_pool_stats_opt_t
	Pool statistics counters options. More...
typedef struct odp_pool_stats_t	odp_pool_stats_t
	Pool statistics counters. More...
typedef struct odp_pool_stats_selected_t	odp_pool_stats_selected_t
	Pool statistics counters. More...
typedef struct odp_pool_capability_t	odp_pool_capability_t
	Pool capabilities.
typedef struct odp_pool_pkt_subparam_t	odp_pool_pkt_subparam_t
	Packet pool subparameters.
typedef enum odp_pool_type_t	odp_pool_type_t
	Pool types.
typedef struct odp_pool_param_t	odp_pool_param_t
	Pool parameters.
typedef struct odp_pool_ext_capability_t	odp_pool_ext_capability_t
	External memory pool capabilities. More...
typedef struct odp_pool_ext_param_t	odp_pool_ext_param_t
	External memory pool parameters.
typedef struct odp_pool_info_t	odp_pool_info_t
	Pool information struct Used to get information about a pool.

Enumerations
enum	odp_pool_type_t {   ODP_POOL_PACKET = ODP_EVENT_PACKET , ODP_POOL_BUFFER = ODP_EVENT_BUFFER , ODP_POOL_TIMEOUT = ODP_EVENT_TIMEOUT , ODP_POOL_VECTOR ,   ODP_POOL_DMA_COMPL , ODP_POOL_ML_COMPL }
	Pool types. More...

Functions
int	odp_pool_capability (odp_pool_capability_t *capa)
	Query pool capabilities. More...
odp_pool_t	odp_pool_create (const char *name, const odp_pool_param_t *param)
	Create a pool. More...
int	odp_pool_destroy (odp_pool_t pool)
	Destroy a pool previously created by odp_pool_create() More...
odp_pool_t	odp_pool_lookup (const char *name)
	Find a pool by name. More...
int	odp_pool_info (odp_pool_t pool, odp_pool_info_t *info)
	Retrieve information about a pool. More...
void	odp_pool_print (odp_pool_t pool)
	Print pool info. More...
void	odp_pool_print_all (void)
	Print debug info about all pools. More...
uint64_t	odp_pool_to_u64 (odp_pool_t hdl)
	Get printable value for an odp_pool_t. More...
void	odp_pool_param_init (odp_pool_param_t *param)
	Initialize pool params. More...
unsigned int	odp_pool_max_index (void)
	Maximum pool index. More...
int	odp_pool_index (odp_pool_t pool)
	Get pool index. More...
int	odp_pool_stats (odp_pool_t pool, odp_pool_stats_t *stats)
	Read pool statistics. More...
int	odp_pool_stats_selected (odp_pool_t pool, odp_pool_stats_selected_t *stats, const odp_pool_stats_opt_t *opt)
	Get selected pool statistics. More...
int	odp_pool_stats_reset (odp_pool_t pool)
	Reset statistics for pool. More...
int	odp_pool_ext_capability (odp_pool_type_t type, odp_pool_ext_capability_t *capa)
	Query capabilities of an external memory pool type. More...
void	odp_pool_ext_param_init (odp_pool_type_t type, odp_pool_ext_param_t *param)
	Initialize pool params. More...
odp_pool_t	odp_pool_ext_create (const char *name, const odp_pool_ext_param_t *param)
	Create an external memory pool. More...
int	odp_pool_ext_populate (odp_pool_t pool, void *buf[], uint32_t buf_size, uint32_t num, uint32_t flags)
	Populate external memory pool with buffer memory. More...

Macro Definition Documentation

ODP_POOL_POPULATE_DONE

#define ODP_POOL_POPULATE_DONE   0x1

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.

Definition at line 657 of file api/spec/pool_types.h.

Typedef Documentation

odp_pool_stats_opt_t

typedef union odp_pool_stats_opt_t odp_pool_stats_opt_t

Pool statistics counters options.

Pool statistics counters listed in a bit field structure.

odp_pool_stats_t

typedef struct odp_pool_stats_t odp_pool_stats_t

Pool statistics counters.

In addition to API alloc and free calls, statistics counters may be updated by alloc/free operations from implementation internal software or hardware components.

odp_pool_stats_selected_t

typedef struct odp_pool_stats_selected_t odp_pool_stats_selected_t

Pool statistics counters.

Same as odp_pool_stats_t excluding per thread counters.

odp_pool_ext_capability_t

typedef struct odp_pool_ext_capability_t odp_pool_ext_capability_t

External memory pool capabilities.

Generic fields (not specific to a pool type) contain capabilities of the requested pool type.

Enumeration Type Documentation

odp_pool_type_t

enum odp_pool_type_t

Pool types.

Enumerator
ODP_POOL_PACKET	Packet pool.
ODP_POOL_BUFFER	Buffer pool.
ODP_POOL_TIMEOUT	Timeout pool.
ODP_POOL_VECTOR	Vector event pool. Each vector event holds an array of handles. All handles of a vector are the same type (such as odp_packet_t). See also ODP_EVENT_PACKET_VECTOR
ODP_POOL_DMA_COMPL	DMA completion event pool.
ODP_POOL_ML_COMPL	ML completion event pool.

Definition at line 402 of file api/spec/pool_types.h.

Function Documentation

odp_pool_capability()

int odp_pool_capability

(

odp_pool_capability_t *

capa

)

Query pool capabilities.

Outputs pool capabilities on success.

Parameters

[out]

capa

Pointer to capability structure for output

Return values

0	on success
<0	on failure

Examples

odp_bench_buffer.c, odp_bench_packet.c, odp_bench_pktio_sp.c, odp_bench_timer.c, odp_cpu_bench.c, odp_crypto.c, odp_dma_perf.c, odp_dmafwd.c, odp_ipsec.c, odp_ipsecfwd.c, odp_l2fwd.c, odp_l2fwd_perf.c, odp_packet_dump.c, odp_packet_gen.c, odp_ping.c, odp_pktio_ordered.c, odp_pool_latency.c, odp_pool_perf.c, odp_queue_perf.c, odp_sched_latency.c, odp_sched_perf.c, odp_sched_pktio.c, odp_simple_pipeline.c, odp_sysinfo.c, and odp_timer_stress.c.

odp_pool_create()

odp_pool_t odp_pool_create	(	const char *	name,
		const odp_pool_param_t *	param
	)

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. Use odp_pool_param_init() to initialize parameters into their default values.

Parameters

name	Name of the pool or NULL. Maximum string length is ODP_POOL_NAME_LEN, including the null character.
param	Pool parameters.

Returns

Handle of the created pool

Return values

ODP_POOL_INVALID

Pool could not be created

Examples

ipsec_api/odp_ipsec.c, ipsec_crypto/odp_ipsec.c, odp_bench_buffer.c, odp_bench_packet.c, odp_bench_pktio_sp.c, odp_bench_timer.c, odp_classifier.c, odp_cpu_bench.c, odp_crypto.c, odp_debug.c, odp_dma_perf.c, odp_dmafwd.c, odp_ipfragreass.c, odp_ipsec.c, odp_ipsecfwd.c, odp_l2fwd.c, odp_l2fwd_perf.c, odp_l3fwd.c, odp_packet_dump.c, odp_packet_gen.c, odp_ping.c, odp_pktio.c, odp_pktio_ordered.c, odp_pktio_perf.c, odp_pool_latency.c, odp_pool_perf.c, odp_queue_perf.c, odp_sched_latency.c, odp_sched_perf.c, odp_sched_pktio.c, odp_simple_pipeline.c, odp_stress.c, odp_switch.c, odp_sysinfo.c, odp_timer_accuracy.c, odp_timer_perf.c, odp_timer_simple.c, odp_timer_stress.c, and odp_traffic_mgmt.c.

odp_pool_destroy()

int odp_pool_destroy

(

odp_pool_t

pool

)

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.

Parameters

pool	Handle of the pool to be destroyed

Return values

0	Success
-1	Failure

Examples

ipsec_api/odp_ipsec.c, ipsec_crypto/odp_ipsec.c, odp_bench_buffer.c, odp_bench_packet.c, odp_bench_pktio_sp.c, odp_bench_timer.c, odp_classifier.c, odp_cpu_bench.c, odp_crypto.c, odp_debug.c, odp_dma_perf.c, odp_dmafwd.c, odp_ipfragreass.c, odp_ipsec.c, odp_ipsecfwd.c, odp_l2fwd.c, odp_l2fwd_perf.c, odp_l3fwd.c, odp_packet_dump.c, odp_packet_gen.c, odp_ping.c, odp_pktio.c, odp_pktio_ordered.c, odp_pktio_perf.c, odp_pool_latency.c, odp_pool_perf.c, odp_queue_perf.c, odp_sched_latency.c, odp_sched_perf.c, odp_sched_pktio.c, odp_simple_pipeline.c, odp_stress.c, odp_switch.c, odp_sysinfo.c, odp_timer_accuracy.c, odp_timer_perf.c, odp_timer_simple.c, odp_timer_stress.c, and odp_traffic_mgmt.c.

odp_pool_lookup()

odp_pool_t odp_pool_lookup

(

const char *

name

)

Find a pool by name.

Parameters

name	Name of the pool

Returns

Handle of the first matching pool

Return values

ODP_POOL_INVALID

Pool could not be found

Examples

odp_crypto.c, odp_ipsec.c, and odp_pktio_perf.c.

odp_pool_info()

int odp_pool_info	(	odp_pool_t	pool,
		odp_pool_info_t *	info
	)

Retrieve information about a pool.

Parameters

	pool	Pool handle
[out]	info	Receives an odp_pool_info_t object that describes the pool.

Return values

0	Success
-1	Failure. Info could not be retrieved.

odp_pool_print()

void odp_pool_print

(

odp_pool_t

pool

)

Print pool info.

Parameters

pool	Pool handle

Note

This routine writes implementation-defined information about the specified pool to the ODP log. The intended use is for debugging.

Examples

odp_bench_buffer.c, odp_bench_packet.c, odp_cpu_bench.c, odp_crypto.c, odp_debug.c, odp_ipsec.c, odp_l2fwd.c, odp_pktio.c, odp_pktio_ordered.c, and odp_switch.c.

odp_pool_print_all()

void odp_pool_print_all

(

void

)

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.

Examples

odp_classifier.c.

odp_pool_to_u64()

uint64_t odp_pool_to_u64

(

odp_pool_t

hdl

)

Get printable value for an odp_pool_t.

Parameters

hdl	odp_pool_t handle to be printed

Returns

uint64_t value that can be used to print/display this handle

Note

This routine is intended to be used for diagnostic purposes to enable applications to generate a printable value that represents an odp_pool_t handle.

Examples

odp_timer_stress.c.

odp_pool_param_init()

void odp_pool_param_init

(

odp_pool_param_t *

param

)

Initialize pool params.

Initialize an odp_pool_param_t to its default values for all fields

Parameters

param

Address of the odp_pool_param_t to be initialized

Examples

ipsec_api/odp_ipsec.c, ipsec_crypto/odp_ipsec.c, odp_bench_buffer.c, odp_bench_packet.c, odp_bench_pktio_sp.c, odp_bench_timer.c, odp_classifier.c, odp_cpu_bench.c, odp_crypto.c, odp_debug.c, odp_dma_perf.c, odp_dmafwd.c, odp_ipfragreass.c, odp_ipsec.c, odp_ipsecfwd.c, odp_l2fwd.c, odp_l2fwd_perf.c, odp_l3fwd.c, odp_packet_dump.c, odp_packet_gen.c, odp_ping.c, odp_pktio.c, odp_pktio_ordered.c, odp_pktio_perf.c, odp_pool_latency.c, odp_pool_perf.c, odp_queue_perf.c, odp_sched_latency.c, odp_sched_perf.c, odp_sched_pktio.c, odp_simple_pipeline.c, odp_stress.c, odp_switch.c, odp_sysinfo.c, odp_timer_accuracy.c, odp_timer_perf.c, odp_timer_simple.c, and odp_timer_stress.c.

odp_pool_max_index()

unsigned int odp_pool_max_index

(

void

)

Maximum pool index.

Return the maximum pool index. Pool indexes (e.g. returned by odp_pool_index()) range from zero to this maximum value.

Returns

Maximum pool index

odp_pool_index()

int odp_pool_index

(

odp_pool_t

pool

)

Get pool index.

Parameters

pool	Pool handle

Returns

Pool index (0..odp_pool_max_index())

Return values

<0	on failure

odp_pool_stats()

int odp_pool_stats	(	odp_pool_t	pool,
		odp_pool_stats_t *	stats
	)

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.

Parameters

	pool	Pool handle
[in,out]	stats	Output buffer for counters

Return values

0	on success
<0	on failure

Examples

odp_pool_perf.c.

odp_pool_stats_selected()

int odp_pool_stats_selected	(	odp_pool_t	pool,
		odp_pool_stats_selected_t *	stats,
		const odp_pool_stats_opt_t *	opt
	)

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.

Parameters

	pool	Pool handle
[out]	stats	Output buffer for counters
	opt	Bit field for selecting the counters to be read

Return values

0	on success
<0	on failure

odp_pool_stats_reset()

int odp_pool_stats_reset

(

odp_pool_t

pool

)

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

Parameters

pool	Pool handle

Return values

0	on success
<0	on failure

odp_pool_ext_capability()

int odp_pool_ext_capability	(	odp_pool_type_t	type,
		odp_pool_ext_capability_t *	capa
	)

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.

Parameters

	type	Pool type
[out]	capa	Pointer to capability structure for output

Return values

0	on success
<0	on failure

Examples

odp_sysinfo.c.

odp_pool_ext_param_init()

void odp_pool_ext_param_init	(	odp_pool_type_t	type,
		odp_pool_ext_param_t *	param
	)

Initialize pool params.

Initialize an odp_pool_ext_param_t to its default values for all fields based on the selected pool type.

Parameters

type	Pool type
param	odp_pool_ext_param_t to be initialized

odp_pool_ext_create()

odp_pool_t odp_pool_ext_create	(	const char *	name,
		const 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.

Parameters

name	Name of the pool or NULL. Maximum string length is ODP_POOL_NAME_LEN, including the null character.
param	Pool parameters

Returns

Pool handle on success

Return values

ODP_POOL_INVALID

on failure

odp_pool_ext_populate()

int odp_pool_ext_populate	(	odp_pool_t	pool,
		void *	buf[],
		uint32_t	buf_size,
		uint32_t	num,
		uint32_t	flags
	)

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.

                     +-------------------------------+    --                     --
         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    |
                     |                               |     |                      |
                     +-------------------------------+    --                     --

Parameters

pool	External memory pool
buf	Buffer pointers to be populated into the pool
buf_size	Buffer size
num	Number of buffer pointers
flags	0: No flags ODP_POOL_POPULATE_DONE: Marks the last populate call and completes the pool population phase

Return values

0	on success
<0	on failure