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