API Description

Stash for storing object handles.

Data Structures
union	odp_stash_stats_opt_t
	Stash statistics counters options. More...

struct	odp_stash_stats_t
	Stash statistics counters. More...

struct	odp_stash_capability_t
	Stash capabilities (per stash type) More...

struct	odp_stash_param_t
	Stash parameters. More...

Macros
#define	ODP_STASH_INVALID ((odp_stash_t)0)
	Invalid stash handle.

#define	ODP_STASH_NAME_LEN 32
	Maximum stash name length, including the null character.

Typedefs
typedef _odp_abi_stash_t *	odp_stash_t
	Stash handle.

typedef enum odp_stash_type_t	odp_stash_type_t
	Stash types.

typedef enum odp_stash_op_mode_t	odp_stash_op_mode_t
	Stash operation mode.

typedef union odp_stash_stats_opt_t	odp_stash_stats_opt_t
	Stash statistics counters options. More...

typedef struct odp_stash_stats_t	odp_stash_stats_t
	Stash statistics counters.

typedef struct odp_stash_capability_t	odp_stash_capability_t
	Stash capabilities (per stash type)

typedef struct odp_stash_param_t	odp_stash_param_t
	Stash parameters.

Enumerations
enum	odp_stash_type_t { ODP_STASH_TYPE_DEFAULT = 0 , ODP_STASH_TYPE_FIFO }
	Stash types. More...

enum	odp_stash_op_mode_t { ODP_STASH_OP_MT = 0 , ODP_STASH_OP_ST , ODP_STASH_OP_LOCAL }
	Stash operation mode. More...

Functions
int	odp_stash_capability (odp_stash_capability_t *capa, odp_stash_type_t type)
	Query stash capabilities. More...

void	odp_stash_param_init (odp_stash_param_t *param)
	Initialize stash params. More...

odp_stash_t	odp_stash_create (const char name, const odp_stash_param_t param)
	Create a stash. More...

int	odp_stash_destroy (odp_stash_t stash)
	Destroy a stash. More...

odp_stash_t	odp_stash_lookup (const char *name)
	Find a stash by name. More...

uint64_t	odp_stash_to_u64 (odp_stash_t stash)
	Get printable value for a stash handle. More...

int32_t	odp_stash_put (odp_stash_t stash, const void *obj, int32_t num)
	Put object handles into a stash. More...

int32_t	odp_stash_put_batch (odp_stash_t stash, const void *obj, int32_t num)
	Put batch of object handles into a stash. More...

int32_t	odp_stash_put_u32 (odp_stash_t stash, const uint32_t val[], int32_t num)
	Put 32-bit integers into a stash. More...

int32_t	odp_stash_put_u32_batch (odp_stash_t stash, const uint32_t val[], int32_t num)
	Put batch of 32-bit integers into a stash. More...

int32_t	odp_stash_put_u64 (odp_stash_t stash, const uint64_t val[], int32_t num)
	Put 64-bit integers into a stash. More...

int32_t	odp_stash_put_u64_batch (odp_stash_t stash, const uint64_t val[], int32_t num)
	Put batch of 64-bit integers into a stash. More...

int32_t	odp_stash_put_ptr (odp_stash_t stash, const uintptr_t ptr[], int32_t num)
	Put pointers into a stash. More...

int32_t	odp_stash_put_ptr_batch (odp_stash_t stash, const uintptr_t ptr[], int32_t num)
	Put batch of pointers into a stash. More...

int32_t	odp_stash_get (odp_stash_t stash, void *obj, int32_t num)
	Get object handles from a stash. More...

int32_t	odp_stash_get_batch (odp_stash_t stash, void *obj, int32_t num)
	Get batch of object handles from a stash. More...

int32_t	odp_stash_get_u32 (odp_stash_t stash, uint32_t val[], int32_t num)
	Get 32-bit integers from a stash. More...

int32_t	odp_stash_get_u32_batch (odp_stash_t stash, uint32_t val[], int32_t num)
	Get batch of 32-bit integers from a stash. More...

int32_t	odp_stash_get_u64 (odp_stash_t stash, uint64_t val[], int32_t num)
	Get 64-bit integers from a stash. More...

int32_t	odp_stash_get_u64_batch (odp_stash_t stash, uint64_t val[], int32_t num)
	Get batch of 64-bit integers from a stash. More...

int32_t	odp_stash_get_ptr (odp_stash_t stash, uintptr_t ptr[], int32_t num)
	Get pointers from a stash. More...

