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_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. More...

typedef odp_timer_retval_t	odp_timer_set_t
	For backwards compatibility, odp_timer_set_t is synonym of odp_timer_retval_t. More...

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 }
	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_FAIL = -3 }
	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...

void	odp_timer_pool_start (void)
	Start 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 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 timer. More...

int	odp_timer_restart (odp_timer_t timer, const odp_timer_start_t *start_param)
	Restart a 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 timer. More...

odp_timeout_t	odp_timeout_from_event (odp_event_t ev)
	Get timeout handle from a 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...

int	odp_timeout_fresh (odp_timeout_t tmo)
	Check for fresh timeout. 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...

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...

Typedef Documentation

◆ odp_timer_periodic_start_t

typedef struct odp_timer_periodic_start_t odp_timer_periodic_start_t

Periodic timer start parameters.

A periodic timer pool can be thought as a wall clock, where the base frequency (odp_timer_pool_param_t::base_freq_hz) defines how many times per second a pointer travels around the clock face. When a timer (see "Timer A" in the figure) is started with the base frequency multiplier (odp_timer_periodic_start_t::freq_multiplier) of one, a single reference to it is placed into the clock face. When a timer (see "Timer B") is started with the multiplier value of two, two references to it is placed into opposite sides of the clock face, etc. When the pointer reaches a timer reference, the timer expires and a timeout event is sent to the destination queue. The maximum base frequency multiplier (odp_timer_pool_param_t::max_multiplier) defines the maximum number of references a timer can have on the clock face. The first expiration time parameter (odp_timer_periodic_start_t::first_tick) is used to tune timer reference placement on the clock face against the current time (the current pointer location).

         Periodic timer pool
 
                  o
             o         o <--- Timer B
 
           o      \      o
                   \
Timer B ---> o      \  o <--- Timer A
                  o
 
 
Timer pool: max_multiplier  = 8
Timer A:    freq_multiplier = 1
Timer B:    freq_multiplier = 2

◆ odp_timer_set_t

typedef odp_timer_retval_t odp_timer_set_t

For backwards compatibility, odp_timer_set_t is synonym of odp_timer_retval_t.

Deprecated:: Use odp_timer_retval_t instead.

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

Enumeration Type Documentation

◆ odp_timer_type_t

enum odp_timer_type_t

Timer type.

There are two 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) keeps expiring and sending timeout events with the given period until it is cancelled.

Enumerator
ODP_TIMER_TYPE_SINGLE	Single shot timer.
ODP_TIMER_TYPE_PERIODIC	Periodic timer.

Definition at line 71 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 227 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 263 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 386 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_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 500 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, and odp_timer_simple.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, and odp_timer_perf.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 base frequency and other parameters. Application sets 'capa' with the requested timer pool base frequency, the maximum frequency multiplier and the minimum timeout resolution. If there is no requirement for timeout resolution, it is set to zero.

When the call returns success, 'capa' fields are overwritten in following ways. On return value of 1, timer supports the requested base frequency exactly, and meets or exceeds other requested values. The base frequency value is not modified, but other 'capa' fields are updated with resulting maximum capabilities.

When the call returns 0, the requested base frequency is not supported exactly, but timer capabilities meet or exceed all other requested values. In this case, the call overwrites 'base_freq_hz' with the closest supported frequency 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 base frequency, and meets or exceeds other requested values.
0	Success. Capability does not match base frequency exactly, but meets or exceeds other requested values.
<0	Failure

Examples: odp_timer_accuracy.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, and odp_timer_simple.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.

Periodic timer expiration frequency is a multiple of the timer pool base frequency (odp_timer_pool_param_t::base_freq_hz). Depending on implementation, the base frequency may need to be selected carefully with respect to the timer pool source clock frequency. Use odp_timer_periodic_capability() to check which base frequencies and multipliers are supported.

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, and odp_timer_simple.c.

◆ odp_timer_pool_start()

void odp_timer_pool_start ( void )

Start a timer pool.

Start all created timer pools, enabling the allocation of timers. The purpose of this call is to coordinate the creation of multiple timer pools that may use the same underlying HW resources. This function may be called multiple times.

Deprecated:: Use odp_timer_pool_start_multi() instead

◆ 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, and odp_timer_simple.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, and odp_timer_simple.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, and odp_timer_simple.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 timer.

