timekeeping documentation?

[Steve Summit]

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
above.