#include <rte_ring.h>

Macros
#define	RTE_SORING_ST_BIT 30

#define	RTE_SORING_ELEM_MAX (RTE_BIT32(RTE_SORING_ST_BIT) - 1)

Functions
__rte_experimental ssize_t	rte_soring_get_memsize (const struct rte_soring_param *prm)

__rte_experimental int	rte_soring_init (struct rte_soring r, const struct rte_soring_param prm)

__rte_experimental unsigned int	rte_soring_count (const struct rte_soring *r)

__rte_experimental unsigned int	rte_soring_free_count (const struct rte_soring *r)

__rte_experimental void	rte_soring_dump (FILE f, const struct rte_soring r)

__rte_experimental uint32_t	rte_soring_enqueue_bulk (struct rte_soring r, const void objs, uint32_t n, uint32_t *free_space)

__rte_experimental uint32_t	rte_soring_enqueux_bulk (struct rte_soring r, const void objs, const void meta, uint32_t n, uint32_t free_space)

__rte_experimental uint32_t	rte_soring_enqueue_burst (struct rte_soring r, const void objs, uint32_t n, uint32_t *free_space)

__rte_experimental uint32_t	rte_soring_enqueux_burst (struct rte_soring r, const void objs, const void meta, uint32_t n, uint32_t free_space)

__rte_experimental uint32_t	rte_soring_dequeue_bulk (struct rte_soring r, void objs, uint32_t num, uint32_t *available)

__rte_experimental uint32_t	rte_soring_dequeux_bulk (struct rte_soring r, void objs, void meta, uint32_t num, uint32_t available)

__rte_experimental uint32_t	rte_soring_dequeue_burst (struct rte_soring r, void objs, uint32_t num, uint32_t *available)

__rte_experimental uint32_t	rte_soring_dequeux_burst (struct rte_soring r, void objs, void meta, uint32_t num, uint32_t available)

__rte_experimental uint32_t	rte_soring_acquire_bulk (struct rte_soring r, void objs, uint32_t stage, uint32_t num, uint32_t ftoken, uint32_t available)

__rte_experimental uint32_t	rte_soring_acquirx_bulk (struct rte_soring r, void objs, void meta, uint32_t stage, uint32_t num, uint32_t ftoken, uint32_t *available)

__rte_experimental uint32_t	rte_soring_acquire_burst (struct rte_soring r, void objs, uint32_t stage, uint32_t num, uint32_t ftoken, uint32_t available)

__rte_experimental uint32_t	rte_soring_acquirx_burst (struct rte_soring r, void objs, void meta, uint32_t stage, uint32_t num, uint32_t ftoken, uint32_t *available)

__rte_experimental void	rte_soring_release (struct rte_soring r, const void objs, uint32_t stage, uint32_t n, uint32_t ftoken)

__rte_experimental void	rte_soring_releasx (struct rte_soring r, const void objs, const void *meta, uint32_t stage, uint32_t n, uint32_t ftoken)

Detailed Description

This file contains definition of DPDK soring (Staged Ordered Ring) public API. Brief description: enqueue/dequeue works the same as for conventional rte_ring: any rte_ring sync types can be used, etc. Plus there could be multiple 'stages'. For each stage there is an acquire (start) and release (finish) operation. after some elems are 'acquired' - user can safely assume having exclusive possession of these elems till 'release' for them is done. Note that right now user has to release exactly the same number of elems acquired before. After 'release', elems can be 'acquired' by next stage and/or dequeued (in case of last stage). Extra debugging might be enabled with RTE_SORING_DEBUG macro.

Definition in file rte_soring.h.

Macro Definition Documentation

◆ RTE_SORING_ST_BIT

#define RTE_SORING_ST_BIT 30

upper 2 bits are used for status

Definition at line 33 of file rte_soring.h.

◆ RTE_SORING_ELEM_MAX

#define RTE_SORING_ELEM_MAX (RTE_BIT32(RTE_SORING_ST_BIT) - 1)

max possible number of elements in the soring

Definition at line 36 of file rte_soring.h.

Function Documentation

◆ rte_soring_get_memsize()

__rte_experimental ssize_t rte_soring_get_memsize ( const struct rte_soring_param * prm )

Warning: EXPERIMENTAL: this API may change without prior notice.