int32_t	odp_stash_get_ptr_batch (odp_stash_t stash, uintptr_t ptr[], int32_t num)
	Get batch of pointers from a stash. More...

int	odp_stash_flush_cache (odp_stash_t stash)
	Flush object handles from the thread local cache. More...

void	odp_stash_print (odp_stash_t stash)
	Print debug information about the stash. More...

int	odp_stash_stats (odp_stash_t stash, odp_stash_stats_t *stats)
	Read statistics counters of a stash. More...

Typedef Documentation

◆ odp_stash_stats_opt_t

typedef union odp_stash_stats_opt_t odp_stash_stats_opt_t

Stash statistics counters options.

Statistics counters listed in a bit field structure.

Enumeration Type Documentation

◆ odp_stash_type_t

enum odp_stash_type_t

Stash types.

Enumerator

ODP_STASH_TYPE_DEFAULT

The default stash type.

It is implementation specific in which order odp_stash_get() calls
return object handles from the stash. The order may be FIFO, LIFO
or something else. Use this for the best performance when any
particular ordering is not required.

ODP_STASH_TYPE_FIFO

Stash type FIFO.

Stash is implemented as a FIFO. A stash maintains object handle
order of consecutive odp_stash_put() calls. Object handles stored
first in the stash are received first by following odp_stash_get()
calls. To maintain (strict) FIFO ordering of object handles,
application needs to ensure that odp_stash_put()
(or odp_stash_get()) operations are not performed concurrently from
multiple threads. When multiple threads put (or get) object handles
concurrently in the stash, object handles from different threads
may be interleaved on output.

Definition at line 43 of file api/spec/stash_types.h.

◆ odp_stash_op_mode_t

enum odp_stash_op_mode_t

Stash operation mode.

Enumerator

ODP_STASH_OP_MT

Multi-thread safe operation.

Multiple threads operate on the stash. A stash operation
(odp_stash_put() or odp_stash_get()) may be performed concurrently
from multiple threads.

ODP_STASH_OP_ST

Single thread operation.

Multiple threads operate on the stash, but application ensures that
a stash operation (odp_stash_put() or odp_stash_get()) is not
performed concurrently from multiple threads.

ODP_STASH_OP_LOCAL

Thread local operation.

Only a single thread operates on the stash. Both stash operations
(odp_stash_put() and odp_stash_get()) are always performed from the
same thread.

Definition at line 72 of file api/spec/stash_types.h.

Function Documentation

◆ odp_stash_capability()

int odp_stash_capability	(	odp_stash_capability_t *	capa,
		odp_stash_type_t	type
	)

Query stash capabilities.

Outputs capabilities of the given stash type on success. The stash type is not supported if 'max_stashes' capability is zero. The default stash type (ODP_STASH_TYPE_DEFAULT) is always supported. The function returns failure if the given stash type is unknown to the implementation.

Parameters

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

Return values

0	on success
<0	on failure

Examples: odp_dmafwd.c, odp_stash_perf.c, and odp_sysinfo.c.

◆ odp_stash_param_init()

void odp_stash_param_init ( odp_stash_param_t * param )

Initialize stash params.

Initialize an odp_stash_param_t to its default values for all fields.

Parameters

param Parameter structure to be initialized

Examples: odp_debug.c, odp_dmafwd.c, and odp_stash_perf.c.

◆ odp_stash_create()

odp_stash_t odp_stash_create	(	const char *	name,
		const odp_stash_param_t *	param
	)

Create a stash.

This routine is used to create a stash for object handles. Object handle values are opaque data to ODP implementation. Application may use a stash to store e.g. pointers, offsets or indexes to arbitrary objects which are allocated and freed frequently (e.g. per packet) during application processing. Object handle size is specified in stash parameters.

It is optional to give a name. Names do not have to be unique. However, odp_stash_lookup() returns only a single matching stash.

Parameters

name	Name of the stash or NULL. Maximum string length is ODP_STASH_NAME_LEN, including the null character.
param	Stash creation parameters

Returns: Handle of the created stash

Return values

ODP_STASH_INVALID Stash could not be created

Examples: odp_debug.c, odp_dmafwd.c, and odp_stash_perf.c.

◆ odp_stash_destroy()

int odp_stash_destroy ( odp_stash_t stash )

Destroy a stash.

Destroy a previously created stash. Stash must be empty before it is destroyed. Results are undefined if an attempt is made to destroy a stash that contains object handles.

Parameters

stash The stash to be destroyed

Return values

0	Success
<0	Failure

