Updated: 2025/Nov/16

Please read Privacy Policy. It's for your privacy.

HEARTBEAT(9)               Kernel Developer's Manual              HEARTBEAT(9)

NAME
     heartbeat - periodic checks to ensure CPUs are making progress

SYNOPSIS
     options HEARTBEAT
     options HEARTBEAT_MAX_PERIOD_DEFAULT=15

     #include <sys/heartbeat.h>

     void
     heartbeat_start(void);

     void
     heartbeat(void);

     void
     heartbeat_suspend(void);

     void
     heartbeat_resume(void);

     #ifdef DDB

     void
     heartbeat_dump(void);

     #endif

DESCRIPTION
     The heartbeat subsystem verifies that soft interrupts (softint(9)) and
     the system timecounter(9) are making progress over time, and panics if
     they appear stuck.

     The number of seconds before heartbeat panics without progress is
     controlled by the sysctl knob kern.heartbeat.max_period, which defaults
     to 15.  If set to zero, heartbeat checks are disabled.

     The periodic hardware timer interrupt handler calls heartbeat() every
     tick on each CPU.  Once per second (i.e., every hz(9) ticks), heartbeat()
     schedules a soft interrupt at priority SOFTINT_CLOCK to advance the
     current CPU's view of time_uptime(9).

     heartbeat() checks whether time_uptime(9) has changed, to see if either
     the timecounter(9) or soft interrupts on the current CPU are stuck.  If
     it hasn't advanced within 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 kern.heartbeat.max_period seconds, then heartbeat()
     panics.

     heartbeat() also checks whether the next online CPU has advanced its view
     of time_uptime(9), to see if soft interrupts (including callout(9)) on
     that CPU are stuck.  If it hasn't updated within
     kern.heartbeat.max_period seconds, heartbeat() sends an ipi(9) to panic
     on that CPU.  If that CPU has not acknowledged the ipi(9) within one
     second, heartbeat() panics on the current CPU instead.

FUNCTIONS
     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.

                       Called by hardclock(9) periodically.

     heartbeat_dump()  Print each CPU's heartbeat counter, uptime cache, and
                       uptime cache timestamp (in units of heartbeats) to the
                       console.

                       Can be invoked from ddb(9) by `call heartbeat_dump'.

     heartbeat_resume()
                       Resume heartbeat monitoring of the current CPU.

                       Called after a CPU has started running but before it
                       has been marked online.

     heartbeat_start()
                       Start monitoring heartbeats systemwide.

                       Called by main() in sys/kern/init_main.c as soon as
                       soft interrupts can be established.

     heartbeat_suspend()
                       Suspend heartbeat monitoring of the current CPU.

                       Called after the current CPU has been marked offline
                       but before it has stopped running.

CODE REFERENCES
     The heartbeat subsystem is implemented in sys/kern/kern_heartbeat.c.

SEE ALSO
     swwdog(4), wdogctl(8)

HISTORY
     The heartbeat subsystem first appeared in NetBSD 11.0.

NetBSD 11.99                     July 6, 2023                     NetBSD 11.99