1.\" $NetBSD: timecounter.9,v 1.11 2021/09/18 18:01:18 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 September 18, 2021 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 52The timecounter interface is a machine-independent implementation 53of a binary timescale using whatever hardware support is at hand 54for tracking time. 55.Pp 56A timecounter is a binary counter which has two properties: 57.Bl -bullet -offset indent 58.It 59it runs at a fixed, known frequency; and 60.It 61it has sufficient bits to not roll over in less than approximately 62max(2 msec, 63.Pf 2/ Em HZ 64seconds) (the value 2 here is really 1 + delta, for some 65indeterminate value of delta). 66.El 67.Pp 68The interface between the hardware which implements a timecounter and the 69machine-independent code which uses this to keep track of time is a 70.Va timecounter 71structure: 72.Bd -literal -offset indent 73struct timecounter { 74 timecounter_get_t *tc_get_timecount; 75 timecounter_pps_t *tc_poll_pps; 76 u_int tc_counter_mask; 77 uint64_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 85The fields of the 86.Va timecounter 87structure are described below. 88.Bl -tag -width indent 89.It Fn "u_int (*tc_get_timecount)" "struct timecounter *" 90This function reads the counter. 91It is not required to mask any unimplemented bits out, as long as they 92are constant. 93.It Fn "void (*tc_poll_pps)" "struct timecounter *" 94This function is optional and can be set to 95.Dv NULL . 96It will be called whenever the timecounter is rewound, and is intended 97to check for PPS events. 98Normal hardware does not need it but timecounters which latch PPS in 99hardware do. 100.It Va tc_counter_mask 101This mask should mask off any unimplemented bits. 102.It Va tc_frequency 103Frequency of the counter in Hz. 104.It Va tc_name 105Name of the timecounter. 106Can be any NUL-terminated string. 107.It Va tc_quality 108Used to determine if this timecounter is better than another timecounter \- 109higher means better. 110Negative means 111.Dq only use at explicit request . 112.It Va tc_priv 113Pointer to the timecounter's private parts. 114.It Va tc_next 115For internal use. 116.El 117.Pp 118To register a new timecounter, 119the hardware device driver should fill a 120.Va timecounter 121structure with appropriate values and call the 122.Fn tc_init 123function, giving a pointer to the structure as a 124.Fa tc 125parameter. 126.Sh TIMESTAMP FORMAT 127The timestamp format used in the machine independent timecounter 128implementation is a 129.Va bintime 130structure: 131.Bd -literal -offset indent 132struct bintime { 133 time_t sec; 134 uint64_t frac; 135} 136.Ed 137.Pp 138The 139.Va sec 140field records the number of seconds as well as the 141.Va tv_sec 142field in the traditional 143.Ux 144.Va timeval 145and 146.Va timespec 147structures, described in 148.Xr timeval 3 . 149.Pp 150The 151.Va frac 152field records fractional seconds represented in a fully 64 bit integer, 153i.e. it goes all the way from 154.Li 0 155through 156.Li 0xFFFFFFFFFFFFFFFF 157per each second. 158The effective resolution of the 159.Va frac 160value depends on a frequency of the machine dependent timecounter source. 161.Pp 162The 163.Va bintime 164format is a binary number, not a pseudo-decimal number, 165so it can be used as a simple binary counter 166without expensive 64 bit arithmetic. 167.Sh CODE REFERENCES 168The timecounter framework is implemented in the file 169.Pa sys/kern/kern_tc.c . 170The 171.Va bintime 172structure and related functions are defined in the file 173.In 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 bintime_add 9 , 180.Xr binuptime 9 , 181.Xr hz 9 , 182.Xr time_second 9 183.Rs 184.%A Poul-Henning Kamp 185.%T "Timecounters: Efficient and precise timekeeping in SMP kernels" 186.%J "Proceedings of EuroBSDCon 2002, Amsterdam" 187.%D 15-17 November, 2002 188.%U http://phk.freebsd.dk/pubs/timecounter.pdf 189.Re 190.Sh HISTORY 191The timecounter interface first appeared in 192.Fx , 193and was ported to 194.Nx 4.0 195by Frank Kardel and Simon Burge. 196