Examples: odp_debug.c, odp_dmafwd.c, and odp_stash_perf.c.

◆ odp_stash_lookup()

odp_stash_t odp_stash_lookup ( const char * name )

Find a stash by name.

Parameters

name	Name of the stash

Returns: Handle of the first matching stash

Return values

ODP_STASH_INVALID Stash could not be found

◆ odp_stash_to_u64()

uint64_t odp_stash_to_u64 ( odp_stash_t stash )

Get printable value for a stash handle.

Parameters

stash Handle to be converted for debugging

Returns: uint64_t value that can be used for debugging (e.g. printed)

◆ odp_stash_put()

int32_t odp_stash_put	(	odp_stash_t	stash,
		const void *	obj,
		int32_t	num
	)

Put object handles into a stash.

Store object handles into the stash. Handle values are opaque data to ODP implementation and may be e.g. pointers or indexes to arbitrary objects. Application specifies object handle size and maximum number of handles to be stored in stash creation parameters.

A successful operation returns the actual number of object handles stored. If the return value is less than 'num', the remaining handles at the end of 'obj' array are not stored.

In case of ODP_STASH_TYPE_FIFO, object handles are stored into the stash in the order they are in the array.

Parameters

stash	Stash handle
obj	Points to an array of object handles to be stored. Object handle size is specified by 'obj_size' in stash creation parameters. The array must be 'obj_size' aligned in memory.
num	Number of object handles to store

Returns: Number of object handles actually stored (0 ... num)

Return values

<0	on failure

Examples: odp_dmafwd.c.

◆ odp_stash_put_batch()

int32_t odp_stash_put_batch	(	odp_stash_t	stash,
		const void *	obj,
		int32_t	num
	)

Put batch of object handles into a stash.

Otherwise like odp_stash_put(), except that this function stores either all 'num' object handles or none. odp_stash_capability_t.max_put_batch defines the maximum supported batch size.

Parameters

stash	Stash handle
obj	Points to an array of object handles to be stored. Object handle size is specified by 'obj_size' in stash creation parameters. The array must be 'obj_size' aligned in memory.
num	Number of object handles to store

Returns: Number of object handles actually stored (0 or num)

Return values

<0	on failure

◆ odp_stash_put_u32()

int32_t odp_stash_put_u32	(	odp_stash_t	stash,
		const uint32_t	val[],
		int32_t	num
	)

Put 32-bit integers into a stash.

Otherwise like odp_stash_put(), except that this function operates on 32-bit integers. The stash must have been created with 'obj_size' of 4.

Parameters

stash	Stash handle
val	Points to an array of 32-bit integers to be stored. The array must be 32-bit aligned in memory.
num	Number of integers to store

Returns: Number of integers actually stored (0 ... num)

Return values

<0	on failure

Examples: odp_debug.c, and odp_stash_perf.c.

◆ odp_stash_put_u32_batch()

int32_t odp_stash_put_u32_batch	(	odp_stash_t	stash,
		const uint32_t	val[],
		int32_t	num
	)

Put batch of 32-bit integers into a stash.

Otherwise like odp_stash_put_u32(), except that this function stores either all 'num' object handles or none. odp_stash_capability_t.max_put_batch defines the maximum supported batch size.

Parameters

stash	Stash handle
val	Points to an array of 32-bit integers to be stored. The array must be 32-bit aligned in memory.
num	Number of integers to store

Returns: Number of integers actually stored (0 or num)

Return values

<0	on failure

◆ odp_stash_put_u64()

int32_t odp_stash_put_u64	(	odp_stash_t	stash,
		const uint64_t	val[],
		int32_t	num
	)

Put 64-bit integers into a stash.

Otherwise like odp_stash_put(), except that this function operates on 64-bit integers. The stash must have been created with 'obj_size' of 8.

Parameters

stash	Stash handle
val	Points to an array of 64-bit integers to be stored. The array must be 64-bit aligned in memory.
num	Number of integers to store

Returns: Number of integers actually stored (0 ... num)

Return values

<0	on failure

◆ odp_stash_put_u64_batch()

int32_t odp_stash_put_u64_batch	(	odp_stash_t	stash,
		const uint64_t	val[],
		int32_t	num
	)

Put batch of 64-bit integers into a stash.

Otherwise like odp_stash_put_u64(), except that this function stores either all 'num' object handles or none. odp_stash_capability_t.max_put_batch defines the maximum supported batch size.

Parameters

