Add a new page about hardware watchdog devices, under a BSD license.

From:  Michael Knudsen

ok various

2 files changed, 84 insertions, 3 deletions

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index cff09fc4cea..a94076d0498 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.282 2004/12/01 01:29:37 pvalchev Exp $
+#	$OpenBSD: Makefile,v 1.283 2004/12/17 00:28:30 jaredy Exp $
 
 MAN=	aac.4 ac97.4 acphy.4 addcom.4 adv.4 aha.4 ahb.4 ahc.4 ahd.4 \
 	aic.4 amdpm.4 ami.4 amphy.4 an.4 aria.4 ast.4 atalk.4 \
@@ -34,8 +34,8 @@ MAN=	aac.4 ac97.4 acphy.4 addcom.4 adv.4 aha.4 ahb.4 ahc.4 ahd.4 \
 	ukphy.4 ulpt.4 umass.4 umct.4 umidi.4 umodem.4 ums.4 \
 	unix.4 upl.4 uplcom.4 urio.4 url.4 urlphy.4 usb.4 \
 	uscanner.4 usscanner.4 uvisor.4 uvscom.4 uyap.4 vga.4 vge.4 \
-	viaenv.4 vlan.4 vnd.4 vr.4 wb.4 wd.4 wdc.4 we.4 wi.4tbl \
-	wscons.4 wsdisplay.4 wskbd.4 wsmouse.4 wsmux.4 xe.4 \
+	viaenv.4 vlan.4 vnd.4 vr.4 watchdog.4 wb.4 wd.4 wdc.4 we.4 \
+	wi.4tbl wscons.4 wsdisplay.4 wskbd.4 wsmouse.4 wsmux.4 xe.4 \
 	xf86.4 xl.4 xmphy.4 yds.4 ym.4 zero.4
 
 
diff --git a/share/man/man4/watchdog.4 b/share/man/man4/watchdog.4
new file mode 100644
index 00000000000..fc4d6ed6670
--- /dev/null
+++ b/share/man/man4/watchdog.4
@@ -0,0 +1,81 @@
+.\"	$OpenBSD: watchdog.4,v 1.1 2004/12/17 00:28:31 jaredy Exp $
+.\"
+.\" Copyright (c) 2004 Michael Knudsen <mk@molioner.dk>
+.\" 
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\" 
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.Dd December 16, 2004
+.Dt WATCHDOG 4
+.Os
+.Sh NAME
+.Nm watchdog
+.Nd hardware timers/counters for quick crash recovery
+.Sh DESCRIPTION
+Hardware watchdog timers are devices that reboot the machine when it
+hangs.
+The kernel continually resets the watchdog clock on a regular basis.
+Thus, if the kernel halts, the clock will time out and reset the machine.
+Some watchdog timers may be configured to be reset from userland,
+causing a reboot if process scheduling fails.
+.Pp
+A few watchdog drivers are supported, and most support timeout
+configuration via
+.Xr sysctl 8
+under the
+.Va kern.watchdog
+name:
+.Bl -tag -width kern.watchdog.period -offset indent
+.It Va kern.watchdog.auto
+Automatically reset
+.Pq Sq tickle
+the watchdog timer.
+.It Va kern.watchdog.period
+The timeout in seconds.
+Setting it to zero disables the watchdog timer.
+.El
+.Pp
+In situations where the machine provides vital services which are not
+handled completely in kernel space, e.g. mail exchange, it may be
+desirable to reboot the machine if process scheduling fails.
+This is done by setting
+.Va kern.watchdog.auto
+to zero and running a process which repeatedly sets
+.Va kern.watchdog.period
+to the desired timeout value.
+Then, if process scheduling fails, the process resetting the timer will
+not be run, leading to the machine being rebooted.
+.Pp
+Watchdog timers should be used in high-availability environments where
+getting machines up and running quickly after a crash is more important
+than determining the cause of the crash.
+A watchdog timer enables a crashed machine to autonomously attempt to
+recover quickly after a system failure.
+.Pp
+Note that this also means that it is unwise to combine watchdog timers
+with
+.Xr ddb 4
+since the latter may prevent the former from resetting the
+watchdog timeout before it expires.
+This means that the machine will be rebooted before any debugging
+can be done.
+.Sh SEE ALSO
+.Xr ddb 4 ,
+.Xr elansc 4 ,
+.Xr geodesc 4 ,
+.Xr wdt 4 ,
+.Xr config 8 ,
+.Xr sysctl 8
+.Sh BUGS
+For systems with multiple watchdog timers available, only a single
+one can be used at a time.
+There is currently no way of selecting which device is used; the first
+discovered by the kernel is selected.