[Midnightbsd-cvs] src: watchdog.4: update man page for watchdog(4)

laffer1 at midnightbsd.org laffer1 at midnightbsd.org
Sun Mar 29 12:18:10 EDT 2009


Log Message:
-----------
update man page for watchdog(4)

Modified Files:
--------------
    src/share/man/man4:
        watchdog.4 (r1.1.1.1 -> r1.2)

-------------- next part --------------
Index: watchdog.4
===================================================================
RCS file: /home/cvs/src/share/man/man4/watchdog.4,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -L share/man/man4/watchdog.4 -L share/man/man4/watchdog.4 -u -r1.1.1.1 -r1.2
--- share/man/man4/watchdog.4
+++ share/man/man4/watchdog.4
@@ -23,7 +23,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $FreeBSD: src/share/man/man4/watchdog.4,v 1.6 2004/06/19 21:17:07 smkelly Exp $
+.\" $FreeBSD: src/share/man/man4/watchdog.4,v 1.9 2007/03/29 10:11:22 des Exp $
 .\"
 .Dd June 25, 2003
 .Dt WATCHDOG 4
@@ -32,55 +32,96 @@
 .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 named
-.Qq Li /dev/
-.Dv _PATH_WATCHDOG
-which responds to a single
+.Pa /dev/fido
+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.
+.El
 .Sh EXAMPLES
-.\" XXX insert some descriptive text here
 .Bd -literal -offset indent
-u_int u = WD_ACTIVE | WD_TO_8SEC;
-int fd = open("/dev/" _PATH_WATCHDOG, 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
@@ -89,14 +130,17 @@
 .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 at 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 at FreeBSD.org .
 Some contributions were made by
 .An Jeff Roberson Aq jeff at FreeBSD.org .


More information about the Midnightbsd-cvs mailing list