196 lines
6.0 KiB
Groff
196 lines
6.0 KiB
Groff
.\" $NetBSD: timecounter.9,v 1.10 2020/08/27 14:14:00 fcambus 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 June 8, 2010
|
|
.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;
|
|
u_int64_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.
|