diff options
Diffstat (limited to 'static/netbsd/man9/timecounter.9')
| -rw-r--r-- | static/netbsd/man9/timecounter.9 | 195 |
1 files changed, 195 insertions, 0 deletions
diff --git a/static/netbsd/man9/timecounter.9 b/static/netbsd/man9/timecounter.9 new file mode 100644 index 00000000..52fb5787 --- /dev/null +++ b/static/netbsd/man9/timecounter.9 @@ -0,0 +1,195 @@ +.\" $NetBSD: timecounter.9,v 1.11 2021/09/18 18:01:18 tsutsui Exp $ +.\" $OpenBSD: tc_init.9,v 1.4 2007/05/31 19:20:01 jmc Exp $ +.\" +.\" Copyright (c) 2004 Alexander Yurchenko <grange@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Copyright (c) 2008 Izumi Tsutsui. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 18, 2021 +.Dt TIMECOUNTER 9 +.Os +.Sh NAME +.Nm timecounter , +.Nm tc_init +.Nd machine-independent binary timescale +.Sh SYNOPSIS +.In sys/timetc.h +.Ft void +.Fn tc_init "struct timecounter *tc" +.Sh DESCRIPTION +The timecounter interface is a machine-independent implementation +of a binary timescale using whatever hardware support is at hand +for tracking time. +.Pp +A timecounter is a binary counter which has two properties: +.Bl -bullet -offset indent +.It +it runs at a fixed, known frequency; and +.It +it has sufficient bits to not roll over in less than approximately +max(2 msec, +.Pf 2/ Em HZ +seconds) (the value 2 here is really 1 + delta, for some +indeterminate value of delta). +.El +.Pp +The interface between the hardware which implements a timecounter and the +machine-independent code which uses this to keep track of time is a +.Va timecounter +structure: +.Bd -literal -offset indent +struct timecounter { + timecounter_get_t *tc_get_timecount; + timecounter_pps_t *tc_poll_pps; + u_int tc_counter_mask; + uint64_t tc_frequency; + const char *tc_name; + int tc_quality; + void *tc_priv; + struct timecounter *tc_next; +} +.Ed +.Pp +The fields of the +.Va timecounter +structure are described below. +.Bl -tag -width indent +.It Fn "u_int (*tc_get_timecount)" "struct timecounter *" +This function reads the counter. +It is not required to mask any unimplemented bits out, as long as they +are constant. +.It Fn "void (*tc_poll_pps)" "struct timecounter *" +This function is optional and can be set to +.Dv NULL . +It will be called whenever the timecounter is rewound, and is intended +to check for PPS events. +Normal hardware does not need it but timecounters which latch PPS in +hardware do. +.It Va tc_counter_mask +This mask should mask off any unimplemented bits. +.It Va tc_frequency +Frequency of the counter in Hz. +.It Va tc_name +Name of the timecounter. +Can be any NUL-terminated string. +.It Va tc_quality +Used to determine if this timecounter is better than another timecounter \- +higher means better. +Negative means +.Dq only use at explicit request . +.It Va tc_priv +Pointer to the timecounter's private parts. +.It Va tc_next +For internal use. +.El +.Pp +To register a new timecounter, +the hardware device driver should fill a +.Va timecounter +structure with appropriate values and call the +.Fn tc_init +function, giving a pointer to the structure as a +.Fa tc +parameter. +.Sh TIMESTAMP FORMAT +The timestamp format used in the machine independent timecounter +implementation is a +.Va bintime +structure: +.Bd -literal -offset indent +struct bintime { + time_t sec; + uint64_t frac; +} +.Ed +.Pp +The +.Va sec +field records the number of seconds as well as the +.Va tv_sec +field in the traditional +.Ux +.Va timeval +and +.Va timespec +structures, described in +.Xr timeval 3 . +.Pp +The +.Va frac +field records fractional seconds represented in a fully 64 bit integer, +i.e. it goes all the way from +.Li 0 +through +.Li 0xFFFFFFFFFFFFFFFF +per each second. +The effective resolution of the +.Va frac +value depends on a frequency of the machine dependent timecounter source. +.Pp +The +.Va bintime +format is a binary number, not a pseudo-decimal number, +so it can be used as a simple binary counter +without expensive 64 bit arithmetic. +.Sh CODE REFERENCES +The timecounter framework is implemented in the file +.Pa sys/kern/kern_tc.c . +The +.Va bintime +structure and related functions are defined in the file +.In sys/time.h . +.Sh SEE ALSO +.Xr clock_settime 2 , +.Xr ntp_adjtime 2 , +.Xr settimeofday 2 , +.Xr bintime 9 , +.Xr bintime_add 9 , +.Xr binuptime 9 , +.Xr hz 9 , +.Xr time_second 9 +.Rs +.%A Poul-Henning Kamp +.%T "Timecounters: Efficient and precise timekeeping in SMP kernels" +.%J "Proceedings of EuroBSDCon 2002, Amsterdam" +.%D 15-17 November, 2002 +.%U http://phk.freebsd.dk/pubs/timecounter.pdf +.Re +.Sh HISTORY +The timecounter interface first appeared in +.Fx , +and was ported to +.Nx 4.0 +by Frank Kardel and Simon Burge. |