ODP QUEUE

API Description

Queues for event passing and scheduling.

Data Structures
struct	odp_queue_capability_t
	Queue capabilities. More...
struct	odp_queue_param_t
	ODP Queue parameters. More...
struct	odp_queue_info_t
	Queue information Retrieve information about a queue with odp_queue_info() More...

Macros
#define	ODP_QUEUE_INVALID   ((odp_queue_t)0)
	Invalid queue.
#define	ODP_QUEUE_NAME_LEN   32
	Maximum queue name length, including the null character.

Typedefs
typedef _odp_abi_queue_t *	odp_queue_t
	ODP queue.
typedef enum odp_queue_type_t	odp_queue_type_t
	Queue type.
typedef enum odp_queue_op_mode_t	odp_queue_op_mode_t
	Queue operation mode.
typedef enum odp_nonblocking_t	odp_nonblocking_t
	Non-blocking level. More...
typedef enum odp_queue_order_t	odp_queue_order_t
	Original event order maintenance options. More...
typedef struct odp_queue_capability_t	odp_queue_capability_t
	Queue capabilities.
typedef struct odp_queue_param_t	odp_queue_param_t
	ODP Queue parameters.
typedef struct odp_queue_info_t	odp_queue_info_t
	Queue information Retrieve information about a queue with odp_queue_info()

Enumerations
enum	odp_queue_type_t { ODP_QUEUE_TYPE_PLAIN = 0 , ODP_QUEUE_TYPE_SCHED }
	Queue type. More...
enum	odp_queue_op_mode_t { ODP_QUEUE_OP_MT = 0 , ODP_QUEUE_OP_MT_UNSAFE , ODP_QUEUE_OP_DISABLED }
	Queue operation mode. More...
enum	odp_nonblocking_t { ODP_BLOCKING = 0 , ODP_NONBLOCKING_LF , ODP_NONBLOCKING_WF }
	Non-blocking level. More...
enum	odp_queue_order_t { ODP_QUEUE_ORDER_KEEP = 0 , ODP_QUEUE_ORDER_IGNORE }
	Original event order maintenance options. More...

Functions
odp_queue_t	odp_queue_create (const char *name, const odp_queue_param_t *param)
	Queue create. More...
int	odp_queue_create_multi (const char *name[], const odp_queue_param_t param[], odp_bool_t share_param, odp_queue_t queue[], int num)
	Create multiple queues. More...
int	odp_queue_destroy (odp_queue_t queue)
	Destroy ODP queue. More...
int	odp_queue_destroy_multi (odp_queue_t queue[], int num)
	Destroy multiple queues. More...
odp_queue_t	odp_queue_lookup (const char *name)
	Find a queue by name. More...
int	odp_queue_capability (odp_queue_capability_t *capa)
	Query queue capabilities. More...
int	odp_queue_context_set (odp_queue_t queue, void *context, uint32_t len)
	Set queue context. More...
void *	odp_queue_context (odp_queue_t queue)
	Get queue context. More...
int	odp_queue_enq (odp_queue_t queue, odp_event_t ev)
	Enqueue an event to a queue. More...
int	odp_queue_enq_multi (odp_queue_t queue, const odp_event_t events[], int num)
	Enqueue multiple events to a queue. More...
odp_event_t	odp_queue_deq (odp_queue_t queue)
	Dequeue an event from a queue. More...
int	odp_queue_deq_multi (odp_queue_t queue, odp_event_t events[], int num)
	Dequeue multiple events from a queue. More...
odp_queue_type_t	odp_queue_type (odp_queue_t queue)
	Queue type. More...
odp_schedule_sync_t	odp_queue_sched_type (odp_queue_t queue)
	Queue schedule type. More...
odp_schedule_prio_t	odp_queue_sched_prio (odp_queue_t queue)
	Queue priority. More...
odp_schedule_group_t	odp_queue_sched_group (odp_queue_t queue)
	Queue group. More...
uint32_t	odp_queue_lock_count (odp_queue_t queue)
	Queue lock count. More...
uint64_t	odp_queue_to_u64 (odp_queue_t hdl)
	Get printable value for an odp_queue_t. More...
void	odp_queue_param_init (odp_queue_param_t *param)
	Initialize queue params. More...
int	odp_queue_info (odp_queue_t queue, odp_queue_info_t *info)
	Retrieve information about a queue. More...
