Loading...
Searching...
No Matches
xtimer high level timer abstraction layer (deprecated)

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.

Deprecated:
xtimer has been deprecated in favor of the ztimer high level timer abstraction layer
Note
With ztimer_xtimer_compat: xtimer wrapper a compatibility wrapper is provided that in the vast majority of cases can function as a drop-in replacement. This compatibility wrapper is expected to replace xtimer in the near future and ensure that code still depending on the xtimer API continues to function.

Note that at least for long running timers, using ztimer high level timer abstraction layer instead of the compatibility layer can yield lower clock drift and lower power consumption compared to using the compatibility layer. For details on how to achieve lower clock drift and lower power consumption please consult the ztimer high level timer abstraction layer documentation.

Files

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

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
 
#define XTIMER_ISR_BACKOFF   20
 xtimer IRQ backoff time, in hardware ticks
 
#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
 
#define XTIMER_MASK   ((0xffffffff >> XTIMER_WIDTH) << XTIMER_WIDTH)
 xtimer timer mask
 
#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   (0)
 xtimer prescaler value
 

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
 
static xtimer_ticks64_t xtimer_now64 (void)
 get the current system time as 64bit time stamp
 
void xtimer_now_timex (timex_t *out)
 get the current system time into a timex_t
 
static uint32_t xtimer_now_usec (void)
 get the current system time in microseconds since start
 
static uint64_t xtimer_now_usec64 (void)
 get the current system time in microseconds since start
 
void xtimer_init (void)
 xtimer initialization function
 
static void xtimer_sleep (uint32_t seconds)
 Pause the execution of a thread for some seconds.
 
static void xtimer_msleep (uint32_t milliseconds)
 Pause the execution of a thread for some milliseconds.
 
static void xtimer_usleep (uint32_t microseconds)
 Pause the execution of a thread for some microseconds.
 
static void xtimer_usleep64 (uint64_t microseconds)
 Pause the execution of a thread for some microseconds.
 
static void xtimer_nanosleep (uint32_t nanoseconds)
 Stop execution of a thread for some time.
 
static void xtimer_tsleep32 (xtimer_ticks32_t ticks)
 Stop execution of a thread for some time, 32bit version.
 
static void xtimer_tsleep64 (xtimer_ticks64_t ticks)
 Stop execution of a thread for some time, 64bit version.
 
static void xtimer_spin (xtimer_ticks32_t ticks)
 Stop execution of a thread for some time, blocking.
 
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).
 
static void xtimer_set_wakeup (xtimer_t *timer, uint32_t offset, kernel_pid_t pid)
 Set a timer that wakes up a thread.
 
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.
 
static void xtimer_set (xtimer_t *timer, uint32_t offset)
 Set a timer to execute a callback at some time in the future.
 
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.
 
void xtimer_remove (xtimer_t *timer)
 remove a timer
 
static bool xtimer_is_set (const xtimer_t *timer)
 state if an xtimer is currently set (waiting to be expired)
 
static xtimer_ticks32_t xtimer_ticks_from_usec (uint32_t usec)
 Convert microseconds to xtimer ticks.
 
static xtimer_ticks64_t xtimer_ticks_from_usec64 (uint64_t usec)
 Convert microseconds to xtimer ticks, 64 bit version.
 
static uint32_t xtimer_usec_from_ticks (xtimer_ticks32_t ticks)
 Convert xtimer ticks to microseconds.
 
static uint64_t xtimer_usec_from_ticks64 (xtimer_ticks64_t ticks)
 Convert xtimer ticks to microseconds, 64 bit version.
 
static xtimer_ticks32_t xtimer_ticks (uint32_t ticks)
 Create an xtimer time stamp.
 
static xtimer_ticks64_t xtimer_ticks64 (uint64_t ticks)
 Create an xtimer time stamp, 64 bit version.
 
static xtimer_ticks32_t xtimer_diff (xtimer_ticks32_t a, xtimer_ticks32_t b)
 Compute difference between two xtimer time stamps.
 
static xtimer_ticks64_t xtimer_diff64 (xtimer_ticks64_t a, xtimer_ticks64_t b)
 Compute difference between two xtimer time stamps, 64 bit version.
 
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.
 
static bool xtimer_less (xtimer_ticks32_t a, xtimer_ticks32_t b)
 Compare two xtimer time stamps.
 
