Zephyr API Documentation  3.7.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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)
#define STRUCT_SECTION_ITERABLE(struct_type, varname)
Defines a new element for an iterable section.
Definition: iterable_sections.h:216

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
nameName of the timer variable.
expiry_fnFunction to invoke each time the timer expires.
stop_fnFunction 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
timerAddress 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
timerAddress 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
timerThe 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
timerAddress of timer.
expiry_fnFunction to invoke each time the timer expires.
stop_fnFunction 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
timerAddress 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
timerThe 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
timerAddress of timer.
durationInitial timer duration.
periodTimer 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
timerAddress 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
timerAddress 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
timerAddress 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
timerAddress 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
timerAddress of timer.
user_dataUser data to associate with the timer.