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

Detailed Description

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_OVERHEAD   20
 xtimer overhead value, in hardware ticks More...
 
#define XTIMER_ISR_BACKOFF   20
 xtimer IRQ backoff time, in hardware ticks More...
 
#define XTIMER_PERIODIC_SPIN   (XTIMER_BACKOFF * 2)
 xtimer_periodic_wakeup spin cutoff More...
 
#define XTIMER_PERIODIC_RELATIVE   (512)
 xtimer_periodic_wakeup relative target cutoff More...
 
#define XTIMER_SHIFT   (0)
 xtimer prescaler value 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   1000000ul
 Frequency of the underlying hardware timer.
 

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_usleep (uint32_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_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 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...
 
void xtimer_remove (xtimer_t *timer)
 remove a timer 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...
 
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...
 

Macro Definition Documentation

◆ XTIMER_BACKOFF

#define XTIMER_BACKOFF   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.

Definition at line 451 of file xtimer.h.

◆ XTIMER_ISR_BACKOFF

#define XTIMER_ISR_BACKOFF   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.

Definition at line 486 of file xtimer.h.

◆ XTIMER_MASK

#define XTIMER_MASK   ((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.

Definition at line 571 of file xtimer.h.

◆ XTIMER_OVERHEAD

#define XTIMER_OVERHEAD   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_now(); xtimer_set(&timer, X); (in callback:) overhead=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.

Definition at line 474 of file xtimer.h.

◆ XTIMER_PERIODIC_RELATIVE

#define XTIMER_PERIODIC_RELATIVE   (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.

Definition at line 509 of file xtimer.h.

◆ XTIMER_PERIODIC_SPIN

#define XTIMER_PERIODIC_SPIN   (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.

Definition at line 496 of file xtimer.h.

◆ XTIMER_SHIFT

#define XTIMER_SHIFT   (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 4 MHz hardware timer, set XTIMER_SHIFT to 2. For a 16 MHz hardware timer, set XTIMER_SHIFT to 4. For a 250 kHz hardware timer, set XTIMER_SHIFT to 2.

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

Definition at line 527 of file xtimer.h.

◆ XTIMER_WIDTH

#define XTIMER_WIDTH   (32)

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

Definition at line 558 of file xtimer.h.

Function Documentation

◆ xtimer_diff()

static xtimer_ticks32_t xtimer_diff ( xtimer_ticks32_t  a,
xtimer_ticks32_t  b 
)
inlinestatic
Parameters
[in]aleft operand
[in]bright operand
Returns
a - b

◆ xtimer_diff32_64()

static xtimer_ticks32_t xtimer_diff32_64 ( xtimer_ticks64_t  a,
xtimer_ticks64_t  b 
)
inlinestatic
Parameters
[in]aleft operand
[in]bright 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
Parameters
[in]aleft operand
[in]bright operand
Returns
a - b

◆ xtimer_init()

void xtimer_init ( void  )

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

◆ xtimer_less()

static bool xtimer_less ( xtimer_ticks32_t  a,
xtimer_ticks32_t  b 
)
inlinestatic
Parameters
[in]aleft operand
[in]bright operand
Returns
a < b

◆ xtimer_less64()

static bool xtimer_less64 ( xtimer_ticks64_t  a,
xtimer_ticks64_t  b 
)
inlinestatic
Parameters
[in]aleft operand
[in]bright operand
Returns
a < b

◆ xtimer_msg_receive_timeout()

static int xtimer_msg_receive_timeout ( msg_t msg,
uint32_t  timeout 
)
inlinestatic
Parameters
[out]msgpointer to a msg_t which will be filled in case of no timeout
[in]timeouttimeout 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
Parameters
[out]msgpointer to a msg_t which will be filled in case of no timeout
[in]timeouttimeout in microseconds relative
Returns
< 0 on error, other value otherwise

◆ xtimer_mutex_lock_timeout()

int xtimer_mutex_lock_timeout ( mutex_t mutex,
uint64_t  us 
)
Note
this requires core_thread_flags to be enabled
Parameters
[in]mutexmutex to lock
[in]ustimeout in microseconds relative
Returns
0, when returned after mutex was locked
-1, when the timeout occcured

◆ xtimer_nanosleep()

static void xtimer_nanosleep ( uint32_t  nanoseconds)
inlinestatic

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]nanosecondsthe amount of nanoseconds the thread should sleep