void	odp_queue_print (odp_queue_t queue)
	Print queue info. More...
void	odp_queue_print_all (void)
	Print debug info about all queues. More...

Typedef Documentation

odp_nonblocking_t

typedef enum odp_nonblocking_t odp_nonblocking_t

Non-blocking level.

A non-blocking level defines implementation guarantees for application progress when multiple threads operate on the same resource (e.g. a queue) simultaneously. The first level (ODP_BLOCKING) does not have any block freedom guarantees, but a suspending thread may block the other threads for the entire time it remains suspended (infinitely if crashed). On the contrary, actual non-blocking levels provide guarantees of progress:

ODP_NONBLOCKING_LF: A non-blocking and lock-free implementation guarantees that at least one of the threads successfully completes its operations, regardless of what other threads do. Application progress is guaranteed, but individual threads may starve while trying to execute their operations on the shared resource.

ODP_NONBLOCKING_WF: A non-blocking and wait-free implementation guarantees application progress with starvation freedom. All threads are guaranteed to complete their operations in a bounded number of steps, regardless of what other threads do.

Non-blocking levels are listed from the weakest to the strongest guarantee of block freedom. Performance of a non-blocking implementation may be lower than the blocking one. Non-blocking guarantees are important e.g. for real-time applications when real-time and non real-time threads share a resource.

odp_queue_order_t

typedef enum odp_queue_order_t odp_queue_order_t

Original event order maintenance options.

Options to keep or ignore the original event order of a source queue. This option is relevant for (plain or parallel scheduled) queues that are destinations for events enqueued while holding an ordered queue synchronization context. By default, an ordered context maintains original event order regardless of the destination queue type. Event re-ordering may cause extra synchronization effort for implementation and a long delay before application can receive a re-ordered event from the destination queue. This is wasteful and in some cases the extra delay is not acceptable for those destination queues that do not need to maintain the original event order. Application can use ODP_QUEUE_ORDER_IGNORE option to prevent implementation from performing unnecessary event re-ordering and negative side-effects of that.

Enumeration Type Documentation

odp_queue_type_t

enum odp_queue_type_t

Queue type.

Enumerator
ODP_QUEUE_TYPE_PLAIN	Plain queue. Plain queues offer simple FIFO storage of events. Application may dequeue directly from these queues.
ODP_QUEUE_TYPE_SCHED	Scheduled queue. Scheduled queues are connected to the scheduler. Application must not dequeue events directly from these queues but use the scheduler instead.

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

odp_queue_op_mode_t

enum odp_queue_op_mode_t

Queue operation mode.

Enumerator
ODP_QUEUE_OP_MT	Multithread safe operation. Queue operation (enqueue or dequeue) is multithread safe. Any number of application threads may perform the operation concurrently.
ODP_QUEUE_OP_MT_UNSAFE	Not multithread safe operation. Queue operation (enqueue or dequeue) may not be multithread safe. Application ensures synchronization between threads so that simultaneously only single thread attempts the operation on the same queue.
ODP_QUEUE_OP_DISABLED	Disabled. Direct enqueue or dequeue operation from application is disabled. An attempt to enqueue/dequeue directly will result undefined behaviour. Various ODP functions (e.g. packet input, timer, crypto, scheduler, etc) are able to perform enqueue or dequeue operations normally on the queue.

Definition at line 61 of file api/spec/queue_types.h.

odp_nonblocking_t

enum odp_nonblocking_t

Non-blocking level.

A non-blocking level defines implementation guarantees for application progress when multiple threads operate on the same resource (e.g. a queue) simultaneously. The first level (ODP_BLOCKING) does not have any block freedom guarantees, but a suspending thread may block the other threads for the entire time it remains suspended (infinitely if crashed). On the contrary, actual non-blocking levels provide guarantees of progress:

ODP_NONBLOCKING_LF: A non-blocking and lock-free implementation guarantees that at least one of the threads successfully completes its operations, regardless of what other threads do. Application progress is guaranteed, but individual threads may starve while trying to execute their operations on the shared resource.

ODP_NONBLOCKING_WF: A non-blocking and wait-free implementation guarantees application progress with starvation freedom. All threads are guaranteed to complete their operations in a bounded number of steps, regardless of what other threads do.

