The Linux Watchdog driver API — The Linux Kernel documentation
The Linux Kernel
7.2.0-rc3
Quick search
Contents
Development process
Submitting patches
Code of conduct
Maintainer handbook
All development-process docs
Core API
Driver APIs
Subsystems<br>Core subsystems
Human interfaces
Networking interfaces
Storage interfaces
Other subsystems<br>Accounting
CPUFreq - CPU frequency and voltage scaling code in the Linux(TM) kernel
EDAC Subsystem
FPGA
I2C/SMBus Subsystem
Industrial I/O
PCMCIA
Serial Peripheral Interface (SPI)
1-Wire Subsystem
Watchdog Support
Virtualization Support
Hardware Monitoring
Compute Accelerators
Security Documentation
Crypto API
BPF Documentation
USB support
PCI Bus Subsystem
Assorted Miscellaneous Devices Documentation
PECI Subsystem
WMI Subsystem
TEE Subsystem
Locking
Licensing rules
Writing documentation
Development tools
Testing guide
Hacking guide
Tracing
Fault injection
Livepatching
Rust
Administration
Build system
Reporting issues
Userspace tools
Userspace API
Firmware
Firmware and Devicetree
CPU architectures
Unsorted documentation
Translations
This Page
Show Source
The Linux Watchdog driver API¶
Last reviewed: 10/05/2007
Copyright 2002 Christer Weingel wingel@nano-system.com>
Some parts of this document are copied verbatim from the sbc60xxwdt<br>driver which is (c) Copyright 2000 Jakob Oestergaard jakob@ostenfeld.dk>
This document describes the state of the Linux 2.4.18 kernel.
Introduction¶
A Watchdog Timer (WDT) is a hardware circuit that can reset the<br>computer system in case of a software fault. You probably knew that<br>already.
Usually a userspace daemon will notify the kernel watchdog driver via the<br>/dev/watchdog special device file that userspace is still alive, at<br>regular intervals. When such a notification occurs, the driver will<br>usually tell the hardware watchdog that everything is in order, and<br>that the watchdog should wait for yet another little while to reset<br>the system. If userspace fails (RAM error, kernel bug, whatever), the<br>notifications cease to occur, and the hardware watchdog will reset the<br>system (causing a reboot) after the timeout occurs.
The Linux watchdog API is a rather ad-hoc construction and different<br>drivers implement different, and sometimes incompatible, parts of it.<br>This file is an attempt to document the existing usage and allow<br>future driver writers to use it as a reference.
The simplest API¶
All drivers support the basic mode of operation, where the watchdog<br>activates as soon as /dev/watchdog is opened and will reboot unless<br>the watchdog is pinged within a certain time; this time is called the<br>timeout or margin. The simplest way to ping the watchdog is to write<br>some data to the device. So a very simple watchdog daemon would look<br>like this source file: see samples/watchdog/watchdog-simple.c
A more advanced driver could for example check that an HTTP server is<br>still responding before doing the write call to ping the watchdog.
When the device is closed, the watchdog is disabled, unless the “Magic<br>Close” feature is supported (see below). This is not always such a<br>good idea, since if there is a bug in the watchdog daemon and it<br>crashes the system will not reboot. Because of this, some of the<br>drivers support the configuration option “Disable watchdog shutdown on<br>close”, CONFIG_WATCHDOG_NOWAYOUT. If it is set to Y when compiling<br>the kernel, there is no way of disabling the watchdog once it has been<br>started. So, if the watchdog daemon crashes, the system will reboot<br>after the timeout has passed. Watchdog devices also usually support<br>the nowayout module parameter so that this option can be controlled at<br>runtime.
Magic Close feature¶
If a driver supports “Magic Close”, the driver will not disable the<br>watchdog unless a specific magic character ‘V’ has been sent to<br>/dev/watchdog just before closing the file. If the userspace daemon<br>closes the file without sending this special character, the driver<br>will assume that the daemon (and userspace in general) died, and will<br>stop pinging the watchdog without disabling it first. This will then<br>cause a reboot if the watchdog is not re-opened in sufficient time.
The ioctl API¶
All conforming drivers also support an ioctl API.
Pinging the watchdog using an ioctl:
All drivers that have an ioctl interface support at least one ioctl,<br>KEEPALIVE. This ioctl does exactly the same thing as a write to the<br>watchdog device, so the main loop in the above program could be<br>replaced with:
while (1) {<br>ioctl(fd, WDIOC_KEEPALIVE, 0);<br>sleep(10);
The argument to the ioctl is ignored.
Setting and getting the timeout¶
For some drivers it is possible to modify the watchdog timeout on the<br>fly with the SETTIMEOUT ioctl; those drivers have the WDIOF_SETTIMEOUT<br>flag set in their option field. The argument is an integer<br>representing the timeout in seconds. The driver returns the real<br>timeout used in the same variable, and this timeout might differ from<br>the requested one due...