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