Timekeeping and Timers
Relevant source files
The following files were used as context for generating this wiki page:
The Timekeeping and Timers subsystem manages the kernel's perception of time and provides mechanisms for scheduled code execution. It encompasses hardware clock sources, timekeeping logic, and various timer interfaces used by both kernel modules and core systems. Sources: Documentation/process/maintainer-tip.rst:54, Documentation/kernel-hacking/hacking.rst:87
Subsystem Architecture
The timer infrastructure is organized into several distinct areas of responsibility. These components reside primarily in the timers/core branch of the kernel tree and work together to provide consistent time services across different hardware architectures. Sources: Documentation/process/maintainer-tip.rst:54-62
Core Components
- Timekeeping: Manages the system wall time and updates it based on clock sources.
- Clocksource Core: Provides a generic interface for various hardware counters used to track time.
- NTP (Network Time Protocol): Synchronizes the system clock with external time servers.
- Alarmtimers: Handles timers that can wake the system from suspended states.
- Clocksource/Event Drivers: Architecture-specific drivers that interface with hardware timers.
The diagram above shows the relationship between the hardware drivers and the core timekeeping logic within the timers/core branch. Sources: Documentation/process/maintainer-tip.rst:54-62
Execution Contexts and Interrupts
Timers operate across different CPU execution states. Hardware interrupts (Hard IRQs) trigger the initial response to a timer tick, while the actual execution of timer-related functions often occurs in software interrupt (Softirq) context. Sources: Documentation/kernel-hacking/hacking.rst:64-70, Documentation/kernel-hacking/hacking.rst:87-92
The Timer Softirq
The kernel uses a specific softirq for timers, defined in include/linux/timer.h. Developers register functions to be called after a specific duration. When a hardware interrupt handler exits or a system call returns to userspace, the kernel runs pending software interrupts, including those for timers. Sources: Documentation/kernel-hacking/hacking.rst:80-92
This sequence illustrates how a hardware timer tick transitions into a software-based callback execution. Sources: Documentation/kernel-hacking/hacking.rst:64-92
Delay and Sleep Mechanisms
The kernel provides several functions for pausing execution. The choice of function depends on the required precision and the current execution context (e.g., whether the code can sleep). Sources: Documentation/kernel-hacking/hacking.rst:293-298
Precision Pauses
For small, non-sleeping pauses, the kernel provides atomic delay routines. Use udelay() and ndelay() for microsecond and nanosecond precision respectively. These functions should not be used for large values as they risk overflow. Sources: Documentation/kernel-hacking/hacking.rst:293-298
| Function | Precision | Context | Usage Note |
|---|---|---|---|
ndelay(n) | Nanoseconds | Atomic/Interrupt | Use for very short hardware delays. |
udelay(n) | Microseconds | Atomic/Interrupt | Standard for small non-sleeping pauses. |
mdelay(n) | Milliseconds | Atomic/Interrupt | Helpful for larger atomic delays; avoid if possible. |
msleep(n) | Milliseconds | User Context | Only allowed in contexts that can sleep. |
Sources: Documentation/kernel-hacking/hacking.rst:293-298
Development Guidelines
Timer-related code must follow strict concurrency and locking rules to prevent deadlocks and race conditions. Sources: Documentation/kernel-hacking/hacking.rst:133-145
- Non-sleeping Contexts: You must not call routines that sleep (like
msleep) while holding spinlocks or within interrupt context. Sources: Documentation/kernel-hacking/hacking.rst:133-138 - Atomic Sleep Checks: Developers should compile kernels with
CONFIG_DEBUG_ATOMIC_SLEEPenabled to detect illegal sleeping in atomic timer contexts. Sources: Documentation/kernel-hacking/hacking.rst:142-145 - Locking Documentation: Maintainers recommend using
lockdep_assert_held()to document and verify locking requirements in timer-related functions. Sources: Documentation/process/maintainer-tip.rst:268-284
Testing with Debug Options
Code touching the timer subsystem should be built and tested with heavyweight debugging options. For x86 architectures, these are found in kernel/configs/x86_debug.config. Sources: Documentation/process/maintainer-tip.rst:370-377
Summary
The Timekeeping and Timers system provides the fundamental infrastructure for time tracking and asynchronous task scheduling in the Linux kernel. It relies on a hierarchy of hardware drivers, core timekeeping logic, and softirq-driven callback mechanisms to ensure accurate and efficient operation across various execution contexts. Sources: Documentation/process/maintainer-tip.rst:54, Documentation/kernel-hacking/hacking.rst:87