Provides a high level timer module to register timers, get current system time, and let a thread sleep for a certain amount of time. More...

Detailed Description

Provides a high level timer module to register timers, get current system time, and let a thread sleep for a certain amount of time.

The implementation takes one low-level timer and multiplexes it.

Insertion and removal of timers has O(n) complexity with (n) being the number of active timers. The reason for this is that multiplexing is realized by next-first singly linked lists.

Files
file	implementation.h
	xtimer implementation

file	tick_conversion.h
	xtimer tick <-> seconds conversions for different values of XTIMER_HZ

file	xtimer.h
	xtimer interface definitions

Data Structures
struct	xtimer_ticks64_t
	xtimer timestamp (64 bit) More...

struct	xtimer_ticks32_t
	xtimer timestamp (32 bit) More...

struct	xtimer
	xtimer timer structure More...

Macros
#define	XTIMER_BACKOFF 30
	xtimer backoff value More...

#define	XTIMER_ISR_BACKOFF 20
	xtimer IRQ backoff time, in hardware ticks More...

#define	XTIMER_DEV TIMER_DEV(0)
	Underlying hardware timer device to assign to xtimer.

#define	XTIMER_CHAN (0)
	Underlying hardware timer channel to assign to xtimer.

#define	XTIMER_WIDTH (32)
	xtimer timer width More...

#define	XTIMER_MASK ((0xffffffff >> XTIMER_WIDTH) << XTIMER_WIDTH)
	xtimer timer mask More...

#define	XTIMER_HZ_BASE (1000000ul)
	Base frequency of xtimer is 1 MHz.

#define	XTIMER_HZ XTIMER_HZ_BASE
	Frequency of the underlying hardware timer.

#define	XTIMER_SHIFT (1)

Typedefs
typedef void(*	xtimer_callback_t) (void *)
	xtimer callback type

typedef struct xtimer	xtimer_t
	xtimer timer structure

Functions
static xtimer_ticks32_t	xtimer_now (void)
	get the current system time as 32bit time stamp value More...

static xtimer_ticks64_t	xtimer_now64 (void)
	get the current system time as 64bit time stamp More...

void	xtimer_now_timex (timex_t *out)
	get the current system time into a timex_t More...

static uint32_t	xtimer_now_usec (void)
	get the current system time in microseconds since start More...

static uint64_t	xtimer_now_usec64 (void)
	get the current system time in microseconds since start More...

void	xtimer_init (void)
	xtimer initialization function More...

static void	xtimer_sleep (uint32_t seconds)
	Pause the execution of a thread for some seconds. More...

static void	xtimer_msleep (uint32_t milliseconds)
	Pause the execution of a thread for some milliseconds. More...

static void	xtimer_usleep (uint32_t microseconds)
	Pause the execution of a thread for some microseconds. More...

static void	xtimer_usleep64 (uint64_t microseconds)
	Pause the execution of a thread for some microseconds. More...

static void	xtimer_nanosleep (uint32_t nanoseconds)
	Stop execution of a thread for some time. More...

static void	xtimer_tsleep32 (xtimer_ticks32_t ticks)
	Stop execution of a thread for some time, 32bit version. More...

static void	xtimer_tsleep64 (xtimer_ticks64_t ticks)
	Stop execution of a thread for some time, 64bit version. More...

static void	xtimer_spin (xtimer_ticks32_t ticks)
	Stop execution of a thread for some time, blocking. More...

static void	xtimer_periodic_wakeup (xtimer_ticks32_t *last_wakeup, uint32_t period)
	will cause the calling thread to be suspended until the absolute time (`last_wakeup` + `period`). More...

static void	xtimer_set_wakeup (xtimer_t *timer, uint32_t offset, kernel_pid_t pid)
	Set a timer that wakes up a thread. More...

static void	xtimer_set_wakeup64 (xtimer_t *timer, uint64_t offset, kernel_pid_t pid)
	Set a timer that wakes up a thread, 64bit version. More...

static void	xtimer_set (xtimer_t *timer, uint32_t offset)
	Set a timer to execute a callback at some time in the future. More...

