share/man/man4/timecounters.4

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