share/man/man9/hz.9

   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
  43 utilizes periodic, one-shot, global or per-CPU
  44 timing hardware using
  45 .Xr eventtimers 9
  46 to produce traditional clock behavior.
  47 These clocks regulate periodic events in the system.
  48 .Pp
  49 The main clock is used to update the system's notion of time via
  50 .Xr timecounters 9
  51 and to pace periodic system processing as documented in
  52 .Xr hardclock 9 .
  53 That routine may be called once every 1 /
  54 .Va hz
  55 seconds, though the call is omitted if no work is needed in the next tick and it
  56 has not been 0.5 seconds since the last call.
  57 .Pp
  58 The stat clock running at
  59 .Va stathz
  60 gathers statistics on the system and its processes.
  61 It computes values for
  62 .Xr getrusage 2
  63 and statistics displayed by
  64 .Xr ps 1
  65 and
  66 .Xr top 1 .
  67 .Pp
  68 Finally, a profiling clock may run at
  69 .Vt profhz
  70 to sample user program counter values for profiling purposes.
  71 This profiling mechanism has been replaced by the more functional
  72 .Xr hwpmc 4
  73 and may be removed in a future version of
  74 .Fx .
  75 .Pp
  76 .Va tick
  77 is the length of time in microseconds of one system tick.
  78 .Pp
  79 These system variables are also available as
  80 .Em struct clockinfo
  81 from
  82 .Xr sysctl 3
  83 and
  84 .Sy kern.clockrate
  85 from
  86 .Xr sysctl 8 .
  87 .Pp
  88 The current global and per-CPU CPU time usage is returned to the user in units
  89 of 1 /
  90 .Va stathz
  91 ticks in the
  92 .Sy kern.cp_time
  93 and
  94 .Sy kern.cp_times
  95 sysctl MIBs.
  96 .Pp
  97 The
  98 .Va hz
  99 rate may be overridden by defining
 100 .Dv HZ
 101 in the kernel configuration file or setting
 102 .Sy kern.hz
 103 system tuneable via
 104 .Xr loader.conf 5 .
 105 .Pp
 106 The current default is 1000 Hz for a tick of 1 ms for real hardware.
 107 For virtual machine guests, the default is 100 Hz for a tick of 10 ms.
 108 Only override the default value if you really know what you are doing.
 109 Due to the adaptive nature of timeouts, changing this value has less effect than
 110 it 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
 123 Historically, both the
 124 .Va stathz
 125 and
 126 .Va profhz
 127 clocks have run off the same physical timer running at the slower rate when no
 128 process is using the profile features, or at the higher rate when at least one
 129 process is using it.
 130 Although the interface is deprecated by
 131 .St -p1003.1-2008
 132 in favor of
 133 .Xr timer_settime 2 ,
 134 several programs still use
 135 .Xr setitimer 2
 136 and
 137 .Va ITIMER_PROF
 138 for a higher-resolution periodic interrupt than has been traditionally
 139 available.
 140 .Pp
 141 Historically,
 142 .Xr hardclock 9
 143 has also been run off a separate interrupt, except on constrained platforms that
 144 lack enough periodic interrupt sources.
 145 .Fx
 146 uses
 147 .Xr eventtimers 9
 148 to abstract these details away, though some old code may still harbor
 149 assumptions that are an imperfect fit to this abstraction.
 150 .Pp
 151 .Xr timecounters 9
 152 are limited to 32-bits and wrap after about a second, so we must update the
 153 time hands they maintain at least every half second to get the proper wrapping
 154 math.
 155 In addition,
 156 .Va kern.cp_times
 157 needs to updated at least once a second so that the values displayed by
 158 .Xr top 1
 159 update every second.