mirror of
https://github.com/freebsd/freebsd-src
synced 2024-07-22 02:37:15 +00:00
160 lines
4.6 KiB
Groff
160 lines
4.6 KiB
Groff
.\"
|
|
.\" Copyright (c) 2021 Netflix, Inc.
|
|
.\"
|
|
.\" 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 NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
|
.\" ``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 FOUNDATION OR CONTRIBUTORS
|
|
.\" 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 July 1, 2021
|
|
.Dt HZ 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm hz ,
|
|
.Nm tick ,
|
|
.Nm stathz ,
|
|
.Nm profhz
|
|
.Nd system time model
|
|
.Sh SYNOPSIS
|
|
.In sys/kernel.h
|
|
.Pp
|
|
.Vt extern int hz;
|
|
.Vt extern int tick;
|
|
.Vt extern int stathz;
|
|
.Vt extern int profhz; /* deprecated */
|
|
.Sh DESCRIPTION
|
|
.Fx
|
|
utilizes periodic, one-shot, global or per-CPU
|
|
timing hardware using
|
|
.Xr eventtimers 9
|
|
to produce traditional clock behavior.
|
|
These clocks regulate periodic events in the system.
|
|
.Pp
|
|
The main clock is used to update the system's notion of time via
|
|
.Xr timecounters 9
|
|
and to pace periodic system processing as documented in
|
|
.Xr hardclock 9 .
|
|
That routine may be called once every 1 /
|
|
.Va hz
|
|
seconds, though the call is omitted if no work is needed in the next tick and it
|
|
has not been 0.5 seconds since the last call.
|
|
.Pp
|
|
The stat clock running at
|
|
.Va stathz
|
|
gathers statistics on the system and its processes.
|
|
It computes values for
|
|
.Xr getrusage 2
|
|
and statistics displayed by
|
|
.Xr ps 1
|
|
and
|
|
.Xr top 1 .
|
|
.Pp
|
|
Finally, a profiling clock may run at
|
|
.Vt profhz
|
|
to sample user program counter values for profiling purposes.
|
|
This profiling mechanism has been replaced by the more functional
|
|
.Xr hwpmc 4
|
|
and may be removed in a future version of
|
|
.Fx .
|
|
.Pp
|
|
.Va tick
|
|
is the length of time in microseconds of one system tick.
|
|
.Pp
|
|
These system variables are also available as
|
|
.Em struct clockinfo
|
|
from
|
|
.Xr sysctl 3
|
|
and
|
|
.Sy kern.clockrate
|
|
from
|
|
.Xr sysctl 8 .
|
|
.Pp
|
|
The current global and per-CPU CPU time usage is returned to the user in units
|
|
of 1 /
|
|
.Va stathz
|
|
ticks in the
|
|
.Sy kern.cp_time
|
|
and
|
|
.Sy kern.cp_times
|
|
sysctl MIBs.
|
|
.Pp
|
|
The
|
|
.Va hz
|
|
rate may be overridden by defining
|
|
.Dv HZ
|
|
in the kernel configuration file or setting
|
|
.Sy kern.hz
|
|
system tuneable via
|
|
.Xr loader.conf 5 .
|
|
.Pp
|
|
The current default is 1000 Hz for a tick of 1 ms for real hardware.
|
|
For virtual machine guests, the default is 100 Hz for a tick of 10 ms.
|
|
Only override the default value if you really know what you are doing.
|
|
Due to the adaptive nature of timeouts, changing this value has less effect than
|
|
it had in the past.
|
|
.Sh SEE ALSO
|
|
.Xr ps 1 ,
|
|
.Xr top 1 ,
|
|
.Xr setitimer 2 ,
|
|
.Xr timer_settime 2 ,
|
|
.Xr loader.conf 5 ,
|
|
.Xr eventtimers 9 ,
|
|
.Xr hardclock 9 ,
|
|
.Xr microtime 9 ,
|
|
.Xr time_second 9 ,
|
|
.Xr timecounters 9
|
|
.Sh IMPLEMENTATION NOTES
|
|
Historically, both the
|
|
.Va stathz
|
|
and
|
|
.Va profhz
|
|
clocks have run off the same physical timer running at the slower rate when no
|
|
process is using the profile features, or at the higher rate when at least one
|
|
process is using it.
|
|
Although the interface is deprecated by
|
|
.St -p1003.1-2008
|
|
in favor of
|
|
.Xr timer_settime 2 ,
|
|
several programs still use
|
|
.Xr setitimer 2
|
|
and
|
|
.Va ITIMER_PROF
|
|
for a higher-resolution periodic interrupt than has been traditionally
|
|
available.
|
|
.Pp
|
|
Historically,
|
|
.Xr hardclock 9
|
|
has also been run off a separate interrupt, except on constrained platforms that
|
|
lack enough periodic interrupt sources.
|
|
.Fx
|
|
uses
|
|
.Xr eventtimers 9
|
|
to abstract these details away, though some old code may still harbor
|
|
assumptions that are an imperfect fit to this abstraction.
|
|
.Pp
|
|
.Xr timecounters 9
|
|
are limited to 32-bits and wrap after about a second, so we must update the
|
|
time hands they maintain at least every half second to get the proper wrapping
|
|
math.
|
|
In addition,
|
|
.Va kern.cp_times
|
|
needs to updated at least once a second so that the values displayed by
|
|
.Xr top 1
|
|
update every second.
|