API Description

Timer generating timeout events.

Data Structures
struct	odp_timer_res_capability_t
	Timer resolution capability. More...

struct	odp_timer_periodic_capability_t
	Periodic timer capability. More...

struct	odp_timer_capability_t
	Timer capability. More...

struct	odp_timer_pool_param_t
	Timer pool parameters. More...

struct	odp_timer_periodic_param_t
	Periodic timer parameters. More...

struct	odp_timer_start_t
	Timer start parameters. More...

struct	odp_timer_periodic_start_t
	Periodic timer start parameters. More...

struct	odp_timer_tick_info_t
	Timer tick information. More...

struct	odp_timer_pool_info_t
	ODP timer pool information and configuration. More...

Macros
#define	ODP_TIMER_POOL_INVALID ((odp_timer_pool_t)0)
	Invalid timer pool handle.

#define	ODP_TIMER_POOL_NAME_LEN 32
	Maximum timer pool name length, including the null character.

#define	ODP_TIMER_INVALID ((odp_timer_t)0)
	Invalid timer handle.

#define	ODP_TIMEOUT_INVALID ((odp_timeout_t)0)
	Invalid timeout handle.

#define	ODP_CLOCK_DEFAULT ODP_CLOCK_SRC_0
	The default clock source.

Typedefs
typedef _odp_abi_timer_pool_t *	odp_timer_pool_t
	ODP timer pool handle.

typedef _odp_abi_timer_t *	odp_timer_t
	ODP timer handle.

typedef _odp_abi_timeout_t *	odp_timeout_t
	ODP timeout handle.

typedef struct odp_timer_start_t	odp_timer_start_t
	Timer start parameters.

typedef struct odp_timer_periodic_start_t	odp_timer_periodic_start_t
	Periodic timer start parameters.

typedef struct odp_timer_tick_info_t	odp_timer_tick_info_t
	Timer tick information.

Enumerations
enum	odp_timer_type_t { ODP_TIMER_TYPE_SINGLE = 0 , ODP_TIMER_TYPE_PERIODIC_BASE_MUL , ODP_TIMER_TYPE_PERIODIC_FREQ }
	Timer type. More...

enum	odp_timer_clk_src_t { ODP_CLOCK_SRC_0 , ODP_CLOCK_SRC_1 , ODP_CLOCK_SRC_2 , ODP_CLOCK_SRC_3 , ODP_CLOCK_SRC_4 , ODP_CLOCK_SRC_5 , ODP_CLOCK_NUM_SRC }
	Clock sources for timer pools. More...

enum	odp_timer_exp_mode_t { ODP_TIMER_EXP_AFTER = 0 , ODP_TIMER_EXP_RELAXED }
	Timer expiration mode. More...

enum	odp_timer_tick_type_t { ODP_TIMER_TICK_REL = 0 , ODP_TIMER_TICK_ABS }
	Timer tick type. More...

enum	odp_timer_retval_t { ODP_TIMER_SUCCESS = 0 , ODP_TIMER_TOO_NEAR = -1 , ODP_TIMER_TOO_FAR = -2 , ODP_TIMER_BUSY = -3 , ODP_TIMER_FAIL = -4 }
	Return values for timer start, restart and cancel calls. More...

Functions
int	odp_timer_capability (odp_timer_clk_src_t clk_src, odp_timer_capability_t *capa)
	Query timer capabilities per clock source. More...

int	odp_timer_res_capability (odp_timer_clk_src_t clk_src, odp_timer_res_capability_t *res_capa)
	Timer resolution capability. More...

int	odp_timer_periodic_capability (odp_timer_clk_src_t clk_src, odp_timer_periodic_capability_t *capa)
	Periodic timer capability. More...

void	odp_timer_pool_param_init (odp_timer_pool_param_t *param)
	Initialize timer pool parameters. More...

odp_timer_pool_t	odp_timer_pool_create (const char name, const odp_timer_pool_param_t params)
	Create a timer pool. More...

int	odp_timer_pool_start_multi (odp_timer_pool_t timer_pool[], int num)
	Start timer pools. More...

void	odp_timer_pool_destroy (odp_timer_pool_t timer_pool)
	Destroy a timer pool. More...

uint64_t	odp_timer_tick_to_ns (odp_timer_pool_t timer_pool, uint64_t ticks)
	Convert timer ticks to nanoseconds. More...

uint64_t	odp_timer_ns_to_tick (odp_timer_pool_t timer_pool, uint64_t ns)
	Convert nanoseconds to timer ticks. More...

uint64_t	odp_timer_current_tick (odp_timer_pool_t timer_pool)
	Current tick value. More...

int	odp_timer_sample_ticks (odp_timer_pool_t timer_pool[], uint64_t tick[], uint64_t clk_count[], int num)
	Sample tick values of timer pools. More...

int	odp_timer_pool_info (odp_timer_pool_t timer_pool, odp_timer_pool_info_t *info)
	Query timer pool configuration and current state. More...

odp_timer_t	odp_timer_alloc (odp_timer_pool_t timer_pool, odp_queue_t queue, const void *user_ptr)
	Allocate a single shot timer. More...

int	odp_timer_free (odp_timer_t timer)
	Free a timer. More...

int	odp_timer_start (odp_timer_t timer, const odp_timer_start_t *start_param)
	Start a single shot timer. More...

int	odp_timer_restart (odp_timer_t timer, const odp_timer_start_t *start_param)
	Restart a single shot timer. More...

