1.\" Copyright (c) 2011 Alexander Motin <mav@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd December 20, 2011 28.Dt TIMECOUNTERS 4 29.Os 30.Sh NAME 31.Nm timecounters 32.Nd kernel time counters subsystem 33.Sh SYNOPSIS 34Kernel uses several types of time-related devices, such as: real time clocks, 35time counters and event timers. 36Real time clocks responsible for tracking real world time, mostly when system 37is down. 38Time counters are responsible for tracking purposes, when system is running. 39Event timers are responsible for generating interrupts at specified time or 40periodically, to run different time-based events. 41This page is about the second. 42.Sh DESCRIPTION 43Time counters are the lowest level of time tracking in kernel. 44They provide monotonically increasing timestamps with known width and 45update frequency. 46They can overflow, drift, etc and so in raw form used only in very limited 47performance-critical places like process scheduler. 48.Pp 49More usable time is created by scaling the values read from the selected 50time counter and combining it with some offset, regularly updated by 51.Fn tc_windup 52on 53.Fn hardclock 54invocation. 55.Pp 56Different platforms provide different kinds of timer hardware. 57The goal of the time counters subsystem is to provide unified way to access 58that hardware. 59.Pp 60Each driver implementing time counters, registers them at the subsystem. 61It is possible to see the list of present time counters, like this, via 62.Va kern.timecounter 63sysctl: 64.Bd -literal 65kern.timecounter.choice: TSC-low(-100) HPET(950) i8254(0) ACPI-fast(900) dummy(-1000000) 66kern.timecounter.tc.ACPI-fast.mask: 16777215 67kern.timecounter.tc.ACPI-fast.counter: 13467909 68kern.timecounter.tc.ACPI-fast.frequency: 3579545 69kern.timecounter.tc.ACPI-fast.quality: 900 70kern.timecounter.tc.i8254.mask: 65535 71kern.timecounter.tc.i8254.counter: 62692 72kern.timecounter.tc.i8254.frequency: 1193182 73kern.timecounter.tc.i8254.quality: 0 74kern.timecounter.tc.HPET.mask: 4294967295 75kern.timecounter.tc.HPET.counter: 3013495652 76kern.timecounter.tc.HPET.frequency: 14318180 77kern.timecounter.tc.HPET.quality: 950 78kern.timecounter.tc.TSC-low.mask: 4294967295 79kern.timecounter.tc.TSC-low.counter: 4067509463 80kern.timecounter.tc.TSC-low.frequency: 11458556 81kern.timecounter.tc.TSC-low.quality: -100 82.Ed 83.Pp 84where: 85.Bl -inset 86.It Va kern.timecounter.tc. Ns Ar X Ns Va .mask 87is a bitmask, defining valid counter bits, 88.It Va kern.timecounter.tc. Ns Ar X Ns Va .counter 89is a present counter value, 90.It Va kern.timecounter.tc. Ns Ar X Ns Va .frequency 91is a counter update frequency, 92.It Va kern.timecounter.tc. Ns Ar X Ns Va .quality 93is an integral value, defining how good is this time counter, 94comparing to others. 95Negative value means that this time counter is broken and should not be used. 96.El 97.Pp 98Time management code of the kernel chooses one time counter from that list. 99Current choice can be read and affected via 100.Va kern.timecounter.hardware 101tunable/sysctl. 102.Sh SEE ALSO 103.Xr attimer 4 , 104.Xr eventtimers 4 , 105.Xr ffclock 4 , 106.Xr hpet 4 107