Provided by: dpdk-doc_25.11-2_all 
NAME
rte_soring.h
SYNOPSIS
#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
#define RTE_SORING_ST_BIT 30
upper 2 bits are used for status
Definition at line 33 of file rte_soring.h.
#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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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.
Author
Generated automatically by Doxygen for DPDK from the source code.
DPDK Version 25.11.0 rte_soring.h(3)