diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index 4c93cfc52d2b..d13d348f1d31 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 78d40d43ce60..751b9ea1a203 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 e29d32f87b44..c935c3e72cdc 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 092996c0945a..cd1b7663cc0a 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 000000000000..8cbcdc16f5dd --- /dev/null +++ b/share/man/man4/timecounters.4 @@ -0,0 +1,105 @@ +.\" Copyright (c) 2011 Alexander Motin +.\" 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