doc: Add blurb on bundled vs external watchdog, handover and reset
@@ -24,6 +24,7 @@ Configuration
* [Limitations](#limitations)
* [/etc/finit.conf](#etcfinitconf)
* [/etc/finit.d](#etcfinitd)
+* [Watchdog](#watchdog)
Introduction
@@ -438,6 +439,8 @@ you will block Finit.
> **Note:** only read and executed in runlevel S (bootstrap).
+[run-parts(8)]: http://manpages.debian.org/cgi-bin/man.cgi?query=run-parts
+
### Including Finit Configs
@@ -597,8 +600,40 @@ There is, however, nothing preventing you from having all configuration
settings in `/etc/finit.conf`.
> **Note:** The `/etc/finit.d` directory was previously the default
-> Finit `runparts` directory. Finit no longer has a default
-> `runparts`, make sure to update your setup, or the finit
-> configuration, accordingly.
+> Finit [runparts](#run-parts-scripts) directory. Finit no
+> longer has a default `runparts`, make sure to update your
+> setup, or the finit configuration, accordingly.
+
+
+Watchdog
+--------
+
+When built `--with-watchdog` a separate service is built and installed
+in `/libexec/finit/watchdogd`. If this exists at runtime, Finit will
+start it and treat it as the elected watchdog service to delegate its
+reboot to. This delegation is to ensure that the system is rebooted by
+a hardware watchdog timer -- on many embedded systems this is crucial to
+ensure all circuits on the board are properly reset for the next boot,
+in effect ensuring the system works the same after both a power-on and
+reboot event.
+
+The delegation is performed at the very last steps of system shutdown,
+if reboot has been selected and an elected watchdog is known, first a
+`SIGPWR` is sent to advise watchdogd of the pending reboot. Then, when
+the necessary steps of preparing the system for shutdown (umount etc.)
+are completed, Finit sends `SIGTERM` to watchdogd and puts itself in a
+10 sec timeout loop waiting for the WDT to reset the board. If a reset
+is not done before the timeout, Finit falls back to`reboot(RB_AUTOBOOT)`
+which tells the kernel to do the reboot.
+
+An external watchdog service can also be used. The more advanced cousin
+[watchdogd](https://github.com/troglobit/watchdogd/) is the recommended
+option here. It can register itself with Finit using the same IPC as
+`initctl`. If the bundled watchdogd is running a hand-over takes place,
+so it's safe to have both services installed on a system. For the
+hand-over to work it requires that the WDT driver supports the safe exit
+functionality where `"V"` is written to the device before closing the
+device descriptor. If the kernel driver has been built without this,
+the only option is to remove `/libexec/finit/watchdogd` or build without
+it at configure time.
-[run-parts(8)]: http://manpages.debian.org/cgi-bin/man.cgi?query=run-parts
