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.Dd January 2, 2018 27.Dt WATCHDOG 4 28.Os 29.Sh NAME 30.Nm watchdog 31.Nd "hardware and software watchdog" 32.Sh SYNOPSIS 33.In sys/watchdog.h 34.Sh DESCRIPTION 35The 36.Nm 37facility is used for controlling hardware and software watchdogs. 38.Pp 39The device 40.Pa /dev/fido 41supports several optional 42.Xr ioctl 2 43calls for configuration, and 44responds to a single operational 45.Xr ioctl 2 46call, 47.Dv WDIOCPATPAT . 48It takes a single argument which represents a timeout value specified as a 49power of two nanoseconds, or-ed with a flag selecting active or passive control 50of the watchdog. 51.Pp 52.Dv WD_ACTIVE 53indicates that the 54.Nm 55will be kept from timing out from userland, for instance by the 56.Xr watchdogd 8 57daemon. 58.Dv WD_PASSIVE 59indicates that the 60.Nm 61will be kept from timing out from the kernel. 62.Pp 63The 64.Dv WDIOCPATPAT 65.Xr ioctl 2 66call will return success if just one of the available 67.Xr watchdog 9 68implementations supports setting the timeout to the specified timeout. 69This 70means that at least one watchdog is armed. 71By default, this will be a hardware watchdog if one is present, but if 72no hardware watchdog is able to process the request, a default software 73watchdog is enabled. 74If the call fails, for instance if 75none of 76.Xr watchdog 9 77implementations support the timeout length, all watchdogs are disabled and must 78be explicitly re-enabled. 79.Pp 80To disable the watchdogs pass 81.Dv WD_TO_NEVER . 82If disarming the watchdog(s) failed an error is returned. 83The watchdog might 84still be armed! 85.Pp 86The optional configuration 87.Xr ioctl 2 88commands are listed here, along with the type of the parameter used. 89Examples of their use can be found in 90.Xr watchdogd 8 . 91.Bl -tag -width "WDIOC_SETSOFTTIMEOUTACT int " 92.It Dv WDIOC_SETTIMEOUT Fa int 93set/reset the timer 94.It Dv WDIOC_GETTIMEOUT Fa int 95get total timeout 96.It Dv WDIOC_GETTIMELEFT Fa int 97get time left 98.It Dv WDIOC_GETPRETIMEOUT Fa int 99get the pre-timeout 100.It Dv WDIOC_SETPRETIMEOUT Fa int 101set the pre-timeout 102.It Dv WDIOC_SETPRETIMEOUTACT Fa int 103Set the action when a pre-timeout occurs (see 104.Li WD_SOFT_* 105below). 106.It Dv WDIOC_SETSOFT Fa int 107Use an internal software watchdog instead of hardware. 108There is also an external software watchdog, which is used by default 109if no hardware watchdog was attached. 110.It Dv WDIOC_SETSOFTTIMEOUTACT Fa int 111Set the action when a soft timeout occurs. 112.El 113.Pp 114The actions that may be specified for the pre-timeout or the internal software 115watchdog are listed here. 116Multiple actions can be specified by ORing values together. 117.Bl -tag -width WD_SOFT_PRINT 118.It Dv WD_SOFT_PANIC 119panic 120.It Dv WD_SOFT_DDB 121enter debugger 122.It Dv WD_SOFT_LOG 123log(9) 124.It Dv WD_SOFT_PRINT 125printf(9) 126.El 127.Sh RETURN VALUES 128The 129.Dv WDIOCPATPAT 130.Xr ioctl 2 131returns zero on success and non-zero on failure. 132.Bl -tag -width Er 133.It Bq Er EOPNOTSUPP 134No watchdog present in the kernel or 135none of the watchdogs supports the requested timeout value 136(timeout value other than 0). 137.It Bq Er EOPNOTSUPP 138Watchdog could not be disabled (timeout value of 0). 139.It Bq Er EINVAL 140Invalid flag combination passed. 141.El 142.Pp 143The configuration 144.Xr ioctl 2 145operations return zero on success and non-zero on failure. 146.Sh EXAMPLES 147.Bd -literal -offset indent 148#include <paths.h> 149#include <sys/watchdog.h> 150 151#define WDPATH "/dev/" _PATH_WATCHDOG 152int wdfd = -1; 153 154static void 155wd_init(void) 156{ 157 wdfd = open(WDPATH, O_RDWR); 158 if (wdfd == -1) 159 err(1, WDPATH); 160} 161static void 162wd_reset(u_int timeout) 163{ 164 if (ioctl(wdfd, WDIOCPATPAT, &timeout) == -1) 165 err(1, "WDIOCPATPAT"); 166} 167 168/* in main() */ 169wd_init(); 170wd_reset(WD_ACTIVE|WD_TO_8SEC); 171/* potential freeze point */ 172wd_reset(WD_TO_NEVER); 173.Ed 174.Pp 175Enables a watchdog to recover from a potentially freezing piece of code. 176.Pp 177.Dl "options SW_WATCHDOG" 178.Pp 179in your kernel config forces a software watchdog in the kernel 180to be configured even if a hardware watchdog is configured, 181dropping to KDB or panicking when firing, depending 182on the KDB and KDB_UNATTENDED kernel configuration options. 183.Sh SEE ALSO 184.Xr watchdogd 8 , 185.Xr watchdog 9 186.Sh HISTORY 187The 188.Nm 189code first appeared in 190.Fx 5.1 . 191.Sh AUTHORS 192.An -nosplit 193The 194.Nm 195facility was written by 196.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org . 197The software watchdog code and this manual page were written by 198.An Sean Kelly Aq Mt smkelly@FreeBSD.org . 199Some contributions were made by 200.An Jeff Roberson Aq Mt jeff@FreeBSD.org . 201.Sh BUGS 202The 203.Dv WD_PASSIVE 204option has not yet been implemented. 205