This article provides information on the Linux® WDT (Watchdog Timer) framework.
It explains how to activate the WDT interface and, based on examples, how to use it.
1. Framework purpose[edit source]
A Watchdog Timer is a hardware circuit that can reset the computer system in case of a software fault (for example, when the software is blocked in an infinity loop and cannot reload the timer before an elapsed time).
2. System overview[edit source]
2.1. Component description[edit source]
From client application to hardware, the components are the following:
- Application (User Space): an application that configures and regularly pings the char device[1].
- User Space interface: composed of a standard char device[1].
- Watchdog framework (Kernel Space): this component provides a watchdog common interface [2](through a char device) to configure and control a watchdog hardware block.
- User driver (Kernel Space): Linux kernel drivers that handle internal peripherals or external devices under watchdog core[3].
- STM32 peripherals (Hardware): Hardware block for watchdog handling (IWDT).
2.2. API description[edit source]
A userspace daemon notifies the kernel watchdog driver that the userspace is still alive at regular intervals. This is done via the char device[1] special device file ((/dev/watchdog). When such a notification occurs, the driver tells the hardware watchdog that everything is in order, and that the watchdog must wait a little more to reset the system. If the userspace fails (because of a RAM error or a kernel bug), the notifications stop and the hardware watchdog resets the system after the timeout occurs, thus causing a reboot.
3. Configuration[edit source]
3.1. Kernel configuration[edit source]
By default, the Watchdog Timer (WDT[2]) framework is activated in STMicroelectronics deliveries. If a specific configuration is needed, this section indicates how the WDT framework can be activated/inactivated in the kernel.
The WDT framework can be activated in the kernel configuration via Linux® Menuconfig tool. Follow the steps below to configure the kernel via Menuconfig:
[*] Watchdog Timer Support --->
[*] Disable watchdog shutdown on close
[*] Update boot-enabled watchdog until userspace takes over
<*> STM32 Independent WatchDoG (IWDG) support
3.2. Device tree configuration[edit source]
DT configuration can be done thanks to STM32CubeMX.
Please refer to the IWDG device tree configuration.
4. How to use the Watchdog framework[edit source]
The Watchdog framework can be used by the userspace application:
- The kernel provides a simple code example[4]
- Busybox provides a watchdog daemon[5]
- Systemd provides a watchdog support[6]
5. How to trace and debug the framework[edit source]
5.1. How to trace[edit source]
For details on dynamic trace usage, refer to How to use the kernel dynamic debug.
echo "file drivers/watchdog/* +p" > /sys/kernel/debug/dynamic_debug/control
6. Source code location[edit source]
7. References[edit source]
- ↑ 1.0 1.1 1.2 character device interface, Linux Kernel and Driver Development training document, see Character drivers and Kernel frameworks for device drivers chapter
- ↑ 2.0 2.1 kernel.org watchdog user api
- ↑ kernel.org watchdog kernel api
- ↑ user example
- ↑ busybox commands
- ↑ systemd watchdog configuration