void	odp_timer_periodic_param_init (odp_timer_periodic_param_t *param)
	Initialize periodic timer parameters. More...

odp_timer_t	odp_timer_periodic_alloc (odp_timer_pool_t timer_pool, const odp_timer_periodic_param_t *params)
	Allocate a periodic timer. More...

int	odp_timer_periodic_start (odp_timer_t timer, const odp_timer_periodic_start_t *start_param)
	Start a periodic timer. More...

int	odp_timer_periodic_ack (odp_timer_t timer, odp_event_t tmo_ev)
	Acknowledge timeout from a periodic timer. More...

int	odp_timer_periodic_cancel (odp_timer_t timer)
	Cancel a periodic timer. More...

int	odp_timer_cancel (odp_timer_t timer, odp_event_t *tmo_ev)
	Cancel a single shot timer. More...

odp_timeout_t	odp_timeout_from_event (odp_event_t ev)
	Get timeout handle from an ODP_EVENT_TIMEOUT type event. More...

void	odp_timeout_from_event_multi (odp_timeout_t tmo[], const odp_event_t ev[], int num)
	Convert multiple timeout events to timeout handles. More...

odp_event_t	odp_timeout_to_event (odp_timeout_t tmo)
	Convert timeout handle to event handle. More...

odp_timer_t	odp_timeout_timer (odp_timeout_t tmo)
	Return timer handle for the timeout. More...

uint64_t	odp_timeout_tick (odp_timeout_t tmo)
	Timeout expiration tick. More...

void *	odp_timeout_user_ptr (odp_timeout_t tmo)
	Return user pointer for the timeout. More...

void *	odp_timeout_user_area (odp_timeout_t tmo)
	Timeout user area. More...

int	odp_timeout_is_periodic (odp_timeout_t tmo)
	Check if timeout is from a periodic timer. More...

odp_timeout_t	odp_timeout_alloc (odp_pool_t pool)
	Timeout alloc. More...

int	odp_timeout_alloc_multi (odp_pool_t pool, odp_timeout_t tmo[], int num)
	Allocate multiple timeouts. More...

void	odp_timeout_free (odp_timeout_t tmo)
	Timeout free. More...

void	odp_timeout_free_multi (odp_timeout_t tmo[], int num)
	Free multiple timeouts. More...

void	odp_timer_pool_print (odp_timer_pool_t timer_pool)
	Print timer pool debug information. More...

void	odp_timer_print (odp_timer_t timer)
	Print timer debug information. More...

void	odp_timeout_print (odp_timeout_t tmo)
	Print timeout debug information. More...

uint64_t	odp_timer_pool_to_u64 (odp_timer_pool_t timer_pool)
	Get printable value for an odp_timer_pool_t. More...

uint64_t	odp_timer_to_u64 (odp_timer_t timer)
	Get printable value for an odp_timer_t. More...

uint64_t	odp_timeout_to_u64 (odp_timeout_t tmo)
	Get printable value for an odp_timeout_t. More...

Enumeration Type Documentation

◆ odp_timer_type_t

enum odp_timer_type_t

Timer type.

There are two main types of timers. A single shot timer (ODP_TIMER_TYPE_SINGLE) is started with an expiration time for each timeout. A periodic timer (ODP_TIMER_TYPE_PERIODIC_BASE_MUL and ODP_TIMER_TYPE_PERIODIC_FREQ) keeps expiring and sending timeout events with the given period until it is cancelled. ODP_TIMER_TYPE_PERIODIC_BASE_MUL and ODP_TIMER_TYPE_PERIODIC_FREQ differ on how period is configured for timers.

Enumerator
ODP_TIMER_TYPE_SINGLE	Single shot timer.
ODP_TIMER_TYPE_PERIODIC_BASE_MUL	Periodic timer, period defined through pool base frequency and a multiplier.
ODP_TIMER_TYPE_PERIODIC_FREQ	Periodic timer, period defined directly with frequency.

Definition at line 73 of file api/spec/timer_types.h.

◆ odp_timer_clk_src_t

enum odp_timer_clk_src_t

Clock sources for timer pools.

ODP_CLOCK_DEFAULT is the default clock source and it is supported always. It is implementation defined which other clock sources are supported. See from implementation documentation how the supported clock sources are mapped into these enumerations.

Enumerator
ODP_CLOCK_SRC_0	Clock source number 0.
ODP_CLOCK_SRC_1	Clock source number 1.
ODP_CLOCK_SRC_2	Clock source number 2.
ODP_CLOCK_SRC_3	Clock source number 3
ODP_CLOCK_SRC_4	Clock source number 4
ODP_CLOCK_SRC_5	Clock source number 5
ODP_CLOCK_NUM_SRC	Number of clock source enumerations.

Definition at line 300 of file api/spec/timer_types.h.

◆ odp_timer_exp_mode_t

enum odp_timer_exp_mode_t

Timer expiration mode.

Expiration mode selects how timer expiration tick is interpreted. In ODP_TIMER_EXP_RELAXED mode, timer implementation may round the requested time up or down within resolution limits, and therefore application may receive timeouts slightly before or after the requested time. In ODP_TIMER_EXP_AFTER mode, timers are limited to expire exactly on the requested time or after it, but never before the time.

Enumerator

ODP_TIMER_EXP_AFTER

Expiration after the target time.

Timers expire on the specified time or after it, but never before it.

ODP_TIMER_EXP_RELAXED

