WATCHDOG(4)

📦
version 15.1 · 3 versions
, in freebsd 15.1, nixpkgs unstable

💅 WATCHDOG(4) — bestie's guide to the hardware + software watchdog 🐶✨

okay so this is watchdog(4), from the Kernel Interfaces Manual, and it is literally the page you want if you've ever needed a thing that goes "hey. hey. you still alive?" to your kernel. it's giving guardian angel but make it a timer 🫶

✨ NAME ✨

watchdog — hardware and software watchdog 💖

🌸 SYNOPSIS 🌸

#include <sys/watchdog.h>

🎀 DESCRIPTION 🎀

so the watchdog facility is the whole system for controlling hardware and software watchdogs. that's the vibe, that's the whole point 🐕

the device /dev/fido supports several optional ioctl(2) calls for configuration, and it responds to one operational ioctl(2) call, WDIOCPATPAT. that call takes a single argument — a timeout value specified as a power of two nanoseconds, or-ed with a flag that picks active or passive control of the watchdog. yes bestie, the timeout is in powers of two nanoseconds, do not question it, just respect it 💅

  • WD_ACTIVE means the watchdog will be kept from timing out from userland, for instance by the watchdogd(8) daemon.
  • WD_PASSIVE means the watchdog will be kept from timing out from the kernel.

the WDIOCPATPAT ioctl(2) call returns success if just one of the available watchdog(9) implementations supports setting the timeout to the specified timeout. meaning at least one watchdog is armed, periodt 🔥 by default that'll be a hardware watchdog if one is present, but if no hardware watchdog is able to process the request, a default software watchdog is enabled. and if the call fails — for example if none of the watchdog(9) implementations support the timeout length — then all watchdogs are disabled and must be explicitly re-enabled. like, you gotta go turn them back on yourself, no auto-rescue, iykyk 😭

to disable the watchdogs, pass WD_TO_NEVER. and if disarming the watchdog(s) failed, an error is returned.

⚠️ real talk bestie: the watchdog might still be armed! do not assume it's off just because you asked nicely 🙈

the optional configuration ioctl(2) commands are listed right here, along with the type of the parameter used. examples of their use can be found in watchdogd(8) 💖

  • WDIOC_SETTIMEOUT int — set/reset the timer
  • WDIOC_GETTIMEOUT int — get total timeout
  • WDIOC_GETTIMELEFT int — get time left
  • WDIOC_GETPRETIMEOUT int — get the pre-timeout
  • WDIOC_SETPRETIMEOUT int — set the pre-timeout
  • WDIOC_SETPRETIMEOUTACT int — set the action when a pre-timeout occurs (see WD_SOFT_* below)
  • WDIOC_SETSOFT int — use an internal software watchdog instead of hardware. there's also an external software watchdog, which is used by default if no hardware watchdog was attached.
  • WDIOC_SETSOFTTIMEOUTACT int — set the action when a soft timeout occurs

and these are the actions that may be specified for the pre-timeout or the internal software watchdog 🌈 multiple actions can be specified by ORing values together, slay:

  • WD_SOFT_PANIC — panic
  • WD_SOFT_DDB — enter debugger
  • WD_SOFT_LOG — log(9)
  • WD_SOFT_PRINT — printf(9)

🦋 RETURN VALUES 🦋

the WDIOCPATPAT ioctl(2) returns zero on success and non-zero on failure ✨

  • [EOPNOTSUPP] — no watchdog present in the kernel, or none of the watchdogs supports the requested timeout value (timeout value other than 0).
  • [EOPNOTSUPP] — watchdog could not be disabled (timeout value of 0).
  • [EINVAL] — invalid flag combination passed.

the configuration ioctl(2) operations return zero on success and non-zero on failure 💅

🧚 EXAMPLES 🧚

#include <paths.h>
#include <sys/watchdog.h>

#define WDPATH  "/dev/" _PATH_WATCHDOG
int wdfd = -1;

static void
wd_init(void)
{
        wdfd = open(WDPATH, O_RDWR);
        if (wdfd == -1)
                err(1, WDPATH);
}
static void
wd_reset(u_int timeout)
{
        if (ioctl(wdfd, WDIOCPATPAT, &timeout) == -1)
                err(1, "WDIOCPATPAT");
}

/* in main() */
wd_init();
wd_reset(WD_ACTIVE|WD_TO_8SEC);
/* potential freeze point */
wd_reset(WD_TO_NEVER);

this enables a watchdog to recover from a potentially freezing piece of code 🔥 iconic behavior honestly

and then, in your kernel config:

options SW_WATCHDOG

forces a software watchdog in the kernel to be configured even if a hardware watchdog is configured, dropping to KDB or panicking when firing, depending on the KDB and KDB_UNATTENDED kernel configuration options 🌸

👑 SEE ALSO 👑

watchdogd(8), watchdog(9)

⭐ HISTORY ⭐

the watchdog code first appeared in FreeBSD 5.1 🎀

💜 AUTHORS 💜

the watchdog facility was written by Poul-Henning Kamp <phk@FreeBSD.org>. the software watchdog code and this manual page were written by Sean Kelly <smkelly@FreeBSD.org>. some contributions were made by Jeff Roberson <jeff@FreeBSD.org>. legends, all of them 🫶

💀 BUGS 💀

the WD_PASSIVE option has not yet been implemented. we wait 🕯️😭

mwah, that's the whole page bestie — brought to you by Debian, dated January 2, 2018. go keep something alive out there 💖🐶✨

📦 where this page comes from