The core timekeeping code is in kernel/time/timekeeping.c, which tracks:
	- wallclock time: current time (seconds since midnight 1970 UTC, or
	  whatever).
	- bootbased time: time since we booted
	- monotonic time: time since we booted, not including time spent
	  in suspend.

(I'm ignoring CLOCK_MONOTONIC_RAW and some other things I don't claim to
understand.)

Both the bootbased and monotonic times start at 0 when the kernel boots.
Think of monotoinc time as kept by a lock that stops whenever the
machine suspends, while the bootbased time keeps ticking.

Neither bootbased nor monotonic time ever go backwards.  The wallclock
time, however, may be changed at any time.  (For example, the user may
realize it's wrong and set it to something else).

Types used to store time include:
	- timespec: tv_sec, tv_nsec (both longs)
	- timeval: tv_sec, tv_usec
	- ktime_t: confusing timespec optimization allowing its value to
	  be referred to either as a single s64 (tv64) or two s32's
	  (tv.sec, tv.nsec).

The three main clocks are kept using three timespecs:

	- xtime: wallclock time
	- wall_to_monotonic: difference (normally negative) between
	  wallclock and monotonic time.
	- total_sleep_time: self-explanatory

So:

	monotonic time == xtime + wall_to_monotonic
	bootbased time == xtime + wall_to_monotonic + total_sleep_time
	time of boot == - wall_to_monotonic - total_sleep_time

There's a getboottime() function which will do the latter calculation
for you.  (Note that it doesn't always return the same value: if the
time is set (for example, ntp adjusts it), then our idea of what time it
was when we booted may change.)

The value of xtime is updated once a clock tick by tick_periodic() and
do_timer().  The frequency of clock ticks is configurable at build time
(between 100 and 1000 hz), and available from kernel code as HZ.

If more accurate time is needed, the kernel will use the best time
source available to it.  Time sources are registered with
clocksource-register(), generally found in drivers/clocksource/ or an
arch-specific file (or in kernel/time/jiffies.c for a trivial
jiffies-based source adequate at least for booting).  At any given
moment timekeeper.clock points to the current preferred time source, and
timekeeping_get_ns() uses it to return a correction factor, in
nanoseconds.  Functions such as gettimeofday() which want high accuracy
can therefore read xtime.c and add the result of timekeeping_get_ns().

Kernel functions which use this infrastructure:

	get_seconds() = xtime.tv_sec (wallclock seconds)
	current_kernel_time() = xtime (HZ-accuracy wallclock time)
	get_monotonic_course() = HZ-accuracy monotonic time

	Functions that use the best available time source:
		wallclock time:
			ktime_t(): ktime_get_real
			timespec(): getnstimeofday
			timeval(): do_gettimeofday
		monotonic:
			ktime_t(): ktime_get
			timespec(): ktime_get_ts

	current_fs_time(): current_kernel_time() rounded off to the
	granularity of a given superblock, and used for file mtime,
	ctime, and atime.

Finally, jiffies is incremented once per clock tick (by do_timer()).  It
may wrap around at any time (jiffies == 0 doesn't designate boot time,
or any time in particular), and jiffies should be compared using
time_before() and time_after().

Acronyms:
	TSC: time stamp counter: http://en.wikipedia.org/wiki/Time_Stamp_Counter

	HPET: high precision event timer: http://en.wikipedia.org/wiki/HPET

todo:
	look at various times used in nfsd4 code:
		- cl_time: shouldn't this be monotonic rather than wall
		  time?

Various userspace interfaces:
	- adjtime
	- adjtimex
	- clock_settime