Last edited 4 years ago

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[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]

Watchdog overview.png

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. 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. 2.0 2.1 kernel.org watchdog user api
  3. kernel.org watchdog user api
  4. user example
  5. busybox commands
  6. systemd watchdog configuration