stash	Stash handle
val	Points to an array of 64-bit integers to be stored. The array must be 64-bit aligned in memory.
num	Number of integers to store

Returns: Number of integers actually stored (0 or num)

Return values

<0	on failure

◆ odp_stash_put_ptr()

int32_t odp_stash_put_ptr	(	odp_stash_t	stash,
		const uintptr_t	ptr[],
		int32_t	num
	)

Put pointers into a stash.

Otherwise like odp_stash_put(), except that this function operates on pointers. The stash must have been created with 'obj_size' matching to the size of uintptr_t.

Parameters

stash	Stash handle
ptr	Points to an array of pointers to be stored. The array must be pointer size aligned in memory.
num	Number of pointers to store

Returns: Number of pointers actually stored (0 ... num)

Return values

<0	on failure

◆ odp_stash_put_ptr_batch()

int32_t odp_stash_put_ptr_batch	(	odp_stash_t	stash,
		const uintptr_t	ptr[],
		int32_t	num
	)

Put batch of pointers into a stash.

Otherwise like odp_stash_put_ptr(), except that this function stores either all 'num' object handles or none. odp_stash_capability_t.max_put_batch defines the maximum supported batch size.

Parameters

stash	Stash handle
ptr	Points to an array of pointers to be stored. The array must be pointer size aligned in memory.
num	Number of pointers to store

Returns: Number of pointers actually stored (0 or num)

Return values

<0	on failure

◆ odp_stash_get()

int32_t odp_stash_get	(	odp_stash_t	stash,
		void *	obj,
		int32_t	num
	)

Get object handles from a stash.

Get previously stored object handles from the stash. Application specifies object handle size in stash creation parameters.

Parameters

	stash	Stash handle
[out]	obj	Points to an array of object handles for output. Object handle size is specified by 'obj_size' in stash creation parameters. The array must be 'obj_size' aligned in memory.
	num	Maximum number of object handles to get from the stash

Returns: Number of object handles actually output (0 ... num) to 'obj' array

Return values

<0	on failure

Examples: odp_dmafwd.c.

◆ odp_stash_get_batch()

int32_t odp_stash_get_batch	(	odp_stash_t	stash,
		void *	obj,
		int32_t	num
	)

Get batch of object handles from a stash.

Otherwise like odp_stash_get(), except that this function outputs either all 'num' object handles or none. odp_stash_capability_t.max_get_batch defines the maximum supported batch size.

Parameters

	stash	Stash handle
[out]	obj	Points to an array of object handles for output. Object handle size is specified by 'obj_size' in stash creation parameters. The array must be 'obj_size' aligned in memory.
	num	Number of object handles to get from the stash

Returns: Number of object handles actually output (0 or num) to 'obj' array

Return values

<0	on failure

◆ odp_stash_get_u32()

int32_t odp_stash_get_u32	(	odp_stash_t	stash,
		uint32_t	val[],
		int32_t	num
	)

Get 32-bit integers from a stash.

Otherwise like odp_stash_get(), except that this function operates on 32-bit integers. The stash must have been created with 'obj_size' of 4.

Parameters

	stash	Stash handle
[out]	val	Points to an array of 32-bit integers for output. The array must be 32-bit aligned in memory.
	num	Maximum number of integers to get from the stash

Returns: Number of integers actually output (0 ... num) to 'val' array

Return values

<0	on failure

Examples: odp_debug.c, and odp_stash_perf.c.

◆ odp_stash_get_u32_batch()

int32_t odp_stash_get_u32_batch	(	odp_stash_t	stash,
		uint32_t	val[],
		int32_t	num
	)

Get batch of 32-bit integers from a stash.

Otherwise like odp_stash_get_u32(), except that this function outputs either all 'num' object handles or none. odp_stash_capability_t.max_get_batch defines the maximum supported batch size.

Parameters

	stash	Stash handle
[out]	val	Points to an array of 32-bit integers for output. The array must be 32-bit aligned in memory.
	num	Number of integers to get from the stash

Returns: Number of integers actually output (0 or num) to 'val' array

Return values

<0	on failure

◆ odp_stash_get_u64()

int32_t odp_stash_get_u64	(	odp_stash_t	stash,
		uint64_t	val[],
		int32_t	num
	)

Get 64-bit integers from a stash.

Otherwise like odp_stash_get(), except that this function operates on 64-bit integers. The stash must have been created with 'obj_size' of 8.

Parameters

	stash	Stash handle
[out]	val	Points to an array of 64-bit integers for output. The array must be 64-bit aligned in memory.
	num	Maximum number of integers to get from the stash

