1 General
- 1.1 Command line interface
- 1.2 Initialization script
- 1.3 Signal handling
2 Northbound API
3 Southbound API
4 Requirements

General

A proxy watchdog daemon to monitor heartbeats of registered services and take appropriate actions in case of emergency

A system can become unresponsive for many unforeseen reasons in the field. The "Platform Watchdog" feature of OpenSync provides a proxy between a HW watchdog timer (WDT) and OpenSync (OS). It provides a Watchdog Proxy Daemon (WPD) with the purpose of stimulating the hardware Watchdog Timer (WDT) while ensuring that the upper layers (OS) remain sufficiently responsive. In case of system anomalies, if the WPD fails to refresh and the hardware Watchdog Timer (WDT) expires, the WDT chip intervenes by resetting the system. Upper layer (OS) is responsible for providing the daemon with information affirming that everything is functioning correctly, prompting the daemon to continue refreshing the WDT.

Command line interface

WPD is implemented as an executable binary located at /usr/opensync/bin/wpd, providing the following interface:

wpd - Watchdog Proxy Daemon

Usage:
  wpd -d, --daemon
  wpd -a, --set-auto
  wpd -n, --set-noauto
  wpd -p, --ping
  wpd -k, --kill
  wpd -v, --verbose
  wpd -x, --proc-name proc name
  wpd -h, --help

Typically, WPD operates as a daemon in non-autonomous mode, meaning that it requires regular stimulation every few seconds (e.g., every 5 seconds). Stimulation is carried out by executing the command wpd --ping .
The --set-auto option is employed to run the daemon in autonomous mode, reserved for specific system operation modes (e.g., manufacturing), where the application is not running, and WPD does not require external stimulation as it automatically refreshes the hardware Watchdog Timer (WDT).

Initialization script

By default, WPD supports a SystemV init script, which is provided in file /etc/init.d/wpd and is universally applicable to both OpenWrt-based systems and other SystemV systems. However, SystemD is currently not supported.

Signal handling

Internal signals:
SIGUSR1 - wpd set mode to autonomous
SIGUSR2 - wpd set mode to non-autonomous
SIGHUP - wpd to ping WD when in non-autonomous mode
SIGINT - kill wpd

If executed as --daemon, it will write it's own PID number to /var/run/wpd.pid, fork(), and run according to non-autonomous mode, waiting for signals to change mode of operation or to ping the watchdog.

If executed to change mode of operation or to ping the WDT, it will send a signal to the process with the PID from the PID file.

Northbound API

No northbound API.

Southbound API

CM in OpenSync calls function bool target_device_wdt_ping(void) which is provided in core and its purpose is to inform WPD that system is functioning correctly. If this function is not called every few seconds, the watchdog timer (WDT) will expire, triggering a hardware reset.

Requirements

WPD requires:

HW WDT chip
Kernel support for WDT providing a /dev/watchdog device to userspace
The watchdog device /dev/watchdog should be closed before starting WPD, allowing WPD to open the watchdog device by itself.
All default Linux watchdog daemons using /dev/watchdog, such as wdctl, should be stopped and are mutually exclusive with WPD.