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 December 20, 2011
  28 .Dt TIMECOUNTERS 4
  29 .Os
  30 .Sh NAME
  31 .Nm timecounters
  32 .Nd kernel time counters subsystem
  33 .Sh SYNOPSIS
  34 Kernel uses several types of time-related devices, such as: real time clocks,
  35 time counters and event timers.
  36 Real time clocks responsible for tracking real world time, mostly when system
  37 is down.
  38 Time counters are responsible for tracking purposes, when system is running.
  39 Event timers are responsible for generating interrupts at 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 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 used only in very limited
  47 performance-critical places like 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 unified way to access
  58 that hardware.
  59 .Pp
  60 Each driver implementing time counters, registers them at the subsystem.
  61 It is possible to see the list of present time counters, like this, via
  62 .Va kern.timecounter
  63 sysctl:
  64 .Bd -literal
  65 kern.timecounter.choice: TSC-low(-100) HPET(950) i8254(0) ACPI-fast(900) dummy(-1000000)
  66 kern.timecounter.tc.ACPI-fast.mask: 16777215
  67 kern.timecounter.tc.ACPI-fast.counter: 13467909
  68 kern.timecounter.tc.ACPI-fast.frequency: 3579545
  69 kern.timecounter.tc.ACPI-fast.quality: 900
  70 kern.timecounter.tc.i8254.mask: 65535
  71 kern.timecounter.tc.i8254.counter: 62692
  72 kern.timecounter.tc.i8254.frequency: 1193182
  73 kern.timecounter.tc.i8254.quality: 0
  74 kern.timecounter.tc.HPET.mask: 4294967295
  75 kern.timecounter.tc.HPET.counter: 3013495652
  76 kern.timecounter.tc.HPET.frequency: 14318180
  77 kern.timecounter.tc.HPET.quality: 950
  78 kern.timecounter.tc.TSC-low.mask: 4294967295
  79 kern.timecounter.tc.TSC-low.counter: 4067509463
  80 kern.timecounter.tc.TSC-low.frequency: 11458556
  81 kern.timecounter.tc.TSC-low.quality: -100
  82 .Ed
  83 .Pp
  84 where:
  85 .Bl -inset
  86 .It Va kern.timecounter.tc. Ns Ar X Ns Va .mask
  87 is a bitmask, defining valid counter bits,
  88 .It Va kern.timecounter.tc. Ns Ar X Ns Va .counter
  89 is a present counter value,
  90 .It Va kern.timecounter.tc. Ns Ar X Ns Va .frequency
  91 is a counter update frequency,
  92 .It Va kern.timecounter.tc. Ns Ar X Ns Va .quality
  93 is an integral value, defining how good is this time counter,
  94 comparing to others.
  95 Negative value means that this time counter is broken and should not be used.
  96 .El
  97 .Pp
  98 Time management code of the kernel chooses one time counter from that list.
  99 Current choice can be read and affected via
 100 .Va kern.timecounter.hardware
 101 tunable/sysctl.
 102 .Sh SEE ALSO
 103 .Xr attimer 4 ,
 104 .Xr eventtimers 4 ,
 105 .Xr ffclock 4 ,
 106 .Xr hpet 4