Watchdog overview

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

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

2.1. Component description

From client application to hardware, the components are the following:

• Application (User Space): an application that configures and regularly pings the char device.
• User Space interface: composed of a standard char device.
• Watchdog framework (Kernel Space): this component provides a watchdog common interface (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.
• STM32 peripherals (Hardware): Hardware block for watchdog handling (IWDT).

2.2. API description

A userspace daemon notifies the kernel watchdog driver that the userspace is still alive at regular intervals. This is done via the char device 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

3.1. Kernel configuration

By default, the Watchdog Timer (WDT) 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

DT configuration can be done thanks to STM32CubeMX.

Please refer to the IWDG device tree configuration.

4. How to use the Watchdog framework

The Watchdog framework can be used by the userspace application:

• The kernel provides a simple code example
• Busybox provides a watchdog daemon
• Systemd provides a watchdog support

5. How to trace and debug the framework

5.1. How to trace

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

• WatchdogAPI core
• WatchdogAPI interface
• stm32 iwdg drivers

Linux^® is a registered trademark of Linus Torvalds.

Application programming interface

Random Access Memory (Early computer memories generally hadserial access. Memories where any given address can be accessed when desired were then called "random access" to distinguish them from the memories where contents can only be accessed in a fixed order. The term is used today for volatile random-acces ssemiconductor memories.)

Independent Watchdog

Device Tree

Linux^® is a registered trademark of Linus Torvalds.

Application programming interface

Random Access Memory (Early computer memories generally hadserial access. Memories where any given address can be accessed when desired were then called "random access" to distinguish them from the memories where contents can only be accessed in a fixed order. The term is used today for volatile random-acces ssemiconductor memories.)

Independent Watchdog

Device Tree