share/man/man9/timecounter.9

   1 .\"     $NetBSD: timecounter.9,v 1.6 2008/11/28 11:16:26 tsutsui Exp $
   2 .\"     $OpenBSD: tc_init.9,v 1.4 2007/05/31 19:20:01 jmc Exp $
   3 .\"
   4 .\" Copyright (c) 2004 Alexander Yurchenko <grange@openbsd.org>
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .\" Copyright (c) 2008 Izumi Tsutsui.  All rights reserved.
  19 .\"
  20 .\" Redistribution and use in source and binary forms, with or without
  21 .\" modification, are permitted provided that the following conditions
  22 .\" are met:
  23 .\" 1. Redistributions of source code must retain the above copyright
  24 .\"    notice, this list of conditions and the following disclaimer.
  25 .\" 2. Redistributions in binary form must reproduce the above copyright
  26 .\"    notice, this list of conditions and the following disclaimer in the
  27 .\"    documentation and/or other materials provided with the distribution.
  28 .\"
  29 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  30 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  31 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  32 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  33 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  34 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  35 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  36 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  37 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  38 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  39 .\"
  40 .Dd November 26, 2008
  41 .Dt TIMECOUNTER 9
  42 .Os
  43 .Sh NAME
  44 .Nm timecounter ,
  45 .Nm tc_init
  46 .Nd machine-independent binary timescale
  47 .Sh SYNOPSIS
  48 .In sys/timetc.h
  49 .Ft void
  50 .Fn tc_init "struct timecounter *tc"
  51 .Sh DESCRIPTION
  52 The timecounter interface is a machine-independent implementation
  53 of a binary timescale using whatever hardware support is at hand
  54 for tracking time.
  55 .Pp
  56 A timecounter is a binary counter which has two properties:
  57 .Bl -bullet -offset indent
  58 .It
  59 it runs at a fixed, known frequency
  60 .It
  61 it has sufficient bits to not roll over in less than approximately
  62 max(2 msec,
  63 .Pf 2/ Em HZ
  64 seconds) (the value 2 here is really 1 + delta, for some
  65 indeterminate value of delta)
  66 .El
  67 .Pp
  68 The interface between the hardware which implements a timecounter and the
  69 machine-independent code which uses this to keep track of time is a
  70 .Va timecounter
  71 structure:
  72 .Bd -literal -offset indent
  73 struct timecounter {
  74         timecounter_get_t       *tc_get_timecount;
  75         timecounter_pps_t       *tc_poll_pps;
  76         u_int                   tc_counter_mask;
  77         u_int64_t               tc_frequency;
  78         const char              *tc_name;
  79         int                     tc_quality;
  80         void                    *tc_priv;
  81         struct timecounter      *tc_next;
  82 }
  83 .Ed
  84 .Pp
  85 The fields of the
  86 .Va timecounter
  87 structure are described below.
  88 .Bl -tag -width indent
  89 .It Fn "u_int (*tc_get_timecount)" "struct timecounter *"
  90 This function reads the counter.
  91 It is not required to mask any unimplemented bits out, as long as they
  92 are constant.
  93 .It Fn "void (*tc_poll_pps)" "struct timecounter *"
  94 This function is optional and can be set to
  95 .Dv NULL .
  96 It will be called whenever the timecounter is rewound, and is intended
  97 to check for PPS events.
  98 Normal hardware does not need it but timecounters which latch PPS in
  99 hardware do.
 100 .It Va tc_counter_mask
 101 This mask should mask off any unimplemented bits.
 102 .It Va tc_frequency
 103 Frequency of the counter in Hz.
 104 .It Va tc_name
 105 Name of the timecounter.
 106 Can be any nul-terminated string.
 107 .It Va tc_quality
 108 Used to determine if this timecounter is better than another timecounter \-
 109 higher means better.
 110 Negative means
 111 .Dq only use at explicit request .
 112 .It Va tc_priv
 113 Pointer to the timecounter's private parts.
 114 .It Va tc_next
 115 For internal use.
 116 .El
 117 .Pp
 118 To register a new timecounter,
 119 the hardware device driver should fill a
 120 .Va timecounter
 121 structure with appropriate values and call the
 122 .Fn tc_init
 123 function, giving a pointer to the structure as a
 124 .Fa tc
 125 parameter.
 126 .Sh TIMESTAMP FORMAT
 127 The timestamp format used in the machine independent timecounter
 128 implementation is a
 129 .Va bintime
 130 structure:
 131 .Bd -literal -offset indent
 132 struct bintime {
 133         time_t  sec;
 134         uint64_t frac;
 135 }
 136 .Ed
 137 .Pp
 138 The
 139 .Va sec
 140 field records the number of seconds as well as the
 141 .Va tv_sec
 142 field in the traditional
 143 .Ux
 144 .Va timeval
 145 and
 146 .Va timespec
 147 structures.
 148 .Pp
 149 The
 150 .Va frac
 151 field records fractional seconds represented in a fully 64 bit integer,
 152 i.e. it goes all the way from
 153 .Li 0
 154 through
 155 .Li 0xFFFFFFFFFFFFFFFF
 156 per each second.
 157 The effective resolution of the
 158 .Va frac
 159 value depends on a frequency of the machine dependent timecounter source.
 160 .Pp
 161 The
 162 .Va bintime
 163 format is a binary number, not a pseudo-decimal number,
 164 so it can be used as a simple binary counter
 165 without expensive 64 bit arithmetics.
 166 .Sh CODE REFERENCES
 167 The timecounter framework is implemented in the file
 168 .Pa sys/kern/kern_tc.c .
 169 .Pp
 170 The
 171 .Va bintime
 172 structure and related functions are defined in the file
 173 .Pa sys/sys/time.h .
 174 .Sh SEE ALSO
 175 .Xr clock_settime 2 ,
 176 .Xr ntp_adjtime 2 ,
 177 .Xr settimeofday 2 ,
 178 .Xr bintime 9 ,
 179 .Xr binuptime 9 ,
 180 .Xr getbintime 9 ,
 181 .Xr getbinuptime 9 ,
 182 .Xr getmicrotime 9 ,
 183 .Xr getmicrouptime 9 ,
 184 .Xr getnanotime 9 ,
 185 .Xr getnanouptime 9 ,
 186 .Xr hz 9 ,
 187 .Xr microtime 9 ,
 188 .Xr microuptime 9 ,
 189 .Xr nanotime 9 ,
 190 .Xr nanouptime 9 ,
 191 .Xr time_second 9
 192 .Rs
 193 .%A "Poul-Henning Kamp"
 194 .%T "Timecounters: Efficient and precise timekeeping in SMP kernels"
 195 .%J "Proceedings of EuroBSDCon 2002, Amsterdam"
 196 .%U http://phk.freebsd.dk/pubs/timecounter.pdf
 197 .Re
 198 .Sh HISTORY
 199 The timecounter interface first appeared in
 200 .Fx ,
 201 and was ported to
 202 .Nx 4.0
 203 by Frank Kardel and Simon Burge.