Timers

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.

void(* xtimer_callback_t()

xtimer callback type

struct xtimer xtimer_t

xtimer timer structure

xtimer_ticks32_t xtimer_now(void)

get the current system time as 32bit time stamp value

Note

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

Return values

  • current time as 32bit time stamp
xtimer_ticks64_t xtimer_now64(void)

get the current system time as 64bit time stamp

Return values

  • current time as 64bit time stamp
void xtimer_now_timex(timex_t * out)

get the current system time into a timex_t

Parameters

out:pointer to timex_t the time will be written to

uint32_t xtimer_now_usec(void)

get the current system time in microseconds since start

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

uint64_t xtimer_now_usec64(void)

get the current system time in microseconds since start

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

void xtimer_init(void)

xtimer initialization function

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

void xtimer_sleep(uint32_t seconds)

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

seconds:the amount of seconds the thread should sleep

void xtimer_usleep(uint32_t microseconds)

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.

Parameters

microseconds:the amount of microseconds the thread should sleep

void xtimer_nanosleep(uint32_t nanoseconds)

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

nanoseconds:the amount of nanoseconds the thread should sleep

void xtimer_tsleep32(xtimer_ticks32_t ticks)

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

ticks:number of ticks the thread should sleep

void xtimer_tsleep64(xtimer_ticks64_t ticks)

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

ticks:number of ticks the thread should sleep

void xtimer_spin(xtimer_ticks32_t ticks)

Stop execution of a thread for some time, blocking.

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

Parameters

ticks:the number of xtimer ticks the thread should spin for

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

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

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

void xtimer_set_msg(xtimer.h::xtimer_t * timer, uint32_t offset, msg_t * msg, kernel_types.h::kernel_pid_t target_pid)

Set a timer that sends a message.

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

The mesage 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

timer:timer struct to work with. Its xtimer.h::xtimer::target and xtimer.h::xtimer::long_target fields need to be initialized with 0 on first use.
offset:microseconds from now
msg:ptr to msg that will be sent
target_pid:pid the message will be sent to

void xtimer_set_msg64(xtimer.h::xtimer_t * timer, uint64_t offset, msg_t * msg, kernel_types.h::kernel_pid_t target_pid)

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

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

The mesage 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

timer:timer struct to work with. Its xtimer.h::xtimer::target and xtimer.h::xtimer::long_target fields need to be initialized with 0 on first use.
offset:microseconds from now
msg:ptr to msg that will be sent
target_pid:pid the message will be sent to

void xtimer_set_wakeup(xtimer.h::xtimer_t * timer, uint32_t offset, kernel_types.h::kernel_pid_t pid)

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

timer:timer struct to work with. Its xtimer.h::xtimer::target and xtimer.h::xtimer::long_target fields need to be initialized with 0 on first use
offset:microseconds from now
pid:pid of the thread that will be woken up

void xtimer_set_wakeup64(xtimer.h::xtimer_t * timer, uint64_t offset, kernel_types.h::kernel_pid_t pid)

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

timer:timer struct to work with. Its xtimer.h::xtimer::target and xtimer.h::xtimer::long_target fields need to be initialized with 0 on first use
offset:microseconds from now
pid:pid of the thread that will be woken up

void xtimer_set(xtimer.h::xtimer_t * timer, uint32_t offset)

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.

Parameters

timer:the timer structure to use. Its xtimer.h::xtimer::target and xtimer.h::xtimer::long_target fields need to be initialized with 0 on first use
offset:time in microseconds from now specifying that timer’s callback’s execution time

void xtimer_set64(xtimer.h::xtimer_t * timer, uint64_t offset_us)

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.

Parameters

timer:the timer structure to use. Its xtimer.h::xtimer::target and xtimer.h::xtimer::long_target fields need to be initialized with 0 on first use
offset_us:time in microseconds from now specifying that timer’s callback’s execution time

void xtimer_remove(xtimer.h::xtimer_t * timer)

remove a timer

Note

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

Parameters

timer:ptr to timer structure that will be removed

int xtimer_msg_receive_timeout(msg_t * msg, uint32_t timeout)

receive a message blocking but with timeout

Parameters

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

Return values

  • < 0 on error, other value otherwise
int xtimer_msg_receive_timeout64(msg_t * msg, uint64_t timeout)

receive a message blocking but with timeout, 64bit version

Parameters

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

Return values

  • < 0 on error, other value otherwise
xtimer_ticks32_t xtimer_ticks_from_usec(uint32_t usec)

Convert microseconds to xtimer ticks.

Parameters

usec:microseconds

Return values

  • xtimer time stamp
xtimer_ticks64_t xtimer_ticks_from_usec64(uint64_t usec)

Convert microseconds to xtimer ticks, 64 bit version.

Parameters

usec:microseconds

Return values

  • xtimer time stamp
uint32_t xtimer_usec_from_ticks(xtimer_ticks32_t ticks)

Convert xtimer ticks to microseconds.

Parameters

ticks:xtimer time stamp

Return values

  • microseconds
uint64_t xtimer_usec_from_ticks64(xtimer_ticks64_t ticks)

Convert xtimer ticks to microseconds, 64 bit version.

Parameters

ticks:xtimer time stamp

Return values

  • microseconds
xtimer_ticks32_t xtimer_ticks(uint32_t ticks)

Create an xtimer time stamp.

Parameters

ticks:number of xtimer ticks

Return values

  • xtimer time stamp
xtimer_ticks64_t xtimer_ticks64(uint64_t ticks)

Create an xtimer time stamp, 64 bit version.

Parameters

ticks:number of xtimer ticks

Return values

  • xtimer time stamp
xtimer_ticks32_t xtimer_diff(xtimer_ticks32_t a, xtimer_ticks32_t b)

Compute difference between two xtimer time stamps.

Parameters

a:left operand
b:right operand

Return values

  • a - b
xtimer_ticks64_t xtimer_diff64(xtimer_ticks64_t a, xtimer_ticks64_t b)

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

Parameters

a:left operand
b:right operand

Return values

  • a - b
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.

Parameters

a:left operand
b:right operand

Return values

  • a - b cast truncated to 32 bit
bool xtimer_less(xtimer_ticks32_t a, xtimer_ticks32_t b)

Compare two xtimer time stamps.

Parameters

a:left operand
b:right operand

Return values

  • a < b
bool xtimer_less64(xtimer_ticks64_t a, xtimer_ticks64_t b)

Compare two xtimer time stamps, 64 bit version.

Parameters

a:left operand
b:right operand

Return values

  • a < b
int xtimer_mutex_lock_timeout(mutex_t * mutex, uint64_t us)

lock a mutex but with timeout

Note

this requires core_thread_flags to be enabled

Parameters

mutex:mutex to lock
us:timeout in microseconds relative

Return values

  • 0, when returned after mutex was locked
  • -1, when the timeout occcured
void xtimer_set_timeout_flag(xtimer.h::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

t:timer struct to use
timeout:timeout in usec

XTIMER_BACKOFF

xtimer backoff value 

1
30

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

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

XTIMER_OVERHEAD

xtimer overhead value, in hardware ticks 

1
20

This value specifies the time a timer will be late if uncorrected, e.g., the system-specific xtimer execution time from timer ISR to executing a timer’s callback’s first instruction.

E.g., with XTIMER_OVERHEAD == 0 start=xtimer.h::xtimer_now(); xtimer_set(&timer, X); (in callback:) overhead=xtimer.h::xtimer_now()-start-X;

xtimer automatically substracts XTIMER_OVERHEAD from a timer’s target time, but when the timer triggers, xtimer will spin-lock until a timer’s target time is reached, so timers will never trigger early.

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

XTIMER_ISR_BACKOFF

xtimer IRQ backoff time, in hardware ticks 

1
20

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.

XTIMER_PERIODIC_SPIN

xtimer_periodic_wakeup spin cutoff 

1
(XTIMER_BACKOFF * 2)

If the difference between target time and now is less than this value, then xtimer_periodic_wakeup will use xtimer_spin instead of setting a timer.

XTIMER_PERIODIC_RELATIVE

xtimer_periodic_wakeup relative target cutoff 

1
(512)

If the difference between target time and now is less than this value, then xtimer_periodic_wakeup will set a relative target time in the future instead of the true target.

This is done to prevent target time underflows.

XTIMER_DEV

Underlying hardware timer device to assign to xtimer. 

1
TIMER_DEV(0)
XTIMER_CHAN

Underlying hardware timer channel to assign to xtimer. 

1
(0)
XTIMER_WIDTH

xtimer timer width 

1
(32)

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

XTIMER_MASK

xtimer timer mask 

1
((0xffffffff >> XTIMER_WIDTH) << XTIMER_WIDTH)

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.

XTIMER_HZ_BASE

Base frequency of xtimer is 1 MHz. 

1
(1000000ul)
XTIMER_HZ

Frequency of the underlying hardware timer. 

1
XTIMER_HZ_BASE
XTIMER_SHIFT

xtimer prescaler value 

1
(0)

If the underlying hardware timer is running at a power of two multiple of 15625, XTIMER_SHIFT can be used to adjust the difference.

For a 1 MHz hardware timer, set XTIMER_SHIFT to 0. For a 2 MHz or 500 kHz, set XTIMER_SHIFT to 1. For a 4 MHz or 250 kHz, set XTIMER_SHIFT to 2. For a 8 MHz or 125 kHz, set XTIMER_SHIFT to 3. For a 16 MHz or 62.5 kHz, set XTIMER_SHIFT to 4. and for 32 MHz, set XTIMER_SHIFT to 5.

The direction of the shift is handled by the macros in tick_conversion.h

struct xtimer_ticks64_t

xtimer timestamp (64 bit)

Note

This is a struct in order to make the xtimer API type strict

uint64_t ticks64

Tick count.

struct xtimer_ticks32_t

xtimer timestamp (32 bit)

Note

This is a struct in order to make the xtimer API type strict

uint32_t ticks32

Tick count.

struct xtimer

xtimer timer structure

struct xtimer * next

reference to next timer in timer lists

uint32_t target

lower 32bit absolute target time

uint32_t long_target

upper 32bit absolute target time

xtimer.h::xtimer_callback_t callback

callback function to call when timer expires

void * arg

argument to pass to callback function