static bool xtimer_less64 (xtimer_ticks64_t a, xtimer_ticks64_t b)
 Compare two xtimer time stamps, 64 bit version.
 
int xtimer_mutex_lock_timeout (mutex_t *mutex, uint64_t us)
 lock a mutex but with timeout
 
int xtimer_rmutex_lock_timeout (rmutex_t *rmutex, uint64_t us)
 lock a rmutex but with timeout
 
void xtimer_set_timeout_flag (xtimer_t *t, uint32_t timeout)
 Set timeout thread flag after timeout.
 
void xtimer_set_timeout_flag64 (xtimer_t *t, uint64_t timeout)
 Set timeout thread flag after timeout.
 
uint64_t xtimer_left_usec (const xtimer_t *timer)
 Get remaining time of timer.
 
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.
 
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.
 
static int xtimer_msg_receive_timeout (msg_t *msg, uint32_t timeout)
 receive a message blocking but with timeout
 
static int xtimer_msg_receive_timeout64 (msg_t *msg, uint64_t timeout)
 receive a message blocking but with timeout, 64bit version
 

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 561 of file xtimer.h.

◆ XTIMER_CHAN

#define XTIMER_CHAN   (0)

Underlying hardware timer channel to assign to xtimer.

Definition at line 587 of file xtimer.h.

◆ XTIMER_DEV

#define XTIMER_DEV   TIMER_DEV(0)

Underlying hardware timer device to assign to xtimer.

Definition at line 583 of file xtimer.h.

◆ XTIMER_HZ

#define XTIMER_HZ   XTIMER_HZ_BASE

Frequency of the underlying hardware timer.

Definition at line 631 of file xtimer.h.

◆ XTIMER_HZ_BASE

#define XTIMER_HZ_BASE   (1000000ul)

Base frequency of xtimer is 1 MHz.

Definition at line 625 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 573 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 617 of file xtimer.h.

◆ XTIMER_SHIFT

#define XTIMER_SHIFT   (0)

xtimer prescaler value

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

Definition at line 655 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 604 of file xtimer.h.

Typedef Documentation

◆ xtimer_callback_t

typedef void(* xtimer_callback_t) (void *)

xtimer callback type

Definition at line 92 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]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

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

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

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

Parameters
[in]aleft operand
[in]bright 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_is_set()

static bool xtimer_is_set ( const xtimer_t timer)
inlinestatic

state if an xtimer is currently set (waiting to be expired)

Parameters
[in]timerptr to timer structure to work on

◆ xtimer_left_usec()

uint64_t xtimer_left_usec ( const xtimer_t timer)

Get remaining time of timer.

Parameters
[in]timertimer 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]aleft operand
[in]bright 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]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

receive a message blocking but with timeout

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

receive a message blocking but with timeout, 64bit version

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

static void xtimer_msleep ( uint32_t  milliseconds)
inlinestatic

Pause the execution of a thread for some milliseconds.

Parameters
[in]millisecondsthe 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]mutexmutex to lock
[in]ustimeout 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.

Deprecated:
This function is deprecated as no XTIMER backend is currently configured to run at more than 1 MHz, making nanoseconds accuracy impossible to achieve.

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

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]outpointer 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_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)

remove a 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_rmutex_lock_timeout()

int xtimer_rmutex_lock_timeout ( rmutex_t rmutex,
uint64_t  us 
)

lock a rmutex but with timeout

Parameters
[in]rmutexrmutex to lock
[in]ustimeout 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]timerthe timer structure to use.
[in]offsettime 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]timerthe timer structure to use.
[in]offset_ustime 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]timertimer struct to work with.
[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

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]timertimer struct to work with.
[in]offsetmicroseconds from now
[in]msgptr to msg that will be sent
[in]target_pidpid 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]ttimer struct to use
[in]timeouttimeout 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]ttimer struct to use
[in]timeouttimeout 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]timertimer struct to work with.
[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

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]timertimer struct to work with.
[in]offsetmicroseconds from now
[in]pidpid 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]secondsthe 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]ticksthe 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]ticksnumber 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]ticksnumber 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]usecmicroseconds
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]usecmicroseconds
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]ticksnumber 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]ticksnumber 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]ticksxtimer 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]ticksxtimer 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]microsecondsthe 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]microsecondsthe amount of microseconds the thread should sleep