HEARTBEAT(9)

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.

July 6, 2023 | NetBSD 11.0