API Description

ODP instance initialization and termination.

Data Structures
struct	odp_init_t
	Global initialization parameters. More...

Macros
#define	ODP_STATIC_ASSERT(cond, msg) _Static_assert(cond, msg)
	Compile time assertion macro. More...

#define	ODP_TERM_FROM_SIGH ((uint64_t)0x1)
	Called from signal handler.

#define	ODP_TERM_LAST_FLAG ODP_TERM_FROM_SIGH
	Last standard flag for abnormal terminate. More...

Typedefs
typedef int(*	odp_log_func_t) (odp_log_level_t level, const char *fmt,...) ODP_PRINTF_FORMAT(2
	Replaceable logging function.

typedef int() typedef void(	odp_abort_func_t) (void) ODP_NORETURN
	Replaceable abort function.

typedef struct odp_init_t	odp_init_t
	Global initialization parameters. More...

typedef uint64_t	odp_instance_t
	ODP instance ID.

typedef struct odp_platform_init_t	odp_platform_init_t
	ODP platform initialization data. More...

Enumerations
enum	odp_log_level_t { ODP_LOG_DBG , ODP_LOG_WARN , ODP_LOG_ERR , ODP_LOG_UNIMPLEMENTED , ODP_LOG_ABORT , ODP_LOG_PRINT }
	ODP log level. More...

enum	odp_mem_model_t { ODP_MEM_MODEL_THREAD = 0 , ODP_MEM_MODEL_PROCESS }
	Application memory model. More...

Functions
int	odp_override_log (odp_log_level_t level, const char *fmt,...) ODP_PRINTF_FORMAT(2
	ODP log function. More...

int void	odp_override_abort (void) ODP_NORETURN
	ODP abort function. More...

void	odp_init_param_init (odp_init_t *param)
	Initialize the odp_init_t to default values for all fields. More...

int	odp_init_global (odp_instance_t instance, const odp_init_t params, const odp_platform_init_t *platform_params)
	Global ODP initialization. More...

int	odp_init_local (odp_instance_t instance, odp_thread_type_t thr_type)
	Thread local ODP initialization. More...

int	odp_term_local (void)
	Thread local ODP termination. More...

int	odp_term_global (odp_instance_t instance)
	Global ODP termination. More...

int	odp_term_abnormal (odp_instance_t instance, uint64_t flags, void *data)
	Abnormal ODP termination after a non-recoverable error. More...

void	odp_log_thread_fn_set (odp_log_func_t func)
	Set thread specific log function. More...

odp_log_func_t	odp_log_fn_get (void)
	Get current log function. More...

odp_abort_func_t	odp_abort_fn_get (void)
	Get abort function. More...

int	odp_instance (odp_instance_t *instance)
	Get instance handle. More...

uint64_t	odp_instance_to_u64 (odp_instance_t instance)
	Get printable value for ODP instance handle. More...

Macro Definition Documentation

◆ ODP_STATIC_ASSERT

#define ODP_STATIC_ASSERT	(	cond,
		msg
	)	_Static_assert(cond, msg)

Compile time assertion macro.

Compile time assertion macro. Fails compilation and outputs 'msg' if condition 'cond' is false. Macro definition is empty when compiler is not supported or the compiler does not support static assertion.

Fails compilation and outputs message 'msg' if condition 'cond' is false. Macro definition is empty when the compiler is not supported or the compiler does not support static assertion.

Parameters

cond	Conditional expression to be evaluated at compile time
msg	Compile time error message to be displayed if cond is false

Examples: odp_atomic_perf.c, odp_bench_buffer.c, odp_bench_misc.c, odp_bench_packet.c, odp_bench_pktio_sp.c, odp_bench_timer.c, odp_cpu_bench.c, odp_dmafwd.c, odp_lock_perf.c, odp_packet_gen.c, odp_ping.c, odp_pktio_ordered.c, odp_pool_latency.c, and odp_sysinfo.c.

◆ ODP_TERM_LAST_FLAG

#define ODP_TERM_LAST_FLAG ODP_TERM_FROM_SIGH

Last standard flag for abnormal terminate.

An implementation may use this for adding its own flags after the standard flags.

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

Typedef Documentation

◆ odp_init_t

typedef struct odp_init_t odp_init_t

Global initialization parameters.

These parameters may be used at global initialization time to configure and optimize ODP implementation to match the intended usage. Application specifies maximum resource usage. Implementation may round up resource reservations as needed. Initialization function returns a failure if resource requirements are too high. Init parameters may be used also to override logging and abort functions.

Use odp_init_param_init() to initialize the parameters into their default values. Unused parameters are left to default values.

◆ odp_platform_init_t

odp_platform_init_t

ODP platform initialization data.

platform specific data

Note: ODP API does nothing with this data. It is the underlying implementation that requires it and any data passed here is not portable. It is required that the application takes care of identifying and passing any required platform specific data.

Enumeration Type Documentation

◆ odp_log_level_t

enum odp_log_level_t

ODP log level.

Enumerator
ODP_LOG_DBG	Debug.
ODP_LOG_WARN	Warning.
ODP_LOG_ERR	Error.
ODP_LOG_UNIMPLEMENTED	Unimplemented.
ODP_LOG_ABORT	Abort.
ODP_LOG_PRINT	Print.

Definition at line 48 of file api/spec/init.h.

◆ odp_mem_model_t

enum odp_mem_model_t

Application memory model.

Enumerator

ODP_MEM_MODEL_THREAD

Thread memory model: by default all memory is shareable between threads.

Within a single ODP instance all ODP handles and pointers to ODP allocated data may be shared amongst threads independent of data allocation time (e.g. before or after thread creation).

ODP_MEM_MODEL_PROCESS

Process memory model: by default all memory is not shareable between processes.

Within a single ODP instance all ODP handles and pointers to ODP allocated data (excluding non-single VA SHM blocks) may be shared amongst processes independent of data allocation time (e.g. before or after fork).

See also: ODP_SHM_SINGLE_VA

Definition at line 125 of file api/spec/init.h.

Function Documentation

◆ odp_override_log()

int odp_override_log	(	odp_log_level_t	level,
		const char *	fmt,
			...
	)

ODP log function.

Instead of direct prints to stdout/stderr all logging in an ODP implementation should be done via this function or its wrappers.

The application can provide this function to the ODP implementation in two ways:

A callback passed in via in odp_init_t and odp_init_global()
By overriding the ODP implementation default log function odp_override_log().

Warning: The latter option is less portable and GNU linker dependent (utilizes function attribute "weak"). If both are defined, the odp_init_t function pointer has priority over the override function.

Parameters

level	Log level
fmt	printf-style message format

Returns: The number of characters logged on success

Return values

<0	on failure

Examples: odp_traffic_mgmt.c.

◆ odp_override_abort()

int void odp_override_abort ( void )

ODP abort function.

Instead of directly calling abort, all abort calls in the implementation should be done via this function or its wrappers.

The application can provide this function to the ODP implementation in two ways:

A callback passed in via odp_init_t and odp_init_global()
By overriding the ODP implementation default abort function odp_override_abort().

The latter option is less portable and GNU linker dependent (utilizes function attribute "weak"). If both are defined, the odp_init_t function pointer has priority over the override function.

Note that no ODP calls should be called in the abort function and the function should not return.

Examples: odp_traffic_mgmt.c.

◆ odp_init_param_init()

void odp_init_param_init ( odp_init_t * param )

Initialize the odp_init_t to default values for all fields.

Parameters

[out] param Address of the odp_init_t to be initialized

◆ odp_init_global()

int odp_init_global	(	odp_instance_t *	instance,
		const odp_init_t *	params,
		const odp_platform_init_t *	platform_params
	)

Global ODP initialization.

An ODP instance is created with an odp_init_global() call. By default, each thread of the instance must call odp_init_local() before calling any other ODP API functions. Exceptions to this are functions that are needed for setting up parameters for odp_init_global() and odp_init_local() calls, and some other functions that may be convenient before initialization.

odp_init_param_init()
odp_cpumask_zero(), odp_cpumask_set(), etc functions to format odp_cpumask_t. However, these cpumask functions are excluded as their behaviour depend on global initialization parameters: odp_cpumask_default_worker(), odp_cpumask_default_control() and odp_cpumask_all_available()
odp_log_fn_get()
odp_abort_fn_get()

A successful odp_init_global() call outputs a handle for the new instance. The handle is used in other initialization and termination calls. For a graceful termination, odp_term_local() must be called first on each thread and then odp_term_global() only once.

When user provides configuration parameters, the platform may configure and optimize the instance to match user requirements. A failure is returned if requirements cannot be met.

Configuration parameters are divided into standard and platform specific parts. Standard parameters are supported by any ODP platform, where as platform specific parameters are defined outside of the ODP API specification. In addition to 'platform_params' there may be other platform specific configuration options available (e.g. environmental variables or a configuration file), but when the application passes 'platform_params', it should always supersede any other configuration method.

Parameters

[out]	instance	Instance handle pointer for output
	params	Standard configuration parameters for the instance. Use NULL to set all parameters to their defaults.
	platform_params	Platform specific configuration parameters. The definition and usage is platform specific. Use NULL to set all parameters to their defaults.

Return values

0	on success
<0	on failure

See also: odp_init_local(), odp_term_global(), odp_init_param_init()

Examples: ipsec_api/odp_ipsec.c, ipsec_crypto/odp_ipsec.c, odp_atomic_perf.c, odp_bench_buffer.c, odp_bench_misc.c, odp_bench_packet.c, odp_bench_pktio_sp.c, odp_bench_timer.c, odp_classifier.c, odp_cli.c, odp_cpu_bench.c, odp_crc.c, odp_crypto.c, odp_debug.c, odp_dma_perf.c, odp_dmafwd.c, odp_hello.c, odp_icache_perf.c, odp_ipfragreass.c, odp_ipsec.c, odp_ipsecfwd.c, odp_l2fwd.c, odp_l2fwd_perf.c, odp_l3fwd.c, odp_lock_perf.c, odp_mem_perf.c, odp_ml_perf.c, odp_ml_run.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_random.c, odp_sched_latency.c, odp_sched_perf.c, odp_sched_pktio.c, odp_simple_pipeline.c, odp_stash_perf.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_init_local()

int odp_init_local	(	odp_instance_t	instance,
		odp_thread_type_t	thr_type
	)

Thread local ODP initialization.

All threads must call this function before calling any other ODP API functions. See odp_init_global() documentation for exceptions to this rule. Global initialization (odp_init_global()) must have completed prior calling this function.

The instance parameter specifies which ODP instance the thread joins. A thread may only join a single ODP instance at a time. The thread type parameter indicates if the thread does most part of application processing (ODP_THREAD_WORKER), or if it performs mostly background tasks (ODP_THREAD_CONTROL).

Parameters

instance	Instance handle
thr_type	Thread type

Return values

0	on success
<0	on failure

See also: odp_init_global(), odp_term_local()

Examples: ipsec_api/odp_ipsec.c, ipsec_crypto/odp_ipsec.c, odp_atomic_perf.c, odp_bench_buffer.c, odp_bench_misc.c, odp_bench_packet.c, odp_bench_pktio_sp.c, odp_bench_timer.c, odp_classifier.c, odp_cli.c, odp_cpu_bench.c, odp_crc.c, odp_crypto.c, odp_debug.c, odp_dma_perf.c, odp_dmafwd.c, odp_hello.c, odp_icache_perf.c, odp_ipfragreass.c, odp_ipsec.c, odp_ipsecfwd.c, odp_l2fwd.c, odp_l2fwd_perf.c, odp_l3fwd.c, odp_lock_perf.c, odp_mem_perf.c, odp_ml_perf.c, odp_ml_run.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_random.c, odp_sched_latency.c, odp_sched_perf.c, odp_sched_pktio.c, odp_simple_pipeline.c, odp_stash_perf.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_term_local()

int odp_term_local ( void )

Thread local ODP termination.

This function is the second to final ODP call made when terminating an ODP application in a controlled way. It cannot handle exceptional circumstances. It is recommended that all ODP resources are freed before the last thread (of the instance) calls this function. This helps ODP to avoid memory and other resource leaks.

odp_term_global() may be called only after all threads of the instance have executed odp_term_local(). To simplify synchronization between threads a return value identifies which one is the last thread of an instance.

Return values

1	on success and more ODP threads exist
0	on success and this is the last ODP thread
<0	on failure

See also: odp_init_local(), odp_term_global()

Examples: ipsec_api/odp_ipsec.c, ipsec_crypto/odp_ipsec.c, odp_atomic_perf.c, odp_bench_buffer.c, odp_bench_misc.c, odp_bench_packet.c, odp_bench_pktio_sp.c, odp_bench_timer.c, odp_classifier.c, odp_cli.c, odp_cpu_bench.c, odp_crc.c, odp_crypto.c, odp_debug.c, odp_dma_perf.c, odp_dmafwd.c, odp_hello.c, odp_icache_perf.c, odp_ipfragreass.c, odp_ipsec.c, odp_ipsecfwd.c, odp_l2fwd.c, odp_l2fwd_perf.c, odp_l3fwd.c, odp_lock_perf.c, odp_mem_perf.c, odp_ml_perf.c, odp_ml_run.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_random.c, odp_sched_latency.c, odp_sched_perf.c, odp_sched_pktio.c, odp_simple_pipeline.c, odp_stash_perf.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_term_global()

int odp_term_global ( odp_instance_t instance )

Global ODP termination.

This function is the final ODP call made when terminating an ODP application in a controlled way. It cannot handle exceptional circumstances.

This function must be called only after all threads of the instance have executed odp_term_local().

Parameters

instance Instance handle

Return values

0	on success
<0	on failure

See also: odp_init_global(), odp_term_local()

Examples: ipsec_api/odp_ipsec.c, ipsec_crypto/odp_ipsec.c, odp_atomic_perf.c, odp_bench_buffer.c, odp_bench_misc.c, odp_bench_packet.c, odp_bench_pktio_sp.c, odp_bench_timer.c, odp_classifier.c, odp_cli.c, odp_cpu_bench.c, odp_crc.c, odp_crypto.c, odp_debug.c, odp_dma_perf.c, odp_dmafwd.c, odp_hello.c, odp_icache_perf.c, odp_ipfragreass.c, odp_ipsec.c, odp_ipsecfwd.c, odp_l2fwd.c, odp_l2fwd_perf.c, odp_l3fwd.c, odp_lock_perf.c, odp_mem_perf.c, odp_ml_perf.c, odp_ml_run.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_random.c, odp_sched_latency.c, odp_sched_perf.c, odp_sched_pktio.c, odp_simple_pipeline.c, odp_stash_perf.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_term_abnormal()

int odp_term_abnormal	(	odp_instance_t	instance,
		uint64_t	flags,
		void *	data
	)

Abnormal ODP termination after a non-recoverable error.

Application may call this function to terminate an ODP instance after facing a non-recoverable error. Depending on the implementation, this function may attempt to dump stack and other memory areas, clean up and stop HW operations and/or perform other actions helpful in postmortem analysis. Depending on the nature of the error resulting in the abnormal termination, these actions may partially or completely fail. Flags (ODP_TERM_*) parameter can be used to control and data parameter can be used to pass additional flag-specific information to the termination process. Implementation specific flags with implementation specific data may also exist, see from implementation documentation how those should be utilized.

Some coordination across threads is required when abnormally terminating, if other threads continue calling ODP functions during or after termination, their operation is most likely affected.

When the function returns, the ODP instance has been destroyed either completely or partially. Application must not attempt to call any ODP functions during its remaining lifetime, but terminate as soon as feasible.

Parameters

instance	Instance handle
flags	A bit mask of control flags (ODP_TERM_*), set to 0 when no flags
data	Additional data, set to NULL when no additional data

Return values

0	on all actions successfully performed
<0	on failure to perform all actions, implementation specific status code for debugging

◆ odp_log_thread_fn_set()

void odp_log_thread_fn_set ( odp_log_func_t func )

Set thread specific log function.

By default, all ODP log writes use the global log function, which may be set as part of odp_init_t. Using this operation, an alternative ODP log function may be set for the calling thread. When set, ODP uses the thread specific log function for all log writes originating from ODP API calls made by the calling thread. Setting the log function to NULL causes the calling thread to use the global log function.

Parameters

func	Log function

◆ odp_log_fn_get()

odp_log_func_t odp_log_fn_get ( void )

Get current log function.

May be called even if ODP is not initialized.

Returns the function previously set by the calling thread via odp_log_thread_fn_set(). If no thread specific log function has been set, returns the log function specified in odp_init_global() parameters. If no log function was specified, returns the default or override log function (see odp_override_log()). Returns NULL if ODP is not initialized.

Returns: Log function

Return values

NULL	ODP not initialized

◆ odp_abort_fn_get()

odp_abort_func_t odp_abort_fn_get ( void )

Get abort function.

May be called even if ODP is not initialized.

Returns the abort function specified in odp_init_global() parameters. If no abort function was specified, returns the default or override abort function (see odp_override_abort()). Returns NULL if ODP is not initialized.

Returns: Abort function

Return values

NULL	ODP not initialized

◆ odp_instance()

int odp_instance ( odp_instance_t * instance )

Get instance handle.

A successful call outputs the calling thread's ODP instance handle.

Parameters

[out] instance Instance handle pointer for output

Return values

0	on success
<0	on failure

See also: odp_init_global(), odp_init_local()

Examples: odp_dma_perf.c, odp_dmafwd.c, odp_ipsecfwd.c, odp_l2fwd_perf.c, odp_pool_latency.c, and odp_timer_stress.c.

◆ odp_instance_to_u64()

uint64_t odp_instance_to_u64 ( odp_instance_t instance )

Get printable value for ODP instance handle.

Parameters

instance Handle to be converted for debugging

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

API Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ ODP_STATIC_ASSERT

◆ ODP_TERM_LAST_FLAG

Typedef Documentation

◆ odp_init_t

◆ odp_platform_init_t

Enumeration Type Documentation

◆ odp_log_level_t

◆ odp_mem_model_t

Function Documentation

◆ odp_override_log()

◆ odp_override_abort()

◆ odp_init_param_init()

◆ odp_init_global()

◆ odp_init_local()

◆ odp_term_local()

◆ odp_term_global()

◆ odp_term_abnormal()

◆ odp_log_thread_fn_set()

◆ odp_log_fn_get()

◆ odp_abort_fn_get()

◆ odp_instance()

◆ odp_instance_to_u64()