Expiration relaxed.

Timers may expire before or after the specified time (within resolution limits). Depending on implementation, this may improve expiration accuracy compared to ODP_TIMER_EXP_AFTER.

Definition at line 336 of file api/spec/timer_types.h.

◆ odp_timer_tick_type_t

enum odp_timer_tick_type_t

Timer tick type.

Enumerator

ODP_TIMER_TICK_REL

Relative ticks.

Timer tick value is relative to the current time (odp_timer_current_tick())
of the timer pool.

ODP_TIMER_TICK_ABS

Absolute ticks.

Timer tick value is absolute timer pool ticks.

Definition at line 632 of file api/spec/timer_types.h.

◆ odp_timer_retval_t

enum odp_timer_retval_t

Return values for timer start, restart and cancel calls.

Enumerator
ODP_TIMER_SUCCESS	Timer operation succeeded. Timer start, restart and cancel operations may return this value.
ODP_TIMER_TOO_NEAR	Timer operation failed, too near to the current time. The operation failed because the requested time/timer has expired already, or is too near to the current time. Timer start, restart and cancel operations may return this value.
ODP_TIMER_TOO_FAR	Timer operation failed, too far from the current time. The operation failed because the requested time is too far from the current time. Only timer start and restart operations may return this value.
ODP_TIMER_BUSY	Timer operation failed, resources temporarily busy. The operation failed because the underlying timer resources are temporarily busy. Timer start and restart may return this value.
ODP_TIMER_FAIL	Timer operation failed. The operation failed due to some other reason than timing of the request. Timer start, restart and cancel operations may return this value.

Definition at line 702 of file api/spec/timer_types.h.

Function Documentation

◆ odp_timer_capability()

int odp_timer_capability	(	odp_timer_clk_src_t	clk_src,
		odp_timer_capability_t *	capa
	)

Query timer capabilities per clock source.

Outputs timer capabilities on success. Returns -1 if the clock source is not supported.

Parameters

	clk_src	Clock source for timers
[out]	capa	Pointer to capability structure for output

Return values

0	on success
-1	when the clock source is not supported
<-1	on other failures

Examples: odp_bench_timer.c, odp_debug.c, odp_sched_pktio.c, odp_stress.c, odp_sysinfo.c, odp_timer_accuracy.c, odp_timer_perf.c, odp_timer_simple.c, and odp_timer_stress.c.

◆ odp_timer_res_capability()

int odp_timer_res_capability	(	odp_timer_clk_src_t	clk_src,
		odp_timer_res_capability_t *	res_capa
	)

Timer resolution capability.

This function fills in capability limits for timer pool resolution and min/max timeout values, based on either resolution or maximum timeout. Set the required value to a resolution field (res_ns or res_hz) or to the maximum timeout field (max_tmo), and set other fields to zero. A successful call fills in the other fields. The call returns a failure, if the user defined value exceeds capability limits. Outputted values are minimums for 'res_ns' and 'min_tmo', and maximums for 'res_hz' and 'max_tmo'.

Parameters

	clk_src	Clock source for timers
[in,out]	res_capa	Resolution capability pointer for input/output. Set either a resolution or max timeout field, a successful call fills in other fields.

Return values

0	on success
<0	on failure

Examples: odp_debug.c, odp_stress.c, odp_timer_perf.c, and odp_timer_stress.c.

◆ odp_timer_periodic_capability()

int odp_timer_periodic_capability	(	odp_timer_clk_src_t	clk_src,
		odp_timer_periodic_capability_t *	capa
	)

Periodic timer capability.

Checks periodic timer capability to support the requested parameters. Application sets 'capa' with the requested values: For ODP_TIMER_TYPE_PERIODIC_BASE_MUL timers, timer pool base frequency and the maximum frequency multiplier. For ODP_TIMER_TYPE_PERIODIC_FREQ timers, a pointer to an array of constraining periodic timer frequencies and the number of items in the array. The minimum timeout resolution can additionally be set for both. If there is no requirement for timeout resolution, it is set to zero. Type is chosen with odp_timer_periodic_capability_t::type.

When the call returns success, 'capa' fields are overwritten in following ways. On return value of 1, timer supports the requested frequencies exactly (odp_timer_periodic_capability_t::base_mul::base_freq_hz or each frequency in odp_timer_periodic_capability_t::freq::freq_hz array), and meets or exceeds other values. Frequency values are not modified, but other 'capa' fields are updated with resulting maximum capabilities.

When the call returns 0, the requested frequencies are not supported exactly, but timer capabilities meet or exceed all other requested values. In this case, the call overwrites frequencies with the closest supported value and updates other 'capa' fields accordingly.

Failure is returned when the requirements are not supported or the call fails otherwise.

Parameters

	clk_src	Clock source for timer pool
[in,out]	capa	Pointer to periodic timer capability for input/output.

Return values

1	Success. Capability matches all frequencies, and meets or exceeds other requested values.
0	Success. Capability does not match all frequencies exactly, but meets or exceeds other requested values.
<0	Failure

Examples: odp_timer_accuracy.c, and odp_timer_stress.c.

◆ odp_timer_pool_param_init()

void odp_timer_pool_param_init ( odp_timer_pool_param_t * param )

Initialize timer pool parameters.

Initialize an odp_timer_pool_param_t to its default values for all fields.

Parameters

[out] param Pointer to the odp_timer_pool_param_t structure to be initialized