static void	xtimer_set64 (xtimer_t *timer, uint64_t offset_us)
	Set a timer to execute a callback at some time in the future, 64bit version. More...

void	xtimer_remove (xtimer_t *timer)
	remove a timer More...

static xtimer_ticks32_t	xtimer_ticks_from_usec (uint32_t usec)
	Convert microseconds to xtimer ticks. More...

static xtimer_ticks64_t	xtimer_ticks_from_usec64 (uint64_t usec)
	Convert microseconds to xtimer ticks, 64 bit version. More...

static uint32_t	xtimer_usec_from_ticks (xtimer_ticks32_t ticks)
	Convert xtimer ticks to microseconds. More...

static uint64_t	xtimer_usec_from_ticks64 (xtimer_ticks64_t ticks)
	Convert xtimer ticks to microseconds, 64 bit version. More...

static xtimer_ticks32_t	xtimer_ticks (uint32_t ticks)
	Create an xtimer time stamp. More...

static xtimer_ticks64_t	xtimer_ticks64 (uint64_t ticks)
	Create an xtimer time stamp, 64 bit version. More...

static xtimer_ticks32_t	xtimer_diff (xtimer_ticks32_t a, xtimer_ticks32_t b)
	Compute difference between two xtimer time stamps. More...

static xtimer_ticks64_t	xtimer_diff64 (xtimer_ticks64_t a, xtimer_ticks64_t b)
	Compute difference between two xtimer time stamps, 64 bit version. More...

static xtimer_ticks32_t	xtimer_diff32_64 (xtimer_ticks64_t a, xtimer_ticks64_t b)
	Compute 32 bit difference between two 64 bit xtimer time stamps. More...

static bool	xtimer_less (xtimer_ticks32_t a, xtimer_ticks32_t b)
	Compare two xtimer time stamps. More...

static bool	xtimer_less64 (xtimer_ticks64_t a, xtimer_ticks64_t b)
	Compare two xtimer time stamps, 64 bit version. More...

int	xtimer_mutex_lock_timeout (mutex_t *mutex, uint64_t us)
	lock a mutex but with timeout More...

int	xtimer_rmutex_lock_timeout (rmutex_t *rmutex, uint64_t us)
	lock a rmutex but with timeout More...

void	xtimer_set_timeout_flag (xtimer_t *t, uint32_t timeout)
	Set timeout thread flag after `timeout`. More...

void	xtimer_set_timeout_flag64 (xtimer_t *t, uint64_t timeout)
	Set timeout thread flag after `timeout`. More...

uint64_t	xtimer_left_usec (const xtimer_t *timer)
	Get remaining time of timer. More...

static void	xtimer_set_msg (xtimer_t timer, uint32_t offset, msg_t msg, kernel_pid_t target_pid)
	Set a timer that sends a message. More...

static void	xtimer_set_msg64 (xtimer_t timer, uint64_t offset, msg_t msg, kernel_pid_t target_pid)
	Set a timer that sends a message, 64bit version. More...

static int	xtimer_msg_receive_timeout (msg_t *msg, uint32_t timeout)
	receive a message blocking but with timeout More...

static int	xtimer_msg_receive_timeout64 (msg_t *msg, uint64_t timeout)
	receive a message blocking but with timeout, 64bit version More...

Macro Definition Documentation

◆ XTIMER_BACKOFF

#define XTIMER_BACKOFF 30

xtimer backoff value

All timers that are less than XTIMER_BACKOFF ticks in the future will just spin.

This is supposed to be defined per-device in e.g., periph_conf.h.

Definition at line 534 of file xtimer.h.

◆ XTIMER_ISR_BACKOFF

#define XTIMER_ISR_BACKOFF 20

xtimer IRQ backoff time, in hardware ticks

When scheduling the next IRQ, if it is less than the backoff time in the future, just spin.

This is supposed to be defined per-device in e.g., periph_conf.h.

Definition at line 546 of file xtimer.h.

◆ XTIMER_MASK

#define XTIMER_MASK ((0xffffffff >> XTIMER_WIDTH) << XTIMER_WIDTH)