Calculate the memory size needed for a soring

This function returns the number of bytes needed for a soring, given the expected parameters for it. This value is the sum of the size of the internal metadata and the size of the memory needed by the actual soring elements and their metadata. The value is aligned to a cache line size.

Parameters

prm	Pointer to the structure that contains soring creation parameters.

Returns

The memory size needed for the soring on success.
-EINVAL if provided parameter values are invalid.

◆ rte_soring_init()

__rte_experimental int rte_soring_init	(	struct rte_soring *	r,
		const struct rte_soring_param *	prm
	)

Warning: EXPERIMENTAL: this API may change without prior notice.

Initialize a soring structure.

Initialize a soring structure in memory pointed by "r". The size of the memory area must be large enough to store the soring internal structures plus the objects and metadata tables. It is strongly advised to use rte_soring_get_memsize() to get the appropriate size.

Parameters

r	Pointer to the soring structure.
prm	Pointer to the structure that contains soring creation parameters.

Returns

0 on success, or a negative error code.

◆ rte_soring_count()

__rte_experimental unsigned int rte_soring_count ( const struct rte_soring * r )

Warning: EXPERIMENTAL: this API may change without prior notice.

Return the total number of filled entries in a soring.

Parameters

r	A pointer to the soring structure.

Returns: The number of entries in the soring.

◆ rte_soring_free_count()

__rte_experimental unsigned int rte_soring_free_count ( const struct rte_soring * r )

Warning: EXPERIMENTAL: this API may change without prior notice.

Return the total number of unfilled entries in a soring.

Parameters

r	A pointer to the soring structure.

Returns: The number of free entries in the soring.

◆ rte_soring_dump()

__rte_experimental void rte_soring_dump	(	FILE *	f,
		const struct rte_soring *	r
	)

Warning: EXPERIMENTAL: this API may change without prior notice.

Dump the status of the soring

Parameters

f	A pointer to a file for output
r	Pointer to the soring structure.

◆ rte_soring_enqueue_bulk()

__rte_experimental uint32_t rte_soring_enqueue_bulk	(	struct rte_soring *	r,
		const void *	objs,
		uint32_t	n,
		uint32_t *	free_space
	)

Warning: EXPERIMENTAL: this API may change without prior notice.

Enqueue several objects on the soring. Enqueues exactly requested number of objects or none.

Parameters

r	A pointer to the soring structure.
objs	A pointer to an array of objects to enqueue. Size of objects to enqueue must be the same value as 'elem_size' parameter used while creating the soring. Otherwise the results are undefined.
n	The number of objects to add in the soring from the 'objs'.
free_space	if non-NULL, returns the amount of space in the soring after the enqueue operation has finished.

Returns

Actual number of objects enqueued, either 0 or n.

◆ rte_soring_enqueux_bulk()

__rte_experimental uint32_t rte_soring_enqueux_bulk	(	struct rte_soring *	r,
		const void *	objs,
		const void *	meta,
		uint32_t	n,
		uint32_t *	free_space
	)

Warning: EXPERIMENTAL: this API may change without prior notice.

Enqueue several objects plus metadata on the soring. Enqueues exactly requested number of objects or none.

Parameters

r	A pointer to the soring structure.
objs	A pointer to an array of objects to enqueue. Size of objects to enqueue must be the same value as 'elem_size' parameter used while creating the soring. Otherwise the results are undefined.
meta	A pointer to an array of metadata values for each object to enqueue. Note that if user not using object metadata values, then this parameter can be NULL. Size of elements in this array must be the same value as 'meta_size' parameter used while creating the soring. If user created the soring with 'meta_size' value equals zero, then 'meta' parameter should be NULL. Otherwise the results are undefined.
n	The number of objects to add in the soring from the 'objs'.
free_space	if non-NULL, returns the amount of space in the soring after the enqueue operation has finished.

Returns

Actual number of objects enqueued, either 0 or n.

◆ rte_soring_enqueue_burst()

__rte_experimental uint32_t rte_soring_enqueue_burst	(	struct rte_soring *	r,
		const void *	objs,
		uint32_t	n,
		uint32_t *	free_space
	)

Warning: EXPERIMENTAL: this API may change without prior notice.

