ztimer.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2018 Kaspar Schleiser <kaspar@schleiser.de>
3  *
4  * This file is subject to the terms and conditions of the GNU Lesser
5  * General Public License v2.1. See the file LICENSE in the top level
6  * directory for more details.
7  */
262 #ifndef ZTIMER_H
263 #define ZTIMER_H
264 
265 #include <stdint.h>
266 
267 #include "sched.h"
268 #include "msg.h"
269 #include "mutex.h"
270 #include "rmutex.h"
271 
272 #ifdef __cplusplus
273 extern "C" {
274 #endif
275 
279 #define ZTIMER_CLOCK_NO_REQUIRED_PM_MODE (UINT8_MAX)
280 
284 typedef struct ztimer_base ztimer_base_t;
285 
289 typedef struct ztimer_clock ztimer_clock_t;
290 
294 typedef void (*ztimer_callback_t)(void *arg);
295 
299 struct ztimer_base {
301  uint32_t offset;
302 };
303 
320 #if MODULE_ZTIMER_NOW64
321 typedef uint64_t ztimer_now_t;
322 #else
323 typedef uint32_t ztimer_now_t;
324 #endif
325 
332 typedef struct {
335  void *arg;
336 } ztimer_t;
337 
345 typedef struct {
351  void (*set)(ztimer_clock_t *clock, uint32_t val);
352 
357  uint32_t (*now)(ztimer_clock_t *clock);
358 
363  void (*cancel)(ztimer_clock_t *clock);
364 } ztimer_ops_t;
365 
369 struct ztimer_clock {
371  const ztimer_ops_t *ops;
373  uint16_t adjust_set;
374  uint16_t adjust_sleep;
376 #if MODULE_ZTIMER_EXTEND || MODULE_ZTIMER_NOW64 || DOXYGEN
377  /* values used for checkpointed intervals and 32bit extension */
378  uint32_t max_value;
379  uint32_t lower_last;
381 #endif
382 #if MODULE_PM_LAYERED || DOXYGEN
383  uint8_t block_pm_mode;
384 #endif
385 };
386 
394 
395 /* User API */
412 uint32_t ztimer_set(ztimer_clock_t *clock, ztimer_t *timer, uint32_t val);
413 
423 unsigned ztimer_is_set(const ztimer_clock_t *clock, const ztimer_t *timer);
424 
442 bool ztimer_remove(ztimer_clock_t *clock, ztimer_t *timer);
443 
459 void ztimer_set_msg(ztimer_clock_t *clock, ztimer_t *timer, uint32_t offset,
460  msg_t *msg, kernel_pid_t target_pid);
461 
480  uint32_t timeout);
481 
482 /* created with dist/tools/define2u16.py */
483 #define MSG_ZTIMER 0xc83e
494 
601 {
602 #if MODULE_ZTIMER_NOW64
603  if (1) {
604 #elif MODULE_ZTIMER_EXTEND
605  if (clock->max_value < UINT32_MAX) {
606 #else
607  if (0) {
608 #endif
609  return _ztimer_now_extend(clock);
610  }
611  else {
612  return clock->ops->now(clock);
613  }
614 }
615 
634 void ztimer_periodic_wakeup(ztimer_clock_t *clock, uint32_t *last_wakeup,
635  uint32_t period);
636 
643 void ztimer_sleep(ztimer_clock_t *clock, uint32_t duration);
644 
653 static inline void ztimer_spin(ztimer_clock_t *clock, uint32_t duration)
654 {
655  uint32_t end = ztimer_now(clock) + duration;
656 
657  /* Rely on integer overflow. `end - now` will be smaller than `duration`,
658  * counting down, until it underflows to UINT32_MAX. Loop ends then. */
659  while ((end - ztimer_now(clock)) <= duration) {}
660 }
661 
673 void ztimer_set_wakeup(ztimer_clock_t *clock, ztimer_t *timer, uint32_t offset,
674  kernel_pid_t pid);
675 
687  uint32_t timeout);
688 
700  uint32_t timeout);
701 
713  uint32_t timeout);
714 
718 void ztimer_init(void);
719 
720 #if defined(MODULE_ZTIMER_EXTEND) || defined(DOXYGEN)
731 static inline void ztimer_init_extend(ztimer_clock_t *clock)
732 {
733  if (clock->max_value < UINT32_MAX) {
734  clock->ops->set(clock, clock->max_value >> 1);
735  }
736 }
737 #endif /* MODULE_ZTIMER_EXTEND */
738 
739 /* default ztimer virtual devices */
743 extern ztimer_clock_t *const ZTIMER_USEC;
744 
748 extern ztimer_clock_t *const ZTIMER_MSEC;
749 
753 extern ztimer_clock_t *const ZTIMER_SEC;
754 
769 extern ztimer_clock_t *const ZTIMER_USEC_BASE;
770 
788 extern ztimer_clock_t *const ZTIMER_MSEC_BASE;
789 
790 #ifdef __cplusplus
791 }
792 #endif
793 
794 #endif /* ZTIMER_H */
int16_t kernel_pid_t
Unique process identifier.
Definition: sched.h:139
void ztimer_init(void)
Initialize the board-specific default ztimer configuration.
void(* ztimer_callback_t)(void *arg)
Type of callbacks in timers.
Definition: ztimer.h:294
void ztimer_periodic_wakeup(ztimer_clock_t *clock, uint32_t *last_wakeup, uint32_t period)
Suspend the calling thread until the time (last_wakeup + period)
void ztimer_set_wakeup(ztimer_clock_t *clock, ztimer_t *timer, uint32_t offset, kernel_pid_t pid)
Set a timer that wakes up a thread.
ztimer_clock_t *const ZTIMER_SEC
Default ztimer second clock.
void ztimer_set_msg(ztimer_clock_t *clock, ztimer_t *timer, uint32_t offset, msg_t *msg, kernel_pid_t target_pid)
Post a message after a delay.
ztimer_clock_t *const ZTIMER_MSEC_BASE
Base ztimer for the millisecond clock (ZTIMER_MSEC)
uint32_t ztimer_set(ztimer_clock_t *clock, ztimer_t *timer, uint32_t val)
Set a timer on a clock.
ztimer_clock_t *const ZTIMER_USEC
Default ztimer microsecond clock.
static void ztimer_spin(ztimer_clock_t *clock, uint32_t duration)
Busy-wait specified duration.
Definition: ztimer.h:653
uint32_t ztimer_now_t
type for ztimer_now() result
Definition: ztimer.h:323
static ztimer_now_t ztimer_now(ztimer_clock_t *clock)
Get the current time from a clock.
Definition: ztimer.h:600
int ztimer_msg_receive_timeout(ztimer_clock_t *clock, msg_t *msg, uint32_t timeout)
receive a message (blocking, with timeout)
static void ztimer_init_extend(ztimer_clock_t *clock)
Initialize possible ztimer extension intermediate timer.
Definition: ztimer.h:731
unsigned ztimer_is_set(const ztimer_clock_t *clock, const ztimer_t *timer)
Check if a timer is currently active.
int ztimer_rmutex_lock_timeout(ztimer_clock_t *clock, rmutex_t *rmutex, uint32_t timeout)
Try to lock the given rmutex, but give up after timeout.
void ztimer_sleep(ztimer_clock_t *clock, uint32_t duration)
Put the calling thread to sleep for the specified number of ticks.
bool ztimer_remove(ztimer_clock_t *clock, ztimer_t *timer)
Remove a timer from a clock.
void ztimer_handler(ztimer_clock_t *clock)
main ztimer callback handler
ztimer_now_t _ztimer_now_extend(ztimer_clock_t *clock)
ztimer_now() for extending timers
ztimer_clock_t *const ZTIMER_USEC_BASE
Base ztimer for the microsecond clock (ZTIMER_USEC)
void ztimer_set_timeout_flag(ztimer_clock_t *clock, ztimer_t *timer, uint32_t timeout)
Set timeout thread flag after timeout.
int ztimer_mutex_lock_timeout(ztimer_clock_t *clock, mutex_t *mutex, uint32_t timeout)
Try to lock the given mutex, but give up after timeout.
ztimer_clock_t *const ZTIMER_MSEC
Default ztimer millisecond clock.
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:196
Mutex structure.
Definition: mutex.h:123
Mutex structure.
Definition: rmutex.h:38
Minimum information for each timer.
Definition: ztimer.h:299
uint32_t offset
offset from last timer in list
Definition: ztimer.h:301
ztimer_base_t * next
next timer in list
Definition: ztimer.h:300
ztimer device structure
Definition: ztimer.h:369
uint16_t adjust_sleep
will be subtracted on every sleep(), in addition to adjust_set
Definition: ztimer.h:374
uint32_t lower_last
timer value at last now() call
Definition: ztimer.h:379
uint32_t max_value
maximum relative timer value
Definition: ztimer.h:378
ztimer_now_t checkpoint
cumulated time at last now() call
Definition: ztimer.h:380
ztimer_base_t * last
last timer in queue, for _is_set()
Definition: ztimer.h:372
ztimer_base_t list
list of active timers
Definition: ztimer.h:370
uint16_t adjust_set
will be subtracted on every set()
Definition: ztimer.h:373
const ztimer_ops_t * ops
pointer to methods structure
Definition: ztimer.h:371
uint8_t block_pm_mode
min.
Definition: ztimer.h:383
ztimer backend method structure
Definition: ztimer.h:345
uint32_t(* now)(ztimer_clock_t *clock)
Get the current count of the timer.
Definition: ztimer.h:357
void(* set)(ztimer_clock_t *clock, uint32_t val)
Set a new timer target.
Definition: ztimer.h:351
ztimer structure
Definition: ztimer.h:332
ztimer_callback_t callback
timer callback function pointer
Definition: ztimer.h:334
void * arg
timer callback argument
Definition: ztimer.h:335
ztimer_base_t base
clock list entry
Definition: ztimer.h:333