Examples: odp_bench_timer.c, odp_debug.c, odp_sched_pktio.c, odp_stress.c, odp_sysinfo.c, odp_timer_accuracy.c, odp_timer_perf.c, odp_timer_simple.c, and odp_timer_stress.c.

◆ odp_timer_pool_create()

odp_timer_pool_t odp_timer_pool_create	(	const char *	name,
		const odp_timer_pool_param_t *	params
	)

Create a timer pool.

Creates a timer pool according to the parameters. Use 'timer_type' parameter to select if timers are single shot or periodic. All timers in the pool are of the same type. The selected timer type defines which other parameters are used or ignored.

The use of pool name is optional. Unique names are not required. Use odp_timer_pool_param_init() to initialize timer pool parameters into their default values.

After creation a timer pool can be either started (see odp_timer_pool_start_multi()) or destroyed. The returned pool handle cannot be used with any other APIs, except odp_timer_pool_to_u64(), before the pool is successfully started.

With periodic timers, timer frequencies may need to be selected carefully with respect to the timer pool source clock frequency. Use odp_timer_periodic_capability() to check which timer frequencies are supported. Additionally with periodic timers, an ODP_EVENT_TIMEOUT pool is created as part of timer pool creation from which events for periodic timeouts are allocated from. The to-be-created timeout pool may decrease the number of event pools that can be subsequently created by application. Application can configure user area size for the event pool with odp_timer_pool_param_t::periodic::uarea_size and later initialize user areas of timeout events associated with a specific timer during timer allocation with odp_timer_periodic_param_t::uarea_init::init_fn.

The call returns failure when requested parameter values are not supported.

Parameters

name	Name of the timer pool or NULL. Maximum string length is ODP_TIMER_POOL_NAME_LEN, including the null character.
params	Timer pool parameters. The content will be copied.

Returns: Timer pool handle on success

Return values

ODP_TIMER_POOL_INVALID on failure

Examples: odp_bench_timer.c, odp_debug.c, odp_sched_pktio.c, odp_stress.c, odp_sysinfo.c, odp_timer_accuracy.c, odp_timer_perf.c, odp_timer_simple.c, and odp_timer_stress.c.

◆ odp_timer_pool_start_multi()

int odp_timer_pool_start_multi	(	odp_timer_pool_t	timer_pool[],
		int	num
	)

Start timer pools.

Start given timer pools. After a pool has been successfully started the pool handle can be used with other APIs. Each timer pool can be started only once.

Returns 'num' when all given timer pools have been successfully started. If the return value N < 'num', only the first N pools started successfully and at least some of the remaining ones failed to start. In case of a negative return value, none of the pools were started. The unstarted timer pools cannot be used anymore (can only be destroyed).

Parameters

timer_pool	Array of timer pool handles
num	Number of pools to start

Return values

num	on success
<num	on failure

Examples: odp_bench_timer.c, odp_debug.c, odp_sched_pktio.c, odp_stress.c, odp_sysinfo.c, odp_timer_accuracy.c, odp_timer_perf.c, odp_timer_simple.c, and odp_timer_stress.c.

◆ odp_timer_pool_destroy()

void odp_timer_pool_destroy ( odp_timer_pool_t timer_pool )

Destroy a timer pool.

Destroy a timer pool, freeing all resources. All timers must have been freed.

Parameters

timer_pool Timer pool

Examples: odp_bench_timer.c, odp_debug.c, odp_sched_pktio.c, odp_stress.c, odp_sysinfo.c, odp_timer_accuracy.c, odp_timer_perf.c, odp_timer_simple.c, and odp_timer_stress.c.

◆ odp_timer_tick_to_ns()

uint64_t odp_timer_tick_to_ns	(	odp_timer_pool_t	timer_pool,
		uint64_t	ticks
	)

Convert timer ticks to nanoseconds.

Parameters

timer_pool	Timer pool
ticks	Timer ticks

Returns: Nanoseconds

Examples: odp_bench_timer.c, and odp_timer_accuracy.c.

◆ odp_timer_ns_to_tick()

uint64_t odp_timer_ns_to_tick	(	odp_timer_pool_t	timer_pool,
		uint64_t	ns
	)

Convert nanoseconds to timer ticks.

Parameters

timer_pool	Timer pool
ns	Nanoseconds

Returns: Timer ticks

Examples: odp_bench_timer.c, odp_debug.c, odp_sched_pktio.c, odp_stress.c, odp_timer_accuracy.c, odp_timer_perf.c, odp_timer_simple.c, and odp_timer_stress.c.

◆ odp_timer_current_tick()

uint64_t odp_timer_current_tick ( odp_timer_pool_t timer_pool )

Current tick value.

Returns the current tick value of the timer pool. Timer tick is an implementation defined unit of time. Ticks and related nanosecond values are timer pool specific. Those may not start from zero, but are guaranteed not to wrap around in at least 10 years from the ODP instance startup.

Timer tick value increments with a constant, timer pool specific frequency. Tick frequency may be equal or higher than the requested timer pool resolution. The frequency can be checked with odp_timer_pool_info(). Tick value increments with implementation specific step sizes.

Use odp_timer_sample_ticks() to determine offset between tick values of two or more timer pools.

Parameters

timer_pool Timer pool

Returns: Current time in timer ticks

See also: odp_timer_tick_info_t

Examples: odp_bench_timer.c, odp_timer_accuracy.c, odp_timer_perf.c, and odp_timer_simple.c.