xtimer timer mask

This value specifies the mask relative to 0xffffffff that the used timer counts to, e.g., 0xffffffff & ~TIMER_MAXVALUE.

For a 16bit timer, the mask would be 0xFFFF0000, for a 24bit timer, the mask would be 0xFF000000.

Definition at line 590 of file xtimer.h.

◆ XTIMER_WIDTH

#define XTIMER_WIDTH (32)

xtimer timer width

This value specifies the width (in bits) of the hardware timer used by xtimer. Default is 32.

Definition at line 577 of file xtimer.h.

Function Documentation

◆ xtimer_diff()

static xtimer_ticks32_t xtimer_diff	(	xtimer_ticks32_t	a,
		xtimer_ticks32_t	b
	)

inlinestatic

Compute difference between two xtimer time stamps.

Parameters

[in]	a	left operand
[in]	b	right operand

Returns: a - b

◆ xtimer_diff32_64()

static xtimer_ticks32_t xtimer_diff32_64	(	xtimer_ticks64_t	a,
		xtimer_ticks64_t	b
	)

inlinestatic

Compute 32 bit difference between two 64 bit xtimer time stamps.

Parameters

[in]	a	left operand
[in]	b	right operand

Returns: a - b cast truncated to 32 bit

◆ xtimer_diff64()

static xtimer_ticks64_t xtimer_diff64	(	xtimer_ticks64_t	a,
		xtimer_ticks64_t	b
	)

inlinestatic

Compute difference between two xtimer time stamps, 64 bit version.

Parameters

[in]	a	left operand
[in]	b	right operand

Returns: a - b

◆ xtimer_init()

void xtimer_init ( void )

xtimer initialization function

This sets up xtimer. Has to be called once at system boot. If auto_init is enabled, it will call this for you.

◆ xtimer_left_usec()

uint64_t xtimer_left_usec ( const xtimer_t * timer )

Get remaining time of timer.

Parameters

[in] timer timer struct to use

Returns: time in usec until timer triggers; 0 if timer is not set (or has already passed)

◆ xtimer_less()

static bool xtimer_less	(	xtimer_ticks32_t	a,
		xtimer_ticks32_t	b
	)

inlinestatic

Compare two xtimer time stamps.

Parameters

[in]	a	left operand
[in]	b	right operand

Returns: a < b

◆ xtimer_less64()

static bool xtimer_less64	(	xtimer_ticks64_t	a,
		xtimer_ticks64_t	b
	)

inlinestatic

Compare two xtimer time stamps, 64 bit version.

Parameters

[in]	a	left operand
[in]	b	right operand

Returns: a < b

◆ xtimer_msg_receive_timeout()

static int xtimer_msg_receive_timeout	(	msg_t *	msg,
		uint32_t	timeout
	)

inlinestatic

receive a message blocking but with timeout

Parameters

[out]	msg	pointer to a msg_t which will be filled in case of no timeout
[in]	timeout	timeout in microseconds relative

Returns: < 0 on error, other value otherwise

◆ xtimer_msg_receive_timeout64()

static int xtimer_msg_receive_timeout64	(	msg_t *	msg,
		uint64_t	timeout
	)

inlinestatic

receive a message blocking but with timeout, 64bit version

Parameters

[out]	msg	pointer to a msg_t which will be filled in case of no timeout
[in]	timeout	timeout in microseconds relative

Returns: < 0 on error, other value otherwise

◆ xtimer_msleep()

static void xtimer_msleep ( uint32_t milliseconds )

inlinestatic

Pause the execution of a thread for some milliseconds.

Parameters

[in] milliseconds the amount of milliseconds the thread should sleep

◆ xtimer_mutex_lock_timeout()

int xtimer_mutex_lock_timeout	(	mutex_t *	mutex,
		uint64_t	us
	)

lock a mutex but with timeout

Parameters

[in]	mutex	mutex to lock
[in]	us	timeout in microseconds relative

Returns: 0, when returned after mutex was locked; -1, when the timeout occurred

◆ xtimer_nanosleep()

