Add tc_init(9) page, a description of the timecounters. With some

help from jmc@.

2 files changed, 120 insertions, 2 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 68a37e10acc..3381bb989c0 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.87 2004/12/17 17:32:02 jaredy Exp $
+#	$OpenBSD: Makefile,v 1.88 2004/12/18 14:26:03 grange Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -18,7 +18,7 @@ MAN=	altq.9 audio.9 autoconf.9 boot.9 buffercache.9 bus_dma.9 bus_space.9 \
 	radio.9 random.9 rasops.9 ratecheck.9 resettodr.9 \
 	shutdownhook_establish.9 sleep.9 spl.9 startuphook_establish.9 \
 	style.9 syscall.9 systrace.9 \
-	time.9 timeout.9 tvtohz.9 uiomove.9 uvm.9 vfs.9 \
+	tc_init.9 time.9 timeout.9 tvtohz.9 uiomove.9 uvm.9 vfs.9 \
 	vaccess.9 vclean.9 vcount.9 vdevgone.9 vfinddev.9 vflush.9 \
 	vflushbuf.9 vget.9 vgone.9 vhold.9 vinvalbuf.9 vput.9 vref.9 \
 	vrele.9 vnode.9 VOP_LOOKUP.9 vn_lock.9 vrecycle.9 vwaitforio.9 \
diff --git a/share/man/man9/tc_init.9 b/share/man/man9/tc_init.9
new file mode 100644
index 00000000000..ab9de4ecdc8
--- /dev/null
+++ b/share/man/man9/tc_init.9
@@ -0,0 +1,118 @@
+.\"	$OpenBSD: tc_init.9,v 1.1 2004/12/18 14:26:03 grange Exp $
+.\"
+.\" Copyright (c) 2004 Alexander Yurchenko <grange@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
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd December 15, 2004
+.Dt TC_INIT 9
+.Os
+.Sh NAME
+.Nm tc_init
+.Nd machine-independent binary timescale
+.Sh SYNOPSIS
+.Fd #include <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.
+.Pp
+A timecounter is a binary counter which has two properties:
+.Bl -bullet -offset indent
+.It
+it runs at a fixed, known frequency
+.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)
+.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
+.Va timecounter
+structure:
+.Bd -literal -offset indent
+struct timecounter {
+	timecounter_get_t	*tc_get_timecount;
+	timecounter_pps_t	*tc_poll_pps;
+	u_int 			tc_counter_mask;
+	u_int64_t		tc_frequency;
+	char			*tc_name;
+	int			tc_quality;
+	void			*tc_priv;
+	struct timecounter	*tc_next;
+}
+.Ed
+.Pp
+The fields of the
+.Va timecounter
+structure are described below.
+.Bl -tag -width indent
+.It Fn "u_int (*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.
+.It Fn "void (*tc_poll_pps)" "struct timecounter *"
+This function is optional and can be set to NULL.
+It will be called whenever the timecounter is rewound, and is intended
+to check for PPS events.
+Normal hardware does not need it but timecounters which latch PPS in
+hardware do.
+.It Va tc_counter_mask
+This mask should mask off any unimplemented bits.
+.It Va tc_frequency
+Frequency of the counter in Hz.
+.It Va tc_name
+Name of the timecounter.
+Can be any null-terminated string.
+.It Va tc_quality
+Used to determine if this timecounter is better than another timecounter \-
+higher means better.
+Negative means ``only use at explicit request''.
+.It Va tc_priv
+Pointer to the timecounter's private parts.
+.It Va tc_next
+For internal use.
+.El
+.Pp
+To register a new timecounter,
+the hardware device driver should fill a
+.Va timecounter
+structure with appropriate values and call the
+.Fn tc_init
+function, giving a pointer to the structure as a
+.Fa tc
+parameter.
+.Sh CODE REFERENCES
+The timecounter framework is implemented in the file
+.Pa sys/kern/kern_tc .
+.Sh SEE ALSO
+.Xr amdpm 4 ,
+.Xr elansc 4 ,
+.Xr gscpm 4 ,
+.Xr ichpcib 4 ,
+.Xr piixpm 4 ,
+.Xr viaenv 4 ,
+.Xr hz 9 ,
+.Xr microtime 9
+.Rs
+.%A Poul-Henning Kamp
+.%T Timecounter: Efficient and precise timekeeping in SMP kernels
+.%J The FreeBSD Project
+.%I http://phk.freebsd.dk/pubs/timecounter.pdf
+.Re
+.Sh HISTORY
+The timecounter interface first appeared in
+.Ox 3.6 .