ztimer 64bit version More...

Detailed Description

ztimer 64bit version

Introduction

This module implements a 64bit version of the ztimer API. All ztimer_* functions have a ztimer64_* equivalent that behaves the same, but allowing offsets >= 2^32.

In addition to that, ztimer64 offers functions taking absolute target times as parameter. If the absolute target time is in the past, a timer would trigger right away.

Here's a table for absolute variants:

relative version	absolute version
ztimer64_set()	ztimer64_set_at()
ztimer64_sleep()	ztimer64_sleep_until()
ztimer64_set_msg()	ztimer64_set_msg_at()
ztimer64_set_wakeup()	ztimer64_set_wakeup_at()
ztimer64_set_timeout_flag()	ztimer64_set_timeout_flag_at()
ztimer64_msg_receive_timeout()	ztimer64_msg_receive_until()
ztimer64_mutex_lock_timeout()	ztimer64_mutex_lock_until()
ztimer64_rmutex_lock_timeout()	ztimer64_rmutex_lock_until()

ztimer64 clocks

ztimer64 provides automatic setup of ZTIMER64_SEC, ZTIMER64_MSEC and ZTIMER64_USEC, using the ztimer(32) clocks as base clocks. Enable them by depending on ztimer64_sec, ztimer64_msec and / or ztimer64_usec.

Warning: ztimer64 always keeps a timer running on the base clock. Depending on the base clock, this blocks low-power sleep modes. If the hardware supports it, the msec and sec timers should be using a low-power capable timer (e.g., periph_rtt). ztimer64_usec will almost certainly block low-power sleep.

TODO:

some explicit power management
implement adjust_set and adjust_sleep API
implement setting a 64bit reference time (epoch)

Modules
	ztimer64_xtimer_compat: 64 Bit xtimer wrapper

Files
file	ztimer64.h
	ztimer 64bit API

Data Structures
struct	ztimer64_base
	Minimum information for each timer. More...

struct	ztimer64_t
	ztimer64 structure More...

struct	ztimer64_clock
	ztimer64 clock structure More...

Macros
#define	MSG_ZTIMER64 0xc83f
	msg type used by ztimer64_msg_receive_timeout

Typedefs
typedef struct ztimer64_base	ztimer64_base_t
	ztimer64_t forward declaration

typedef struct ztimer64_clock	ztimer64_clock_t
	ztimer64_clock_t forward declaration

Functions
uint64_t	ztimer64_now (ztimer64_clock_t *clock)
	Get the current time from a clock.

static uint64_t	ztimer64_offset2absolute (ztimer64_clock_t *clock, uint64_t offset)
	Get absolute target time for a clock given offset.

void	ztimer64_set_at (ztimer64_clock_t clock, ztimer64_t timer, uint64_t target)
	Set a timer on a clock (absolute version)

static void	ztimer64_set (ztimer64_clock_t clock, ztimer64_t timer, uint64_t offset)
	Set a timer on a clock (relative version)

unsigned	ztimer64_is_set (const ztimer64_t *timer)
	Check if a timer is currently active.

void	ztimer64_remove (ztimer64_clock_t clock, ztimer64_t timer)
	Remove a timer from a clock.

void	ztimer64_set_msg_at (ztimer64_clock_t clock, ztimer64_t timer, uint64_t target, msg_t *msg, kernel_pid_t target_pid)
	Post a message at a specified time.

static void	ztimer64_set_msg (ztimer64_clock_t clock, ztimer64_t timer, uint64_t offset, msg_t *msg, kernel_pid_t target_pid)
	Post a message after a delay (relative version)

int	ztimer64_msg_receive_until (ztimer64_clock_t clock, msg_t msg, uint64_t target)
	receive a message (blocking, with absolute timeout)

static int	ztimer64_msg_receive_timeout (ztimer64_clock_t clock, msg_t msg, uint64_t timeout)
	receive a message (blocking, with relative timeout)

void	ztimer64_periodic_wakeup (ztimer64_clock_t clock, uint64_t last_wakeup, uint64_t period)
	Suspend the calling thread until the time (`last_wakeup` + `period`)

void	ztimer64_sleep_until (ztimer64_clock_t *clock, uint64_t target)
	Put the calling thread to sleep until the specified time.