static void xtimer_nanosleep ( uint32_t nanoseconds )

inlinestatic

Stop execution of a thread for some time.

Don't expect nanosecond accuracy. As of now, this function just calls xtimer_usleep(nanoseconds/1000).

When called from an ISR, this function will spin-block, so only use it there for very short periods.

Parameters

[in] nanoseconds the amount of nanoseconds the thread should sleep

◆ xtimer_now()

static xtimer_ticks32_t xtimer_now ( void )

inlinestatic

get the current system time as 32bit time stamp value

Note: Overflows 2**32 ticks, thus returns xtimer_now64() % 32, but is cheaper.

Returns: current time as 32bit time stamp

◆ xtimer_now64()

static xtimer_ticks64_t xtimer_now64 ( void )

inlinestatic

get the current system time as 64bit time stamp

Returns: current time as 64bit time stamp

◆ xtimer_now_timex()

void xtimer_now_timex ( timex_t * out )

get the current system time into a timex_t

Parameters

[out] out pointer to timex_t the time will be written to

◆ xtimer_now_usec()

static uint32_t xtimer_now_usec ( void )

inlinestatic

get the current system time in microseconds since start

This is a convenience function for xtimer_usec_from_ticks(xtimer_now())

◆ xtimer_now_usec64()

static uint64_t xtimer_now_usec64 ( void )

inlinestatic

get the current system time in microseconds since start

This is a convenience function for xtimer_usec_from_ticks64(xtimer_now64())

◆ xtimer_periodic_wakeup()

static void xtimer_periodic_wakeup	(	xtimer_ticks32_t *	last_wakeup,
		uint32_t	period
	)

inlinestatic

will cause the calling thread to be suspended until the absolute time (last_wakeup + period).

When the function returns, last_wakeup is set to (last_wakeup + period).

This function can be used to create periodic wakeups. last_wakeup should be set to xtimer_now() before first call of the function.

If the result of (last_wakeup + period) would be in the past, the function sets last_wakeup to last_wakeup + period and returns immediately.

Parameters

[in]	last_wakeup	base time stamp for the wakeup
[in]	period	time in microseconds that will be added to last_wakeup

◆ xtimer_remove()

void xtimer_remove ( xtimer_t * timer )

remove a timer

Note: this function runs in O(n) with n being the number of active timers

Parameters

[in] timer ptr to timer structure that will be removed

◆ xtimer_rmutex_lock_timeout()

int xtimer_rmutex_lock_timeout	(	rmutex_t *	rmutex,
		uint64_t	us
	)

lock a rmutex but with timeout

Parameters

[in]	rmutex	rmutex to lock
[in]	us	timeout in microseconds relative

Returns: 0, when returned after rmutex was locked; -1, when the timeout occurred

◆ xtimer_set()

static void xtimer_set	(	xtimer_t *	timer,
		uint32_t	offset
	)

inlinestatic

Set a timer to execute a callback at some time in the future.

Expects timer->callback to be set.

The callback specified in the timer struct will be executed offset ticks in the future.

Warning: BEWARE! Callbacks from xtimer_set() are being executed in interrupt context (unless offset < XTIMER_BACKOFF converted to µs). DON'T USE THIS FUNCTION unless you know exactly what that means.

Parameters

[in]	timer	the timer structure to use.
[in]	offset	time in microseconds from now specifying that timer's callback's execution time

◆ xtimer_set64()

static void xtimer_set64	(	xtimer_t *	timer,
		uint64_t	offset_us
	)

inlinestatic

Set a timer to execute a callback at some time in the future, 64bit version.

Expects timer->callback to be set.

The callback specified in the timer struct will be executed offset_usec microseconds in the future.

Warning: BEWARE! Callbacks from xtimer_set() are being executed in interrupt context (unless offset < XTIMER_BACKOFF converted to µs). DON'T USE THIS FUNCTION unless you know exactly what that means.

Parameters

[in]	timer	the timer structure to use.
[in]	offset_us	time in microseconds from now specifying that timer's callback's execution time

◆ xtimer_set_msg()