◆ odp_timer_sample_ticks()

int odp_timer_sample_ticks	(	odp_timer_pool_t	timer_pool[],
		uint64_t	tick[],
		uint64_t	clk_count[],
		int	num
	)

Sample tick values of timer pools.

Reads timer pool tick values simultaneously (or closely back-to-back) from all requested timer pools, and outputs those on success. Optionally, outputs corresponding source clock (HW) counter values, which are implementation specific and may be used for debugging. When a timer pool does not support reading of the source clock value, zero is written instead. Values are written into the output arrays in the same order which timer pools were defined. Nothing is written on failure.

Parameters

	timer_pool	Timer pools to sample
[out]	tick	Tick value array for output (one element per timer pool)
[out]	clk_count	Source clock counter value array for output (one element per timer pool), or NULL when counter values are not requested.
	num	Number of timer pools to sample

Return values

0	All requested timer pools sampled successfully
-1	Failure

◆ odp_timer_pool_info()

int odp_timer_pool_info	(	odp_timer_pool_t	timer_pool,
		odp_timer_pool_info_t *	info
	)

Query timer pool configuration and current state.

Parameters

	timer_pool	Timer pool
[out]	info	Pointer to information buffer

Return values

0	on success
<0	on failure. Info could not be retrieved.

Examples: odp_sysinfo.c, and odp_timer_perf.c.

◆ odp_timer_alloc()

odp_timer_t odp_timer_alloc	(	odp_timer_pool_t	timer_pool,
		odp_queue_t	queue,
		const void *	user_ptr
	)

Allocate a single shot timer.

Allocates a single shot timer from the timer pool. The pool must have been created with ODP_TIMER_TYPE_SINGLE type. The allocated timer is started with odp_timer_start() call. A timer may be reused multiple times before freeing it back into the timer pool.

When timer expires, a timeout event, configured with odp_timer_start_t::tmo_ev, is sent into the provided destination queue.

The provided user pointer value is copied into timeout events when the event type is ODP_EVENT_TIMEOUT. The value can be retrieved from an event with odp_timeout_user_ptr() call.

Parameters

timer_pool	Timer pool
queue	Destination queue for timeout events
user_ptr	User defined pointer value or NULL

Returns: Timer handle on success

Return values

ODP_TIMER_INVALID on failure

Examples: odp_bench_timer.c, odp_debug.c, odp_sched_pktio.c, odp_stress.c, odp_timer_accuracy.c, odp_timer_perf.c, odp_timer_simple.c, and odp_timer_stress.c.

◆ odp_timer_free()

int odp_timer_free ( odp_timer_t timer )

Free a timer.

Frees a previously allocated timer. The timer must be inactive when calling this function. In other words, the application must cancel an active single shot timer (odp_timer_cancel()) successfully or wait it to expire before freeing it. Similarly for an active periodic timer, the application must cancel it (odp_timer_periodic_cancel()) and acknowledge all events delivered by the timer (odp_timer_periodic_ack()) before freeing it.

The call returns failure only on non-recoverable errors. Application must not use the timer handle anymore after the call, regardless of the return value.

Parameters

timer Timer

Return values

0	on success
<0	on failure

Examples: odp_bench_timer.c, odp_debug.c, odp_sched_pktio.c, odp_stress.c, odp_timer_accuracy.c, odp_timer_perf.c, odp_timer_simple.c, and odp_timer_stress.c.

◆ odp_timer_start()

int odp_timer_start	(	odp_timer_t	timer,
		const odp_timer_start_t *	start_param
	)

Start a single shot timer.

Starts a single shot timer with an expiration time and a timeout event. The timer must not be active when calling this function. After a successful call, the timer remains active until it expires or is cancelled successfully. An active timer can be restarted with odp_timer_restart().

The timeout event is sent to the destination queue when the timer expires. The expiration time may be passed as absolute timer ticks or ticks relative to the current time. Use 'tick_type' parameter to select between the tick types. Current time of the timer pool can be read with odp_timer_current_tick().

The timer is not started when a failure is returned. A failure is returned when expiration time is too near to the current time (ODP_TIMER_TOO_NEAR), too far from the current time (ODP_TIMER_TOO_FAR) or other failure (ODP_TIMER_FAIL). The call can also fail due to resources being temporarily busy (ODP_TIMER_BUSY). Start is likely to succeed after enough resources are available.

Parameters

timer	Timer to be started
start_param	Timer start parameters

Return values

ODP_TIMER_SUCCESS	Success
ODP_TIMER_TOO_NEAR	Failure. The expiration time passed already, or is too near to the current time.
ODP_TIMER_TOO_FAR	Failure. The expiration time is too far from the current time.
ODP_TIMER_BUSY	Failure. Resources temporarily busy.
ODP_TIMER_FAIL	Other failure.

Examples: odp_bench_timer.c, odp_debug.c, odp_sched_pktio.c, odp_stress.c, odp_timer_accuracy.c, odp_timer_perf.c, odp_timer_simple.c, and odp_timer_stress.c.

◆ odp_timer_restart()

int odp_timer_restart	(	odp_timer_t	timer,
		const odp_timer_start_t *	start_param
	)

Restart a single shot timer.

A successful restart call updates the expiration time of an active single shot timer. The timeout event is not changed.

