From owner-dev-commits-src-main@freebsd.org Thu Jul 1 15:34:03 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 27332665FD7; Thu, 1 Jul 2021 15:34:03 +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 4GG2Lg0Td3z4T3s; Thu, 1 Jul 2021 15:34:03 +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 ED08022EAE; Thu, 1 Jul 2021 15:34:02 +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 161FY28u067621; Thu, 1 Jul 2021 15:34:02 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 161FY2BC067620; Thu, 1 Jul 2021 15:34:02 GMT (envelope-from git) Date: Thu, 1 Jul 2021 15:34:02 GMT Message-Id: <202107011534.161FY2BC067620@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: 1426907f4dd0 - main - hz.9: update stathz for current usage 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: 1426907f4dd017d978caf7d946d2d398d68673fd 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: Thu, 01 Jul 2021 15:34:03 -0000 The branch main has been updated by imp: URL: https://cgit.FreeBSD.org/src/commit/?id=1426907f4dd017d978caf7d946d2d398d68673fd commit 1426907f4dd017d978caf7d946d2d398d68673fd Author: Warner Losh AuthorDate: 2021-07-01 15:32:40 +0000 Commit: Warner Losh CommitDate: 2021-07-01 15:33:03 +0000 hz.9: update stathz for current usage Update the stathz description to reflect reality. profhz is the only thing we should deprecate. Add some implementation notes that describe the optimizations made to date. Discusssed with: emaste Reviewed by: kib (prior), jhb (prior), gbe Sponsored by: Netflix Differential Revision: https://reviews.freebsd.org/D30815 --- share/man/man9/hz.9 | 99 ++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 72 insertions(+), 27 deletions(-) diff --git a/share/man/man9/hz.9 b/share/man/man9/hz.9 index d0e5d1b1ff3e..73efcf3b0da3 100644 --- a/share/man/man9/hz.9 +++ b/share/man/man9/hz.9 @@ -22,7 +22,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd June 18, 2021 +.Dd July 1, 2021 .Dt HZ 9 .Os .Sh NAME @@ -36,7 +36,7 @@ .Pp .Vt extern int hz; .Vt extern int tick; -.Vt extern int stathz; /* deprecated */ +.Vt extern int stathz; .Vt extern int profhz; /* deprecated */ .Sh DESCRIPTION .Fx @@ -44,37 +44,34 @@ 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 callbacks via -.Xr callout 9 , -.Xr epoch 9 , -and other methods documented in +and to pace periodic system processing as documented in .Xr hardclock 9 . -That routine will be called approximately +That routine may be called once every 1 / .Va hz -times per second. +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 second clock, running at either +The stat clock running at .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 . +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. @@ -88,6 +85,15 @@ and 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 @@ -103,12 +109,51 @@ 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 callout 9 , .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.