static void xtimer_set_msg	(	xtimer_t *	timer,
		uint32_t	offset,
		msg_t *	msg,
		kernel_pid_t	target_pid
	)

inlinestatic

Set a timer that sends a message.

This function sets a timer that will send a message offset ticks from now.

The message struct specified by msg parameter will not be copied, e.g., it needs to point to valid memory until the message has been delivered.

Parameters

[in]	timer	timer struct to work with.
[in]	offset	microseconds from now
[in]	msg	ptr to msg that will be sent
[in]	target_pid	pid the message will be sent to

◆ xtimer_set_msg64()

static void xtimer_set_msg64	(	xtimer_t *	timer,
		uint64_t	offset,
		msg_t *	msg,
		kernel_pid_t	target_pid
	)

inlinestatic

Set a timer that sends a message, 64bit version.

This function sets a timer that will send a message offset microseconds from now.

The message struct specified by msg parameter will not be copied, e.g., it needs to point to valid memory until the message has been delivered.

Parameters

[in]	timer	timer struct to work with.
[in]	offset	microseconds from now
[in]	msg	ptr to msg that will be sent
[in]	target_pid	pid the message will be sent to

◆ xtimer_set_timeout_flag()

void xtimer_set_timeout_flag	(	xtimer_t *	t,
		uint32_t	timeout
	)

Set timeout thread flag after timeout.

This function will set THREAD_FLAG_TIMEOUT on the current thread after timeout usec have passed.

Parameters

[in]	t	timer struct to use
[in]	timeout	timeout in usec

◆ xtimer_set_timeout_flag64()

void xtimer_set_timeout_flag64	(	xtimer_t *	t,
		uint64_t	timeout
	)

Set timeout thread flag after timeout.

See xtimer_set_timeout_flag() for more information.

Parameters

[in]	t	timer struct to use
[in]	timeout	timeout in usec

◆ xtimer_set_wakeup()

static void xtimer_set_wakeup	(	xtimer_t *	timer,
		uint32_t	offset,
		kernel_pid_t	pid
	)

inlinestatic

Set a timer that wakes up a thread.

This function sets a timer that will wake up a thread when the timer has expired.

Parameters

[in]	timer	timer struct to work with.
[in]	offset	microseconds from now
[in]	pid	pid of the thread that will be woken up

◆ xtimer_set_wakeup64()

static void xtimer_set_wakeup64	(	xtimer_t *	timer,
		uint64_t	offset,
		kernel_pid_t	pid
	)

inlinestatic

Set a timer that wakes up a thread, 64bit version.

This function sets a timer that will wake up a thread when the timer has expired.

Parameters

[in]	timer	timer struct to work with.
[in]	offset	microseconds from now
[in]	pid	pid of the thread that will be woken up

◆ xtimer_sleep()

static void xtimer_sleep ( uint32_t seconds )

inlinestatic

Pause the execution of a thread for some seconds.

When called from an ISR, this function will spin and thus block the MCU in interrupt context for the specified amount in seconds, so don't ever use it there.

Parameters

[in] seconds the amount of seconds the thread should sleep

◆ xtimer_spin()

static void xtimer_spin ( xtimer_ticks32_t ticks )

inlinestatic

Stop execution of a thread for some time, blocking.

This function will spin-block, so only use it very short periods.

Parameters

[in] ticks the number of xtimer ticks the thread should spin for

◆ xtimer_ticks()

static xtimer_ticks32_t xtimer_ticks ( uint32_t ticks )

inlinestatic

Create an xtimer time stamp.

Parameters

[in] ticks number of xtimer ticks

Returns: xtimer time stamp

◆ xtimer_ticks64()

static xtimer_ticks64_t xtimer_ticks64 ( uint64_t ticks )

inlinestatic

Create an xtimer time stamp, 64 bit version.

Parameters

[in] ticks number of xtimer ticks

Returns: xtimer time stamp

◆ xtimer_ticks_from_usec()

static xtimer_ticks32_t xtimer_ticks_from_usec ( uint32_t usec )

inlinestatic

Convert microseconds to xtimer ticks.

Parameters

