System Clock APIs

System Clock APIs. More...

Topics
	System Timer Low-power Companion Interface
	System timer low-power companion interface.

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_TIMEOUT_SUM(timeout1, timeout2)
	Add two k_timeout_t values together.
#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 microsecond
#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.
#define	SYS_CLOCK_REALTIME   1
	The real-time clock (i.e.
#define	SYS_CLOCK_MONOTONIC   4
	The monotonic clock.
#define	SYS_TIMER_ABSTIME   4
	The flag used for specifying absolute timeouts.

Typedefs
typedef uint32_t	k_ticks_t
	Tick precision used in timeout APIs.

Functions
k_spinlock_key_t	sys_clock_lock (void)
	Lock the system clock.
void	sys_clock_unlock (k_spinlock_key_t key)
	Unlock the system clock.
void	sys_clock_set_timeout (uint32_t ticks, bool idle)
	Set system clock timeout.
void	sys_clock_idle_exit (void)
	Timer idle exit notification.
void	sys_clock_announce_locked (uint32_t ticks, k_spinlock_key_t key)
	Announce time progress to the kernel.
static void	sys_clock_announce (uint32_t ticks)
	Announce time progress to the kernel (legacy wrapper).
uint32_t	sys_clock_elapsed (void)
	Ticks elapsed since last sys_clock_announce() call.
void	sys_clock_disable (void)
	Disable system timer.
void	sys_clock_no_timeout (void)
	Notify the timer driver that no timeout is pending.
void	sys_clock_idle_enter (uint32_t ticks)
	Notify the timer driver that the CPU is entering low-power idle.
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, and update the referenced 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.
void	sys_clock_getrtoffset (struct timespec *tp)
	Get the offset SYS_CLOCK_REALTIME with respect to SYS_CLOCK_MONOTONIC.
int	sys_clock_gettime (int clock_id, struct timespec *tp)
	Get the current time from the specified clock.
int	sys_clock_settime (int clock_id, const struct timespec *tp)
	Set the current time for the specified clock.
int	sys_clock_nanosleep (int clock_id, int flags, const struct timespec *rqtp, struct timespec *rmtp)
	Sleep for the specified amount of time with respect to the specified clock.

Detailed Description

System Clock APIs.

Macro Definition Documentation

HOUR_PER_DAY

#define HOUR_PER_DAY   24U

#include <clock.h>

number of hours per day

K_CYC

#define K_CYC

(

t

)

#include <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 <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 <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 <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 <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 <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 <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 <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 <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 <clock.h>

K_TIMEOUT_EQ

#define K_TIMEOUT_EQ	(		a,
			b )

#include <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_TIMEOUT_SUM

#define K_TIMEOUT_SUM	(		timeout1,
			timeout2 )

#include <kernel.h>

Value:

K_TICKS(z_timeout_sum(timeout1, timeout2))

Add two k_timeout_t values together.

This macro adds two k_timeout_t values together. If only one value is an absolute timeout, the result will be an absolute timeout. If both are relative timeouts, the result will be a relative timeout. If the calculation overflows, underflows or if both values are absolute timeouts, K_FOREVER is returned.

Parameters

timeout1	First k_timeout_t value
timeout2	Second k_timeout_t value

Returns

Sum of the two timeout values, or K_FOREVER if incalculable

K_USEC

#define K_USEC

(

t

)

#include <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 <clock.h>

number of minutes per hour

MSEC_PER_SEC

#define MSEC_PER_SEC   1000U

#include <clock.h>

number of milliseconds per second

NSEC_PER_MSEC

#define NSEC_PER_MSEC   1000000U

#include <clock.h>

number of nanoseconds per millisecond

NSEC_PER_SEC

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

#include <clock.h>

number of nanoseconds per second

NSEC_PER_USEC

#define NSEC_PER_USEC   1000U

#include <clock.h>

number of nanoseconds per microsecond

SEC_PER_DAY

#define SEC_PER_DAY   86400U

#include <clock.h>

number of seconds per day

