System Clock APIs

System Clock APIs . More...

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

Macros
#define	K_NO_WAIT   Z_TIMEOUT_NO_WAIT
	Generate null timeout delay.
#define	K_NSEC(t)
	Generate timeout delay from nanoseconds.
#define	K_USEC(t)
	Generate timeout delay from microseconds.
#define	K_CYC(t)
	Generate timeout delay from cycles.
#define	K_TICKS(t)
	Generate timeout delay from system ticks.
#define	K_MSEC(ms)
	Generate timeout delay from milliseconds.
#define	K_SECONDS(s)
	Generate timeout delay from seconds.
#define	K_MINUTES(m)
	Generate timeout delay from minutes.
#define	K_HOURS(h)
	Generate timeout delay from hours.
#define	K_FOREVER   Z_FOREVER
	Generate infinite timeout delay.
#define	K_TICKS_FOREVER   ((k_ticks_t) -1)
#define	K_TIMEOUT_EQ(a, b)
	Compare timeouts for equality.
#define	NSEC_PER_USEC   1000U
	number of nanoseconds per micorsecond
#define	NSEC_PER_MSEC   1000000U
	number of nanoseconds per millisecond
#define	USEC_PER_MSEC   1000U
	number of microseconds per millisecond
#define	MSEC_PER_SEC   1000U
	number of milliseconds per second
#define	SEC_PER_MIN   60U
	number of seconds per minute
#define	SEC_PER_HOUR   3600U
	number of seconds per hour
#define	SEC_PER_DAY   86400U
	number of seconds per day
#define	MIN_PER_HOUR   60U
	number of minutes per hour
#define	HOUR_PER_DAY   24U
	number of hours per day
#define	USEC_PER_SEC   ((USEC_PER_MSEC) * (MSEC_PER_SEC))
	number of microseconds per second
#define	NSEC_PER_SEC   ((NSEC_PER_USEC) * (USEC_PER_MSEC) * (MSEC_PER_SEC))
	number of nanoseconds per second
#define	SYS_CLOCK_HW_CYCLES_TO_NS_AVG(X, NCYCLES)
	SYS_CLOCK_HW_CYCLES_TO_NS_AVG converts CPU clock cycles to nanoseconds and calculates the average cycle time.

Typedefs
typedef uint32_t	k_ticks_t
	Tick precision used in timeout APIs.

Functions
void	sys_clock_set_timeout (int32_t ticks, bool idle)
	Set system clock timeout.
void	sys_clock_idle_exit (void)
	Timer idle exit notification.
void	sys_clock_announce (int32_t ticks)
	Announce time progress to the kernel.
uint32_t	sys_clock_elapsed (void)
	Ticks elapsed since last sys_clock_announce() call.
void	sys_clock_disable (void)
	Disable system timer.
uint32_t	sys_clock_cycle_get_32 (void)
	Hardware cycle counter.
uint64_t	sys_clock_cycle_get_64 (void)
	64 bit hardware cycle counter
int64_t	k_uptime_ticks (void)
	Get system uptime, in system ticks.
static int64_t	k_uptime_get (void)
	Get system uptime.
static uint32_t	k_uptime_get_32 (void)
	Get system uptime (32-bit version).
static uint32_t	k_uptime_seconds (void)
	Get system uptime in seconds.
static int64_t	k_uptime_delta (int64_t *reftime)
	Get elapsed time.
static uint32_t	k_cycle_get_32 (void)
	Read the hardware clock.
static uint64_t	k_cycle_get_64 (void)
	Read the 64-bit hardware clock.
uint32_t	sys_clock_tick_get_32 (void)
	Return the lower part of the current system tick count.
int64_t	sys_clock_tick_get (void)
	Return the current system tick count.
k_timepoint_t	sys_timepoint_calc (k_timeout_t timeout)
	Calculate a timepoint value.
k_timeout_t	sys_timepoint_timeout (k_timepoint_t timepoint)
	Remaining time to given timepoint.
static int	sys_timepoint_cmp (k_timepoint_t a, k_timepoint_t b)
	Compare two timepoint values.
static bool	sys_timepoint_expired (k_timepoint_t timepoint)
	Indicates if timepoint is expired.

Detailed Description

System Clock APIs .

Macro Definition Documentation

HOUR_PER_DAY

#define HOUR_PER_DAY   24U

#include <zephyr/sys_clock.h>

number of hours per day

K_CYC

#define K_CYC