The timer is not modified when a failure is returned. The call returns ODP_TIMER_FAIL if the timer has expired already, is so close to expire that it cannot be restarted anymore or other failure. A failure is returned also when the new expiration time is too near to the current time (ODP_TIMER_TOO_NEAR) or too far from the current time (ODP_TIMER_TOO_FAR). The call can also fail due to resources being temporarily busy (ODP_TIMER_BUSY). Restart is likely to succeed after enough resources are available.

The new expiration time is passed the same way as with odp_timer_start() call.

Parameters

timer	Timer to be restarted
start_param	Timer start parameters. Value of 'tmo_ev' parameter is ignored.

Return values

ODP_TIMER_SUCCESS	Success
ODP_TIMER_TOO_NEAR	Failure. The new expiration time passed already, or is too near to the current time.
ODP_TIMER_TOO_FAR	Failure. The new expiration time is too far from the current time.
ODP_TIMER_BUSY	Failure. Resources temporarily busy.
ODP_TIMER_FAIL	Failure. The timer expired already, or other failure.

Examples: odp_sched_pktio.c.

◆ odp_timer_periodic_param_init()

void odp_timer_periodic_param_init ( odp_timer_periodic_param_t * param )

Initialize periodic timer parameters.

Initialize an odp_timer_periodic_param_t to its default values for all fields.

Parameters

[out] param Pointer to the odp_timer_periodic_param_t structure to be initialized

Examples: odp_timer_accuracy.c, and odp_timer_stress.c.

◆ odp_timer_periodic_alloc()

odp_timer_t odp_timer_periodic_alloc	(	odp_timer_pool_t	timer_pool,
		const odp_timer_periodic_param_t *	params
	)

Allocate a periodic timer.

Allocates a periodic timer from the timer pool according to the parameters. The pool must have been created with a periodic timer type (ODP_TIMER_TYPE_PERIODIC_BASE_MUL or ODP_TIMER_TYPE_PERIODIC_FREQ). The allocated timer is started with odp_timer_periodic_start() call. A timer may be reused multiple times before freeing it back into the timer pool.

Parameters

timer_pool	Timer pool
params	Timer parameters

Returns: Timer handle on success

Return values

ODP_TIMER_INVALID on failure

Examples: odp_timer_accuracy.c, and odp_timer_stress.c.

◆ odp_timer_periodic_start()

int odp_timer_periodic_start	(	odp_timer_t	timer,
		const odp_timer_periodic_start_t *	start_param
	)

Start a periodic timer.

Starts a periodic timer. Timeout events are delivered periodically to the destination queue starting from the first expiration time provided. The timeout events are from the timeout pool created during periodic timer pool creation. Depending on the implementation, each delivered event may be a unique event or a single event delivered multiple times (meaning the same event may appear in a destination queue multiple times if application falls behind) or something in between. The timer must not be active when calling this function. After a successful call, the timer remains active until it is cancelled and all its timeout events have been acknowledged.

Timer period cannot be changed after timer allocation. If period requires a change, the current timer is cancelled (and freed), and a new timer is allocated and started with new parameters.

Received events must not be freed by the application and each received event must be acknowledged with odp_timer_periodic_ack(). Attached data (e.g. odp_timeout_user_ptr() and odp_timeout_user_area()) may be accessed once received until event acknowledgment. Ensuring thread-safe modifications of the data is up to the application.

The timer is not started when a failure is returned. A failure is returned when the first expiration time is too near to the current time (ODP_TIMER_TOO_NEAR), too far from the current time (ODP_TIMER_TOO_FAR) or other failure (ODP_TIMER_FAIL). The call can also fail due to resources being temporarily busy (ODP_TIMER_BUSY). Periodic start is likely to succeed after enough resources are available.

Parameters

timer	Periodic timer to be started
start_param	Periodic timer start parameters

Return values

ODP_TIMER_SUCCESS	Success
ODP_TIMER_TOO_NEAR	Failure. The first expiration time passed already, or is too near to the current time.
ODP_TIMER_TOO_FAR	Failure. The first expiration time is too far from the current time.
ODP_TIMER_BUSY	Failure. Resources temporarily busy.
ODP_TIMER_FAIL	Other failure.

See also: odp_timer_periodic_cancel()

Examples: odp_timer_accuracy.c, and odp_timer_stress.c.

◆ odp_timer_periodic_ack()

int odp_timer_periodic_ack	(	odp_timer_t	timer,
		odp_event_t	tmo_ev
	)

Acknowledge timeout from a periodic timer.

This call is valid only for periodic timers. Each time a periodic timeout is received, it must be acknowledged with this call. Acknowledgment should be done as soon as possible after receiving the event. A late call may affect accuracy of the following period(s). However, a missing acknowledgment may not stop timeout event delivery to the destination queue, potentially filling it up if application falls behind. The events may be acknowledged in any order or in parallel by multiple threads. Attached data (e.g. odp_timeout_user_ptr() and odp_timeout_user_area()) of received timeout events is accessible until acknowledgment. Once acknowledged, a timeout event must not be used or its data accessed by application.

Normally, the acknowledgment call returns zero on success. After cancellation, the timer delivers any remaining event(s) (always at least one, may not arrive at the requested interval) to the destination queue. Acknowledgment call continues to return zero on success until last event delivered by the timer, return value of 1 marks the last delivered event. After application has acknowledged it and all other events from the timer, it can free or start the timer again.

Note that when a multi-threaded application uses a plain or scheduled parallel/ordered queue as a timer destination queue, one of the threads may receive the last timeout event before the other threads receive preceding timeout events from the timer. Also in this case, the application must ensure that it acknowledges all the events before freeing or starting the timer.