SEC_PER_HOUR

#define SEC_PER_HOUR   3600U

#include <clock.h>

number of seconds per hour

SEC_PER_MIN

#define SEC_PER_MIN   60U

#include <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 <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.

SYS_CLOCK_MONOTONIC

#define SYS_CLOCK_MONOTONIC   4

#include <clock.h>

The monotonic clock.

This steady clock is used to measure time since the system booted. Time from this clock is always monotonically increasing.

SYS_CLOCK_REALTIME

#define SYS_CLOCK_REALTIME   1

#include <clock.h>

The real-time clock (i.e.

"wall clock")

This clock is used to measure time since the epoch (1970-01-01 00:00:00 UTC).

It is not a steady clock; i.e. it may be adjusted for a number of reasons from initialization of a hardware real-time-clock, to network-time synchronization, to manual adjustment from the application.

SYS_TIMER_ABSTIME

#define SYS_TIMER_ABSTIME   4

#include <clock.h>

The flag used for specifying absolute timeouts.

This flag may be passed to sys_clock_nanosleep to indicate the requested timeout is an absolute time with respect to the specified clock.

USEC_PER_MSEC

#define USEC_PER_MSEC   1000U

#include <clock.h>

number of microseconds per millisecond

USEC_PER_SEC

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

#include <clock.h>

number of microseconds per second

Typedef Documentation

k_ticks_t

typedef uint32_t k_ticks_t

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

uint32_t k_cycle_get_32 ( void )

inlinestatic

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

uint64_t k_cycle_get_64 ( void )

inlinestatic

#include <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.

Note

Requires

CONFIG_TIMER_HAS_64BIT_CYCLE_COUNTER 

. When that option is not enabled this routine asserts and returns 0.

See also

CONFIG_TIMER_HAS_64BIT_CYCLE_COUNTER

Returns

Current hardware clock up-counter (in cycles).

k_uptime_delta()

int64_t k_uptime_delta ( int64_t * reftime )

inlinestatic

#include <kernel.h>

Get elapsed time, and update the referenced 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, in milliseconds.

k_uptime_get()

int64_t k_uptime_get ( void )

inlinestatic

#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

CONFIG_SYS_CLOCK_TICKS_PER_SEC 

config option.

Returns

Current uptime in milliseconds.

k_uptime_get_32()

uint32_t k_uptime_get_32 ( void )

inlinestatic

#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

CONFIG_SYS_CLOCK_TICKS_PER_SEC 

config option

Returns

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

k_uptime_seconds()

uint32_t k_uptime_seconds ( void )

inlinestatic

#include <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 <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 ( uint32_t ticks )

inlinestatic

#include <system_timer.h>

Announce time progress to the kernel (legacy wrapper).

Convenience wrapper around sys_clock_announce_locked that acquires the system clock lock internally. New drivers should prefer sys_clock_lock() + sys_clock_announce_locked() to protect driver state and tick accounting under a single lock.

Parameters

ticks

Elapsed time, in ticks

sys_clock_announce_locked()

void sys_clock_announce_locked	(	uint32_t	ticks,
		k_spinlock_key_t	key )

#include <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 deliver these announcements as close as practical (subject to hardware and latency limitations) to tick boundaries.

The caller must already hold the system clock lock obtained via sys_clock_lock(). The key is consumed: the lock is released when this function returns.

This is the preferred interface for timer ISRs that need to update driver-internal state (e.g. cycle counter baseline) atomically with the kernel tick accounting. See sys_clock_lock() for example usage.

Parameters

ticks	Elapsed time, in ticks
key	Lock key obtained from sys_clock_lock().

sys_clock_cycle_get_32()

uint32_t sys_clock_cycle_get_32

(

void

)

#include <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 <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 <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 <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.

Note

This function is called by the kernel with the system clock lock held.

sys_clock_getrtoffset()

void sys_clock_getrtoffset

(

struct timespec *

tp

)

#include <clock.h>

Get the offset SYS_CLOCK_REALTIME with respect to SYS_CLOCK_MONOTONIC.