Non-blocking levels are listed from the weakest to the strongest guarantee of block freedom. Performance of a non-blocking implementation may be lower than the blocking one. Non-blocking guarantees are important e.g. for real-time applications when real-time and non real-time threads share a resource.

Enumerator
ODP_BLOCKING	Blocking implementation. A suspeding thread may block all other threads, i.e. no block freedom guarantees. This is the lowest level.
ODP_NONBLOCKING_LF	Non-blocking and lock-free implementation. Other threads can make progress while a thread is suspended. Starvation freedom is not guaranteed.
ODP_NONBLOCKING_WF	Non-blocking and wait-free implementation. Other threads can make progress while a thread is suspended. Starvation freedom is guaranteed.

Definition at line 117 of file api/spec/queue_types.h.

odp_queue_order_t

enum odp_queue_order_t

Original event order maintenance options.

Options to keep or ignore the original event order of a source queue. This option is relevant for (plain or parallel scheduled) queues that are destinations for events enqueued while holding an ordered queue synchronization context. By default, an ordered context maintains original event order regardless of the destination queue type. Event re-ordering may cause extra synchronization effort for implementation and a long delay before application can receive a re-ordered event from the destination queue. This is wasteful and in some cases the extra delay is not acceptable for those destination queues that do not need to maintain the original event order. Application can use ODP_QUEUE_ORDER_IGNORE option to prevent implementation from performing unnecessary event re-ordering and negative side-effects of that.

Enumerator
ODP_QUEUE_ORDER_KEEP	Keep original event order. Events enqueued into this queue while holding an ordered queue synchronization context maintain the original event order of the source queue.
ODP_QUEUE_ORDER_IGNORE	Ignore original event order. Events enqueued into this queue do not need to maintain the original event order of the source queue. Implementation must avoid significant event re-ordering delays.

Definition at line 153 of file api/spec/queue_types.h.

Function Documentation

odp_queue_create()

odp_queue_t odp_queue_create	(	const char *	name,
		const odp_queue_param_t *	param
	)

Queue create.

Create a queue according to the queue parameters. The use of queue name is optional. Unique names are not required. However, odp_queue_lookup() returns only a single matching queue. Use odp_queue_param_init() to initialize parameters into their default values. Default values are also used when 'param' pointer is NULL.

Parameters

name	Name of the queue or NULL. Maximum string length is ODP_QUEUE_NAME_LEN, including the null character.
param	Queue parameters. Uses defaults if NULL.

Returns

Queue handle

Return values

ODP_QUEUE_INVALID

on failure

Examples

ipsec_api/odp_ipsec.c, ipsec_crypto/odp_ipsec.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_pktio_ordered.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_timer_accuracy.c, odp_timer_perf.c, and odp_timer_simple.c.

odp_queue_create_multi()

int odp_queue_create_multi	(	const char *	name[],
		const odp_queue_param_t	param[],
		odp_bool_t	share_param,
		odp_queue_t	queue[],
		int	num
	)

Create multiple queues.

Otherwise like odp_queue_create(), but creates multiple queues with a single call. The output queue handles are written in the same order as input parameters. A single odp_queue_create_multi() call is equivalent to calling odp_queue_create() 'num' times in row.

If 'share_param' value is false, 'param' array must contain 'num' elements. If the value is true, only a single element is required and it's used as queue parameters for all created queues. If 'name' array is not NULL, the array must contain 'num' elements.

Parameters

	name	Array of queue name pointers or NULL. NULL is also valid queue name pointer value.
	param	Array of queue parameters
	share_param	If true, use same parameters ('param[0]') for all queues.
[out]	queue	Array of queue handles for output
	num	Number of queues to create

Returns

Number of queues actually created (0 ... num)

Return values

<0	on failure

odp_queue_destroy()

int odp_queue_destroy

(

odp_queue_t

queue

)

Destroy ODP queue.

Destroys ODP queue. The queue must be empty and detached from other ODP API (crypto, pktio, classifier, timer, etc). Application must ensure that no other operations on this queue are invoked in parallel. Otherwise behavior is undefined.

Parameters

queue

Queue handle

Return values

0	on success
<0	on failure

Examples

ipsec_api/odp_ipsec.c, ipsec_crypto/odp_ipsec.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_pktio_ordered.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_timer_accuracy.c, odp_timer_perf.c, and odp_timer_simple.c.

