Zephyr API Documentation  3.6.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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)   Z_TIMEOUT_NS(t)
 Generate timeout delay from nanoseconds.
 
#define K_USEC(t)   Z_TIMEOUT_US(t)
 Generate timeout delay from microseconds.
 
#define K_CYC(t)   Z_TIMEOUT_CYC(t)
 Generate timeout delay from cycles.
 
#define K_TICKS(t)   Z_TIMEOUT_TICKS(t)
 Generate timeout delay from system ticks.
 
#define K_MSEC(ms)   Z_TIMEOUT_MS(ms)
 Generate timeout delay from milliseconds.
 
#define K_SECONDS(s)   K_MSEC((s) * MSEC_PER_SEC)
 Generate timeout delay from seconds.
 
#define K_MINUTES(m)   K_SECONDS((m) * 60)
 Generate timeout delay from minutes.
 
#define K_HOURS(h)   K_MINUTES((h) * 60)
 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)   ((a).ticks == (b).ticks)
 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 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)    (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.
 

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 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 uint64_t sys_clock_timeout_end_calc (k_timeout_t timeout)
 Provided for backward compatibility.
 
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)    Z_TIMEOUT_CYC(t)

#include <zephyr/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
tDuration 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)    K_MINUTES((h) * 60)

#include <zephyr/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
hDuration in hours.
Returns
Timeout delay value.

◆ K_MINUTES

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

#include <zephyr/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
mDuration in minutes.
Returns
Timeout delay value.

◆ K_MSEC

#define K_MSEC (   ms)    Z_TIMEOUT_MS(ms)

#include <zephyr/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
msDuration 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)    Z_TIMEOUT_NS(t)

#include <zephyr/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
tDuration in nanoseconds.
Returns
Timeout delay value.

◆ K_SECONDS

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

#include <zephyr/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
sDuration in seconds.
Returns
Timeout delay value.

◆ K_TICKS

#define K_TICKS (   t)    Z_TIMEOUT_TICKS(t)

#include <zephyr/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
tDuration 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,
 
)    ((a).ticks == (b).ticks)

#include <zephyr/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 <zephyr/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
tDuration 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_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 
)     (uint32_t)(k_cyc_to_ns_floor64(X) / NCYCLES)

#include <zephyr/sys_clock.h>

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

#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
reftimePointer 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_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
ticksElapsed 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 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
ticksTimeout in tick units
idleHint 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_clock_timeout_end_calc()

static uint64_t sys_clock_timeout_end_calc ( k_timeout_t  timeout)
inlinestatic

#include <zephyr/sys_clock.h>

Provided for backward compatibility.

This is deprecated. Consider sys_timepoint_calc() instead.

See also
sys_timepoint_calc()

◆ 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
timeoutTimeout value relative to current time (may also be K_FOREVER or K_NO_WAIT).
Return values
Timepointvalue 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
aTimepoint to compare
bTimepoint 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
timepointTimepoint to evaluate
Return values
trueif 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
timepointTimepoint for which a timeout value is wanted.
Return values
Correspondingtimeout value.
See also
sys_timepoint_calc()