Enqueue several objects on the soring. Enqueues up to requested number of objects.

Parameters

r	A pointer to the soring structure.
objs	A pointer to an array of objects to enqueue. Size of objects to enqueue must be the same value as 'elem_size' parameter used while creating the soring. Otherwise the results are undefined.
n	The number of objects to add in the soring from the 'objs'.
free_space	if non-NULL, returns the amount of space in the soring after the enqueue operation has finished.

Returns

Actual number of objects enqueued.

◆ rte_soring_enqueux_burst()

__rte_experimental uint32_t rte_soring_enqueux_burst	(	struct rte_soring *	r,
		const void *	objs,
		const void *	meta,
		uint32_t	n,
		uint32_t *	free_space
	)

Warning: EXPERIMENTAL: this API may change without prior notice.

Enqueue several objects plus metadata on the soring. Enqueues up to requested number of objects.

Parameters

r	A pointer to the soring structure.
objs	A pointer to an array of objects to enqueue. Size of objects to enqueue must be the same value as 'elem_size' parameter used while creating the soring. Otherwise the results are undefined.
meta	A pointer to an array of metadata values for each object to enqueue. Note that if user not using object metadata values, then this parameter can be NULL. Size of elements in this array must be the same value as 'meta_size' parameter used while creating the soring. If user created the soring with 'meta_size' value equals zero, then 'meta' parameter should be NULL. Otherwise the results are undefined.
n	The number of objects to add in the soring from the 'objs'.
free_space	if non-NULL, returns the amount of space in the soring after the enqueue operation has finished.

Returns

Actual number of objects enqueued.

◆ rte_soring_dequeue_bulk()

__rte_experimental uint32_t rte_soring_dequeue_bulk	(	struct rte_soring *	r,
		void *	objs,
		uint32_t	num,
		uint32_t *	available
	)

Warning: EXPERIMENTAL: this API may change without prior notice.

Dequeue several objects from the soring. Dequeues exactly requested number of objects or none.

Parameters

r	A pointer to the soring structure.
objs	A pointer to an array of objects to dequeue. Size of objects to enqueue must be the same value as 'elem_size' parameter used while creating the soring. Otherwise the results are undefined.
num	The number of objects to dequeue from the soring into the objs.
available	If non-NULL, returns the number of remaining soring entries after the dequeue has finished.

Returns

Actual number of objects dequeued, either 0 or 'num'.

◆ rte_soring_dequeux_bulk()

__rte_experimental uint32_t rte_soring_dequeux_bulk	(	struct rte_soring *	r,
		void *	objs,
		void *	meta,
		uint32_t	num,
		uint32_t *	available
	)

Warning: EXPERIMENTAL: this API may change without prior notice.

Dequeue several objects plus metadata from the soring. Dequeues exactly requested number of objects or none.

Parameters

r	A pointer to the soring structure.
objs	A pointer to an array of objects to dequeue. Size of objects to enqueue must be the same value as 'elem_size' parameter used while creating the soring. Otherwise the results are undefined.
meta	A pointer to array of metadata values for each object to dequeue. Note that if user not using object metadata values, then this parameter can be NULL. Size of elements in this array must be the same value as 'meta_size' parameter used while creating the soring. If user created the soring with 'meta_size' value equals zero, then 'meta' parameter should be NULL. Otherwise the results are undefined.
num	The number of objects to dequeue from the soring into the objs.
available	If non-NULL, returns the number of remaining soring entries after the dequeue has finished.

Returns

Actual number of objects dequeued, either 0 or 'num'.

◆ rte_soring_dequeue_burst()

__rte_experimental uint32_t rte_soring_dequeue_burst	(	struct rte_soring *	r,
		void *	objs,
		uint32_t	num,
		uint32_t *	available
	)

Warning: EXPERIMENTAL: this API may change without prior notice.

Dequeue several objects from the soring. Dequeues up to requested number of objects.

Parameters

r	A pointer to the soring structure.
objs	A pointer to an array of objects to dequeue. Size of objects to enqueue must be the same value as 'elem_size' parameter used while creating the soring. Otherwise the results are undefined.
num	The number of objects to dequeue from the soring into the objs.
available	If non-NULL, returns the number of remaining soring entries after the dequeue has finished.

Returns

Actual number of objects dequeued.