odp_queue_destroy_multi()

int odp_queue_destroy_multi	(	odp_queue_t	queue[],
		int	num
	)

Destroy multiple queues.

Otherwise like odp_queue_destroy(), but destroys multiple queues with a single call.

Parameters

queue	Array of queue handles
num	Number of queues to destroy

Return values

Number	of queues actually destroyed (1 ... num)
<0	on failure

odp_queue_lookup()

odp_queue_t odp_queue_lookup

(

const char *

name

)

Find a queue by name.

Parameters

name	Queue name

Returns

Handle of the first matching queue

Return values

ODP_QUEUE_INVALID

on failure

Examples

odp_crypto.c, and odp_ipsec.c.

odp_queue_capability()

int odp_queue_capability

(

odp_queue_capability_t *

capa

)

Query queue capabilities.

Outputs queue capabilities on success.

Parameters

[out]

capa

Pointer to capability structure for output

Return values

0	on success
<0	on failure

Examples

odp_queue_perf.c, odp_simple_pipeline.c, and odp_sysinfo.c.

odp_queue_context_set()

int odp_queue_context_set	(	odp_queue_t	queue,
		void *	context,
		uint32_t	len
	)

Set queue context.

It is the responsibility of the user to ensure that the queue context is stored in a location accessible by all threads that attempt to access it.

Parameters

queue	Queue handle
context	Address to the queue context
len	Queue context data length in bytes

Return values

0	on success
<0	on failure

Examples

odp_pktio_ordered.c, odp_sched_perf.c, and odp_sched_pktio.c.

odp_queue_context()

void* odp_queue_context

(

odp_queue_t

queue

)

Get queue context.

Returns previously stored queue context pointer. The context pointer may be set with odp_queue_context_set() or during queue creation (see odp_queue_param_t). The pointer value is set to NULL by default.

Parameters

queue

Queue handle

Returns

pointer to the queue context

Return values

NULL	on failure

See also

odp_queue_context_set(), odp_queue_create()

Examples

odp_pktio_ordered.c, odp_sched_perf.c, and odp_sched_pktio.c.

odp_queue_enq()

int odp_queue_enq	(	odp_queue_t	queue,
		odp_event_t	ev
	)

Enqueue an event to a queue.

Enqueues the event into the queue. The caller loses ownership of the event on a successful call. The event is not enqueued on failure, and the caller maintains ownership of it.

When successful, this function acts as a release memory barrier between the sender (the calling thread) and the receiver of the event. The receiver sees correctly the memory stores done by the sender before it enqueued the event.

Parameters

queue	Queue handle
ev	Event handle

Return values

0	on success
<0	on failure

Examples

ipsec_crypto/odp_ipsec.c, odp_cpu_bench.c, odp_ipfragreass.c, odp_pktio_ordered.c, odp_queue_perf.c, odp_sched_latency.c, odp_sched_perf.c, odp_sched_pktio.c, and odp_stress.c.

odp_queue_enq_multi()

int odp_queue_enq_multi	(	odp_queue_t	queue,
		const odp_event_t	events[],
		int	num
	)

Enqueue multiple events to a queue.

Like odp_queue_enq(), but enqueues multiple events into the queue. Events are stored into the queue in the order they are in the array. A successful call returns the actual number of events enqueued. If return value is less than 'num', the remaining events at the end of events[] are not enqueued, and the caller maintains ownership of those.

Parameters

queue	Queue handle
events	Array of event handles
num	Number of events to enqueue

Returns

Number of events actually enqueued (0 ... num)

Return values

<0	on failure

Examples

odp_ipsecfwd.c, odp_l2fwd.c, odp_queue_perf.c, odp_sched_latency.c, odp_sched_perf.c, odp_sched_pktio.c, and odp_simple_pipeline.c.

odp_queue_deq()

odp_event_t odp_queue_deq

(

odp_queue_t

queue

)

Dequeue an event from a queue.

Returns the next event from head of the queue, or ODP_EVENT_INVALID when the queue is empty. Cannot be used for ODP_QUEUE_TYPE_SCHED type queues (use odp_schedule() instead).

When successful, this function acts as an acquire memory barrier between the sender and the receiver (the calling thread) of the event. The receiver sees correctly the memory stores done by the sender before it enqueued the event.

Parameters

queue

