NOTES for Watchdog

Date: 2015-02-01

On OpenWrt, the watchdog binary (/sbin/watchdog) and device (/dev/watchdog) are not well documented. After some searching I was able to at least find a paper on the theory. These notes should help implementors understand the system, because the use of the watchdog has fair documentation, but the actual mechanism and understanding has to be derived from scant documenation.

First, this video should help you understand the watchdog timer, even though it is NOT part of the Linux side of the Yún.

Tutorial: Using the Arduino Watchdog Timer (10:30)
https://www.youtube.com/watch?v=BDsu8YhYn8g

Next, /sbin/watchdog is part of Busybox, which has limited functionality. Below is the reference section from documentation.

watchdog watchdog [-t N[ms]] [-T N[ms]] [-F] DEV Periodically write to watchdog device DEV Options: -T N Reboot after N seconds if not reset (default 60) -t N Reset every N seconds (default 30) -F Run in foreground Use 500ms to specify period in milliseconds

After that - to get the theory, we have to look at the busy box source code (aka watchdog.c)1. In the function watchdog_shutdown(), is the hint we need to find our explaination. In the comments it says, /* Magic, see watchdog-api.txt in kernel */. Of course, we google for that string2. And of course we find our answer.

Quoting from the paper:

The Linux watchdog API is a rather ad-hoc construction and different drivers implement different, and sometimes incompatible, parts of it. This file is an attempt to document the existing usage and allow future driver writers to use it as a reference.

Looking back at the Busybox code for watchdog, we see all it does is ping /dev/watchdog every few seconds. However, it's not clear what reads it. It must be presumed that the kernel is actually watching /dev/watchdog and will take action, and the binary /sbin/watchdog is the pinger.

On that there are two (2) kernel modules available:

  1. kmod-softdog
  2. kmod-wdt-ath79

So how hotplug figures into this is NOT documented! It's in the configuration file (for hotplug), but it does not say what it is for.

So I had to know. So, I killed the daemon. Nothing happened. No reboot.

  1. Google: busybox watchdog.c
  2. Google: watchdog-api.txt
  3. For libbb.h See: https://git.busybox.net/busybox/plain/include/libbb.h?h=1_6_stable