(

t

)

#include <zephyr/kernel.h>

Value:

Z_TIMEOUT_CYC(t)

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 <zephyr/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

)

#include <zephyr/kernel.h>

Value:

K_MINUTES((h) * 60)

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

)

#include <zephyr/kernel.h>

Value:

K_SECONDS((m) * 60)

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

)

#include <zephyr/kernel.h>

Value:

Z_TIMEOUT_MS(ms)

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 <zephyr/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

)

#include <zephyr/kernel.h>

Value:

Z_TIMEOUT_NS(t)

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

)

#include <zephyr/kernel.h>

Value:

K_MSEC((s) * MSEC_PER_SEC)

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

)

#include <zephyr/kernel.h>

Value:

Z_TIMEOUT_TICKS(t)

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 <zephyr/sys_clock.h>

K_TIMEOUT_EQ

#define K_TIMEOUT_EQ	(		a,
			b )

#include <zephyr/sys_clock.h>

Value:

((a).ticks == (b).ticks)

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

)

#include <zephyr/kernel.h>

Value:

Z_TIMEOUT_US(t)

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.

MIN_PER_HOUR

#define MIN_PER_HOUR   60U

#include <zephyr/sys_clock.h>

number of minutes per hour

MSEC_PER_SEC

#define MSEC_PER_SEC   1000U

#include <zephyr/sys_clock.h>

number of milliseconds per second

NSEC_PER_MSEC

#define NSEC_PER_MSEC   1000000U

#include <zephyr/sys_clock.h>

number of nanoseconds per millisecond

NSEC_PER_SEC

#define NSEC_PER_SEC   ((NSEC_PER_USEC) * (USEC_PER_MSEC) * (MSEC_PER_SEC))

#include <zephyr/sys_clock.h>

number of nanoseconds per second

NSEC_PER_USEC

#define NSEC_PER_USEC   1000U

#include <zephyr/sys_clock.h>

number of nanoseconds per micorsecond

SEC_PER_DAY

#define SEC_PER_DAY   86400U

#include <zephyr/sys_clock.h>

number of seconds per day

SEC_PER_HOUR

#define SEC_PER_HOUR   3600U

#include <zephyr/sys_clock.h>

number of seconds per hour

SEC_PER_MIN

#define SEC_PER_MIN   60U

#include <zephyr/sys_clock.h>

number of seconds per minute

SYS_CLOCK_HW_CYCLES_TO_NS_AVG

#define SYS_CLOCK_HW_CYCLES_TO_NS_AVG	(		X,
			NCYCLES )

#include <zephyr/sys_clock.h>

Value:

        (uint32_t)(k_cyc_to_ns_floor64(X) / NCYCLES)

SYS_CLOCK_HW_CYCLES_TO_NS_AVG converts CPU clock cycles to nanoseconds and calculates the average cycle time.

USEC_PER_MSEC

#define USEC_PER_MSEC   1000U

#include <zephyr/sys_clock.h>

number of microseconds per millisecond

USEC_PER_SEC

#define USEC_PER_SEC   ((USEC_PER_MSEC) * (MSEC_PER_SEC))

#include <zephyr/sys_clock.h>

number of microseconds per second

Typedef Documentation

k_ticks_t

typedef uint32_t k_ticks_t

#include <zephyr/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

k_cycle_get_32()

static uint32_t k_cycle_get_32 ( void )

inlinestatic

#include <zephyr/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_cycle_get_64()

static uint64_t k_cycle_get_64 ( void )

inlinestatic

#include <zephyr/kernel.h>

Read the 64-bit hardware clock.

This routine returns the current time in 64-bits, as measured by the system's hardware clock, if available.

See also

CONFIG_TIMER_HAS_64BIT_CYCLE_COUNTER

Returns

Current hardware clock up-counter (in cycles).

k_uptime_delta()

static int64_t k_uptime_delta ( int64_t * reftime )

inlinestatic

#include <zephyr/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 <zephyr/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 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 <zephyr/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 CONFIG_SYS_CLOCK_TICKS_PER_SEC config option

Returns

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

k_uptime_seconds()

static uint32_t k_uptime_seconds ( void )

inlinestatic

#include <zephyr/kernel.h>

Get system uptime in seconds.

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

Returns

Current uptime in seconds.

k_uptime_ticks()

int64_t k_uptime_ticks

(

void

)

#include <zephyr/kernel.h>

Get system uptime, in system ticks.