Queue handle

Returns

Event handle

Return values

ODP_EVENT_INVALID

on failure, or when the queue is empty

Examples

ipsec_api/odp_ipsec.c, ipsec_crypto/odp_ipsec.c, odp_bench_timer.c, odp_crypto.c, odp_ipfragreass.c, odp_ipsec.c, odp_l2fwd.c, odp_pktio.c, odp_pktio_perf.c, and odp_queue_perf.c.

odp_queue_deq_multi()

int odp_queue_deq_multi	(	odp_queue_t	queue,
		odp_event_t	events[],
		int	num
	)

Dequeue multiple events from a queue.

Like odp_queue_deq(), but dequeues multiple events from head of the queue. Cannot be used for ODP_QUEUE_TYPE_SCHED type queues (use odp_schedule_multi() instead). A successful call returns the actual number of events dequeued.

Parameters

	queue	Queue handle
[out]	events	Array of event handles for output
	num	Maximum number of events to dequeue

Returns

Number of events actually dequeued (0 ... num)

Return values

<0	on failure

Examples

odp_ipsec.c, odp_l2fwd.c, odp_pktio_perf.c, odp_queue_perf.c, and odp_simple_pipeline.c.

odp_queue_type()

odp_queue_type_t odp_queue_type

(

odp_queue_t

queue

)

Queue type.

Parameters

queue

Queue handle

Returns

Queue type

Examples

odp_pktio_perf.c.

odp_queue_sched_type()

odp_schedule_sync_t odp_queue_sched_type

(

odp_queue_t

queue

)

Queue schedule type.

Parameters

queue

Queue handle

Returns

Queue schedule synchronization type

odp_queue_sched_prio()

odp_schedule_prio_t odp_queue_sched_prio

(

odp_queue_t

queue

)

Queue priority.

Note

Passing an invalid queue_handle will result in UNDEFINED behavior

Parameters

queue

Queue handle

Returns

Queue schedule priority

odp_queue_sched_group()

odp_schedule_group_t odp_queue_sched_group

(

odp_queue_t

queue

)

Queue group.

Note

Passing an invalid queue_handle will result in UNDEFINED behavior

Parameters

queue

Queue handle

Returns

Queue schedule group

odp_queue_lock_count()

uint32_t odp_queue_lock_count

(

odp_queue_t

queue

)

Queue lock count.

Return number of ordered locks associated with this ordered queue. Lock count is defined in odp_schedule_param_t.

Parameters

queue

Queue handle

Returns

Number of ordered locks associated with this ordered queue

Return values

0	Specified queue is not ordered or no ordered lock associated with the ordered queue.

odp_queue_to_u64()

uint64_t odp_queue_to_u64

(

odp_queue_t

hdl

)

Get printable value for an odp_queue_t.

Parameters

hdl	odp_queue_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_queue_t handle.

Examples

ipsec_api/odp_ipsec.c, ipsec_crypto/odp_ipsec.c, and odp_sched_latency.c.

odp_queue_param_init()

void odp_queue_param_init

(

odp_queue_param_t *

param

)

Initialize queue params.

Initialize an odp_queue_param_t to its default values for all fields. Also the schedule parameters are set to defaults, although the default queue type is ODP_QUEUE_TYPE_PLAIN.

Parameters

param

Address of the odp_queue_param_t to be initialized

Examples

ipsec_api/odp_ipsec.c, ipsec_crypto/odp_ipsec.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_pktio_ordered.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_timer_accuracy.c, odp_timer_perf.c, and odp_timer_simple.c.

odp_queue_info()

int odp_queue_info	(	odp_queue_t	queue,
		odp_queue_info_t *	info
	)

Retrieve information about a queue.

Invalid queue handles or handles to free/destroyed queues leads to undefined behaviour. Not intended for fast path use.

Parameters

	queue	Queue handle
[out]	info	Queue info pointer for output

Return values

0	Success
<0	Failure. Info could not be retrieved.

Examples

odp_classifier.c.

odp_queue_print()

void odp_queue_print

(

odp_queue_t

queue

)

Print queue info.

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

Parameters

queue

Queue handle

Examples

odp_debug.c.

odp_queue_print_all()

void odp_queue_print_all

(

void

)

Print debug info about all queues.

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

Examples

odp_debug.c, and odp_sched_perf.c.