Date: Fri, 18 Jun 2021 14:43:49 GMT From: Warner Losh <imp@FreeBSD.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org Subject: git: 4c0bc591466f - main - man9: add hz(9) and hardclock(9) Message-ID: <202106181443.15IEhn4t010735@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by imp: URL: https://cgit.FreeBSD.org/src/commit/?id=4c0bc591466fd2731ba892269260b7dab74cfbad commit 4c0bc591466fd2731ba892269260b7dab74cfbad Author: Warner Losh <imp@FreeBSD.org> AuthorDate: 2021-06-18 14:39:42 +0000 Commit: Warner Losh <imp@FreeBSD.org> CommitDate: 2021-06-18 14:42:51 +0000 man9: add hz(9) and hardclock(9) Document aspects of system time keeping. Hz is the nominal rate that we interrupt the system and is known and the 'tick' period of 1 / hz. hardclock is the routine that does various bits of timekeeping. stathz and profhz are documented as historical relics that are deprecated and replaced by hwpmc.4 and others. Reviewed by: phk@, mav@ and gnn@ (previous version) Obtained from: hardclock.9 from NetBSD (with FreeBSD adjustments) Sponsored by: Netflix Differential Revision: https://reviews.freebsd.org/D30802 --- share/man/man9/Makefile | 3 ++ share/man/man9/hardclock.9 | 100 +++++++++++++++++++++++++++++++++++++++ share/man/man9/hz.9 | 114 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 217 insertions(+) diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 179f79b39573..f7d72ad8cd8f 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -159,10 +159,12 @@ MAN= accept_filter.9 \ g_provider_by_name.9 \ groupmember.9 \ g_wither_geom.9 \ + hardclock.9 \ hash.9 \ hashinit.9 \ hexdump.9 \ hhook.9 \ + hz.9 \ ieee80211.9 \ ieee80211_amrr.9 \ ieee80211_beacon.9 \ @@ -1125,6 +1127,7 @@ MLINKS+=hhook.9 hhook_head_register.9 \ hhook.9 hhook_run_hooks.9 \ hhook.9 HHOOKS_RUN_IF.9 \ hhook.9 HHOOKS_RUN_LOOKUP_IF.9 +MLINKS+=hz.9 tick.9 MLINKS+=ieee80211.9 ieee80211_ifattach.9 \ ieee80211.9 ieee80211_ifdetach.9 MLINKS+=ieee80211_amrr.9 ieee80211_amrr_choose.9 \ diff --git a/share/man/man9/hardclock.9 b/share/man/man9/hardclock.9 new file mode 100644 index 000000000000..2aab68cb5f85 --- /dev/null +++ b/share/man/man9/hardclock.9 @@ -0,0 +1,100 @@ +.\" $NetBSD: hardclock.9,v 1.3 2010/03/25 15:17:38 jruoho Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Thomas Klausner. +.\" +.\" 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 March 25, 2010 +.Dt HARDCLOCK 9 +.Os +.Sh NAME +.Nm hardclock +.Nd real-time timer +.Sh SYNOPSIS +.Ft void +.Fn hardclock "int cnt" "int usermode" +.Sh DESCRIPTION +The +.Fn hardclock +function is called +.Xr hz 9 +times per second. +It implements the real-time system clock. +The argument +.Va cnt +is the estimated number of ticks since the last call to +.Fn hardclock . +The argument +.Va usermode +is none-zero when +.Fn hardclock +is called from a user-mode context. +.Pp +.Fn hardclock +may perform different tasks such as: +.Bl -bullet -offset indent +.It +Run the current process's virtual and profile time (decrease the +corresponding timers, if they are activated, and generate +.Li SIGVTALRM +or +.Li SIGPROF , +respectively). +.It +Increment the time-of-day, taking care of any +.Xr ntpd 8 +or +.Xr adjtime 2 +induced changes and leap seconds, as well as any necessary +compensations to keep in sync with PPS signals or external clocks, if +support for this is in the kernel (see +.Xr options 4 ) . +.It +Schedule softclock interrupts ( +.Xr swi 9 ) +processing. +.It +Collect +.Xr hwpmc 4 +statistics. +.It +Do device polling, when enabled. +.It +Implement software +.Xr watchdog 9 +processing. +.It +Enqueue +.Xr epoch 9 +processing. +.El +.Sh SEE ALSO +.Xr adjtime 2 , +.Xr ntp_adjtime 2 , +.Xr signal 3 , +.Xr ntpd 8 , +.Xr callout 9 , +.Xr hz 9 diff --git a/share/man/man9/hz.9 b/share/man/man9/hz.9 new file mode 100644 index 000000000000..d0e5d1b1ff3e --- /dev/null +++ b/share/man/man9/hz.9 @@ -0,0 +1,114 @@ +.\" +.\" 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 June 18, 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; /* deprecated */ +.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. +.Pp +The main clock is used to update the system's notion of time via +.Xr timecounters 9 +and to pace periodic system callbacks via +.Xr callout 9 , +.Xr epoch 9 , +and other methods documented in +.Xr hardclock 9 . +That routine will be called approximately +.Va hz +times per second. +.Pp +The second clock, running at either +.Va stathz +or +.Va profhz +was used to gather timing statistics, but has been replaced with the more +functional +.Xr hwpmc 4 . +These values are returned for +.Qq compatibility +with +.Bx 4.4 , +.St -p1003.1-2001 +and the +.Xr setitimer 2 +.Va ITIMER_PROF +flag, which were deprecated in +.St -p1003.1-2008 +in favor of +.Xr timer_settime 2 . +.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 +.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 setitimer 2 , +.Xr timer_settime 2 , +.Xr loader.conf 5 , +.Xr callout 9 , +.Xr eventtimers 9 , +.Xr hardclock 9 , +.Xr microtime 9 , +.Xr time_second 9 , +.Xr timecounters 9
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202106181443.15IEhn4t010735>