tc_init.9: miscellaneous cleanup and rewrites

- In DESCRIPTION, try to more fully describe what kern_tc.c does.
  Clean up the wording.

- Mention *all* the requirements for timekeeping hardware.  Describe
  the rollover margin in plainer language.

- Revise field descriptions for struct timecounter.  Don't mention
  fields the driver doesn't need to initialize.  Document the tc_user
  field.

- Add a CONTEXT section.

- In SEE ALSO, switch to an https URI on the main freebsd.org website.

- In HISTORY, note that the timecounting code first reached end users
  in FreeBSD 3.0.  This commit is probably the first one:

"Replace TOD clock code with more systematic approach."
https://cgit.freebsd.org/src/commit/sys/sys/timetc.h?id=7ec73f64179417aeda085c1c338385559fb49c23

- Add an AUTHORS section.

With input from Poul-Henning Kamp.

Link: https://marc.info/?l=openbsd-tech&m=168004968214914&w=2

ok jmc@

1 files changed, 81 insertions, 49 deletions

diff --git a/share/man/man9/tc_init.9 b/share/man/man9/tc_init.9
index b04275cdc33..53446c84950 100644
--- a/share/man/man9/tc_init.9
+++ b/share/man/man9/tc_init.9
@@ -1,6 +1,7 @@
-.\"	$OpenBSD: tc_init.9,v 1.11 2023/02/04 19:19:36 cheloha Exp $
+.\"    $OpenBSD: tc_init.9,v 1.12 2023/04/02 00:02:26 cheloha Exp $
 .\"
 .\" Copyright (c) 2004 Alexander Yurchenko <grange@openbsd.org>
+.\" Copyright (c) 2023 Scott Cheloha <cheloha@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -14,83 +15,109 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: February 4 2023 $
+.Dd $Mdocdate: April 2 2023 $
 .Dt TC_INIT 9
 .Os
 .Sh NAME
 .Nm tc_init
-.Nd machine-independent binary timescale
+.Nd timecounting subsystem
 .Sh SYNOPSIS
 .In sys/timetc.h
 .Ft void
 .Fn tc_init "struct timecounter *tc"
 .Sh DESCRIPTION
-The timecounter interface is a machine-independent implementation
-of a binary timescale using whatever hardware support is at hand
-for tracking time.
+The
+.Sy timecounting
+subsystem implements a uniform interface to timekeeping hardware,
+measures the passage of time,
+and implements the kernel's software clocks
+.Po see
+.Xr microtime 9
+for details
+.Pc .
 .Pp
-A timecounter is a binary counter which has two properties:
-.Bl -bullet -offset indent
+A hardware clock is suitable for counting time if it meets the following
+requirements:
+.Bl -enum -offset indent
+.It
+It is a binary counter.
+.It
+It advances at a fixed, known frequency.
+.It
+Its count is synchronized between all CPUs on the system.
 .It
-it runs at a fixed, known frequency
+It continues counting when it rolls over.
 .It
-it has sufficient bits to not roll over in less than approximately
-max(2 msec, 2/HZ seconds) (the value 2 here is really 1 + delta, for some
-indeterminate value of delta)
+If
+.Xr hz 9
+is less than or equal to one millisecond,
+the counter does not roll over in less than two milliseconds.
+If
+.Xr hz 9
+exceeds one millisecond,
+the counter does not roll over in less than
+.Pq 2 / Va hz
+seconds.
 .El
 .Pp
-The interface between the hardware which implements a timecounter and the
-machine-independent code which uses this to keep track of time is a
+Hardware clocks are described with a
 .Va timecounter
 structure:
 .Bd -literal -offset indent
 struct timecounter {
-	timecounter_get_t	*tc_get_timecount;
-	u_int 			tc_counter_mask;
-	u_int64_t		tc_frequency;
-	char			*tc_name;
-	int			tc_quality;
-	void			*tc_priv;
-	struct timecounter	*tc_next;
-}
+	u_int (*tc_get_timecount)(struct timecounter *);
+	u_int tc_counter_mask;
+	u_int64_t tc_frequency;
+	char *tc_name;
+	int tc_quality;
+	void *tc_priv;
+	u_int tc_user;
+};
 .Ed
-.Pp
-The fields of the
-.Va timecounter
-structure are described below.
 .Bl -tag -width indent
 .It Ft u_int Fn (*tc_get_timecount) "struct timecounter *"
-This function reads the counter.
-It is not required to mask any unimplemented bits out, as long as they
-are constant.
+Reads the hardware clock and returns its count.
+Any unimplemented bits only need to be masked if they are not constant.
+If the counter is larger than 32 bits,
+this function must return a 32-bit subset.
+The subsystem requires an upward count;
+downward counts must be inverted before they are returned.
 .It Va tc_counter_mask
-This mask should mask off any unimplemented bits.
+The mask of implemented bits.
+Used to discard unimplemented bits from
+.Fn tc_get_timecount .
 .It Va tc_frequency
-Frequency of the counter in Hz.
+The counter's fixed frequency.
 .It Va tc_name
-Name of the timecounter.
-Can be any null-terminated string.
+The counter's unique name.
+A
+.Dv NUL Ns -terminated string.
 .It Va tc_quality
-Used to determine if this timecounter is better than another timecounter \-
-higher means better.
-If this field is negative, the counter is only used at explicit request.
+A relative quality metric used to compare counters.
+Higher values indicate a better counter.
+A negative value indicates that the counter is non-monotonic
+or otherwise deficient.
+The system will only use negative-quality counters if requested.
 .It Va tc_priv
-Pointer to the timecounter's private parts.
-.It Va tc_next
-For internal use.
+May point to anything the driver needs during
+.Fn tc_get_timecount .
+.It Va tc_user
+If non-zero,
+a unique value identifying the userspace implementation of
+.Fn tc_get_timecount .
 .El
 .Pp
-To register a new timecounter,
-the hardware device driver should fill a
+To register a timecounter,
+a device driver initializes the above-described fields of a
 .Va timecounter
-structure with appropriate values and call the
+structure and calls
+.Fn tc_init
+with a pointer to that structure as argument.
+.Sh CONTEXT
 .Fn tc_init
-function, giving a pointer to the structure as a
-.Fa tc
-parameter.
+may only be called during autoconf.
 .Sh CODE REFERENCES
-The timecounter framework is implemented in the file
-.Pa sys/kern/kern_tc.c .
+.Pa sys/kern/kern_tc.c
 .Sh SEE ALSO
 .Xr amdpm 4 ,
 .Xr gscpm 4 ,
@@ -102,8 +129,13 @@ The timecounter framework is implemented in the file
 .%A Poul-Henning Kamp
 .%T Timecounter: Efficient and precise timekeeping in SMP kernels
 .%J The FreeBSD Project
-.%U http://phk.freebsd.dk/pubs/timecounter.pdf
+.%D 2002
+.%U https://papers.freebsd.org/2002/phk-timecounters.files/timecounter.pdf
 .Re
 .Sh HISTORY
-The timecounter interface first appeared in
+The timecounting subsystem first appeared in
+.Fx 3.0 .
+It was ported to
 .Ox 3.6 .
+.Sh AUTHORS
+.An Poul-Henning Kamp