Clock APIs. More...

Data Structures
struct	k_timeout_t
	Kernel timeout type. More...

Macros
#define	K_NO_WAIT Z_TIMEOUT_NO_WAIT
	Generate null timeout delay. More...

#define	K_NSEC(t) Z_TIMEOUT_NS(t)
	Generate timeout delay from nanoseconds. More...

#define	K_USEC(t) Z_TIMEOUT_US(t)
	Generate timeout delay from microseconds. More...

#define	K_CYC(t) Z_TIMEOUT_CYC(t)
	Generate timeout delay from cycles. More...

#define	K_TICKS(t) Z_TIMEOUT_TICKS(t)
	Generate timeout delay from system ticks. More...

#define	K_MSEC(ms) Z_TIMEOUT_MS(ms)
	Generate timeout delay from milliseconds. More...

#define	K_SECONDS(s) K_MSEC((s) * MSEC_PER_SEC)
	Generate timeout delay from seconds. More...

#define	K_MINUTES(m) K_SECONDS((m) * 60)
	Generate timeout delay from minutes. More...

#define	K_HOURS(h) K_MINUTES((h) * 60)
	Generate timeout delay from hours. More...

#define	K_FOREVER Z_FOREVER
	Generate infinite timeout delay. More...

#define	K_TICKS_FOREVER ((k_ticks_t) -1)

#define	K_TIMEOUT_EQ(a, b) ((a).ticks == (b).ticks)
	Compare timeouts for equality. More...

Typedefs
typedef uint32_t	k_ticks_t
	Tick precision used in timeout APIs. More...

Functions
int	sys_clock_driver_init (const struct device *dev)
	Initialize system clock driver. More...

int	clock_device_ctrl (const struct device *dev, enum pm_device_state state)
	Initialize system clock driver. More...

void	sys_clock_set_timeout (int32_t ticks, bool idle)
	Set system clock timeout. More...

void	sys_clock_idle_exit (void)
	Timer idle exit notification. More...

void	sys_clock_announce (int32_t ticks)
	Announce time progress to the kernel. More...

uint32_t	sys_clock_elapsed (void)
	Ticks elapsed since last sys_clock_announce() call. More...

int64_t	k_uptime_ticks (void)
	Get system uptime, in system ticks. More...

static int64_t	k_uptime_get (void)
	Get system uptime. More...

static uint32_t	k_uptime_get_32 (void)
	Get system uptime (32-bit version). More...

static int64_t	k_uptime_delta (int64_t *reftime)
	Get elapsed time. More...

static uint32_t	k_cycle_get_32 (void)
	Read the hardware clock. More...

Detailed Description

Clock APIs.

Macro Definition Documentation

◆ K_CYC

#define K_CYC ( t ) Z_TIMEOUT_CYC(t)

#include <include/kernel.h>

Generate timeout delay from cycles.

This macro generates a timeout delay that instructs a kernel API to wait up to t cycles to perform the requested operation.

Parameters

t	Duration in cycles.

Returns: Timeout delay value.

◆ K_FOREVER

#define K_FOREVER Z_FOREVER

#include <include/kernel.h>

Generate infinite timeout delay.

This macro generates a timeout delay that instructs a kernel API to wait as long as necessary to perform the requested operation.

Returns: Timeout delay value.

◆ K_HOURS

#define K_HOURS ( h ) K_MINUTES((h) * 60)

#include <include/kernel.h>

Generate timeout delay from hours.

This macro generates a timeout delay that instructs a kernel API to wait up to h hours to perform the requested operation.

Parameters

h	Duration in hours.

Returns: Timeout delay value.

◆ K_MINUTES

#define K_MINUTES ( m ) K_SECONDS((m) * 60)

#include <include/kernel.h>

Generate timeout delay from minutes.

This macro generates a timeout delay that instructs a kernel API to wait up to m minutes to perform the requested operation.

Parameters

m	Duration in minutes.

Returns: Timeout delay value.

◆ K_MSEC

#define K_MSEC ( ms ) Z_TIMEOUT_MS(ms)

#include <include/kernel.h>

Generate timeout delay from milliseconds.

This macro generates a timeout delay that instructs a kernel API to wait up to ms milliseconds to perform the requested operation.

Parameters

ms	Duration in milliseconds.

Returns: Timeout delay value.

◆ K_NO_WAIT

#define K_NO_WAIT Z_TIMEOUT_NO_WAIT

#include <include/kernel.h>

Generate null timeout delay.

This macro generates a timeout delay that instructs a kernel API not to wait if the requested operation cannot be performed immediately.

Returns: Timeout delay value.

◆ K_NSEC

#define K_NSEC ( t ) Z_TIMEOUT_NS(t)