The "wall clock" (i.e. SYS_CLOCK_REALTIME) depends on a base time that is set by the system. The base time may be updated for a number of reasons, such as initialization of a hardware real-time-clock (RTC), network time protocol (NTP) synchronization, or manual adjustment by the application.

This function retrieves the current time offset, as a timespec object, for SYS_CLOCK_REALTIME, with respect to SYS_CLOCK_MONOTONIC, and writes it to the provided memory location pointed-to by tp.

Note

This function may assert if tp is NULL.

Parameters

tp	Pointer to memory where time will be written.

sys_clock_gettime()

int sys_clock_gettime	(	int	clock_id,
		struct timespec *	tp )

#include <clock.h>

Get the current time from the specified clock.

Parameters

clock_id	The clock from which to query time.
tp	Pointer to memory where time will be written.

Return values

0	on success.
-EINVAL	when an invalid clock_id is specified.

sys_clock_idle_enter()

void sys_clock_idle_enter

(

uint32_t

ticks

)

#include <system_timer.h>

Notify the timer driver that the CPU is entering low-power idle.

Called from the power-management idle path when the CPU is about to sleep. A driver that hands off to a low-power wakeup timer, or otherwise reconfigures itself for sleep, does so here. sys_clock_idle_exit() undoes it on the way out. A driver with no low-power handling does not need to implement this hook.

The hook is optional. Without it, sys_clock_set_timeout() is called with its deprecated idle argument set to true, which keeps a driver keying its low-power handling on that argument working. It goes with the argument, by which time a platform using the power management facility is expected to have implemented sys_clock_idle_enter() itself.

Parameters

ticks

Ticks until the next expected wakeup, or SYS_CLOCK_IDLE_FOREVER when nothing needs to wake the CPU and the uptime accounting is allowed to drift, in which case the driver may stop its time base. Only the calling CPU is going idle: a driver whose time base is shared between CPUs must ensure only the last CPU going idle stops the clock.

sys_clock_idle_exit()

void sys_clock_idle_exit

(

void

)

#include <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_lock()

k_spinlock_key_t sys_clock_lock

(

void

)

#include <system_timer.h>

Lock the system clock.

Acquires the kernel timer lock that protects tick accounting and the timeout queue. Timer drivers should call this at the start of their ISR and pass the returned key to sys_clock_announce_locked() which consumes it. The lock is released when sys_clock_announce_locked() returns.

The driver-provided functions sys_clock_set_timeout() and sys_clock_elapsed() are always called by the kernel with this lock already held.

Example usage from a timer ISR:

static void timer_isr(const void *arg)
{
    k_spinlock_key_t key = sys_clock_lock();
 
    // Update driver-private state (e.g. cycle counter baseline)
    uint64_t now = read_hw_counter();
    uint32_t dticks = (now - last_cycle) / CYC_PER_TICK;
    last_cycle += (uint64_t)dticks * CYC_PER_TICK;
 
    // Reprogram comparator if needed ...
 
    // Announce ticks — key ownership transfers to announce.
    sys_clock_announce_locked(dticks, key);
}

Returns

Lock key to be passed to sys_clock_announce_locked() or sys_clock_unlock().

sys_clock_nanosleep()

int sys_clock_nanosleep	(	int	clock_id,
		int	flags,
		const struct timespec *	rqtp,
		struct timespec *	rmtp )

#include <clock.h>

Sleep for the specified amount of time with respect to the specified clock.

This function will cause the calling thread to sleep either

• until the absolute time specified by rqtp (if flags includes SYS_TIMER_ABSTIME), or
• until the relative time specified by rqtp (if flags does not include SYS_TIMER_ABSTIME).

The accepted values for clock_id include

• SYS_CLOCK_REALTIME
• SYS_CLOCK_MONOTONIC

If rmtp is not NULL, and the thread is awoken prior to the time specified by rqtp, then any remaining time will be written to rmtp. If the thread has slept for at least the time specified by rqtp, then rmtp will be set to zero.

Parameters