static void	ztimer64_sleep (ztimer64_clock_t *clock, uint64_t duration)
	Put the calling thread to sleep for the specified number of ticks.

static void	ztimer64_spin_until (ztimer64_clock_t *clock, uint64_t target)
	Busy-wait until specified target time.

void	ztimer64_set_wakeup_at (ztimer64_clock_t clock, ztimer64_t timer, uint64_t target, kernel_pid_t pid)
	Set a timer that wakes up a thread (absolute version)

static void	ztimer64_set_wakeup (ztimer64_clock_t clock, ztimer64_t timer, uint64_t offset, kernel_pid_t pid)
	Set a timer that wakes up a thread (relative version)

void	ztimer64_set_timeout_flag_at (ztimer64_clock_t clock, ztimer64_t timer, uint64_t target)
	Set timeout thread flag at `target` time.

static void	ztimer64_set_timeout_flag (ztimer64_clock_t clock, ztimer64_t timer, uint64_t timeout)
	Set timeout thread flag after `timeout`.

int	ztimer64_mutex_lock_until (ztimer64_clock_t clock, mutex_t mutex, uint64_t target)
	Try to lock the given mutex, but give up at `target` time.

static int	ztimer64_mutex_lock_timeout (ztimer64_clock_t clock, mutex_t mutex, uint64_t timeout)
	Try to lock the given mutex, but give up after `timeout`.

int	ztimer64_rmutex_lock_until (ztimer64_clock_t clock, rmutex_t rmutex, uint64_t target)
	Try to lock the given rmutex, but give up at `time`.

static int	ztimer64_rmutex_lock_timeout (ztimer64_clock_t clock, rmutex_t rmutex, uint64_t timeout)
	Try to lock the given rmutex, but give up after `timeout`.

void	ztimer64_update_head_offset (ztimer64_clock_t *clock)
	Update ztimer clock head list offset.

void	ztimer64_init (void)
	Initialize the board-specific default ztimer configuration.

void	ztimer64_clock_init (ztimer64_clock_t clock, ztimer_clock_t base_clock)
	Initialize `clock` to be run from `base_clock`.

int64_t	ztimer64_overhead (ztimer64_clock_t *clock, uint64_t base)
	Measure ztimer64 overhead.

Variables
ztimer64_clock_t *const	ZTIMER64_USEC
	Default ztimer microsecond clock.

ztimer64_clock_t *const	ZTIMER64_MSEC
	Default ztimer millisecond clock.

ztimer64_clock_t *const	ZTIMER64_SEC
	Default ztimer second clock.

Macro Definition Documentation

◆ MSG_ZTIMER64

#define MSG_ZTIMER64 0xc83f

msg type used by ztimer64_msg_receive_timeout

Definition at line 296 of file ztimer64.h.

Typedef Documentation

◆ ztimer64_base_t

typedef struct ztimer64_base ztimer64_base_t

ztimer64_t forward declaration

Definition at line 81 of file ztimer64.h.

◆ ztimer64_clock_t

typedef struct ztimer64_clock ztimer64_clock_t

ztimer64_clock_t forward declaration

Definition at line 85 of file ztimer64.h.

Function Documentation

◆ ztimer64_clock_init()

void ztimer64_clock_init	(	ztimer64_clock_t *	clock,
		ztimer_clock_t *	base_clock
	)

Initialize clock to be run from base_clock.

Parameters

[in,out]	clock	Clock to initialize
[in]	base_clock	Base clock to use

◆ ztimer64_is_set()

unsigned ztimer64_is_set ( const ztimer64_t * timer )

Check if a timer is currently active.

Parameters

[in] timer timer to check

Returns: 1 if timer is active; 0 if timer is not active

◆ ztimer64_msg_receive_timeout()

static int ztimer64_msg_receive_timeout	(	ztimer64_clock_t *	clock,
		msg_t *	msg,
		uint64_t	timeout
	)

inlinestatic

receive a message (blocking, with relative timeout)

Similar to msg_receive(), but with a timeout parameter. The function will return after waiting at most timeout ticks.

Note: : This might function might leave a message with type MSG_ZTIMER64 in the thread's message queue, which must be handled (ignored).