#include <include/kernel.h>

Generate timeout delay from nanoseconds.

This macro generates a timeout delay that instructs a kernel API to wait up to t nanoseconds to perform the requested operation. Note that timer precision is limited to the tick rate, not the requested value.

Parameters

t	Duration in nanoseconds.

Returns: Timeout delay value.

◆ K_SECONDS

#define K_SECONDS ( s ) K_MSEC((s) * MSEC_PER_SEC)

#include <include/kernel.h>

Generate timeout delay from seconds.

This macro generates a timeout delay that instructs a kernel API to wait up to s seconds to perform the requested operation.

Parameters

s	Duration in seconds.

Returns: Timeout delay value.

◆ K_TICKS

#define K_TICKS ( t ) Z_TIMEOUT_TICKS(t)

#include <include/kernel.h>

Generate timeout delay from system ticks.

This macro generates a timeout delay that instructs a kernel API to wait up to t ticks to perform the requested operation.

Parameters

t	Duration in system ticks.

Returns: Timeout delay value.

◆ K_TICKS_FOREVER

#define K_TICKS_FOREVER ((k_ticks_t) -1)

#include <include/sys_clock.h>

◆ K_TIMEOUT_EQ

#define K_TIMEOUT_EQ	(	a,
		b
	)	((a).ticks == (b).ticks)

#include <include/sys_clock.h>

Compare timeouts for equality.

The k_timeout_t object is an opaque struct that should not be inspected by application code. This macro exists so that users can test timeout objects for equality with known constants (e.g. K_NO_WAIT and K_FOREVER) when implementing their own APIs in terms of Zephyr timeout constants.

Returns: True if the timeout objects are identical

◆ K_USEC

#define K_USEC ( t ) Z_TIMEOUT_US(t)

#include <include/kernel.h>

Generate timeout delay from microseconds.

This macro generates a timeout delay that instructs a kernel API to wait up to t microseconds to perform the requested operation. Note that timer precision is limited to the tick rate, not the requested value.

Parameters

t	Duration in microseconds.

Returns: Timeout delay value.

Typedef Documentation

◆ k_ticks_t

typedef uint32_t k_ticks_t

#include <include/sys_clock.h>

Tick precision used in timeout APIs.

This type defines the word size of the timeout values used in k_timeout_t objects, and thus defines an upper bound on maximum timeout length (or equivalently minimum tick duration). Note that this does not affect the size of the system uptime counter, which is always a 64 bit count of ticks.

Function Documentation

◆ clock_device_ctrl()

int clock_device_ctrl	(	const struct device *	dev,
		enum pm_device_state	state
	)

#include <include/drivers/timer/system_timer.h>

Initialize system clock driver.

The system clock is a Zephyr device created globally. This is its device control callback, used in a few devices for power management. It is a weak symbol that will be implemented as a noop if undefined in the clock driver.

◆ k_cycle_get_32()

static uint32_t k_cycle_get_32 ( void )

inlinestatic

#include <include/kernel.h>

Read the hardware clock.

This routine returns the current time, as measured by the system's hardware clock.

Returns: Current hardware clock up-counter (in cycles).

◆ k_uptime_delta()

static int64_t k_uptime_delta ( int64_t * reftime )

inlinestatic

#include <include/kernel.h>

Get elapsed time.

This routine computes the elapsed time between the current system uptime and an earlier reference time, in milliseconds.

Parameters

reftime Pointer to a reference time, which is updated to the current uptime upon return.

Returns: Elapsed time.

◆ k_uptime_get()

static int64_t k_uptime_get ( void )

inlinestatic

#include <include/kernel.h>

Get system uptime.

This routine returns the elapsed time since the system booted, in milliseconds.

Note

While this function returns time in milliseconds, it does not mean it has millisecond resolution. The actual resolution depends on

embed:rst:inline :kconfig:`CONFIG_SYS_CLOCK_TICKS_PER_SEC`

config option.

Returns: Current uptime in milliseconds.

◆ k_uptime_get_32()

static uint32_t k_uptime_get_32 ( void )

inlinestatic

#include <include/kernel.h>

Get system uptime (32-bit version).

This routine returns the lower 32 bits of the system uptime in milliseconds.

Because correct conversion requires full precision of the system clock there is no benefit to using this over k_uptime_get() unless you know the application will never run long enough for the system clock to approach 2^32 ticks. Calls to this function may involve interrupt blocking and 64-bit math.

Note

While this function returns time in milliseconds, it does not mean it has millisecond resolution. The actual resolution depends on

embed:rst:inline :kconfig:`CONFIG_SYS_CLOCK_TICKS_PER_SEC`

config option

Returns: The low 32 bits of the current uptime, in milliseconds.