[in] usec microseconds

Returns: xtimer time stamp

◆ xtimer_ticks_from_usec64()

static xtimer_ticks64_t xtimer_ticks_from_usec64 ( uint64_t usec )

inlinestatic

Convert microseconds to xtimer ticks, 64 bit version.

Parameters

[in] usec microseconds

Returns: xtimer time stamp

◆ xtimer_tsleep32()

static void xtimer_tsleep32 ( xtimer_ticks32_t ticks )

inlinestatic

Stop execution of a thread for some time, 32bit version.

When called from an ISR, this function will spin and thus block the MCU for the specified amount, so only use it there for very short periods, e.g. less than XTIMER_BACKOFF.

Parameters

[in] ticks number of ticks the thread should sleep

◆ xtimer_tsleep64()

static void xtimer_tsleep64 ( xtimer_ticks64_t ticks )

inlinestatic

Stop execution of a thread for some time, 64bit version.

When called from an ISR, this function will spin and thus block the MCU for the specified amount, so only use it there for very short periods, e.g. less than XTIMER_BACKOFF.

Parameters

[in] ticks number of ticks the thread should sleep

◆ xtimer_usec_from_ticks()

static uint32_t xtimer_usec_from_ticks ( xtimer_ticks32_t ticks )

inlinestatic

Convert xtimer ticks to microseconds.

Parameters

[in] ticks xtimer time stamp

Returns: microseconds

◆ xtimer_usec_from_ticks64()

static uint64_t xtimer_usec_from_ticks64 ( xtimer_ticks64_t ticks )

inlinestatic

Convert xtimer ticks to microseconds, 64 bit version.

Parameters

[in] ticks xtimer time stamp

Returns: microseconds

◆ xtimer_usleep()

static void xtimer_usleep ( uint32_t microseconds )

inlinestatic

Pause the execution of a thread for some microseconds.

When called from an ISR, this function will spin and thus block the MCU for the specified amount in microseconds, so only use it there for very short periods, e.g., less than XTIMER_BACKOFF converted to µs.

Parameters

[in] microseconds the amount of microseconds the thread should sleep

◆ xtimer_usleep64()

static void xtimer_usleep64 ( uint64_t microseconds )

inlinestatic

Pause the execution of a thread for some microseconds.

See xtimer_usleep() for more information.

Parameters

[in] microseconds the amount of microseconds the thread should sleep

Detailed Description

Files

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

◆ XTIMER_BACKOFF

◆ XTIMER_ISR_BACKOFF

◆ XTIMER_MASK

◆ XTIMER_WIDTH

Function Documentation

◆ xtimer_diff()

◆ xtimer_diff32_64()

◆ xtimer_diff64()

◆ xtimer_init()

◆ xtimer_left_usec()

◆ xtimer_less()

◆ xtimer_less64()

◆ xtimer_msg_receive_timeout()

◆ xtimer_msg_receive_timeout64()

◆ xtimer_msleep()

◆ xtimer_mutex_lock_timeout()

◆ xtimer_nanosleep()

◆ xtimer_now()

◆ xtimer_now64()

◆ xtimer_now_timex()

◆ xtimer_now_usec()

◆ xtimer_now_usec64()

◆ xtimer_periodic_wakeup()

◆ xtimer_remove()

◆ xtimer_rmutex_lock_timeout()

◆ xtimer_set()

◆ xtimer_set64()

◆ xtimer_set_msg()

◆ xtimer_set_msg64()

◆ xtimer_set_timeout_flag()

◆ xtimer_set_timeout_flag64()

◆ xtimer_set_wakeup()

◆ xtimer_set_wakeup64()

◆ xtimer_sleep()

◆ xtimer_spin()

◆ xtimer_ticks()

◆ xtimer_ticks64()

◆ xtimer_ticks_from_usec()

◆ xtimer_ticks_from_usec64()

◆ xtimer_tsleep32()

◆ xtimer_tsleep64()

◆ xtimer_usec_from_ticks()

◆ xtimer_usec_from_ticks64()

◆ xtimer_usleep()

◆ xtimer_usleep64()