xtimer.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2015 Kaspar Schleiser <kaspar@schleiser.de>
3  * Copyright (C) 2016 Eistec AB
4  *
5  * This file is subject to the terms and conditions of the GNU Lesser
6  * General Public License v2.1. See the file LICENSE in the top level
7  * directory for more details.
8  */
9 
29 #ifndef XTIMER_H
30 #define XTIMER_H
31 
32 #include <stdbool.h>
33 #include <stdint.h>
34 #include "timex.h"
35 #ifdef MODULE_CORE_MSG
36 #include "msg.h"
37 #endif /* MODULE_CORE_MSG */
38 #include "mutex.h"
39 #include "sched.h"
40 #include "rmutex.h"
41 
42 #ifdef MODULE_ZTIMER_XTIMER_COMPAT
43 #include "ztimer/xtimer_compat.h"
44 #else
45 
46 #include "board.h"
47 #ifndef MODULE_XTIMER_ON_ZTIMER
48 #include "periph_conf.h"
49 #endif
50 
51 #ifdef __cplusplus
52 extern "C" {
53 #endif
54 
60 typedef struct {
61  uint64_t ticks64;
63 
69 typedef struct {
70  uint32_t ticks32;
72 
76 typedef void (*xtimer_callback_t)(void*);
77 
81 typedef struct xtimer {
82  struct xtimer *next;
83  uint32_t offset;
84  uint32_t long_offset;
85  uint32_t start_time;
86  uint32_t long_start_time;
89  void *arg;
91 
100 static inline xtimer_ticks32_t xtimer_now(void);
101 
107 static inline xtimer_ticks64_t xtimer_now64(void);
108 
115 
121 static inline uint32_t xtimer_now_usec(void);
122 
128 static inline uint64_t xtimer_now_usec64(void);
129 
136 void xtimer_init(void);
137 
147 static inline void xtimer_sleep(uint32_t seconds);
148 
154 static inline void xtimer_msleep(uint32_t milliseconds);
155 
165 static inline void xtimer_usleep(uint32_t microseconds);
166 
174 static inline void xtimer_usleep64(uint64_t microseconds);
175 
191 static inline void xtimer_nanosleep(uint32_t nanoseconds);
192 
202 static inline void xtimer_tsleep32(xtimer_ticks32_t ticks);
203 
213 static inline void xtimer_tsleep64(xtimer_ticks64_t ticks);
214 
222 static inline void xtimer_spin(xtimer_ticks32_t ticks);
223 
241 static inline void xtimer_periodic_wakeup(xtimer_ticks32_t *last_wakeup, uint32_t period);
242 
253 static inline void xtimer_set_wakeup(xtimer_t *timer, uint32_t offset, kernel_pid_t pid);
254 
265 static inline void xtimer_set_wakeup64(xtimer_t *timer, uint64_t offset, kernel_pid_t pid);
266 
283 static inline void xtimer_set(xtimer_t *timer, uint32_t offset);
284 
302 static inline void xtimer_set64(xtimer_t *timer, uint64_t offset_us);
303 
311 void xtimer_remove(xtimer_t *timer);
312 
320 static inline xtimer_ticks32_t xtimer_ticks_from_usec(uint32_t usec);
321 
329 static inline xtimer_ticks64_t xtimer_ticks_from_usec64(uint64_t usec);
330 
338 static inline uint32_t xtimer_usec_from_ticks(xtimer_ticks32_t ticks);
339 
347 static inline uint64_t xtimer_usec_from_ticks64(xtimer_ticks64_t ticks);
348 
356 static inline xtimer_ticks32_t xtimer_ticks(uint32_t ticks);
357 
365 static inline xtimer_ticks64_t xtimer_ticks64(uint64_t ticks);
366 
376 
386 
396 
406 
416 
426 int xtimer_mutex_lock_timeout(mutex_t *mutex, uint64_t us);
427 
437 int xtimer_rmutex_lock_timeout(rmutex_t *rmutex, uint64_t us);
438 
439 #if defined(MODULE_CORE_THREAD_FLAGS) || defined(DOXYGEN)
440 
450 void xtimer_set_timeout_flag(xtimer_t *t, uint32_t timeout);
451 
460 void xtimer_set_timeout_flag64(xtimer_t *t, uint64_t timeout);
461 #endif
462 
471 uint64_t xtimer_left_usec(const xtimer_t *timer);
472 
473 #if defined(MODULE_CORE_MSG) || defined(DOXYGEN)
488 static inline void xtimer_set_msg(xtimer_t *timer, uint32_t offset, msg_t *msg, kernel_pid_t target_pid);
489 
504 static inline void xtimer_set_msg64(xtimer_t *timer, uint64_t offset, msg_t *msg, kernel_pid_t target_pid);
505 
515 static inline int xtimer_msg_receive_timeout(msg_t *msg, uint32_t timeout);
516 
526 static inline int xtimer_msg_receive_timeout64(msg_t *msg, uint64_t timeout);
527 #endif
528 
537 #ifndef XTIMER_BACKOFF
538 #define XTIMER_BACKOFF 30
539 #endif
540 
541 #ifndef XTIMER_ISR_BACKOFF
550 #define XTIMER_ISR_BACKOFF 20
551 #endif
552 
553 /*
554  * Default xtimer configuration
555  */
556 #ifndef XTIMER_DEV
560 #define XTIMER_DEV TIMER_DEV(0)
564 #define XTIMER_CHAN (0)
565 
566 #if (TIMER_0_MAX_VALUE) == 0xfffffful
567 #define XTIMER_WIDTH (24)
568 #elif (TIMER_0_MAX_VALUE) == 0xffff
569 #define XTIMER_WIDTH (16)
570 #endif
571 
572 #endif
573 
574 #ifndef XTIMER_WIDTH
581 #define XTIMER_WIDTH (32)
582 #endif
583 
584 #if (XTIMER_WIDTH != 32) || DOXYGEN
594 #define XTIMER_MASK ((0xffffffff >> XTIMER_WIDTH) << XTIMER_WIDTH)
595 #else
596 #define XTIMER_MASK (0)
597 #endif
598 
602 #define XTIMER_HZ_BASE (1000000ul)
603 
604 #if !defined(XTIMER_HZ) && !defined(MODULE_XTIMER_ON_ZTIMER)
608 #define XTIMER_HZ XTIMER_HZ_BASE
609 #endif
610 
611 #if !defined(XTIMER_SHIFT) && !defined(MODULE_XTIMER_ON_ZTIMER)
612 #if (XTIMER_HZ == 32768ul)
613 /* No shift necessary, the conversion is not a power of two and is handled by
614  * functions in tick_conversion.h */
615 #define XTIMER_SHIFT (0)
616 #elif (XTIMER_HZ == XTIMER_HZ_BASE)
632 #define XTIMER_SHIFT (0)
633 #elif (XTIMER_HZ >> 1 == XTIMER_HZ_BASE) || (XTIMER_HZ << 1 == XTIMER_HZ_BASE)
634 #define XTIMER_SHIFT (1)
635 #elif (XTIMER_HZ >> 2 == XTIMER_HZ_BASE) || (XTIMER_HZ << 2 == XTIMER_HZ_BASE)
636 #define XTIMER_SHIFT (2)
637 #elif (XTIMER_HZ >> 3 == XTIMER_HZ_BASE) || (XTIMER_HZ << 3 == XTIMER_HZ_BASE)
638 #define XTIMER_SHIFT (3)
639 #elif (XTIMER_HZ >> 4 == XTIMER_HZ_BASE) || (XTIMER_HZ << 4 == XTIMER_HZ_BASE)
640 #define XTIMER_SHIFT (4)
641 #elif (XTIMER_HZ >> 5 == XTIMER_HZ_BASE) || (XTIMER_HZ << 5 == XTIMER_HZ_BASE)
642 #define XTIMER_SHIFT (5)
643 #elif (XTIMER_HZ >> 6 == XTIMER_HZ_BASE) || (XTIMER_HZ << 6 == XTIMER_HZ_BASE)
644 #define XTIMER_SHIFT (6)
645 #else
646 #error "XTIMER_SHIFT cannot be derived for given XTIMER_HZ, verify settings!"
647 #endif
648 #elif !defined(MODULE_XTIMER_ON_ZTIMER)
649 #error "XTIMER_SHIFT is set relative to XTIMER_HZ, no manual define required!"
650 #endif
651 
652 #include "xtimer/tick_conversion.h"
653 
654 #include "xtimer/implementation.h"
655 
656 #ifdef __cplusplus
657 }
658 #endif
659 
660 #endif /* MODULE_ZTIMER_XTIMER_COMPAT */
661 
663 #endif /* XTIMER_H */
int16_t kernel_pid_t
Unique process identifier.
Definition: sched.h:134
void xtimer_set_timeout_flag64(xtimer_t *t, uint64_t timeout)
Set timeout thread flag after timeout.
static void xtimer_usleep(uint32_t microseconds)
Pause the execution of a thread for some microseconds.
static xtimer_ticks32_t xtimer_diff(xtimer_ticks32_t a, xtimer_ticks32_t b)
Compute difference between two xtimer time stamps.
static uint32_t xtimer_now_usec(void)
get the current system time in microseconds since start
static xtimer_ticks64_t xtimer_ticks_from_usec64(uint64_t usec)
Convert microseconds to xtimer ticks, 64 bit version.
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.
void xtimer_remove(xtimer_t *timer)
remove a timer
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 bool xtimer_less64(xtimer_ticks64_t a, xtimer_ticks64_t b)
Compare two xtimer time stamps, 64 bit version.
static xtimer_ticks64_t xtimer_now64(void)
get the current system time as 64bit time stamp
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_callback_t)(void *)
xtimer callback type
Definition: xtimer.h:76
static void xtimer_tsleep32(xtimer_ticks32_t ticks)
Stop execution of a thread for some time, 32bit version.
static void xtimer_msleep(uint32_t milliseconds)
Pause the execution of a thread for some milliseconds.
static void xtimer_sleep(uint32_t seconds)
Pause the execution of a thread for some seconds.
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.
int xtimer_rmutex_lock_timeout(rmutex_t *rmutex, uint64_t us)
lock a rmutex but with timeout
static xtimer_ticks64_t xtimer_ticks64(uint64_t ticks)
Create an xtimer time stamp, 64 bit version.
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_msg(xtimer_t *timer, uint32_t offset, msg_t *msg, kernel_pid_t target_pid)
Set a timer that sends a message.
static bool xtimer_less(xtimer_ticks32_t a, xtimer_ticks32_t b)
Compare two xtimer time stamps.
static uint32_t xtimer_usec_from_ticks(xtimer_ticks32_t ticks)
Convert xtimer ticks to microseconds.
static xtimer_ticks64_t xtimer_diff64(xtimer_ticks64_t a, xtimer_ticks64_t b)
Compute difference between two xtimer time stamps, 64 bit version.
int xtimer_mutex_lock_timeout(mutex_t *mutex, uint64_t us)
lock a mutex but with timeout
static void xtimer_usleep64(uint64_t microseconds)
Pause the execution of a thread for some microseconds.
static int xtimer_msg_receive_timeout(msg_t *msg, uint32_t timeout)
receive a message blocking but with timeout
void xtimer_now_timex(timex_t *out)
get the current system time into a timex_t
void xtimer_set_timeout_flag(xtimer_t *t, uint32_t timeout)
Set timeout thread flag after timeout.
static void xtimer_tsleep64(xtimer_ticks64_t ticks)
Stop execution of a thread for some time, 64bit version.
static void xtimer_nanosleep(uint32_t nanoseconds)
Stop execution of a thread for some time.
static void xtimer_set_wakeup(xtimer_t *timer, uint32_t offset, kernel_pid_t pid)
Set a timer that wakes up a thread.
void xtimer_init(void)
xtimer initialization function
static void xtimer_spin(xtimer_ticks32_t ticks)
Stop execution of a thread for some time, blocking.
static uint64_t xtimer_now_usec64(void)
get the current system time in microseconds since start
static void xtimer_set(xtimer_t *timer, uint32_t offset)
Set a timer to execute a callback at some time in the future.
static xtimer_ticks32_t xtimer_ticks_from_usec(uint32_t usec)
Convert microseconds to xtimer ticks.
struct xtimer xtimer_t
xtimer timer structure
static xtimer_ticks32_t xtimer_ticks(uint32_t ticks)
Create an xtimer time stamp.
static xtimer_ticks32_t xtimer_now(void)
get the current system time as 32bit time stamp value
static uint64_t xtimer_usec_from_ticks64(xtimer_ticks64_t ticks)
Convert xtimer ticks to microseconds, 64 bit version.
static int xtimer_msg_receive_timeout64(msg_t *msg, uint64_t timeout)
receive a message blocking but with timeout, 64bit version
uint64_t xtimer_left_usec(const xtimer_t *timer)
Get remaining time of timer.
xtimer implementation
Mutex for thread synchronization.
Recursive Mutex for thread synchronization.
Scheduler API definition.
Describes a message object which can be sent between threads.
Definition: msg.h:185
Mutex structure.
Definition: mutex.h:123
Mutex structure.
Definition: rmutex.h:43
A timex timestamp.
Definition: timex.h:49
xtimer timestamp (32 bit)
Definition: xtimer.h:69
uint32_t ticks32
Tick count.
Definition: xtimer.h:70
xtimer timestamp (64 bit)
Definition: xtimer.h:60
uint64_t ticks64
Tick count.
Definition: xtimer.h:61
xtimer timer structure
Definition: xtimer.h:81
uint32_t long_offset
upper 32bit offset time
Definition: xtimer.h:84
struct xtimer * next
reference to next timer in timer lists
Definition: xtimer.h:82
void * arg
argument to pass to callback function
Definition: xtimer.h:89
uint32_t start_time
lower 32bit absolute start time
Definition: xtimer.h:85
uint32_t long_start_time
upper 32bit absolute start time
Definition: xtimer.h:86
xtimer_callback_t callback
callback function to call when timer expires
Definition: xtimer.h:87
uint32_t offset
lower 32bit offset time
Definition: xtimer.h:83
xtimer tick <-> seconds conversions for different values of XTIMER_HZ
Utility library for comparing and computing timestamps.
ztimer xtimer wrapper interface