Timeout events associated with a periodic timer can be distinguished with odp_timeout_is_periodic().

Parameters

timer	Periodic timer
tmo_ev	Timeout event that was received from the periodic timer

Return values

1	Success, the last event delivered by a cancelled timer.
0	Success.
<0	Failure.

Examples: odp_timer_accuracy.c, and odp_timer_stress.c.

◆ odp_timer_periodic_cancel()

int odp_timer_periodic_cancel ( odp_timer_t timer )

Cancel a periodic timer.

Cancel a previously started periodic timer. A successful operation stops timer expiration. The timer delivers remaining timeout event(s) into the destination queue. Note that there is always at least one event delivered and that the event(s) may not arrive at the requested interval. Return value of odp_timer_periodic_ack() call will indicate the last timeout event delivered by the timer.

Parameters

timer Timer

Return values

0	Periodic timer expiration stopped. Remaining timeout events will be received through the destination queue.
<0	Timer cancel failed.

Examples: odp_timer_accuracy.c, and odp_timer_stress.c.

◆ odp_timer_cancel()

int odp_timer_cancel	(	odp_timer_t	timer,
		odp_event_t *	tmo_ev
	)

Cancel a single shot timer.

Cancels a previously started single shot timer. A successful operation (ODP_TIMER_SUCCESS) prevents timer expiration and returns the timeout event back to application. Application may use or free the event normally.

When the timer is close to expire or has expired already, the call may not be able cancel it anymore. In this case, the call returns ODP_TIMER_TOO_NEAR and the timeout is delivered to the destination queue.

Parameters

	timer	Timer
[out]	tmo_ev	Pointer to an event handle for output. Event handle is written only on success.

Return values

ODP_TIMER_SUCCESS	Timer was cancelled successfully. Timeout event returned in 'tmo_ev'.
ODP_TIMER_TOO_NEAR	Timer cannot be cancelled. Timer has expired already, or cannot be cancelled due to close expiration time.
ODP_TIMER_FAIL	Other failure.

Examples: odp_bench_timer.c, odp_debug.c, odp_timer_accuracy.c, odp_timer_perf.c, and odp_timer_stress.c.

◆ odp_timeout_from_event()

odp_timeout_t odp_timeout_from_event ( odp_event_t ev )

Get timeout handle from an ODP_EVENT_TIMEOUT type event.

Parameters

ev	An event of type ODP_EVENT_TIMEOUT

Returns: timeout handle

Examples: odp_bench_timer.c, odp_debug.c, odp_stress.c, odp_timer_accuracy.c, odp_timer_perf.c, and odp_timer_stress.c.

◆ odp_timeout_from_event_multi()

void odp_timeout_from_event_multi	(	odp_timeout_t	tmo[],
		const odp_event_t	ev[],
		int	num
	)

Convert multiple timeout events to timeout handles.

All events must be of type ODP_EVENT_TIMEOUT.

Parameters

[out]	tmo	Timeout handle array for output
	ev	Array of event handles to convert
	num	Number of timeouts and events

◆ odp_timeout_to_event()

odp_event_t odp_timeout_to_event ( odp_timeout_t tmo )

Convert timeout handle to event handle.

Parameters

tmo	Timeout handle

Returns: Event handle

Examples: odp_bench_packet.c, odp_bench_timer.c, odp_debug.c, odp_sched_pktio.c, odp_stress.c, odp_timer_accuracy.c, odp_timer_perf.c, odp_timer_simple.c, and odp_timer_stress.c.

◆ odp_timeout_timer()

odp_timer_t odp_timeout_timer ( odp_timeout_t tmo )

Return timer handle for the timeout.

Parameters

tmo	Timeout handle

Returns: Timer handle

Examples: odp_bench_timer.c, odp_stress.c, and odp_timer_stress.c.

◆ odp_timeout_tick()

uint64_t odp_timeout_tick ( odp_timeout_t tmo )

Timeout expiration tick.

Returns the absolute expiration time (in timer ticks) that was used to set (or reset) the timer. For timers set with absolute expiration time this equals the provided tick value.

For periodic timers, returns the expiration time of the period, or zero. When periodic timer implementation cannot return expiration time, it returns zero for all timeouts from the timer pool.

Parameters

tmo	Timeout handle

Returns: Expiration tick

Examples: odp_bench_timer.c, and odp_timer_accuracy.c.

◆ odp_timeout_user_ptr()

void* odp_timeout_user_ptr ( odp_timeout_t tmo )

Return user pointer for the timeout.

The user pointer was specified when the timer was allocated.

Parameters

tmo	Timeout handle

Returns: User pointer

Examples: odp_bench_timer.c, odp_timer_accuracy.c, odp_timer_perf.c, and odp_timer_stress.c.

◆ odp_timeout_user_area()

void* odp_timeout_user_area ( odp_timeout_t tmo )

Timeout user area.

Returns pointer to the user area associated with the timeout. Size of the area is fixed and defined in timeout pool parameters.

Parameters

tmo	Timeout handle

Returns: Pointer to the user area of the timeout

Return values

NULL	The timeout does not have user area

Examples: odp_bench_timer.c, and odp_pool_latency.c.

◆ odp_timeout_is_periodic()

int odp_timeout_is_periodic ( odp_timeout_t tmo )

Check if timeout is from a periodic timer.

Parameters

tmo	Timeout handle

Return values

