Loading...
Searching...
No Matches
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
273extern "C" {
274#endif
275
279#define ZTIMER_CLOCK_NO_REQUIRED_PM_MODE (UINT8_MAX)
280
285
290
294typedef void (*ztimer_callback_t)(void *arg);
295
301 uint32_t offset;
302};
303
320#if MODULE_ZTIMER_NOW64
321typedef uint64_t ztimer_now_t;
322#else
323typedef uint32_t ztimer_now_t;
324#endif
325
337
345typedef 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
365#if MODULE_ZTIMER_ONDEMAND || DOXYGEN
370 void (*start)(ztimer_clock_t *clock);
371
376 void (*stop)(ztimer_clock_t *clock);
377#endif
379
387 uint16_t adjust_set;
388 uint16_t adjust_sleep;
390#if MODULE_ZTIMER_ONDEMAND || DOXYGEN
394 uint16_t users;
395#endif
396#if MODULE_ZTIMER_EXTEND || MODULE_ZTIMER_NOW64 || DOXYGEN
397 /* values used for checkpointed intervals and 32bit extension */
398 uint32_t max_value;
399 uint32_t lower_last;
401#endif
402#if MODULE_PM_LAYERED && !MODULE_ZTIMER_ONDEMAND || DOXYGEN
405#endif
406};
407
415
416/* User API */
428#if MODULE_ZTIMER_ONDEMAND || DOXYGEN
430#else
431static inline bool ztimer_acquire(ztimer_clock_t *clock)
432{
433 (void)clock;
434 return false;
435}
436#endif
437
448#if MODULE_ZTIMER_ONDEMAND || DOXYGEN
450#else
451static inline bool ztimer_release(ztimer_clock_t *clock)
452{
453 (void)clock;
454 return false;
455}
456#endif
457
474uint32_t ztimer_set(ztimer_clock_t *clock, ztimer_t *timer, uint32_t val);
475
485unsigned ztimer_is_set(const ztimer_clock_t *clock, const ztimer_t *timer);
486
505
521void ztimer_set_msg(ztimer_clock_t *clock, ztimer_t *timer, uint32_t offset,
522 msg_t *msg, kernel_pid_t target_pid);
523
542 uint32_t timeout);
543
544/* created with dist/tools/define2u16.py */
545#define MSG_ZTIMER 0xc83e
556
567
681{
682#if MODULE_ZTIMER_ONDEMAND && DEVELHELP
684#endif
685
686#if MODULE_ZTIMER_NOW64
687 if (1) {
688#elif MODULE_ZTIMER_EXTEND
689 if (clock->max_value < UINT32_MAX) {
690#else
691 if (0) {
692#endif
693 return _ztimer_now_extend(clock);
694 }
695 else {
696 return clock->ops->now(clock);
697 }
698}
699
722void ztimer_periodic_wakeup(ztimer_clock_t *clock, uint32_t *last_wakeup,
723 uint32_t period);
724
731void ztimer_sleep(ztimer_clock_t *clock, uint32_t duration);
732
741static inline void ztimer_spin(ztimer_clock_t *clock, uint32_t duration)
742{
743 ztimer_acquire(clock);
744 uint32_t end = ztimer_now(clock) + duration;
745
746 /* Rely on integer overflow. `end - now` will be smaller than `duration`,
747 * counting down, until it underflows to UINT32_MAX. Loop ends then. */
748 while ((end - ztimer_now(clock)) <= duration) {}
749 ztimer_release(clock);
750}
751
763void ztimer_set_wakeup(ztimer_clock_t *clock, ztimer_t *timer, uint32_t offset,
764 kernel_pid_t pid);
765
777 uint32_t timeout);
778
790 uint32_t timeout, mutex_t *mutex);
791
803 uint32_t timeout);
804
816 uint32_t timeout);
817
821void ztimer_init(void);
822
823#if defined(MODULE_ZTIMER_EXTEND) || defined(DOXYGEN)
834static inline void ztimer_init_extend(ztimer_clock_t *clock)
835{
836 if (clock->max_value < UINT32_MAX) {
837 clock->ops->set(clock, clock->max_value >> 1);
838 }
839}
840#endif /* MODULE_ZTIMER_EXTEND */
841
842/* default ztimer virtual devices */
846extern ztimer_clock_t *const ZTIMER_USEC;
847
851extern ztimer_clock_t *const ZTIMER_MSEC;
852
856extern ztimer_clock_t *const ZTIMER_SEC;
857
872extern ztimer_clock_t *const ZTIMER_USEC_BASE;
873
891extern ztimer_clock_t *const ZTIMER_MSEC_BASE;
892
893#ifdef __cplusplus
894}
895#endif
896
897#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.
bool ztimer_release(ztimer_clock_t *clock)
Release a clock.
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:741
bool ztimer_acquire(ztimer_clock_t *clock)
Acquire a clock.
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:680
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:834
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
void ztimer_mutex_unlock(ztimer_clock_t *clock, ztimer_t *timer, uint32_t timeout, mutex_t *mutex)
Unlock mutex after timeout.
ztimer_clock_t *const ZTIMER_USEC_BASE
Base ztimer for the microsecond clock (ZTIMER_USEC)
void _ztimer_assert_clock_active(ztimer_clock_t *clock)
asserts the given clock to be active
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:146
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:383
uint16_t adjust_sleep
will be subtracted on every sleep(), in addition to adjust_set
Definition ztimer.h:388
uint32_t lower_last
timer value at last now() call
Definition ztimer.h:399
uint32_t max_value
maximum relative timer value
Definition ztimer.h:398
ztimer_now_t checkpoint
cumulated time at last now() call
Definition ztimer.h:400
ztimer_base_t * last
last timer in queue, for _is_set()
Definition ztimer.h:386
uint16_t users
user count of this clock
Definition ztimer.h:394
ztimer_base_t list
list of active timers
Definition ztimer.h:384
uint16_t adjust_clock_start
will be subtracted on every set(), if the underlying periph is in stopped state
Definition ztimer.h:391
uint16_t adjust_set
will be subtracted on every set()
Definition ztimer.h:387
const ztimer_ops_t * ops
pointer to methods structure
Definition ztimer.h:385
uint8_t block_pm_mode
min.
Definition ztimer.h:403
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