Parameters

[in]	clock	ztimer64 clock to operate on
[out]	msg	pointer to buffer which will be filled if a message is received
[in]	timeout	relative timeout, in `clock` time units

Returns: >=0 if a message was received; -ETIME on timeout

Definition at line 288 of file ztimer64.h.

◆ ztimer64_msg_receive_until()

int ztimer64_msg_receive_until	(	ztimer64_clock_t *	clock,
		msg_t *	msg,
		uint64_t	target
	)

receive a message (blocking, with absolute timeout)

Similar to msg_receive(), but with a timeout parameter. The function will return after waiting at most until target.

Note: : This might function might leave a message with type MSG_ZTIMER64 in the thread's message queue, which must be handled (ignored).

Parameters

[in]	clock	ztimer64 clock to operate on
[out]	msg	pointer to buffer which will be filled if a message is received
[in]	target	absolute target, in `clock` time

Returns: >=0 if a message was received; -ETIME on timeout

◆ ztimer64_mutex_lock_timeout()

static int ztimer64_mutex_lock_timeout	(	ztimer64_clock_t *	clock,
		mutex_t *	mutex,
		uint64_t	timeout
	)

inlinestatic

Try to lock the given mutex, but give up after timeout.

Parameters

[in]	clock	ztimer64 clock to operate on
[in,out]	mutex	Mutex object to lock
[in]	timeout	timeout after which to give up

Return values

0	Success, caller has the mutex
-ECANCELED	Failed to obtain mutex within `timeout`

Definition at line 441 of file ztimer64.h.

◆ ztimer64_mutex_lock_until()

int ztimer64_mutex_lock_until	(	ztimer64_clock_t *	clock,
		mutex_t *	mutex,
		uint64_t	target
	)

Try to lock the given mutex, but give up at target time.

Parameters

[in]	clock	ztimer64 clock to operate on
[in,out]	mutex	Mutex object to lock
[in]	target	time after which to give up

Return values

0	Success, caller has the mutex
-ECANCELED	Failed to obtain mutex within `timeout`

◆ ztimer64_now()

uint64_t ztimer64_now ( ztimer64_clock_t * clock )

Get the current time from a clock.

Parameters

[in] clock ztimer clock to operate on

Returns: Current count on clock

◆ ztimer64_offset2absolute()

static uint64_t ztimer64_offset2absolute	(	ztimer64_clock_t *	clock,
		uint64_t	offset
	)

inlinestatic

Get absolute target time for a clock given offset.

Parameters

[in]	clock	ztimer64 clock to operate on
[in]	offset	relative target time

Returns: absolute target time

Definition at line 140 of file ztimer64.h.

◆ ztimer64_overhead()

int64_t ztimer64_overhead	(	ztimer64_clock_t *	clock,
		uint64_t	base
	)

Measure ztimer64 overhead.

This function can be used to measure the overhead incurred by ztimer64. It will configure a callback to trigger after base ticks, then return the number of ticks that have passed, minus base.

Parameters

[in]	clock	ztimer64 clock to operate on
[in]	base	base interval to use

Returns: (time from ztimer64_set() until callback) - base

◆ ztimer64_periodic_wakeup()

void ztimer64_periodic_wakeup	(	ztimer64_clock_t *	clock,
		uint64_t *	last_wakeup,
		uint64_t	period
	)

Suspend the calling thread until the time (last_wakeup + period)

This function can be used to create periodic wakeups.

When the function returns, last_wakeup is set to (last_wakeup + period).

last_wakeup should be set to ztimer64_now(clock) before first call of the function.

If the time (last_wakeup + period) has already passed, the function sets last_wakeup to last_wakeup + period and returns immediately.

Note: if you period is smaller than 2^32 ticks, consider using the 32bit version.

Parameters

[in]	clock	ztimer64 clock to operate on
[in]	last_wakeup	base time stamp for the wakeup
[in]	period	time in ticks that will be added to `last_wakeup`

◆ ztimer64_remove()

void ztimer64_remove	(	ztimer64_clock_t *	clock,
		ztimer64_t *	timer
	)

Remove a timer from a clock.

This will place timer in the timer targets queue for clock.

