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.Dd August 12, 2015 26.Dt TIMECOUNTERS 4 27.Os 28.Sh NAME 29.Nm timecounters 30.Nd kernel time counters subsystem 31.Sh SYNOPSIS 32The kernel uses several types of time-related devices, such as: real time clocks, 33time counters and event timers. 34Real time clocks are responsible for tracking real world time, mostly when the system 35is down. 36Time counters are responsible for tracking purposes, when the system is running. 37Event timers are responsible for generating interrupts at a specified time or 38periodically, to run different time-based events. 39This page is about the second. 40.Sh DESCRIPTION 41Time counters are the lowest level of time tracking in the kernel. 42They provide monotonically increasing timestamps with known width and 43update frequency. 44They can overflow, drift, etc and so in raw form can be used only in very limited 45performance-critical places like the process scheduler. 46.Pp 47More usable time is created by scaling the values read from the selected 48time counter and combining it with some offset, regularly updated by 49.Fn tc_windup 50on 51.Fn hardclock 52invocation. 53.Pp 54Different platforms provide different kinds of timer hardware. 55The goal of the time counters subsystem is to provide a unified way to access 56that hardware. 57.Pp 58Each driver implementing time counters registers them with the subsystem. 59It is possible to see the list of present time counters, via the 60.Va kern.timecounter 61.Xr sysctl 8 62variable: 63.Bd -literal 64kern.timecounter.choice: TSC-low(-100) HPET(950) i8254(0) ACPI-fast(900) dummy(-1000000) 65kern.timecounter.tc.ACPI-fast.mask: 16777215 66kern.timecounter.tc.ACPI-fast.counter: 13467909 67kern.timecounter.tc.ACPI-fast.frequency: 3579545 68kern.timecounter.tc.ACPI-fast.quality: 900 69kern.timecounter.tc.i8254.mask: 65535 70kern.timecounter.tc.i8254.counter: 62692 71kern.timecounter.tc.i8254.frequency: 1193182 72kern.timecounter.tc.i8254.quality: 0 73kern.timecounter.tc.HPET.mask: 4294967295 74kern.timecounter.tc.HPET.counter: 3013495652 75kern.timecounter.tc.HPET.frequency: 14318180 76kern.timecounter.tc.HPET.quality: 950 77kern.timecounter.tc.TSC-low.mask: 4294967295 78kern.timecounter.tc.TSC-low.counter: 4067509463 79kern.timecounter.tc.TSC-low.frequency: 11458556 80kern.timecounter.tc.TSC-low.quality: -100 81.Ed 82.Pp 83The output nodes are defined as follows: 84.Bl -inset 85.It Va kern.timecounter.tc. Ns Ar X Ns Va .mask 86is a bitmask, defining valid counter bits, 87.It Va kern.timecounter.tc. Ns Ar X Ns Va .counter 88is a present counter value, 89.It Va kern.timecounter.tc. Ns Ar X Ns Va .frequency 90is a counter update frequency, 91.It Va kern.timecounter.tc. Ns Ar X Ns Va .quality 92is an integral value, defining the quality of this time counter 93compared to others. 94A negative value means this time counter is broken and should not be used. 95.El 96.Pp 97The time management code of the kernel automatically switches to a 98higher-quality time counter when it registers, unless the 99.Va kern.timecounter.hardware 100sysctl has been used to choose a specific device. 101.Pp 102There is no way to unregister a time counter once it has registered 103with the kernel. 104If a dynamically loaded module contains a time counter you will not 105be able to unload that module, even if the time counter it contains 106is not the one currently in use. 107.Sh SEE ALSO 108.Xr attimer 4 , 109.Xr eventtimers 4 , 110.Xr ffclock 4 , 111.Xr hpet 4 112