xref: /freebsd/share/man/man4/watchdog.4 (revision 39beb93c3f8bdbf72a61fda42300b5ebed7390c8)
1.\" Copyright (c) 2004 Poul-Henning Kamp <phk@FreeBSD.org>
2.\" Copyright (c) 2003, 2004 Sean M. Kelly <smkelly@FreeBSD.org>
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
26.\" $FreeBSD$
27.\"
28.Dd June 25, 2003
29.Dt WATCHDOG 4
30.Os
31.Sh NAME
32.Nm watchdog
33.Nd "hardware and software watchdog"
34.Sh SYNOPSIS
35.In sys/watchdog.h
36.Sh DESCRIPTION
37The
38.Nm
39facility is used for controlling hardware and software watchdogs.
40.Pp
41.Pa /dev/fido
42responds to a single
43.Xr ioctl 2
44call,
45.Dv WDIOCPATPAT .
46It takes a single argument which represents a timeout value specified as a
47power of two nanoseconds, or-ed with a flag selecting active or passive control
48of the watchdog.
49.Pp
50.Dv WD_ACTIVE
51indicates that the
52.Nm
53will be kept from timing out from userland, for instance by the
54.Xr watchdogd 8
55daemon.
56.Dv WD_PASSIVE
57indicates that the
58.Nm
59will be kept from timing out from the kernel.
60.Pp
61The
62.Xr ioctl 2
63call will return success if just one of the available
64.Xr watchdog 9
65implementations supports setting the timeout to the specified timeout. This
66means that at least one watchdog is armed. If the call fails, for instance if
67none of
68.Xr watchdog 9
69implementations support the timeout length, all watchdogs are disabled and must
70be explicitly re-enabled.
71.Pp
72To disable the watchdogs pass
73.Dv WD_TO_NEVER .
74If disarming the watchdog(s) failed an error is returned. The watchdog might
75still be armed!
76.Sh RETURN VALUES
77The ioctl returns zero on success and non-zero on failure.
78.Bl -tag -width Er
79.It Bq Er EOPNOTSUPP
80No watchdog present in the kernel (timeout value other than 0).
81.It Bq Er EOPNOTSUPP
82Watchdog could not be disabled (timeout value of 0).
83.It Bq Er EINVALID
84Invalid flag combination passed.
85.It Bq Er EINVALID
86None of the watchdogs supports the requested timeout value.
87.El
88.Sh EXAMPLES
89.Bd -literal -offset indent
90#include <paths.h>
91#include <sys/watchdog.h>
92
93#define WDPATH	"/dev/" _PATH_WATCHDOG
94int wdfd = -1;
95
96static void
97wd_init(void)
98{
99	wdfd = open(WDPATH, O_RDWR);
100	if (wdfd == -1)
101		err(1, WDPATH);
102}
103static void
104wd_reset(u_int timeout)
105{
106	if (ioctl(wdfd, WDIOCPATPAT, &timeout) == -1)
107		err(1, "WDIOCPATPAT");
108}
109
110/* in main() */
111wd_init();
112wd_reset(WD_ACTIVE|WD_TO_8SEC);
113/* potential freeze point */
114wd_reset(WD_TO_NEVER);
115.Ed
116.Pp
117Enables a watchdog to recover from a potentially freezing piece of code.
118.Pp
119.Bd -literal -offset indent
120options SW_WATCHDOG
121.Ed
122.Pp
123in your kernel config adds a software watchdog in the kernel, dropping to KDB
124or panic-ing when firing.
125.Sh SEE ALSO
126.Xr watchdogd 8 ,
127.Xr watchdog 9
128.Sh HISTORY
129The
130.Nm
131code first appeared in
132.Fx 5.1 .
133.Sh BUGS
134The
135.Dv WD_PASSIVE
136option has not yet been implemented.
137.Sh AUTHORS
138.An -nosplit
139The
140.Nm
141facility was written by
142.An Poul-Henning Kamp Aq phk@FreeBSD.org .
143The software watchdog code and this manual page were written by
144.An Sean Kelly Aq smkelly@FreeBSD.org .
145Some contributions were made by
146.An Jeff Roberson Aq jeff@FreeBSD.org .
147