This function does nothing if timer is not found in the timer queue of clock.

Parameters

[in]	clock	ztimer64 clock to operate on
[in]	timer	timer entry to remove

◆ ztimer64_rmutex_lock_timeout()

static int ztimer64_rmutex_lock_timeout	(	ztimer64_clock_t *	clock,
		rmutex_t *	rmutex,
		uint64_t	timeout
	)

inlinestatic

Try to lock the given rmutex, but give up after timeout.

Parameters

[in]	clock	ztimer64 clock to operate on
[in,out]	rmutex	rmutex object to lock
[in]	timeout	timeout after which to give up

Return values

0	Success, caller has the rmutex
-ECANCELED	Failed to obtain rmutex within `timeout`

Definition at line 472 of file ztimer64.h.

◆ ztimer64_rmutex_lock_until()

int ztimer64_rmutex_lock_until	(	ztimer64_clock_t *	clock,
		rmutex_t *	rmutex,
		uint64_t	target
	)

Try to lock the given rmutex, but give up at time.

Parameters

[in]	clock	ztimer64 clock to operate on
[in,out]	rmutex	rmutex object to lock
[in]	target	time after which to give up

Return values

0	Success, caller has the rmutex
-ECANCELED	Failed to obtain rmutex before `time`

◆ ztimer64_set()

static void ztimer64_set	(	ztimer64_clock_t *	clock,
		ztimer64_t *	timer,
		uint64_t	offset
	)

inlinestatic

Set a timer on a clock (relative version)

This will place timer in the timer targets queue of clock.

Note: The memory pointed to by timer is not copied and must remain in scope until the callback is fired or the timer is removed via ztimer64_remove

Parameters

[in]	clock	ztimer64 clock to operate on
[in]	timer	timer entry to set
[in]	offset	relative target time

Definition at line 179 of file ztimer64.h.

◆ ztimer64_set_at()

void ztimer64_set_at	(	ztimer64_clock_t *	clock,
		ztimer64_t *	timer,
		uint64_t	target
	)

Set a timer on a clock (absolute version)

This will place timer in the timer targets queue of clock.

Note: The memory pointed to by timer is not copied and must remain in scope until the callback is fired or the timer is removed via ztimer64_remove

Parameters

[in]	clock	ztimer64 clock to operate on
[in]	timer	timer entry to set
[in]	target	absolute target time

◆ ztimer64_set_msg()

static void ztimer64_set_msg	(	ztimer64_clock_t *	clock,
		ztimer64_t *	timer,
		uint64_t	offset,
		msg_t *	msg,
		kernel_pid_t	target_pid
	)

inlinestatic

Post a message after a delay (relative version)

This function sets a timer that will send a message offset ticks from now.

Note: The memory pointed to by timer and msg will not be copied, i.e. *timer and *msg needs to remain valid until the timer has triggered.

Parameters

[in]	clock	ztimer64 clock to operate on
[in]	timer	ztimer64 timer struct to use
[in]	offset	relative target time
[in]	msg	pointer to msg that will be sent
[in]	target_pid	pid the message will be sent to

Definition at line 242 of file ztimer64.h.

◆ ztimer64_set_msg_at()

void ztimer64_set_msg_at	(	ztimer64_clock_t *	clock,
		ztimer64_t *	timer,
		uint64_t	target,
		msg_t *	msg,
		kernel_pid_t	target_pid
	)

Post a message at a specified time.

This function sets a timer that will send a message at time target.

Note: The memory pointed to by timer and msg will not be copied, i.e. *timer and *msg needs to remain valid until the timer has triggered.

Parameters

[in]	clock	ztimer64 clock to operate on
[in]	timer	ztimer64 timer struct to use
[in]	target	absolute target time
[in]	msg	pointer to msg that will be sent
[in]	target_pid	pid the message will be sent to

◆ ztimer64_set_timeout_flag()

static void ztimer64_set_timeout_flag	(	ztimer64_clock_t *	clock,
		ztimer64_t *	timer,
		uint64_t	timeout
	)

inlinestatic

Set timeout thread flag after timeout.

This function will set THREAD_FLAG_TIMEOUT on the current thread after timeout usec have passed.

Parameters

