Timer APIs

Macros
#define	K_TIMER_DEFINE(name, expiry_fn, stop_fn)
	Statically define and initialize a timer.

Typedefs
typedef void(*	k_timer_expiry_t) (struct k_timer *timer)
	Timer expiry function type.
typedef void(*	k_timer_stop_t) (struct k_timer *timer)
	Timer stop function type.

Functions
void	k_timer_init (struct k_timer *timer, k_timer_expiry_t expiry_fn, k_timer_stop_t stop_fn)
	Initialize a timer.
void	k_timer_start (struct k_timer *timer, k_timeout_t duration, k_timeout_t period)
	Start a timer.
void	k_timer_stop (struct k_timer *timer)
	Stop a timer.
uint32_t	k_timer_status_get (struct k_timer *timer)
	Read timer status.
uint32_t	k_timer_status_sync (struct k_timer *timer)
	Synchronize thread to timer expiration.
k_ticks_t	k_timer_expires_ticks (const struct k_timer *timer)
	Get next expiration time of a timer, in system ticks.
k_ticks_t	k_timer_remaining_ticks (const struct k_timer *timer)
	Get time remaining before a timer next expires, in system ticks.
static uint32_t	k_timer_remaining_get (struct k_timer *timer)
	Get time remaining before a timer next expires.
void	k_timer_user_data_set (struct k_timer *timer, void *user_data)
	Associate user-specific data with a timer.
void *	k_timer_user_data_get (const struct k_timer *timer)
	Retrieve the user-specific data from a timer.

Detailed Description

Macro Definition Documentation

K_TIMER_DEFINE

#define K_TIMER_DEFINE	(		name,
			expiry_fn,
			stop_fn
	)

#include <zephyr/kernel.h>

Value:

        STRUCT_SECTION_ITERABLE(k_timer, name) = \
                Z_TIMER_INITIALIZER(name, expiry_fn, stop_fn)

Statically define and initialize a timer.

The timer can be accessed outside the module where it is defined using:

extern struct k_timer <name>; 

Parameters

name	Name of the timer variable.
expiry_fn	Function to invoke each time the timer expires.
stop_fn	Function to invoke if the timer is stopped while running.

Typedef Documentation

k_timer_expiry_t

k_timer_expiry_t

#include <zephyr/kernel.h>

Timer expiry function type.

A timer's expiry function is executed by the system clock interrupt handler each time the timer expires. The expiry function is optional, and is only invoked if the timer has been initialized with one.

Parameters

timer

Address of timer.

k_timer_stop_t

k_timer_stop_t

#include <zephyr/kernel.h>

Timer stop function type.

A timer's stop function is executed if the timer is stopped prematurely. The function runs in the context of call that stops the timer. As k_timer_stop() can be invoked from an ISR, the stop function must be callable from interrupt context (isr-ok).

The stop function is optional, and is only invoked if the timer has been initialized with one.

Parameters

timer

Address of timer.

Function Documentation

k_timer_expires_ticks()

k_ticks_t k_timer_expires_ticks

(

const struct k_timer *

timer

)

#include <zephyr/kernel.h>

Get next expiration time of a timer, in system ticks.

This routine returns the future system uptime reached at the next time of expiration of the timer, in units of system ticks. If the timer is not running, current system time is returned.

Parameters

timer

The timer object

Returns

Uptime of expiration, in ticks

k_timer_init()

void k_timer_init	(	struct k_timer *	timer,
		k_timer_expiry_t	expiry_fn,
		k_timer_stop_t	stop_fn
	)

#include <zephyr/kernel.h>

Initialize a timer.

This routine initializes a timer, prior to its first use.

Parameters

timer	Address of timer.
expiry_fn	Function to invoke each time the timer expires.
stop_fn	Function to invoke if the timer is stopped while running.

k_timer_remaining_get()

static uint32_t k_timer_remaining_get ( struct k_timer *  timer )

inlinestatic

#include <zephyr/kernel.h>

Get time remaining before a timer next expires.

This routine computes the (approximate) time remaining before a running timer next expires. If the timer is not running, it returns zero.

Parameters

timer

Address of timer.

Returns

Remaining time (in milliseconds).

k_timer_remaining_ticks()

k_ticks_t k_timer_remaining_ticks

(

const struct k_timer *

timer

)

#include <zephyr/kernel.h>

Get time remaining before a timer next expires, in system ticks.

This routine computes the time remaining before a running timer next expires, in units of system ticks. If the timer is not running, it returns zero.

Parameters

timer

The timer object

Returns

Remaining time until expiration, in ticks

k_timer_start()

void k_timer_start	(	struct k_timer *	timer,
		k_timeout_t	duration,
		k_timeout_t	period
	)

#include <zephyr/kernel.h>

Start a timer.

This routine starts a timer, and resets its status to zero. The timer begins counting down using the specified duration and period values.

Attempting to start a timer that is already running is permitted. The timer's status is reset to zero and the timer begins counting down using the new duration and period values.

Parameters

timer	Address of timer.
duration	Initial timer duration.
period	Timer period.

k_timer_status_get()

uint32_t k_timer_status_get

(

struct k_timer *

timer

)

#include <zephyr/kernel.h>

Read timer status.

This routine reads the timer's status, which indicates the number of times it has expired since its status was last read.

Calling this routine resets the timer's status to zero.

Parameters

timer

Address of timer.

Returns

Timer status.

k_timer_status_sync()

uint32_t k_timer_status_sync

(

struct k_timer *

timer

)

#include <zephyr/kernel.h>

Synchronize thread to timer expiration.

This routine blocks the calling thread until the timer's status is non-zero (indicating that it has expired at least once since it was last examined) or the timer is stopped. If the timer status is already non-zero, or the timer is already stopped, the caller continues without waiting.

Calling this routine resets the timer's status to zero.

This routine must not be used by interrupt handlers, since they are not allowed to block.

Parameters

timer

Address of timer.

Returns

Timer status.

k_timer_stop()

void k_timer_stop

(

struct k_timer *

timer

)

#include <zephyr/kernel.h>

Stop a timer.

This routine stops a running timer prematurely. The timer's stop function, if one exists, is invoked by the caller.

Attempting to stop a timer that is not running is permitted, but has no effect on the timer.

Note

The stop handler has to be callable from ISRs if k_timer_stop is to be called from ISRs.

Function properties (list may not be complete)

isr-ok

Parameters

timer

Address of timer.

k_timer_user_data_get()

void * k_timer_user_data_get

(

const struct k_timer *

timer

)

#include <zephyr/kernel.h>

Retrieve the user-specific data from a timer.

Parameters

timer

Address of timer.

Returns

The user data.

k_timer_user_data_set()

void k_timer_user_data_set	(	struct k_timer *	timer,
		void *	user_data
	)

#include <zephyr/kernel.h>

Associate user-specific data with a timer.

This routine records the user_data with the timer, to be retrieved later.

It can be used e.g. in a timer handler shared across multiple subsystems to retrieve data specific to the subsystem this timer is associated with.

Parameters

timer	Address of timer.
user_data	User data to associate with the timer.