Copyright (c) 2023 The NetBSD Foundation, Inc.
All rights reserved.
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 6, 2023 .Dt HEARTBEAT 9 .Os """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh NAME .Nm heartbeat .Nd periodic checks to ensure CPUs are making progress """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh SYNOPSIS .Fd "options HEARTBEAT" .Fd "options HEARTBEAT_MAX_PERIOD_DEFAULT=15"
n sys/heartbeat.h
.Ft void .Fn heartbeat_start void .Ft void .Fn heartbeat void .Ft void .Fn heartbeat_suspend void .Ft void .Fn heartbeat_resume void .Fd "#ifdef DDB" .Ft void .Fn heartbeat_dump void .Fd "#endif" """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh DESCRIPTION The .Nm subsystem verifies that soft interrupts
q Xr softint 9 and the system .Xr timecounter 9 are making progress over time, and panics if they appear stuck.
p The number of seconds before .Nm panics without progress is controlled by the sysctl knob .Li kern.heartbeat.max_period , which defaults to 15. If set to zero, heartbeat checks are disabled.
p The periodic hardware timer interrupt handler calls .Fn heartbeat every tick on each CPU. Once per second
o i.e., every .Xr hz 9 ticks
c , .Fn heartbeat schedules a soft interrupt at priority .Dv SOFTINT_CLOCK to advance the current CPU's view of .Xr time_uptime 9 .
p .Fn heartbeat checks whether .Xr time_uptime 9 has changed, to see if either the .Xr timecounter 9 or soft intrrupts on the current CPU are stuck. If it hasn't advanced within .Li kern.heartbeat.max_period seconds worth of ticks, or if it has updated and the current CPU's view of it hasn't been updated by more than .Li kern.heartbeat.max_period seconds, then .Fn heartbeat panics.
p .Fn heartbeat also checks whether the next online CPU has advanced its view of .Xr time_uptime 9 , to see if soft interrupts
q including Xr callout 9
on that CPU are stuck.
If it hasn't updated within
.Li kern.heartbeat.max_period
seconds,
.Fn heartbeat
sends an
.Xr ipi 9
to panic on that CPU.
If that CPU has not acknowledged the
.Xr ipi 9
within one second,
.Fn heartbeat
panics on the current CPU instead.
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh FUNCTIONS
l -tag -width Fn t Fn heartbeat Check for timecounter and soft interrupt progress on this CPU and on
another CPU, and schedule a soft interrupt to advance this CPU's view
of timecounter progress.
p Called by .Xr hardclock 9 periodically. t Fn heartbeat_dump Print all the heartbeat counter, uptime cache, and uptime cache timestamp (in units of heartbeats) to the console.
p Can be invoked from .Xr ddb 9 by .Ql call heartbeat_dump . t Fn heartbeat_resume Resume heartbeat monitoring of the current CPU.
p Called after a CPU has started running but before it has been marked online. t Fn heartbeat_start Start monitoring heartbeats systemwide.
p Called by .Xr main 9 as soon as soft interrupts can be established. t Fn heartbeat_suspend Suspend heartbeat monitoring of the current CPU.
p
Called after the current CPU has been marked offline but before it has
stopped running.
.El
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh CODE REFERENCES
The
.Nm
subsystem is implemented in
a sys/kern/kern_heartbeat.c .
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh SEE ALSO
.Xr swwdog 4 ,
.Xr wdogctl 8
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh HISTORY
The
.Nm
subsystem first appeared in
.Nx 11.0 .