[in]	clock	ztimer64 clock to operate on
[in]	timer	timer struct to use
[in]	timeout	timeout in ztimer64_clock's ticks

Definition at line 410 of file ztimer64.h.

◆ ztimer64_set_timeout_flag_at()

void ztimer64_set_timeout_flag_at	(	ztimer64_clock_t *	clock,
		ztimer64_t *	timer,
		uint64_t	target
	)

Set timeout thread flag at target time.

This function will set THREAD_FLAG_TIMEOUT on the current thread at time target.

Parameters

[in]	clock	ztimer64 clock to operate on
[in]	timer	timer struct to use
[in]	target	target in `clock` time

◆ ztimer64_set_wakeup()

static void ztimer64_set_wakeup	(	ztimer64_clock_t *	clock,
		ztimer64_t *	timer,
		uint64_t	offset,
		kernel_pid_t	pid
	)

inlinestatic

Set a timer that wakes up a thread (relative version)

This function sets a timer that will wake up a thread when the timer has expired.

Parameters

[in]	clock	ztimer64 clock to operate on
[in]	timer	timer struct to work with.
[in]	offset	clock ticks from now
[in]	pid	pid of the thread that will be woken up

Definition at line 379 of file ztimer64.h.

◆ ztimer64_set_wakeup_at()

void ztimer64_set_wakeup_at	(	ztimer64_clock_t *	clock,
		ztimer64_t *	timer,
		uint64_t	target,
		kernel_pid_t	pid
	)

Set a timer that wakes up a thread (absolute version)

This function sets a timer that will wake up a thread when the timer has expired.

Parameters

[in]	clock	ztimer64 clock to operate on
[in]	timer	timer struct to work with.
[in]	target	wakeup time
[in]	pid	pid of the thread that will be woken up

◆ ztimer64_sleep()

static void ztimer64_sleep	(	ztimer64_clock_t *	clock,
		uint64_t	duration
	)

inlinestatic

Put the calling thread to sleep for the specified number of ticks.

Parameters

[in]	clock	ztimer64 clock to use
[in]	duration	duration of sleep, in `ztimer` time units

Definition at line 335 of file ztimer64.h.

◆ ztimer64_sleep_until()

void ztimer64_sleep_until	(	ztimer64_clock_t *	clock,
		uint64_t	target
	)

Put the calling thread to sleep until the specified time.

Parameters

[in]	clock	ztimer64 clock to use
[in]	target	wakeup time, in `clock` time

◆ ztimer64_spin_until()

static void ztimer64_spin_until	(	ztimer64_clock_t *	clock,
		uint64_t	target
	)

inlinestatic

Busy-wait until specified target time.

Note: : This blocks lower priority threads. Use only for very short delays.

Parameters

[in]	clock	ztimer64 clock to use
[in]	target	time when spinning should end, in `clock` time

Definition at line 348 of file ztimer64.h.

Detailed Description

Introduction

ztimer64 clocks

Modules

Files

Data Structures

Macros

Typedefs

Functions

Variables

Macro Definition Documentation

◆ MSG_ZTIMER64

Typedef Documentation

◆ ztimer64_base_t

◆ ztimer64_clock_t

Function Documentation

◆ ztimer64_clock_init()

◆ ztimer64_is_set()

◆ ztimer64_msg_receive_timeout()

◆ ztimer64_msg_receive_until()

◆ ztimer64_mutex_lock_timeout()

◆ ztimer64_mutex_lock_until()

◆ ztimer64_now()

◆ ztimer64_offset2absolute()

◆ ztimer64_overhead()

◆ ztimer64_periodic_wakeup()

◆ ztimer64_remove()

◆ ztimer64_rmutex_lock_timeout()

◆ ztimer64_rmutex_lock_until()

◆ ztimer64_set()

◆ ztimer64_set_at()

◆ ztimer64_set_msg()

◆ ztimer64_set_msg_at()

◆ ztimer64_set_timeout_flag()

◆ ztimer64_set_timeout_flag_at()

◆ ztimer64_set_wakeup()

◆ ztimer64_set_wakeup_at()

◆ ztimer64_sleep()

◆ ztimer64_sleep_until()

◆ ztimer64_spin_until()