◆ k_uptime_ticks()

int64_t k_uptime_ticks ( void )

#include <include/kernel.h>

Get system uptime, in system ticks.

This routine returns the elapsed time since the system booted, in ticks (c.f.

embed:rst:inline :kconfig:`CONFIG_SYS_CLOCK_TICKS_PER_SEC`

), which is the fundamental unit of resolution of kernel timekeeping.

Returns: Current uptime in ticks.

◆ sys_clock_announce()

void sys_clock_announce ( int32_t ticks )

#include <include/drivers/timer/system_timer.h>

Announce time progress to the kernel.

Informs the kernel that the specified number of ticks have elapsed since the last call to sys_clock_announce() (or system startup for the first call). The timer driver is expected to delivery these announcements as close as practical (subject to hardware and latency limitations) to tick boundaries.

Parameters

ticks Elapsed time, in ticks

◆ sys_clock_driver_init()

int sys_clock_driver_init ( const struct device * dev )

#include <include/drivers/timer/system_timer.h>

Initialize system clock driver.

The system clock is a Zephyr device created globally. This is its initialization callback. It is a weak symbol that will be implemented as a noop if undefined in the clock driver.

◆ sys_clock_elapsed()

uint32_t sys_clock_elapsed ( void )

#include <include/drivers/timer/system_timer.h>

Ticks elapsed since last sys_clock_announce() call.

Queries the clock driver for the current time elapsed since the last call to sys_clock_announce() was made. The kernel will call this with appropriate locking, the driver needs only provide an instantaneous answer.

◆ sys_clock_idle_exit()

void sys_clock_idle_exit ( void )

#include <include/drivers/timer/system_timer.h>

Timer idle exit notification.

This notifies the timer driver that the system is exiting the idle and allows it to do whatever bookkeeping is needed to restore timer operation and compute elapsed ticks.

Note: Legacy timer drivers also use this opportunity to call back into sys_clock_announce() to notify the kernel of expired ticks. This is allowed for compatibility, but not recommended. The kernel will figure that out on its own.

◆ sys_clock_set_timeout()

void sys_clock_set_timeout	(	int32_t	ticks,
		bool	idle
	)

#include <include/drivers/timer/system_timer.h>

Set system clock timeout.

Informs the system clock driver that the next needed call to sys_clock_announce() will not be until the specified number of ticks from the the current time have elapsed. Note that spurious calls to sys_clock_announce() are allowed (i.e. it's legal to announce every tick and implement this function as a noop), the requirement is that one tick announcement should occur within one tick BEFORE the specified expiration (that is, passing ticks==1 means "announce the next tick", this convention was chosen to match legacy usage). Similarly a ticks value of zero (or even negative) is legal and treated identically: it simply indicates the kernel would like the next tick announcement as soon as possible.

Note that ticks can also be passed the special value K_TICKS_FOREVER, indicating that no future timer interrupts are expected or required and that the system is permitted to enter an indefinite sleep even if this could cause rollover of the internal counter (i.e. the system uptime counter is allowed to be wrong

Note also that it is conventional for the kernel to pass INT_MAX for ticks if it wants to preserve the uptime tick count but doesn't have a specific event to await. The intent here is that the driver will schedule any needed timeout as far into the future as possible. For the specific case of INT_MAX, the next call to sys_clock_announce() may occur at any point in the future, not just at INT_MAX ticks. But the correspondence between the announced ticks and real-world time must be correct.

A final note about SMP: note that the call to sys_clock_set_timeout() is made on any CPU, and reflects the next timeout desired globally. The resulting calls(s) to sys_clock_announce() must be properly serialized by the driver such that a given tick is announced exactly once across the system. The kernel does not (cannot, really) attempt to serialize things by "assigning" timeouts to specific CPUs.

Parameters

ticks	Timeout in tick units
idle	Hint to the driver that the system is about to enter the idle state immediately after setting the timeout

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ K_CYC

◆ K_FOREVER

◆ K_HOURS

◆ K_MINUTES

◆ K_MSEC

◆ K_NO_WAIT

◆ K_NSEC

◆ K_SECONDS

◆ K_TICKS

◆ K_TICKS_FOREVER

◆ K_TIMEOUT_EQ

◆ K_USEC

Typedef Documentation

◆ k_ticks_t

Function Documentation

◆ clock_device_ctrl()

◆ k_cycle_get_32()

◆ k_uptime_delta()

◆ k_uptime_get()

◆ k_uptime_get_32()

◆ k_uptime_ticks()

◆ sys_clock_announce()

◆ sys_clock_driver_init()

◆ sys_clock_elapsed()

◆ sys_clock_idle_exit()

◆ sys_clock_set_timeout()