timekeeping documentation?

From: Steve Summit
Date: Wed Jan 25 2017 - 07:35:43 EST

Does anyone know of any good documentation about what goes
on in kernel/time/timekeeping.c? I know about the file
Documentation/timers/timekeeping.txt, but that's mostly talking
about underlying clock sources.

The documentation I'm looking for would answer questions such as:

* How is is the kernel's primary wallclock time (xtime) defined?
* How are other clocks (boot, monotonic, etc.) derived from xtime?
* What is ktime_t and how does it differ from time_t?
* What are the invariants involving the timekeeper offsets
wall_to_monotonic, offs_real, offs_boot, and offs_tai?
* What is the distinction between the regular and the "coarse" clocks?
(And what about the "raw" and "alarm" clocks?)
* What are the timekeeper "base" variables tkr_mono and tkr_raw?
How are they used, and what are the invariants surrounding them?
* Which of the functions in timekeeping.c are called at interrupt time?
* What are the locking requirements surrounding the timekeeper
data structures?
* What are the main, suggested, primary calls for fetching the
current time? (What about setting it?)
* What is the separation of functionality between time.c,
timekeeping.c, posix-timers.c, and ntp.c?
* What abstractions are intended to be imposed by the inline
functions defined in timekeeping.h (current_kernel_time(), etc.)?
* How much of this is historical and/or accidental, and what (if any)
cleanups and/or improvements to the timekeeping architecture
might be in the works?

If there's no such documentation, I may try to write something,
but I'll likely need some help, as I haven't personally worked
out good answers yet for all of the example questions I've posed