This routine returns the elapsed time since the system booted, in ticks (c.f. 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 <zephyr/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_cycle_get_32()

uint32_t sys_clock_cycle_get_32

(

void

)

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

Hardware cycle counter.

Timer drivers are generally responsible for the system cycle counter as well as the tick announcements. This function is generally called out of the architecture layer (

See also

arch_k_cycle_get_32()) to implement the cycle counter, though the user-facing API is owned by the architecture, not the driver. The rate must match CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC.

Note

If the counter clock is large enough for this to wrap its full range within a few seconds (i.e. CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC is greater than 50Mhz) then it is recommended to also implement sys_clock_cycle_get_64().

Returns

The current cycle time. This should count up monotonically through the full 32 bit space, wrapping at 0xffffffff. Hardware with fewer bits of precision in the timer is expected to synthesize a 32 bit count.

sys_clock_cycle_get_64()

uint64_t sys_clock_cycle_get_64

(

void

)

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

64 bit hardware cycle counter

As for sys_clock_cycle_get_32(), but with a 64 bit return value. Not all hardware has 64 bit counters. This function need be implemented only if CONFIG_TIMER_HAS_64BIT_CYCLE_COUNTER is set.

Note

If the counter clock is large enough for sys_clock_cycle_get_32() to wrap its full range within a few seconds (i.e. CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC is greater than 50Mhz) then it is recommended to implement this API.

Returns

The current cycle time. This should count up monotonically through the full 64 bit space, wrapping at 2^64-1. Hardware with fewer bits of precision in the timer is generally not expected to implement this API.

sys_clock_disable()

void sys_clock_disable

(

void

)

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

Disable system timer.

Note

Not all system timer drivers has the capability of being disabled. The config CONFIG_SYSTEM_TIMER_HAS_DISABLE_SUPPORT can be used to check if the system timer has the capability of being disabled.

sys_clock_elapsed()

uint32_t sys_clock_elapsed

(

void

)

#include <zephyr/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 <zephyr/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 <zephyr/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 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

sys_clock_tick_get()

int64_t sys_clock_tick_get

(

void

)

#include <zephyr/sys_clock.h>

Return the current system tick count.

Returns

the current system tick count

sys_clock_tick_get_32()

uint32_t sys_clock_tick_get_32

(

void

)

#include <zephyr/sys_clock.h>

Return the lower part of the current system tick count.

Returns

the current system tick count

sys_timepoint_calc()

k_timepoint_t sys_timepoint_calc

(

k_timeout_t

timeout

)

#include <zephyr/sys_clock.h>

Calculate a timepoint value.

Returns a timepoint corresponding to the expiration (relative to an unlocked "now"!) of a timeout object. When used correctly, this should be called once, synchronously with the user passing a new timeout value. It should not be used iteratively to adjust a timeout (see sys_timepoint_timeout() for that purpose).

Parameters

timeout

Timeout value relative to current time (may also be K_FOREVER or K_NO_WAIT).

Return values

Timepoint

value corresponding to given timeout

See also

sys_timepoint_timeout()

sys_timepoint_expired()

sys_timepoint_cmp()

static int sys_timepoint_cmp ( k_timepoint_t a, k_timepoint_t b )

inlinestatic

#include <zephyr/sys_clock.h>

Compare two timepoint values.

This function is used to compare two timepoint values.

Parameters

a	Timepoint to compare
b	Timepoint to compare against.

Returns

zero if both timepoints are the same. Negative value if timepoint a is before timepoint b, positive otherwise.

sys_timepoint_expired()

static bool sys_timepoint_expired ( k_timepoint_t timepoint )

inlinestatic

#include <zephyr/sys_clock.h>

Indicates if timepoint is expired.

Parameters

timepoint

Timepoint to evaluate

Return values

true	if the timepoint is in the past, false otherwise

See also

sys_timepoint_calc()

sys_timepoint_timeout()

k_timeout_t sys_timepoint_timeout

(

k_timepoint_t

timepoint

)

#include <zephyr/sys_clock.h>

Remaining time to given timepoint.

Returns the timeout interval between current time and provided timepoint. If the timepoint is now in the past or if it was created with K_NO_WAIT then K_NO_WAIT is returned. If it was created with K_FOREVER then K_FOREVER is returned.

Parameters

timepoint

Timepoint for which a timeout value is wanted.

Return values

Corresponding

timeout value.

See also

sys_timepoint_calc()