Zephyr API Documentation  2.7.0-rc2
A Scalable Open Source RTOS
Clock APIs

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
tDuration 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
hDuration 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
mDuration 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
msDuration 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
tDuration 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
sDuration 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
tDuration 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,
 
)    ((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
tDuration in microseconds.
Returns
Timeout delay value.

Typedef Documentation

◆ 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
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 <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
ticksElapsed 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
ticksTimeout in tick units
idleHint to the driver that the system is about to enter the idle state immediately after setting the timeout