non-zero	Timeout is from a periodic timer
0	Timeout is not from a periodic timer

Examples: odp_bench_timer.c.

◆ odp_timeout_alloc()

odp_timeout_t odp_timeout_alloc ( odp_pool_t pool )

Timeout alloc.

Allocates timeout from pool. Pool must be created with ODP_POOL_TIMEOUT type.

Parameters

pool	Pool handle

Returns: Timeout handle

Return values

ODP_TIMEOUT_INVALID Timeout could not be allocated

Examples: odp_bench_packet.c, odp_bench_timer.c, odp_debug.c, odp_sched_pktio.c, odp_stress.c, odp_timer_accuracy.c, odp_timer_perf.c, odp_timer_simple.c, and odp_timer_stress.c.

◆ odp_timeout_alloc_multi()

int odp_timeout_alloc_multi	(	odp_pool_t	pool,
		odp_timeout_t	tmo[],
		int	num
	)

Allocate multiple timeouts.

Otherwise like odp_timeout_alloc(), but allocates multiple timeouts from a pool.

Parameters

	pool	Pool handle
[out]	tmo	Array of timeout handles for output
	num	Number of timeouts to allocate

Returns: Number of timeouts actually allocated (0 ... num)

Return values

<0	on failure

Examples: odp_pool_latency.c.

◆ odp_timeout_free()

void odp_timeout_free ( odp_timeout_t tmo )

Timeout free.

Frees the timeout back to the pool it was allocated from.

Parameters

tmo	Timeout handle

Examples: odp_bench_timer.c, odp_debug.c, and odp_timer_perf.c.

◆ odp_timeout_free_multi()

void odp_timeout_free_multi	(	odp_timeout_t	tmo[],
		int	num
	)

Free multiple timeouts.

Otherwise like odp_timeout_free(), but frees multiple timeouts to their originating pools.

Parameters

tmo	Array of timeout handles
num	Number of timeouts to free

Examples: odp_pool_latency.c.

◆ odp_timer_pool_print()

void odp_timer_pool_print ( odp_timer_pool_t timer_pool )

Print timer pool debug information.

Prints implementation specific debug information about the timer pool to the ODP log.

Parameters

timer_pool Timer pool handle

Examples: odp_debug.c, and odp_timer_accuracy.c.

◆ odp_timer_print()

void odp_timer_print ( odp_timer_t timer )

Print timer debug information.

Prints implementation specific debug information about the timer to the ODP log.

Parameters

timer Timer handle

Examples: odp_debug.c.

◆ odp_timeout_print()

void odp_timeout_print ( odp_timeout_t tmo )

Print timeout debug information.

Prints implementation specific debug information about the timeout to the ODP log.

Parameters

tmo	Timeout handle

Examples: odp_debug.c.

◆ odp_timer_pool_to_u64()

uint64_t odp_timer_pool_to_u64 ( odp_timer_pool_t timer_pool )

Get printable value for an odp_timer_pool_t.

Parameters

timer_pool odp_timer_pool_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_timer_pool_t handle.

Examples: odp_bench_timer.c, and odp_timer_stress.c.

◆ odp_timer_to_u64()

uint64_t odp_timer_to_u64 ( odp_timer_t timer )

Get printable value for an odp_timer_t.

Parameters

timer odp_timer_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_timer_t handle.

Examples: odp_bench_timer.c, and odp_timer_stress.c.

◆ odp_timeout_to_u64()

uint64_t odp_timeout_to_u64 ( odp_timeout_t tmo )

Get printable value for an odp_timeout_t.

Parameters

tmo	odp_timeout_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_timeout_t handle.

Examples: odp_bench_timer.c.

API Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Enumeration Type Documentation

◆ odp_timer_type_t

◆ odp_timer_clk_src_t

◆ odp_timer_exp_mode_t

◆ odp_timer_tick_type_t

◆ odp_timer_retval_t

Function Documentation

◆ odp_timer_capability()

◆ odp_timer_res_capability()

◆ odp_timer_periodic_capability()

◆ odp_timer_pool_param_init()

◆ odp_timer_pool_create()

◆ odp_timer_pool_start_multi()

◆ odp_timer_pool_destroy()

◆ odp_timer_tick_to_ns()

◆ odp_timer_ns_to_tick()

◆ odp_timer_current_tick()

◆ odp_timer_sample_ticks()

◆ odp_timer_pool_info()

◆ odp_timer_alloc()

◆ odp_timer_free()

◆ odp_timer_start()

◆ odp_timer_restart()

◆ odp_timer_periodic_param_init()

◆ odp_timer_periodic_alloc()

◆ odp_timer_periodic_start()

◆ odp_timer_periodic_ack()

◆ odp_timer_periodic_cancel()

◆ odp_timer_cancel()

◆ odp_timeout_from_event()

◆ odp_timeout_from_event_multi()

◆ odp_timeout_to_event()

◆ odp_timeout_timer()

◆ odp_timeout_tick()

◆ odp_timeout_user_ptr()

◆ odp_timeout_user_area()

◆ odp_timeout_is_periodic()

◆ odp_timeout_alloc()

◆ odp_timeout_alloc_multi()

◆ odp_timeout_free()

◆ odp_timeout_free_multi()

◆ odp_timer_pool_print()

◆ odp_timer_print()

◆ odp_timeout_print()

◆ odp_timer_pool_to_u64()

◆ odp_timer_to_u64()

◆ odp_timeout_to_u64()