◆ rte_soring_dequeux_burst()

__rte_experimental uint32_t rte_soring_dequeux_burst	(	struct rte_soring *	r,
		void *	objs,
		void *	meta,
		uint32_t	num,
		uint32_t *	available
	)

Warning: EXPERIMENTAL: this API may change without prior notice.

Dequeue several objects plus metadata from the soring. Dequeues up to requested number of objects.

Parameters

r	A pointer to the soring structure.
objs	A pointer to an array of objects to dequeue. Size of objects to enqueue must be the same value as 'elem_size' parameter used while creating the soring. Otherwise the results are undefined.
meta	A pointer to array of metadata values for each object to dequeue. Note that if user not using object metadata values, then this parameter can be NULL. Size of elements in this array must be the same value as 'meta_size' parameter used while creating the soring. If user created the soring with 'meta_size' value equals zero, then 'meta' parameter should be NULL. Otherwise the results are undefined.
num	The number of objects to dequeue from the soring into the objs.
available	If non-NULL, returns the number of remaining soring entries after the dequeue has finished.

Returns

Actual number of objects dequeued.

◆ rte_soring_acquire_bulk()

__rte_experimental uint32_t rte_soring_acquire_bulk	(	struct rte_soring *	r,
		void *	objs,
		uint32_t	stage,
		uint32_t	num,
		uint32_t *	ftoken,
		uint32_t *	available
	)

Warning: EXPERIMENTAL: this API may change without prior notice.

Acquire several objects from the soring for given stage. Acquires exactly requested number of objects or none.

Parameters

r	A pointer to the soring structure.
objs	A pointer to an array of objects to acquire. Size of objects must be the same value as 'elem_size' parameter used while creating the soring. Otherwise the results are undefined.
stage	Stage to acquire objects for.
num	The number of objects to acquire.
ftoken	Pointer to the opaque 'token' value used by release() op. User has to store this value somewhere, and later provide to the release().
available	If non-NULL, returns the number of remaining soring entries for given stage after the acquire has finished.

Returns

Actual number of objects acquired, either 0 or 'num'.

◆ rte_soring_acquirx_bulk()

__rte_experimental uint32_t rte_soring_acquirx_bulk	(	struct rte_soring *	r,
		void *	objs,
		void *	meta,
		uint32_t	stage,
		uint32_t	num,
		uint32_t *	ftoken,
		uint32_t *	available
	)

Warning: EXPERIMENTAL: this API may change without prior notice.

Acquire several objects plus metadata from the soring for given stage. Acquires exactly requested number of objects or none.

Parameters

r	A pointer to the soring structure.
objs	A pointer to an array of objects to acquire. Size of objects must be the same value as 'elem_size' parameter used while creating the soring. Otherwise the results are undefined.
meta	A pointer to an array of metadata values for each for each acquired object. Note that if user not using object metadata values, then this parameter can be NULL. Size of elements in this array must be the same value as 'meta_size' parameter used while creating the soring. If user created the soring with 'meta_size' value equals zero, then 'meta' parameter should be NULL. Otherwise the results are undefined.
stage	Stage to acquire objects for.
num	The number of objects to acquire.
ftoken	Pointer to the opaque 'token' value used by release() op. User has to store this value somewhere, and later provide to the release().
available	If non-NULL, returns the number of remaining soring entries for given stage after the acquire has finished.

Returns

Actual number of objects acquired, either 0 or 'num'.

◆ rte_soring_acquire_burst()

__rte_experimental uint32_t rte_soring_acquire_burst	(	struct rte_soring *	r,
		void *	objs,
		uint32_t	stage,
		uint32_t	num,
		uint32_t *	ftoken,
		uint32_t *	available
	)

Warning: EXPERIMENTAL: this API may change without prior notice.

Acquire several objects from the soring for given stage. Acquires up to requested number of objects.

Parameters

r	A pointer to the soring structure.
objs	A pointer to an array of objects to acquire. Size of objects must be the same value as 'elem_size' parameter used while creating the soring. Otherwise the results are undefined.
stage	Stage to acquire objects for.
num	The number of objects to acquire.
ftoken	Pointer to the opaque 'token' value used by release() op. User has to store this value somewhere, and later provide to the release().
available	If non-NULL, returns the number of remaining soring entries for given stage after the acquire has finished.

