From owner-dev-commits-src-main@freebsd.org Fri Jun 18 14:43:50 2021 Return-Path: Delivered-To: dev-commits-src-main@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 1B01D64683B; Fri, 18 Jun 2021 14:43:50 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4G61rj6vNFz4j6t; Fri, 18 Jun 2021 14:43:49 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id D2B2D246BD; Fri, 18 Jun 2021 14:43:49 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 15IEhnsj010736; Fri, 18 Jun 2021 14:43:49 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 15IEhn4t010735; Fri, 18 Jun 2021 14:43:49 GMT (envelope-from git) Date: Fri, 18 Jun 2021 14:43:49 GMT Message-Id: <202106181443.15IEhn4t010735@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Warner Losh Subject: git: 4c0bc591466f - main - man9: add hz(9) and hardclock(9) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: imp X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 4c0bc591466fd2731ba892269260b7dab74cfbad Auto-Submitted: auto-generated X-BeenThere: dev-commits-src-main@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Commit messages for the main branch of the src repository List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 18 Jun 2021 14:43:50 -0000 The branch main has been updated by imp: URL: https://cgit.FreeBSD.org/src/commit/?id=4c0bc591466fd2731ba892269260b7dab74cfbad commit 4c0bc591466fd2731ba892269260b7dab74cfbad Author: Warner Losh AuthorDate: 2021-06-18 14:39:42 +0000 Commit: Warner Losh 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