◆ xtimer_now()

static xtimer_ticks32_t xtimer_now ( void  )
inlinestatic
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
Returns
current time as 64bit time stamp

◆ xtimer_now_timex()

void xtimer_now_timex ( timex_t out)
Parameters
[out]outpointer to timex_t the time will be written to

◆ xtimer_now_usec()

static uint32_t xtimer_now_usec ( void  )
inlinestatic

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

◆ xtimer_now_usec64()

static uint64_t xtimer_now_usec64 ( void  )
inlinestatic

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

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_wakeupbase time stamp for the wakeup
[in]periodtime in microseconds that will be added to last_wakeup

◆ xtimer_remove()

void xtimer_remove ( xtimer_t timer)
Note
this function runs in O(n) with n being the number of active timers
Parameters
[in]timerptr to timer structure that will be removed

◆ xtimer_set()

static void xtimer_set ( xtimer_t timer,
uint32_t  offset 
)
inlinestatic

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). DON'T USE THIS FUNCTION unless you know exactly what that means.
Parameters
[in]timerthe timer structure to use. Its xtimer_t::target and xtimer_t::long_target fields need to be initialized with 0 on first use
[in]offsettime 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

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
[in]timertimer struct to work with. Its xtimer_t::target and xtimer_t::long_target fields need to be initialized with 0 on first use.
[in]offsetmicroseconds from now
[in]msgptr to msg that will be sent
[in]target_pidpid 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

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
[in]timertimer struct to work with. Its xtimer_t::target and xtimer_t::long_target fields need to be initialized with 0 on first use.
[in]offsetmicroseconds from now
[in]msgptr to msg that will be sent
[in]target_pidpid the message will be sent to

◆ xtimer_set_wakeup()

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

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

Parameters
[in]timertimer struct to work with. Its xtimer_t::target and xtimer_t::long_target fields need to be initialized with 0 on first use
[in]offsetmicroseconds from now
[in]pidpid 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

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

Parameters
[in]timertimer struct to work with. Its xtimer_t::target and xtimer_t::long_target fields need to be initialized with 0 on first use
[in]offsetmicroseconds from now
[in]pidpid of the thread that will be woken up

◆ xtimer_sleep()

static void xtimer_sleep ( uint32_t  seconds)
inlinestatic

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]secondsthe amount of seconds the thread should sleep

◆ xtimer_spin()

static void xtimer_spin ( xtimer_ticks32_t  ticks)
inlinestatic

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

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

◆ xtimer_ticks()

static xtimer_ticks32_t xtimer_ticks ( uint32_t  ticks)
inlinestatic
Parameters
[in]ticksnumber of xtimer ticks
Returns
xtimer time stamp

◆ xtimer_ticks64()

static xtimer_ticks64_t xtimer_ticks64 ( uint64_t  ticks)
inlinestatic
Parameters
[in]ticksnumber of xtimer ticks
Returns
xtimer time stamp

◆ xtimer_ticks_from_usec()

static xtimer_ticks32_t xtimer_ticks_from_usec ( uint32_t  usec)
inlinestatic
Parameters
[in]usecmicroseconds
Returns
xtimer time stamp

◆ xtimer_ticks_from_usec64()

static xtimer_ticks64_t xtimer_ticks_from_usec64 ( uint64_t  usec)
inlinestatic
Parameters
[in]usecmicroseconds
Returns
xtimer time stamp

◆ xtimer_tsleep32()

static void xtimer_tsleep32 ( xtimer_ticks32_t  ticks)
inlinestatic

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]ticksnumber of ticks the thread should sleep

◆ xtimer_tsleep64()

static void xtimer_tsleep64 ( xtimer_ticks64_t  ticks)
inlinestatic

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]ticksnumber of ticks the thread should sleep

◆ xtimer_usec_from_ticks()

static uint32_t xtimer_usec_from_ticks ( xtimer_ticks32_t  ticks)
inlinestatic
Parameters
[in]ticksxtimer time stamp
Returns
microseconds

◆ xtimer_usec_from_ticks64()

static uint64_t xtimer_usec_from_ticks64 ( xtimer_ticks64_t  ticks)
inlinestatic
Parameters
[in]ticksxtimer time stamp
Returns
microseconds

◆ xtimer_usleep()

static void xtimer_usleep ( uint32_t  microseconds)
inlinestatic

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
[in]microsecondsthe amount of microseconds the thread should sleep