Returns

Actual number of objects acquired.

◆ rte_soring_acquirx_burst()

__rte_experimental uint32_t rte_soring_acquirx_burst	(	struct rte_soring *	r,
		void *	objs,
		void *	meta,
		uint32_t	stage,
		uint32_t	num,
		uint32_t *	ftoken,
		uint32_t *	available
	)

Warning: EXPERIMENTAL: this API may change without prior notice.

Acquire several objects plus metadata from the soring for given stage. Acquires up to requested number of objects.

Parameters

r	A pointer to the soring structure.
objs	A pointer to an array of objects to acquire. Size of objects must be the same value as 'elem_size' parameter used while creating the soring. Otherwise the results are undefined.
meta	A pointer to an array of metadata values for each for each acquired object. Note that if user not using object metadata values, then this parameter can be NULL. Size of elements in this array must be the same value as 'meta_size' parameter used while creating the soring. If user created the soring with 'meta_size' value equals zero, then 'meta' parameter should be NULL. Otherwise the results are undefined.
stage	Stage to acquire objects for.
num	The number of objects to acquire.
ftoken	Pointer to the opaque 'token' value used by release() op. User has to store this value somewhere, and later provide to the release().
available	If non-NULL, returns the number of remaining soring entries for given stage after the acquire has finished.

Returns

Actual number of objects acquired.

◆ rte_soring_release()

__rte_experimental void rte_soring_release	(	struct rte_soring *	r,
		const void *	objs,
		uint32_t	stage,
		uint32_t	n,
		uint32_t	ftoken
	)

Warning: EXPERIMENTAL: this API may change without prior notice.

Release several objects for given stage back to the soring. Note that it means these objects become available for next stage or dequeue.

Parameters

r	A pointer to the soring structure.
objs	A pointer to an array of objects to release. Note that unless user needs to overwrite soring objects this parameter can be NULL. Size of objects must be the same value as 'elem_size' parameter used while creating the soring. Otherwise the results are undefined.
stage	Current stage.
n	The number of objects to release. Has to be the same value as returned by acquire() op.
ftoken	Opaque 'token' value obtained from acquire() op.

◆ rte_soring_releasx()

__rte_experimental void rte_soring_releasx	(	struct rte_soring *	r,
		const void *	objs,
		const void *	meta,
		uint32_t	stage,
		uint32_t	n,
		uint32_t	ftoken
	)

Warning: EXPERIMENTAL: this API may change without prior notice.

Release several objects plus metadata for given stage back to the soring. Note that it means these objects become available for next stage or dequeue.

Parameters

r	A pointer to the soring structure.
objs	A pointer to an array of objects to release. Note that unless user needs to overwrite soring objects this parameter can be NULL. Size of objects must be the same value as 'elem_size' parameter used while creating the soring. Otherwise the results are undefined.
meta	A pointer to an array of metadata values for each object to release. Note that if user not using object metadata values, then this parameter can be NULL. Size of elements in this array must be the same value as 'meta_size' parameter used while creating the soring. If user created the soring with 'meta_size' value equals zero, then meta parameter should be NULL. Otherwise the results are undefined.
stage	Current stage.
n	The number of objects to release. Has to be the same value as returned by acquire() op.
ftoken	Opaque 'token' value obtained from acquire() op.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ RTE_SORING_ST_BIT

◆ RTE_SORING_ELEM_MAX

Function Documentation

◆ rte_soring_get_memsize()

◆ rte_soring_init()

◆ rte_soring_count()

◆ rte_soring_free_count()

◆ rte_soring_dump()

◆ rte_soring_enqueue_bulk()

◆ rte_soring_enqueux_bulk()

◆ rte_soring_enqueue_burst()

◆ rte_soring_enqueux_burst()

◆ rte_soring_dequeue_bulk()

◆ rte_soring_dequeux_bulk()

◆ rte_soring_dequeue_burst()

◆ rte_soring_dequeux_burst()

◆ rte_soring_acquire_bulk()

◆ rte_soring_acquirx_bulk()

◆ rte_soring_acquire_burst()

◆ rte_soring_acquirx_burst()

◆ rte_soring_release()

◆ rte_soring_releasx()