1.\" $OpenBSD: tc_init.9,v 1.12 2023/04/02 00:02:26 cheloha Exp $ 2.\" 3.\" Copyright (c) 2004 Alexander Yurchenko <grange@openbsd.org> 4.\" Copyright (c) 2023 Scott Cheloha <cheloha@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.Dd $Mdocdate: April 2 2023 $ 19.Dt TC_INIT 9 20.Os 21.Sh NAME 22.Nm tc_init 23.Nd timecounting subsystem 24.Sh SYNOPSIS 25.In sys/timetc.h 26.Ft void 27.Fn tc_init "struct timecounter *tc" 28.Sh DESCRIPTION 29The 30.Sy timecounting 31subsystem implements a uniform interface to timekeeping hardware, 32measures the passage of time, 33and implements the kernel's software clocks 34.Po see 35.Xr microtime 9 36for details 37.Pc . 38.Pp 39A hardware clock is suitable for counting time if it meets the following 40requirements: 41.Bl -enum -offset indent 42.It 43It is a binary counter. 44.It 45It advances at a fixed, known frequency. 46.It 47Its count is synchronized between all CPUs on the system. 48.It 49It continues counting when it rolls over. 50.It 51If 52.Xr hz 9 53is less than or equal to one millisecond, 54the counter does not roll over in less than two milliseconds. 55If 56.Xr hz 9 57exceeds one millisecond, 58the counter does not roll over in less than 59.Pq 2 / Va hz 60seconds. 61.El 62.Pp 63Hardware clocks are described with a 64.Va timecounter 65structure: 66.Bd -literal -offset indent 67struct timecounter { 68 u_int (*tc_get_timecount)(struct timecounter *); 69 u_int tc_counter_mask; 70 u_int64_t tc_frequency; 71 char *tc_name; 72 int tc_quality; 73 void *tc_priv; 74 u_int tc_user; 75}; 76.Ed 77.Bl -tag -width indent 78.It Ft u_int Fn (*tc_get_timecount) "struct timecounter *" 79Reads the hardware clock and returns its count. 80Any unimplemented bits only need to be masked if they are not constant. 81If the counter is larger than 32 bits, 82this function must return a 32-bit subset. 83The subsystem requires an upward count; 84downward counts must be inverted before they are returned. 85.It Va tc_counter_mask 86The mask of implemented bits. 87Used to discard unimplemented bits from 88.Fn tc_get_timecount . 89.It Va tc_frequency 90The counter's fixed frequency. 91.It Va tc_name 92The counter's unique name. 93A 94.Dv NUL Ns -terminated string. 95.It Va tc_quality 96A relative quality metric used to compare counters. 97Higher values indicate a better counter. 98A negative value indicates that the counter is non-monotonic 99or otherwise deficient. 100The system will only use negative-quality counters if requested. 101.It Va tc_priv 102May point to anything the driver needs during 103.Fn tc_get_timecount . 104.It Va tc_user 105If non-zero, 106a unique value identifying the userspace implementation of 107.Fn tc_get_timecount . 108.El 109.Pp 110To register a timecounter, 111a device driver initializes the above-described fields of a 112.Va timecounter 113structure and calls 114.Fn tc_init 115with a pointer to that structure as argument. 116.Sh CONTEXT 117.Fn tc_init 118may only be called during autoconf. 119.Sh CODE REFERENCES 120.Pa sys/kern/kern_tc.c 121.Sh SEE ALSO 122.Xr amdpm 4 , 123.Xr gscpm 4 , 124.Xr ichpcib 4 , 125.Xr viapm 4 , 126.Xr hz 9 , 127.Xr microtime 9 128.Rs 129.%A Poul-Henning Kamp 130.%T Timecounter: Efficient and precise timekeeping in SMP kernels 131.%J The FreeBSD Project 132.%D 2002 133.%U https://papers.freebsd.org/2002/phk-timecounters.files/timecounter.pdf 134.Re 135.Sh HISTORY 136The timecounting subsystem first appeared in 137.Fx 3.0 . 138It was ported to 139.Ox 3.6 . 140.Sh AUTHORS 141.An Poul-Henning Kamp 142