Returns: Number of integers actually output (0 ... num) to 'val' array

Return values

<0	on failure

◆ odp_stash_get_u64_batch()

int32_t odp_stash_get_u64_batch	(	odp_stash_t	stash,
		uint64_t	val[],
		int32_t	num
	)

Get batch of 64-bit integers from a stash.

Otherwise like odp_stash_get_u64(), except that this function outputs either all 'num' object handles or none. odp_stash_capability_t.max_get_batch defines the maximum supported batch size.

Parameters

	stash	Stash handle
[out]	val	Points to an array of 64-bit integers for output. The array must be 64-bit aligned in memory.
	num	Number of integers to get from the stash

Returns: Number of integers actually output (0 or num) to 'val' array

Return values

<0	on failure

◆ odp_stash_get_ptr()

int32_t odp_stash_get_ptr	(	odp_stash_t	stash,
		uintptr_t	ptr[],
		int32_t	num
	)

Get pointers from a stash.

Otherwise like odp_stash_get(), except that this function operates on pointers. The stash must have been created with 'obj_size' matching to the size of uintptr_t.

Parameters

	stash	Stash handle
[out]	ptr	Points to an array of pointers for output. The array must be pointer size aligned in memory.
	num	Maximum number of pointers to get from the stash

Returns: Number of pointers actually output (0 ... num) to 'ptr' array

Return values

<0	on failure

◆ odp_stash_get_ptr_batch()

int32_t odp_stash_get_ptr_batch	(	odp_stash_t	stash,
		uintptr_t	ptr[],
		int32_t	num
	)

Get batch of pointers from a stash.

Otherwise like odp_stash_get_ptr(), except that this function outputs either all 'num' object handles or none. odp_stash_capability_t.max_get_batch defines the maximum supported batch size.

Parameters

	stash	Stash handle
[out]	ptr	Points to an array of pointers for output. The array must be pointer size aligned in memory.
	num	Number of pointers to get from the stash

Returns: Number of pointers actually output (0 or num) to 'ptr' array

Return values

<0	on failure

◆ odp_stash_flush_cache()

int odp_stash_flush_cache ( odp_stash_t stash )

Flush object handles from the thread local cache.

Flushes all object handles from the thread local cache into the stash, so that those are available to odp_stash_get() calls from other threads. This call may be used to ensure that thread local cache is empty e.g. before the calling thread stops using the stash.

Flush and put operations share 'put_mode' setting in stash creation parameters. So, application must ensure that flush and put operations are not used concurrently, when ODP_STASH_OP_ST is selected.

Parameters

stash Stash handle

Return values

0	on success
<0	on failure

◆ odp_stash_print()

void odp_stash_print ( odp_stash_t stash )

Print debug information about the stash.

Print implementation defined information about the stash to the ODP log. The information is intended to be used for debugging.

Parameters

stash Stash handle

Examples: odp_debug.c.

◆ odp_stash_stats()

int odp_stash_stats	(	odp_stash_t	stash,
		odp_stash_stats_t *	stats
	)

Read statistics counters of a stash.

Read the statistics counters enabled using odp_stash_stats_opt_t during stash creation. Inactive counters are set to zero by the implementation.

Parameters

	stash	Stash handle
[out]	stats	Points to statistics counters structure for output

Return values

0	on success
<0	on failure

API Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Typedef Documentation

◆ odp_stash_stats_opt_t

Enumeration Type Documentation

◆ odp_stash_type_t

◆ odp_stash_op_mode_t

Function Documentation

◆ odp_stash_capability()

◆ odp_stash_param_init()

◆ odp_stash_create()

◆ odp_stash_destroy()

◆ odp_stash_lookup()

◆ odp_stash_to_u64()

◆ odp_stash_put()

◆ odp_stash_put_batch()

◆ odp_stash_put_u32()

◆ odp_stash_put_u32_batch()

◆ odp_stash_put_u64()

◆ odp_stash_put_u64_batch()

◆ odp_stash_put_ptr()

◆ odp_stash_put_ptr_batch()

◆ odp_stash_get()

◆ odp_stash_get_batch()

◆ odp_stash_get_u32()

◆ odp_stash_get_u32_batch()

◆ odp_stash_get_u64()

◆ odp_stash_get_u64_batch()

◆ odp_stash_get_ptr()

◆ odp_stash_get_ptr_batch()

◆ odp_stash_flush_cache()

◆ odp_stash_print()

◆ odp_stash_stats()