Add timecounters(4) man page alike to eventtimers(4).

5 files changed, 111 insertions, 2 deletions

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 4c93cfc..d13d348 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -445,6 +445,7 @@ MAN=	aac.4 \
 	termios.4 \
 	textdump.4 \
 	ti.4 \
+	timecounters.4 \
 	tl.4 \
 	tnt4882.4 \
 	${_tpm.4} \
diff --git a/share/man/man4/attimer.4 b/share/man/man4/attimer.4
index 78d40d4..751b9ea 100644
--- a/share/man/man4/attimer.4
+++ b/share/man/man4/attimer.4
@@ -73,4 +73,5 @@ Event timer provided by the driver is irrelevant to CPU power states.
 .Xr apic 4 ,
 .Xr atrtc 4 ,
 .Xr eventtimers 4 ,
-.Xr hpet 4
+.Xr hpet 4 ,
+.Xr timecounters 4
diff --git a/share/man/man4/eventtimers.4 b/share/man/man4/eventtimers.4
index e29d32f8..c935c3e 100644
--- a/share/man/man4/eventtimers.4
+++ b/share/man/man4/eventtimers.4
@@ -149,4 +149,5 @@ always generating.
 .Xr atrtc 4 ,
 .Xr attimer 4 ,
 .Xr hpet 4 ,
+.Xr timecounters 4 ,
 .Xr eventtimers 9
diff --git a/share/man/man4/hpet.4 b/share/man/man4/hpet.4
index 092996c..cd1b766 100644
--- a/share/man/man4/hpet.4
+++ b/share/man/man4/hpet.4
@@ -97,7 +97,8 @@ of these comparators has own unsharable IRQ.
 .Xr apic 4 ,
 .Xr atrtc 4 ,
 .Xr attimer 4 ,
-.Xr eventtimers 4
+.Xr eventtimers 4 ,
+.Xr timecounters 4
 .Sh HISTORY
 The
 .Nm
diff --git a/share/man/man4/timecounters.4 b/share/man/man4/timecounters.4
new file mode 100644
index 0000000..8cbcdc1
--- /dev/null
+++ b/share/man/man4/timecounters.4
@@ -0,0 +1,105 @@
+.\" Copyright (c) 2011 Alexander Motin <mav@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd December 20, 2011
+.Dt TIMECOUNTERS 4
+.Os
+.Sh NAME
+.Nm timecounters
+.Nd kernel time counters subsystem
+.Sh SYNOPSIS
+Kernel uses several types of time-related devices, such as: real time clocks,
+time counters and event timers.
+Real time clocks responsible for tracking real world time, mostly when system
+is down.
+Time counters are responsible for tracking purposes, when system is running.
+Event timers are responsible for generating interrupts at specified time or
+periodically, to run different time-based events.
+This page is about the second.
+.Sh DESCRIPTION
+Time counters are the lowest level of time tracking in kernel.
+They provide monotonically increasing timestamps with known width and
+update frequency.
+They can overflow, drift, etc and so in raw form used only in very limited
+performance-critical places like process scheduler.
+.Pp
+More usable time is created by scaling the values read from the selected
+time counter and combining it with some offset, regularly updated by
+.Fn tc_windup
+on
+.Fn hardclock
+invocation.
+.Pp
+Different platforms provide different kinds of timer hardware.
+The goal of the time counters subsystem is to provide unified way to access
+that hardware.
+.Pp
+Each driver implementing time counters, registers them at the subsystem.
+It is possible to see the list of present time counters, like this, via
+.Va kern.timecounter
+sysctl:
+.Bd -literal
+kern.timecounter.choice: TSC-low(-100) HPET(950) i8254(0) ACPI-fast(900) dummy(-1000000)
+kern.timecounter.tc.ACPI-fast.mask: 16777215
+kern.timecounter.tc.ACPI-fast.counter: 13467909
+kern.timecounter.tc.ACPI-fast.frequency: 3579545
+kern.timecounter.tc.ACPI-fast.quality: 900
+kern.timecounter.tc.i8254.mask: 65535
+kern.timecounter.tc.i8254.counter: 62692
+kern.timecounter.tc.i8254.frequency: 1193182
+kern.timecounter.tc.i8254.quality: 0
+kern.timecounter.tc.HPET.mask: 4294967295
+kern.timecounter.tc.HPET.counter: 3013495652
+kern.timecounter.tc.HPET.frequency: 14318180
+kern.timecounter.tc.HPET.quality: 950
+kern.timecounter.tc.TSC-low.mask: 4294967295
+kern.timecounter.tc.TSC-low.counter: 4067509463
+kern.timecounter.tc.TSC-low.frequency: 11458556
+kern.timecounter.tc.TSC-low.quality: -100
+.Ed
+.Pp
+where:
+.Bl -inset
+.It Va kern.timecounter.tc. Ns Ar X Ns Va .mask
+is a bitmask, defining valid counter bits,
+.It Va kern.timecounter.tc. Ns Ar X Ns Va .counter
+is a present counter value,
+.It Va kern.eventtimer.tc. Ns Ar X Ns Va .frequency
+is a counter update frequency,
+.It Va kern.eventtimer.tc. Ns Ar X Ns Va .quality
+is an integral value, defining how good is this time counter,
+comparing to others.
+Negative value means that this time counter is broken and should not be used.
+.El
+.Pp
+Time management code of the kernel chooses one time counter from that list.
+Current choice can be read and affected via
+.Va kern.timecounter.hardware
+tunable/sysctl.
+.Sh SEE ALSO
+.Xr attimer 4 ,
+.Xr eventtimers 4 ,
+.Xr hpet 4