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.

HISTORY

The heartbeat subsystem first appeared in NetBSD 11.0.