clock_id	The clock to by which to sleep.
flags	Flags to modify the behavior of the sleep operation.
rqtp	Pointer to the requested time to sleep.
rmtp	Pointer to memory into which to copy the remaining time, if any.

Return values

0	on success.
-EINVAL	when an invalid clock_id, when rqtp contains nanoseconds outside of the range [0, 999999999], or when rqtp contains a negative value.

sys_clock_no_timeout()

void sys_clock_no_timeout

(

void

)

#include <system_timer.h>

Notify the timer driver that no timeout is pending.

Called by the kernel in place of sys_clock_set_timeout() when the timeout queue is empty and

CONFIG_SYSTEM_CLOCK_SLOPPY_IDLE 

is enabled. No tick announcement is forthcoming and the system does not care about precise uptime keeping, so the driver may do something to save resources: mask the wakeup, program the longest interval the hardware can hold, or both. Normal operation resumes at the next sys_clock_set_timeout().

The CPU keeps running, so sys_clock_cycle_get_32() and sys_clock_cycle_get_64() must keep counting: a thread can still call k_cycle_get_32() or k_busy_wait(). A driver whose cycle counter is driven by the timer it would stop can therefore only mask the interrupt. One whose cycle counter lives in a different clock or power domain may stop more. Stopping the time base belongs in sys_clock_idle_enter().

Unlike sys_clock_disable(), this is not a teardown.

The hook is optional. Without it, sys_clock_set_timeout() is asked for the longest wait it can express, UINT32_MAX ticks. That is numerically what K_TICKS_FOREVER was here, so a driver that has not migrated and still keys on that value stops its clock as it always did.

sys_clock_set_timeout()

void sys_clock_set_timeout	(	uint32_t	ticks,
		bool	idle )

#include <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 is legal: it simply indicates the kernel would like the next tick announcement as soon as possible.

No tick count carries a meaning of its own. The driver arms what it is asked for, clamping to what its hardware can hold and announcing the ticks that did elapse.

The two conditions a driver used to infer from the tick value now have their own entry points: sys_clock_no_timeout() for "no timeout is pending" and sys_clock_idle_enter() for "the CPU is going to sleep".

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.

Note

This function is called by the kernel with the system clock lock held.

Parameters

ticks	Timeout in tick units
idle	Deprecated, and always false when the kernel calls this function: idle entry is notified through sys_clock_idle_enter(), whose fallback passes true here. Scheduled for removal in a future release; new code must ignore it.

sys_clock_settime()

int sys_clock_settime	(	int	clock_id,
		const struct timespec *	tp )

#include <clock.h>

Set the current time for the specified clock.

Parameters

clock_id	The clock for which the time should be set.
tp	Pointer to memory specifying the desired time.

Return values

0	on success.
-EINVAL	when an invalid clock_id is specified or when tp contains nanoseconds outside of the range [0, 999999999].

sys_clock_tick_get()

int64_t sys_clock_tick_get

(

void

)

#include <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 <clock.h>

Return the lower part of the current system tick count.

Returns

the current system tick count

sys_clock_unlock()

void sys_clock_unlock

(

k_spinlock_key_t

key

)

#include <system_timer.h>

Unlock the system clock.

Releases the kernel timer lock previously acquired with sys_clock_lock(). Provided for drivers with special needs; most drivers should use sys_clock_announce_locked() which handles unlocking automatically.

Parameters

key	Lock key returned by sys_clock_lock().

sys_timepoint_calc()

k_timepoint_t sys_timepoint_calc

(

k_timeout_t

timeout

)

#include <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).

Returns

Timepoint value corresponding to given timeout

See also

sys_timepoint_timeout()

sys_timepoint_expired()

sys_timepoint_cmp()

int sys_timepoint_cmp ( k_timepoint_t a, k_timepoint_t b )

inlinestatic

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

bool sys_timepoint_expired ( k_timepoint_t timepoint )

inlinestatic

#include <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 <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.

Returns

Corresponding timeout value.

See also

sys_timepoint_calc()