System Timer Drivers
This page describes the interface between the kernel’s tick accounting and the driver for the hardware that produces those ticks. The kernel side of that accounting, and everything an application sees, is described in Kernel Timing.
Timer Drivers
Kernel timing at the tick level is driven by a timer driver with a comparatively simple API.
The driver is expected to be able to “announce” new ticks to the kernel via the
sys_clock_announce()call, which passes an integer number of ticks that have elapsed since the last announce call (or system boot). These calls can occur at any time, but the driver is expected to attempt to ensure (to the extent practical given interrupt latency interactions) that they occur near tick boundaries (i.e. not “halfway through” a tick), and most importantly that they be correct over time and subject to minimal skew vs. other counters and real world time.The driver is expected to provide a
sys_clock_set_timeout()call to the kernel which indicates how many ticks may elapse before the kernel must receive an announce call to trigger registered timeouts. It is legal to announce new ticks before that moment (though they must be correct) but delay after that will cause events to be missed. Note that the timeout value passed here is in a delta from current time, but that does not absolve the driver of the requirement to provide ticks at a steady rate over time. Naive implementations of this function are subject to bugs where the fractional tick gets “reset” incorrectly and causes clock skew.The driver is expected to provide a
sys_clock_elapsed()call which provides a current indication of how many ticks have elapsed (as compared to a real world clock) since the last call tosys_clock_announce(), which the kernel needs to test newly arriving timeouts for expiration.The driver may optionally provide a
sys_clock_no_timeout()call. The kernel invokes it in place ofsys_clock_set_timeout()when no timeout is pending, that is when the timeout queue is empty, andCONFIG_SYSTEM_CLOCK_SLOPPY_IDLEis 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. Normal operation resumes at the next
sys_clock_set_timeout(); unlikesys_clock_disable(), this is not a teardown.The timer counter must not be stopped.
sys_clock_cycle_get_32()andsys_clock_cycle_get_64()must keep counting up as if the call had never happened.Note
The CPU keeps running with an empty timeout queue, for instance because the ready queue still holds threads, or because an interrupt fires. Those threads and ISRs may call
k_cycle_get_32()ork_busy_wait(). That limits what an implementation may do: masking the timer interrupt is safe, gating the timer’s clock most likely is not. Exactly what is safe is hardware specific.The hook is optional. Without it,
sys_clock_set_timeout()is asked for the longest wait it can express,UINT32_MAXticks. That is numerically whatK_TICKS_FOREVERwas here, the long-standing “no deadline” signal, so a driver that has not been converted keeps working.The driver may optionally provide a
sys_clock_idle_enter()call, which the power-management path uses in place ofsys_clock_set_timeout()when the CPU is about to enter low-power idle. It receives the number of ticks until the next expected wakeup, orSYS_CLOCK_IDLE_FOREVERwhen there is none and the uptime accounting may drift.A driver that hands off to a low-power wakeup timer, or otherwise reconfigures itself for sleep, does so here. Told
SYS_CLOCK_IDLE_FOREVERit may also stop its time base, whichsys_clock_no_timeout()does not allow, because the CPU is on its way out andsys_clock_idle_exit()is guaranteed to run on the way back in. Only the calling CPU goes idle, so a driver whose time base is shared between CPUs must ensure only the last CPU going idle stops the clock.The hook is optional. Without it,
sys_clock_set_timeout()is called with its deprecatedidleargument set totrue, so a driver still keying its low-power handling on that argument keeps working.
The last three entry points divide the four states a system can be in:
nothing pending |
something pending |
|
|---|---|---|
running |
|
|
idle |
|
|
Without CONFIG_SYSTEM_CLOCK_SLOPPY_IDLE the left column never
arises: the kernel keeps a synthetic deadline armed so the uptime stays exact,
and a driver only ever sees the right one.
Timer Driver Locking
The kernel exposes a unified timer lock via sys_clock_lock() and
sys_clock_unlock(). This lock protects both the kernel’s internal
tick accounting (curr_tick, the timeout queue) and any driver-private
state that must be consistent with it (e.g. a hardware cycle counter
baseline).
Timer drivers that maintain internal state should acquire this lock at
the start of their ISR, update their hardware state, then pass the lock
key to sys_clock_announce_locked() which consumes it. This
ensures that the driver’s cycle counter baseline and the kernel’s
curr_tick are always updated under the same lock, eliminating race
conditions that can arise on SMP systems (or, less commonly, on UP
systems where higher-priority ISRs need consistent realtime references)
when two separate locks are used.
The driver-provided callbacks sys_clock_set_timeout() and
sys_clock_elapsed() are always invoked by the kernel with this
lock already held.
For backward compatibility, sys_clock_announce() remains
available and acquires the lock internally. New and migrated drivers
should prefer the sys_clock_lock() /
sys_clock_announce_locked() pattern.
Note that a natural implementation of this API results in a “tickless” kernel, which receives and processes timer interrupts only for registered events, relying on programmable hardware counters to provide irregular interrupts. But a traditional, “ticked” or “dumb” counter driver can be trivially implemented also:
The driver can receive interrupts at a regular rate corresponding to the OS tick rate, calling
sys_clock_announce()with an argument of one each time.The driver can ignore calls to
sys_clock_set_timeout(), as every tick will be announced regardless of timeout status.The driver can return zero for every call to
sys_clock_elapsed()as no more than one tick can be detected as having elapsed (because otherwise an interrupt would have been received).
SMP Details
In general, the timer API described above does not change when run in a multiprocessor context. The kernel will internally synchronize all access appropriately, and ensure that all critical sections are small and minimal. But some notes are important to detail:
Zephyr is agnostic about which CPU services timer interrupts. It is not illegal (though probably undesirable in some circumstances) to have every timer interrupt handled on a single processor. Existing SMP architectures implement symmetric timer drivers.
The
sys_clock_announce()call is expected to be globally synchronized at the driver level. The kernel does not do any per-CPU tracking, and expects that if two timer interrupts fire near simultaneously, that only one will provide the current tick count to the timing subsystem. The other may legally provide a tick count of zero if no ticks have elapsed. It should not “skip” the announce call because of timeslicing requirements (see the time slicing notes in Kernel Timing).Some SMP hardware uses a single, global timer device, others use a per-CPU counter. The complexity here (for example: ensuring counter synchronization between CPUs) is expected to be managed by the driver, not the kernel.
The next timeout value passed back to the driver via
sys_clock_set_timeout()is done identically for every CPU. So by default, every CPU will see simultaneous timer interrupts for every event, even though by definition only one of them should see a non-zero ticks argument tosys_clock_announce(). This is probably a correct default for timing sensitive applications (because it minimizes the chance that an errant ISR or interrupt lock will delay a timeout), but may be a performance problem in some cases. The current design expects that any such optimization is the responsibility of the timer driver.
Generic Tickless Core
The work described above, the cycle-to-tick conversion, the announce baseline, the tick-aligned deadline computation and the counter wrap and range handling, is nearly the same in every tickless driver, and the hand-rolled variations are a recurring source of timer bugs. With drivers/timer/system_timer_generic.h the driver only has to read the counter and arm the alarm.
This header holds the actual sys_clock_set_timeout(),
sys_clock_elapsed(), sys_clock_cycle_get_32() and
sys_clock_cycle_get_64(), so a driver includes it once, from its .c
file in drivers/timer/, after the definitions listed below. New
tickless drivers should build on it rather than do their own tick accounting.
What the driver provides
One backend, matching the hardware:
TIMER_CORE_BACKEND_COMPARE_ORDEREDFree-running counter with a compare register that fires once the counter reaches or passes it. A value already in the past fires right away.
TIMER_CORE_BACKEND_COMPARE_EXACTSame, but the compare fires only on an exact match. A value written too late is missed until the counter wraps, so the core reads the counter back after each write and moves the value out if needed.
TIMER_CORE_BACKEND_RELOADA timer that fires after a given delay and then reloads by itself, like a down-counter.
timer_driver_cycle_get(), which returns the raw counter value. The core handles the wraps, given the counter width inTIMER_CORE_COUNTER_WIDTH.One arming function:
timer_driver_set_compare()for the compare backends, which writes an absolute counter value, ortimer_driver_set_reload()for the reload backend, which fires the interrupt a number of cycles from now.An ISR that acknowledges the hardware, then calls
timer_core_announce().An init function that connects the IRQ, then calls
timer_core_init().On SMP,
smp_timer_init(), which callstimer_core_smp_prime().
Optional settings cover a counter running at another rate than the kernel’s, a rate known only at run time, a counter that isn’t a single register read, an alarm with a shorter reach than the counter, and the like. drivers/timer/system_timer_generic.h lists them all, with their defaults. Most drivers need one or two at most.
The core provides both cycle getters. Whether to also select
CONFIG_TIMER_HAS_64BIT_CYCLE_COUNTER is up to the driver:
select it when sys_clock_cycle_get_64() costs no more than the 32-bit
one, as with a 64-bit counter.
Example: a compare timer
This fictitious timer block has a 32-bit counter and an exact-match compare register, as found on many microcontrollers:
COUNTFree-running 32-bit up-counter, read-only. It runs at the kernel’s hardware clock rate,
CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC.COMPAREThe interrupt fires when
COUNTequals this value.STATUSWriting 1 to bit 0 clears the pending interrupt.
#include <zephyr/init.h>
#include <zephyr/irq.h>
#include <zephyr/sys/sys_io.h>
#define TMR_BASE 0x40001000
#define TMR_COUNT (TMR_BASE + 0x0)
#define TMR_COMPARE (TMR_BASE + 0x4)
#define TMR_STATUS (TMR_BASE + 0x8)
#define TMR_IRQ 5
#define TIMER_CORE_BACKEND_COMPARE_EXACT
#define TIMER_CORE_COUNTER_WIDTH 32
static inline uint32_t timer_driver_cycle_get(void)
{
return sys_read32(TMR_COUNT);
}
static inline void timer_driver_set_compare(uint32_t cycles)
{
sys_write32(cycles, TMR_COMPARE);
}
#include "system_timer_generic.h"
static void tmr_isr(const void *arg)
{
ARG_UNUSED(arg);
sys_write32(BIT(0), TMR_STATUS);
timer_core_announce();
}
static int tmr_init(void)
{
IRQ_CONNECT(TMR_IRQ, 0, tmr_isr, NULL, 0);
timer_core_init();
irq_enable(TMR_IRQ);
return 0;
}
SYS_INIT(tmr_init, PRE_KERNEL_2, CONFIG_SYSTEM_CLOCK_INIT_PRIORITY);
TIMER_CORE_COUNTER_WIDTH is needed on a 64-bit CPU, where the default is 64.
If the compare fired on “reached or passed” instead, as with a 64-bit counter
like the RISC-V machine timer, the only change would be
TIMER_CORE_BACKEND_COMPARE_ORDERED.
Example: a reload timer
This fictitious timer block has the same free-running counter plus a separate down-counter that raises the interrupt:
COUNTFree-running 32-bit up-counter, read-only, at the kernel’s hardware clock rate.
RELOAD24-bit down-counter period, counted at the same rate as
COUNT. Writing it restarts the countdown from the new value. When the countdown reaches zero, the interrupt fires and the countdown restarts fromRELOAD.STATUSWriting 1 to bit 0 clears the pending interrupt.
CTRLBit 0 starts the countdown, bit 1 enables its interrupt.
#include <zephyr/init.h>
#include <zephyr/irq.h>
#include <zephyr/sys/sys_io.h>
#define TMR_BASE 0x40002000
#define TMR_COUNT (TMR_BASE + 0x0)
#define TMR_RELOAD (TMR_BASE + 0x4)
#define TMR_STATUS (TMR_BASE + 0x8)
#define TMR_CTRL (TMR_BASE + 0xc)
#define TMR_IRQ 6
#define TIMER_CORE_BACKEND_RELOAD
#define TIMER_CORE_COUNTER_WIDTH 32
#define TIMER_CORE_ALARM_MAX_CYCLES 0xffffffU
static inline uint32_t timer_driver_cycle_get(void)
{
return sys_read32(TMR_COUNT);
}
static inline void timer_driver_set_reload(uint32_t cycles)
{
sys_write32(cycles, TMR_RELOAD);
}
#include "system_timer_generic.h"
static void tmr_isr(const void *arg)
{
ARG_UNUSED(arg);
sys_write32(BIT(0), TMR_STATUS);
timer_core_announce();
}
static int tmr_init(void)
{
/* One tick: the period on a ticking kernel, where the core
* never writes RELOAD.
*/
sys_write32(TIMER_CORE_CYC_PER_TICK, TMR_RELOAD);
sys_write32(BIT(0) | BIT(1), TMR_CTRL);
IRQ_CONNECT(TMR_IRQ, 0, tmr_isr, NULL, 0);
timer_core_init();
irq_enable(TMR_IRQ);
return 0;
}
SYS_INIT(tmr_init, PRE_KERNEL_2, CONFIG_SYSTEM_CLOCK_INIT_PRIORITY);
RELOAD is narrower than COUNT, so TIMER_CORE_ALARM_MAX_CYCLES gives
its limit. A deadline further out than that takes several reloads, which the
core handles.
Many down-counters have no free-running counter next to them. The driver then
builds the count in software from the reload values and the current countdown,
sets TIMER_CORE_COUNTER_NONATOMIC, and adds each finished period to its
count in the ISR under the clock lock, before calling
timer_core_announce_from(). drivers/timer/cmsdk_apb_timer.c
does this.