1.\" 2.\" Copyright (c) 2021 Netflix, Inc. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 14.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 15.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 16.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 17.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 18.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 19.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 20.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 21.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 22.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 23.\" POSSIBILITY OF SUCH DAMAGE. 24.\" 25.Dd July 1, 2021 26.Dt HZ 9 27.Os 28.Sh NAME 29.Nm hz , 30.Nm tick , 31.Nm stathz , 32.Nm profhz 33.Nd system time model 34.Sh SYNOPSIS 35.In sys/kernel.h 36.Pp 37.Vt extern int hz; 38.Vt extern int tick; 39.Vt extern int stathz; 40.Vt extern int profhz; /* deprecated */ 41.Sh DESCRIPTION 42.Fx 43utilizes periodic, one-shot, global or per-CPU 44timing hardware using 45.Xr eventtimers 9 46to produce traditional clock behavior. 47These clocks regulate periodic events in the system. 48.Pp 49The main clock is used to update the system's notion of time via 50.Xr timecounters 9 51and to pace periodic system processing as documented in 52.Xr hardclock 9 . 53That routine may be called once every 1 / 54.Va hz 55seconds, though the call is omitted if no work is needed in the next tick and it 56has not been 0.5 seconds since the last call. 57.Pp 58The stat clock running at 59.Va stathz 60gathers statistics on the system and its processes. 61It computes values for 62.Xr getrusage 2 63and statistics displayed by 64.Xr ps 1 65and 66.Xr top 1 . 67.Pp 68Finally, a profiling clock may run at 69.Vt profhz 70to sample user program counter values for profiling purposes. 71This profiling mechanism has been replaced by the more functional 72.Xr hwpmc 4 73and may be removed in a future version of 74.Fx . 75.Pp 76.Va tick 77is the length of time in microseconds of one system tick. 78.Pp 79These system variables are also available as 80.Em struct clockinfo 81from 82.Xr sysctl 3 83and 84.Sy kern.clockrate 85from 86.Xr sysctl 8 . 87.Pp 88The current global and per-CPU CPU time usage is returned to the user in units 89of 1 / 90.Va stathz 91ticks in the 92.Sy kern.cp_time 93and 94.Sy kern.cp_times 95sysctl MIBs. 96.Pp 97The 98.Va hz 99rate may be overridden by defining 100.Dv HZ 101in the kernel configuration file or setting 102.Sy kern.hz 103system tuneable via 104.Xr loader.conf 5 . 105.Pp 106The current default is 1000 Hz for a tick of 1 ms for real hardware. 107For virtual machine guests, the default is 100 Hz for a tick of 10 ms. 108Only override the default value if you really know what you are doing. 109Due to the adaptive nature of timeouts, changing this value has less effect than 110it had in the past. 111.Sh SEE ALSO 112.Xr ps 1 , 113.Xr top 1 , 114.Xr setitimer 2 , 115.Xr timer_settime 2 , 116.Xr loader.conf 5 , 117.Xr eventtimers 9 , 118.Xr hardclock 9 , 119.Xr microtime 9 , 120.Xr time_second 9 , 121.Xr timecounters 9 122.Sh IMPLEMENTATION NOTES 123Historically, both the 124.Va stathz 125and 126.Va profhz 127clocks have run off the same physical timer running at the slower rate when no 128process is using the profile features, or at the higher rate when at least one 129process is using it. 130Although the interface is deprecated by 131.St -p1003.1-2008 132in favor of 133.Xr timer_settime 2 , 134several programs still use 135.Xr setitimer 2 136and 137.Va ITIMER_PROF 138for a higher-resolution periodic interrupt than has been traditionally 139available. 140.Pp 141Historically, 142.Xr hardclock 9 143has also been run off a separate interrupt, except on constrained platforms that 144lack enough periodic interrupt sources. 145.Fx 146uses 147.Xr eventtimers 9 148to abstract these details away, though some old code may still harbor 149assumptions that are an imperfect fit to this abstraction. 150.Pp 151.Xr timecounters 9 152are limited to 32-bits and wrap after about a second, so we must update the 153time hands they maintain at least every half second to get the proper wrapping 154math. 155In addition, 156.Va kern.cp_times 157needs to updated at least once a second so that the values displayed by 158.Xr top 1 159update every second. 160