Documentation/timers/timekeeping.rst

2 Clock sources, Clock events, sched_clock() and delay timers
10 If you grep through the kernel source you will find a number of architecture-
11 specific implementations of clock sources, clockevents and several likewise
12 architecture-specific overrides of the sched_clock() function and some
15 To provide timekeeping for your platform, the clock source provides
16 the basic timeline, whereas clock events shoot interrupts on certain points
17 on this timeline, providing facilities such as high-resolution timers.
22 Clock sources
23 -------------
25 The purpose of the clock source is to provide a timeline for the system that
27 a Linux system will eventually read the clock source to determine exactly
30 Typically the clock source is a monotonic, atomic counter which will provide
31 n bits which count from 0 to (2^n)-1 and then wraps around to 0 and start over.
32 It will ideally NEVER stop ticking as long as the system is running. It
33 may stop during system suspend.
35 The clock source shall have as high resolution as possible, and the frequency
36 shall be as stable and correct as possible as compared to a real-world wall
37 clock. It should not move unpredictably back and forth in time or miss a few
46 When the wall-clock accuracy of the clock source isn't satisfactory, there
48 the user-visible time to RTC clocks in the system or against networked time
50 the clock source, which provides the fundamental timeline for the system.
51 These measures does not affect the clock source per se, they only adapt the
52 system to the shortcomings of it.
54 The clock source struct shall provide means to translate the provided counter
63 You will find a number of helper functions in the clock source code intended
68 factors using the frequency of the clock source as the only input.
70 For real simple clock sources accessed from a single I/O memory location
73 register counts up or down, and the timer clock rate, and then conjure all
76 Since a 32-bit counter at say 100 MHz will wrap around to zero after some 43
77 seconds, the code handling the clock source will have to compensate for this.
78 That is the reason why the clock source struct also contains a 'mask'
81 compensation code on both sides of the wrap point so that the system timeline
85 Clock events
86 ------------
88 Clock events are the conceptual reverse of clock sources: they take a
92 Clock events are orthogonal to clock sources. The same hardware
93 and register range may be used for the clock event, but it is essentially
94 a different thing. The hardware driving clock events has to be able to
95 fire interrupts, so as to trigger events on the system timeline. On an SMP
96 system, it is ideal (and customary) to have one such event driving timer per
100 You will notice that the clock event device code is based on the same basic
103 assigning these values. The clock event driver does not need a 'mask'
104 attribute however: the system will not try to plan events beyond the time
105 horizon of the clock event.
109 -------------
111 In addition to the clock sources and clock events there is a special weak
113 number of nanoseconds since the system was started. An architecture may or
115 implementation is not provided, the system jiffy counter will be used as
118 As the name suggests, sched_clock() is used for scheduling the system,
123 Compared to clock sources, sched_clock() has to be very fast: it is called
124 much more often, especially by the scheduler. If you have to do trade-offs
125 between accuracy compared to the clock source, you may sacrifice accuracy
127 characteristics as the clock source, i.e. it should be monotonic.
135 jiffy frequency for the architecture. This will affect scheduling accuracy
136 and will likely show up in system benchmarks.
138 The clock driving sched_clock() may stop or reset to zero during system
140 events on the system. However it may result in interesting timestamps in
143 The sched_clock() function should be callable in any context, IRQ- and
144 NMI-safe and return a sane value in any context.
147 counter to derive a 64-bit nanosecond value, so for example on the ARM
149 sched_clock() nanosecond base from a 16- or 32-bit counter. Sometimes the
150 same counter that is also used as clock source is used for this purpose.
155 drift between the CPUs on the system. The kernel can work around this by
157 that makes sched_clock() different from the ordinary clock source.
161 --------------------------------------
163 On systems with variable CPU frequency, the various kernel delay() functions
168 Let's hope that your system is running on maximum frequency when this value
169 is calibrated: as an effect when the frequency is geared down to half the
170 full frequency, any delay() will be twice as long. Usually this does not
174 Enter timer-based delays. Using these, a timer read may be used instead of
175 a hard-coded loop for providing the desired delay.