Index: share/man/man9/hz.9
===================================================================
--- share/man/man9/hz.9
+++ share/man/man9/hz.9
@@ -36,7 +36,7 @@
 .Pp
 .Vt extern int hz;
 .Vt extern int tick;
-.Vt extern int stathz;	/* deprecated */
+.Vt extern int stathz;
 .Vt extern int profhz;	/* deprecated */
 .Sh DESCRIPTION
 .Fx
@@ -47,34 +47,29 @@
 .Pp
 The main clock is used to update the system's notion of time via
 .Xr timecounters 9
-and to pace periodic system callbacks via
-.Xr callout 9 ,
-.Xr epoch 9 ,
-and other methods documented in
+and to pace periodic system processing as documented in
 .Xr hardclock 9 .
-That routine will be called approximately
+That routine will be called periodically, no more than
 .Va hz
 times per second.
 .Pp
-The second clock, running at either
+A second clock running at
 .Va stathz
-or
-.Va profhz
-was used to gather timing statistics, but has been replaced with the more
-functional
-.Xr hwpmc 4 .
-These values are returned for
-.Qq compatibility
-with
-.Bx 4.4 ,
-.St -p1003.1-2001
-and the
-.Xr setitimer 2
-.Va ITIMER_PROF
-flag, which were deprecated in
-.St -p1003.1-2008
-in favor of
-.Xr timer_settime 2 .
+gathers statistics on the system and its processes.
+It computes values for
+.Xr getrusage 2
+and statistics displayed by
+.Xr ps 1
+and
+.Xr top 1 .
+.Pp
+Finally, a third clock runs at
+.Vt profhz
+to sample user program counter values for profiling purposes.
+This profiling clock has been replaced by the more functional
+.Xr hwpmc 4
+and may be removed in a future version of
+.Fx .
 .Pp
 .Va tick
 is the length of time in microseconds of one system tick.
@@ -88,6 +83,15 @@
 from
 .Xr sysctl 8 .
 .Pp
+The current global and per-CPU CPU time usage is returned to the user in units
+of 1 /
+.Va stathz
+ticks in the
+.Sy kern.cp_time
+and
+.Sy kern.cp_times
+sysctl MIBs.
+.Pp
 The
 .Va hz
 rate may be overridden by defining
@@ -112,3 +116,31 @@
 .Xr microtime 9 ,
 .Xr time_second 9 ,
 .Xr timecounters 9
+.Sh IMPLEMENTATION NOTES
+Historically, both the
+.Va stathz
+and
+.Va profhz
+clocks have run off the same physical timer running at the slower rate when no
+process is using the profile features, or at the higher rate when at least one
+process is using it.
+Although the interface is deprecated by in
+.St -p1003.1-2008
+in favor of
+.Xr timer_settime 2 ,
+several programs still use
+.Xr setitimer 2
+and
+.Va ITIMER_PROF
+for a higher-resolution periodic interrupt than has been traditionally
+available.
+.Pp
+Historically,
+.Xr hardclock 9
+has also been run off a separate interrupt, except on constrained platforms that
+lack enough periodic interrupt sources.
+.Fx
+uses
+.Xr eventtimers 9
+to abstract these details away, though some old code may still harbor
+assumptions that are an imperfect fit to this abstraction.