Allocates a timer from the timer pool. Depending on timer type, the allocated timer is started with either odp_timer_start() or odp_timer_periodic_start() call. A timer may be reused multiple times before freeing it back into the timer pool.

When timer expires, the timeout event defined in timer start parameters (see odp_timer_start_t::tmo_ev or odp_timer_periodic_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, and odp_timer_simple.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 receive the last event from 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, and odp_timer_simple.c.

◆ odp_timer_start()

int odp_timer_start	(	odp_timer_t	timer,
		const odp_timer_start_t *	start_param
	)

Start a timer.

Starts a 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.

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_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, and odp_timer_simple.c.

◆ odp_timer_restart()

int odp_timer_restart	(	odp_timer_t	timer,
		const odp_timer_start_t *	start_param
	)

Restart a timer.

A successful restart call updates the expiration time of an active 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, or is so close to expire that it cannot be restarted anymore. 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 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_FAIL	Failure. The timer expired already, or other failure.

Examples: odp_sched_pktio.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 timer that delivers timeout events periodically to the destination queue starting from the first expiration time provided. The timer must have been allocated from a pool of periodic timers. 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 expiration frequency (period) is defined as a multiple of the timer pool base frequency (odp_timer_pool_param_t::base_freq_hz). The timeout event type must be ODP_EVENT_TIMEOUT (odp_timeout_t).

Periodic timers cannot be restarted. If the period needs to be changed, the timer is first cancelled and then started again with new parameters.

Application must acknowledge each timeout event with odp_timer_periodic_ack() call. The call should be made as soon as possible after receiving the event.

The timer is not started when a failure is returned.

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_FAIL	Other failure.

See also: odp_timer_periodic_cancel()

Examples: odp_timer_accuracy.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 timeout event from a periodic timer 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, and thus the same event may appear in the destination queue multiple times (when application falls behind).

Normally, the acknowledgment call returns zero on success and consumes the timeout event. Application must not use the event anymore after this. A greater than zero return value indicates timeout events from a cancelled timer. These events may not arrive at the requested interval, but are used to finalize the timer cancel request. Return value of 2 marks the last event from a cancelled timer. After receiving it application may free the timer and the timeout event.

Parameters

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

Return values

2	Success, the last event from a cancelled timer. The call did not consume the event.
1	Success, an event from a cancelled timer. The call consumed the event.
0	Success, the call consumed the event.
<0	Failure, the call did not consume the event.

Examples: odp_timer_accuracy.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 these events may not arrive at the requested interval. Return value of odp_timer_periodic_ack() call will indicate the last timeout event from the timer. Application may free the timer and the timeout event only after receiving the last event.

Parameters

timer Timer

Return values

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

Examples: odp_timer_accuracy.c.

◆ odp_timer_cancel()

int odp_timer_cancel	(	odp_timer_t	timer,
		odp_event_t *	tmo_ev
	)

Cancel a 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_debug.c, and odp_timer_perf.c.

◆ odp_timeout_from_event()

odp_timeout_t odp_timeout_from_event ( odp_event_t ev )

Get timeout handle from a 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, and odp_timer_perf.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_timer.c, odp_debug.c, odp_sched_pktio.c, odp_stress.c, odp_timer_accuracy.c, odp_timer_perf.c, and odp_timer_simple.c.

◆ odp_timeout_fresh()

int odp_timeout_fresh ( odp_timeout_t tmo )

Check for fresh timeout.

If the corresponding timer has been reset or cancelled since this timeout was enqueued, the timeout is stale (not fresh).

Parameters

tmo	Timeout handle

Return values

1	Timeout is fresh
0	Timeout is stale

Deprecated:: The function will be removed in a future API version.

◆ 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, and odp_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, and odp_timer_perf.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_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_timer.c, odp_debug.c, odp_sched_pktio.c, odp_stress.c, odp_timer_accuracy.c, odp_timer_perf.c, and odp_timer_simple.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.

◆ 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.

◆ 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

Typedef Documentation

◆ odp_timer_periodic_start_t

◆ odp_timer_set_t

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()

◆ 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_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_fresh()

◆ odp_timeout_timer()

◆ odp_timeout_tick()

◆ odp_timeout_user_ptr()

◆ odp_timeout_user_area()

◆ 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()