Align the interfaces for the various watchdogs and make the interface

behave as expected.

Also:
- Return an error if WD_PASSIVE is passed in to the ioctl as only
  WD_ACTIVE is implemented at the moment. See sys/watchdog.h for an
  explanation of the difference between WD_ACTIVE and WD_PASSIVE.
- Remove the I_HAVE_TOTALLY_LOST_MY_SENSE_OF_HUMOR define. If you've
  lost your sense of humor, than don't add a define.

Specific changes:

i80321_wdog.c
  Don't roll your own passive watchdog tickle as this would defeat the
  purpose of an active (userland) watchdog tickle.

ichwd.c / ipmi.c:
  WD_ACTIVE means active patting of the watchdog by a userland process,
  not whether the watchdog is active. See sys/watchdog.h.

kern_clock.c:
  (software watchdog) Remove a check for WD_ACTIVE as this does not make
  sense here. This reverts r1.181.

3 files changed, 77 insertions, 26 deletions

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 162955b..dd5b34f 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -516,6 +516,7 @@ MLINKS+=wb.4 if_wb.4
 MLINKS+=wi.4 if_wi.4
 MLINKS+=xe.4 if_xe.4
 MLINKS+=xl.4 if_xl.4
+MLINKS+=watchdog.4 SW_WATCHDOG.4
 
 .if ${MACHINE_ARCH} == "amd64" || ${MACHINE_ARCH} == "i386"
 _acpi_dock.4=	acpi_dock.4
diff --git a/share/man/man4/watchdog.4 b/share/man/man4/watchdog.4
index a533ec8..c0887fa 100644
--- a/share/man/man4/watchdog.4
+++ b/share/man/man4/watchdog.4
@@ -32,54 +32,95 @@
 .Nm watchdog
 .Nd "hardware and software watchdog"
 .Sh SYNOPSIS
-.Cd "options CPU_ELAN"
-.Cd "options CPU_GEODE"
-.Cd "options SW_WATCHDOG"
-.Pp
 .In sys/watchdog.h
 .Sh DESCRIPTION
 The
 .Nm
 facility is used for controlling hardware and software watchdogs.
 .Pp
-The interface is through a device
 .Pa /dev/fido
-which responds to a single
+responds to a single
 .Xr ioctl 2
 call,
 .Dv WDIOCPATPAT .
+It takes a single argument which represents a timeout value specified as a
+power of two nanoseconds, or-ed with a flag selecting active or passive control
+of the watchdog.
 .Pp
-The call takes a single argument which represents a timeout value
-specified as an integer power of two nanoseconds.
-.Pp
-The
 .Dv WD_ACTIVE
-flag signals that the
+indicates that the
 .Nm
-will be kept from
-timing out from userland, for instance by the
+will be kept from timing out from userland, for instance by the
 .Xr watchdogd 8
 daemon.
-.Pp
-To disable the watchdogs, an argument of zero should be used.
+.Dv WD_PASSIVE
+indicates that the
+.Nm
+will be kept from timing out from the kernel.
 .Pp
 The
 .Xr ioctl 2
 call will return success if just one of the available
 .Xr watchdog 9
-implementations support the request.
-If the call fails, for instance if none of
+implementations supports setting the timeout to the specified timeout. This
+means that at least one watchdog is armed. If the call fails, for instance if
+none of
 .Xr watchdog 9
-implementations support the timeout
-length, all watchdogs are disabled and must be explicitly re-enabled.
+implementations support the timeout length, all watchdogs are disabled and must
+be explicitly re-enabled.
+.Pp
+To disable the watchdogs pass
+.Dv WD_TO_NEVER .
+If disarming the watchdog(s) failed an error is returned. The watchdog might
+still be armed!
+.Sh RETURN VALUES
+The ioctl returns zero on success and non-zero on failure.
+.Bl -tag -width Er
+.It Bq Er EOPNOTSUPP
+No watchdog present in the kernel (timeout value other than 0).
+.It Bq Er EOPNOTSUPP
+Watchdog could not be disabled (timeout value of 0).
+.It Bq Er EINVALID
+Invalid flag combination passed.
+.It Bq Er EINVALID
+None of the watchdogs supports the requested timeout value.
 .Sh EXAMPLES
-.\" XXX insert some descriptive text here
 .Bd -literal -offset indent
-u_int u = WD_ACTIVE | WD_TO_8SEC;
-int fd = open("/dev/fido", O_RDWR);
+#include <paths.h>
+#include <sys/watchdog.h>
+
+#define WDPATH	"/dev/" _PATH_WATCHDOG
+int wdfd = -1;
 
-ioctl(fd, WDIOCPATPAT, &u);
+static void
+wd_init(void) 
+{
+	wdfd = open(WDPATH, O_RDWR);
+	if (wdfd == -1)
+		err(1, WDPATH);
+}
+static void
+wd_reset(u_int timeout)
+{
+	if (ioctl(wdfd, WDIOCPATPAT, &timeout) == -1)
+		err(1, "WDIOCPATPAT");
+}
+
+/* in main() */
+wd_init();
+wd_reset(WD_ACTIVE|WD_TO_8SEC);
+/* potential freeze point */
+wd_reset(WD_TO_NEVER);
 .Ed
+.Pp
+Enables a watchdog to recover from a potentially freezing piece of code.
+.Pp
+.Bd -literal -offset indent
+options SW_WATCHDOG
+.Ed
+.Pp
+in your kernel config adds a software watchdog in the kernel, dropping to KDB
+or panic-ing when firing.
 .Sh SEE ALSO
 .Xr watchdogd 8 ,
 .Xr watchdog 9
@@ -88,14 +129,17 @@ The
 .Nm
 code first appeared in
 .Fx 5.1 .
+.Sh BUGS
+The
+.Dv WD_PASSIVE
+option has not yet been implemented.
 .Sh AUTHORS
 .An -nosplit
 The
 .Nm
 facility was written by
 .An Poul-Henning Kamp Aq phk@FreeBSD.org .
-The software watchdog code
-and this manual page were written by
+The software watchdog code and this manual page were written by
 .An Sean Kelly Aq smkelly@FreeBSD.org .
 Some contributions were made by
 .An Jeff Roberson Aq jeff@FreeBSD.org .
diff --git a/share/man/man9/watchdog.9 b/share/man/man9/watchdog.9
index 4c9a365..b53b0f5 100644
--- a/share/man/man9/watchdog.9
+++ b/share/man/man9/watchdog.9
@@ -35,6 +35,7 @@
 .Ft void
 .Fn watchdog_fn "void *private" "u_int cmd" "int *error"
 .Fn EVENTHANDLER_REGISTER watchdog_list watchdog_fn private 0
+.Fn EVENTHANDLER_DEREGISTER watchdog_list eventhandler_tag
 .Sh DESCRIPTION
 To implement a watchdog in software or hardware, only a single
 function needs to be written and registered on the global
@@ -60,7 +61,12 @@ argument be set to zero.
 If the watchdog cannot be configured to the proposed timeout, it
 must be disabled and the
 .Fa error
-argument left untouched.
+argument set to
+.Dv EINVAL .
+If the watchdog cannot be disabled, the
+.Fa error
+argument must be set to 
+.Dv EOPNOTSUPP .
 .Pp
 There is no specification of what the watchdog should do when it
 times out, but a hardware reset or similar