PEP 418: split resolution/accuracy in the able; add a section on Linux timers

pep-0418.txt

@@ -186,18 +186,29 @@ Summary
 Table summarizing all monotonic clocks:
 
 
-=========================  ===============  ================  ====================
+========================= =============== =============== ================ ====================
-Name                       Resolution       Adjusted by NTP?  Action on suspend
+Name                      Resolution      Accuracy        Adjusted by NTP? Action on suspend
-=========================  ===============  ================  ====================
+========================= =============== =============== ================ ====================
-CLOCK_MONOTONIC_RAW        1 ns             No                Stopped
+CLOCK_MONOTONIC_RAW       1 ns            ?               No               Stopped
-gethrtime                  1 ns             No                Not stopped
+gethrtime                 1 ns            ?               No               Not stopped
-mach_absolute_time()       1 ns             No                ?
+mach_absolute_time()      1 ns            ?               No               ?
-CLOCK_HIGHRES              1 ns             No                ?
+CLOCK_HIGHRES             1 ns            ?               No               ?
-CLOCK_MONOTONIC            1 ns             Yes on Linux      Stopped on Linux
+CLOCK_MONOTONIC           1 ns            ?               Yes on Linux     Stopped on Linux
-QueryPerformanceCounter()  0.3 ns - 5 ns    No                Accuracy issue
+QueryPerformanceCounter() \-              0.3 ns - 5 ns   No               Accuracy issue
-GetTickCount[64]()         1 ms - 15 ms     No                Include suspend time
+GetTickCount[64]()        1 ms            1 ms - 15 ms    No               Include suspend time
-timeGetTime()              1 ms - 15 ms     No                ?
+timeGetTime()             1 ms            1 ms - 15 ms    No               ?
-=========================  ===============  ================  ====================
+========================= =============== =============== ================ ====================
+
+The resolution is the smallest difference between two timestamps supported by
+the format used by the clock. For example, clock_gettime() uses a timespec
+structure which has two integer fileds, tv_sec and tv_nsec, so the resolution
+is 1 nanosecond.
+
+The accuracy is the effective smallest difference of two timestamps of the
+clock. It does not reflect the stability the clock rate.  For example,
+QueryPerformanceCounter() has a good accuracy but is known to not have a steady
+rate.
+
 
 mach_absolute_time
 ^^^^^^^^^^^^^^^^^^
@@ -351,7 +362,7 @@ The default precision of the timeGetTime function can be five milliseconds or
 more, depending on the machine.
 
 timeBeginPeriod() can be used to increase the precision of timeGetTime() up to
-1 millisecond.
+1 millisecond, but it negatively affects power consumption.
 
 .. note::
    timeGetTime() and timeBeginPeriod() are part the Windows multimedia library
@@ -477,6 +488,50 @@ QueryUnbiasedInterruptTime() is not monotonic.
 
 QueryUnbiasedInterruptTime() was introduced in Windows 7.
 
+Linux timers
+------------
+
+There were 4 implementations of the time in the Linux kernel: UTIME (1996),
+timer wheel (1997), HRT (2001) and hrtimers (2007). The later is the result of
+the "high-res-timers" project started by George Anzinger in 2001, contributed
+by Thomas Gleixner and Douglas Niehaus. hrtimers implementation was merged into
+Linux 2.6.21 released in 2007.
+
+hrtimers supports various clock sources. It sets a priority to each source to
+decide which one will be used.
+
+ * TSC (Time Stamp Counter): Internal processor clock incremented at each
+   processor cycle. Its frequency is the processor frequency and so usually
+   higher than 1 GHz. Its priority is 300 by default, but falls to 0 if the
+   processor frequency changes and the counter becomes unstable.
+ * HPET: An HPET chip consists of a 64-bit up-counter (main counter) counting
+   at least at 10 MHz and a set of up to 256 comparators (at least 3). Each
+   HPET can have up to 32 timers.
+ * PIT (programmable interrupt timer): Intel 8253/8254 chipsets with a
+   configurable frequecency in range 18.2 Hz - 1.2 MHz. Linux uses the
+   frequency: 1,193,181.8 Hz. It is a 16-bit counter.
+ * PMTMR (power management timer): ACPI 24-bit timer with a frequency of 3.5
+   MHz (3,579,545 Hz). Its priority is 200 by default, but changes to 110 if
+   the chipset is broken and need a software workaround. HPET can cause around
+   3 seconds of drift per day.
+ * Cyclone: The Cyclone timer uses a 32-bit counter on IBM Extended
+   X-Architecture (EXA) chipsets which include computers that use the IBM
+   "Summit" series chipsets (ex: x440). This is available in IA32 and IA64
+   architectures.
+
+High-resolution timers are not supported on all hardware architectures. They
+are at least provided on x86/x86_64, ARM and PowerPC.
+
+The list of available clock sources can be read in
+/sys/devices/system/clocksource/clocksource0/available_clocksource. It is
+possible to force a clocksource at runtime by writing its name into
+/sys/devices/system/clocksource/clocksource0/current_clocksource.
+/proc/timer_list contains the list of all hardware timers.
+
+Read also the `time(7) manual page
+<http://www.kernel.org/doc/man-pages/online/pages/man7/time.7.html>`_:
+"overview of time and timers".
+
 
 Alternatives: API design
 ========================
@@ -584,6 +639,8 @@ Librairies exposing monotonic clocks:
 
 Time:
 
+ * `hrtimers - subsystem for high-resolution kernel timers
+   <http://www.kernel.org/doc/Documentation/timers/hrtimers.txt>`_
  * `C++ Timeout Specification
    <http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3128.html>`_
  * `Windows: Game Timing and Multicore Processors