ztimer.h

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2018 Kaspar Schleiser <kaspar@schleiser.de>
 * SPDX-License-Identifier: LGPL-2.1-only
 */
 
#pragma once
 
#include <stdint.h>
 
#include "mbox.h"
#include "msg.h"
#include "mutex.h"
#include "rmutex.h"
#include "sched.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define ZTIMER_CLOCK_NO_REQUIRED_PM_MODE (UINT8_MAX)
 
typedef struct ztimer_base ztimer_base_t;
 
typedef struct ztimer_clock ztimer_clock_t;
 
typedef void (*ztimer_callback_t)(void *arg);
 
struct ztimer_base {
    ztimer_base_t *next;        
    uint32_t offset;            
};
 
typedef uint32_t ztimer_now_t;
 
typedef struct {
    ztimer_base_t base;             
    ztimer_callback_t callback;     
    void *arg;                      
} ztimer_t;
 
typedef struct {
    void (*set)(ztimer_clock_t *clock, uint32_t val);
 
    uint32_t (*now)(ztimer_clock_t *clock);
 
    void (*cancel)(ztimer_clock_t *clock);
 
#if MODULE_ZTIMER_ONDEMAND || DOXYGEN
    void (*start)(ztimer_clock_t *clock);
 
    void (*stop)(ztimer_clock_t *clock);
#endif
} ztimer_ops_t;
 
struct ztimer_clock {
    ztimer_base_t list;             
    const ztimer_ops_t *ops;        
    ztimer_base_t *last;            
    uint16_t adjust_set;            
    uint16_t adjust_sleep;          
#if MODULE_ZTIMER_ONDEMAND || DOXYGEN
    uint16_t adjust_clock_start;    
    uint16_t users;                 
#endif
#if MODULE_ZTIMER_EXTEND || DOXYGEN
    /* values used for checkpointed intervals and 32bit extension */
    uint32_t max_value;             
    uint32_t lower_last;            
    ztimer_now_t checkpoint;        
#endif
#if MODULE_PM_LAYERED && !MODULE_ZTIMER_ONDEMAND || DOXYGEN
    uint8_t block_pm_mode;          
#endif
};
 
void ztimer_handler(ztimer_clock_t *clock);
 
/* User API */
#if MODULE_ZTIMER_ONDEMAND || DOXYGEN
bool ztimer_acquire(ztimer_clock_t *clock);
#else
static inline bool ztimer_acquire(ztimer_clock_t *clock)
{
    (void)clock;
    return false;
}
#endif
 
#if MODULE_ZTIMER_ONDEMAND || DOXYGEN
bool ztimer_release(ztimer_clock_t *clock);
#else
static inline bool ztimer_release(ztimer_clock_t *clock)
{
    (void)clock;
    return false;
}
#endif
 
uint32_t ztimer_set(ztimer_clock_t *clock, ztimer_t *timer, uint32_t val);
 
unsigned ztimer_is_set(const ztimer_clock_t *clock, const ztimer_t *timer);
 
bool ztimer_remove(ztimer_clock_t *clock, ztimer_t *timer);
 
void ztimer_set_msg(ztimer_clock_t *clock, ztimer_t *timer, uint32_t offset,
                    msg_t *msg, kernel_pid_t target_pid);
 
int ztimer_msg_receive_timeout(ztimer_clock_t *clock, msg_t *msg,
                               uint32_t timeout);
 
/* created with dist/tools/define2u16.py */
#define MSG_ZTIMER 0xc83e   
int ztimer_mbox_get_timeout(ztimer_clock_t *clock, mbox_t *mbox, msg_t *msg, uint32_t timeout);
 
ztimer_now_t _ztimer_now_extend(ztimer_clock_t *clock);
 
void _ztimer_assert_clock_active(ztimer_clock_t *clock);
 
static inline ztimer_now_t ztimer_now(ztimer_clock_t *clock)
{
#if MODULE_ZTIMER_ONDEMAND && DEVELHELP
    _ztimer_assert_clock_active(clock);
#endif
 
#if MODULE_ZTIMER_EXTEND
    if (clock->max_value < UINT32_MAX) {
#else
    if (0) {
#endif
        return _ztimer_now_extend(clock);
    }
    else {
        return clock->ops->now(clock);
    }
}
 
void ztimer_periodic_wakeup(ztimer_clock_t *clock, uint32_t *last_wakeup,
                            uint32_t period);
 
void ztimer_sleep(ztimer_clock_t *clock, uint32_t duration);
 
static inline void ztimer_spin(ztimer_clock_t *clock, uint32_t duration)
{
    ztimer_acquire(clock);
    uint32_t end = ztimer_now(clock) + duration;
 
    /* Rely on integer overflow. `end - now` will be smaller than `duration`,
     * counting down, until it underflows to UINT32_MAX. Loop ends then. */
    while ((end - ztimer_now(clock)) <= duration) {}
    ztimer_release(clock);
}
 
void ztimer_set_wakeup(ztimer_clock_t *clock, ztimer_t *timer, uint32_t offset,
                       kernel_pid_t pid);
 
void ztimer_set_timeout_flag(ztimer_clock_t *clock, ztimer_t *timer,
                             uint32_t timeout);
 
void ztimer_mutex_unlock(ztimer_clock_t *clock, ztimer_t *timer,
                         uint32_t timeout, mutex_t *mutex);
 
int ztimer_mutex_lock_timeout(ztimer_clock_t *clock, mutex_t *mutex,
                              uint32_t timeout);
 
int ztimer_rmutex_lock_timeout(ztimer_clock_t *clock, rmutex_t *rmutex,
                               uint32_t timeout);
 
void ztimer_init(void);
 
#if defined(MODULE_ZTIMER_EXTEND) || defined(DOXYGEN)
static inline void ztimer_init_extend(ztimer_clock_t *clock)
{
    if (clock->max_value < UINT32_MAX) {
        clock->ops->set(clock, clock->max_value >> 1);
    }
}
#endif /* MODULE_ZTIMER_EXTEND */
 
/* default ztimer virtual devices */
extern ztimer_clock_t *const ZTIMER_USEC;
 
extern ztimer_clock_t *const ZTIMER_MSEC;
 
extern ztimer_clock_t *const ZTIMER_SEC;
 
extern ztimer_clock_t *const ZTIMER_USEC_BASE;
 
extern ztimer_clock_t *const ZTIMER_MSEC_BASE;
 
#ifdef __cplusplus
}
#endif