1Last reviewed: 10/05/2007
2
3
4The Linux Watchdog driver API.
5
6Copyright 2002 Christer Weingel <wingel@nano-system.com>
7
8Some parts of this document are copied verbatim from the sbc60xxwdt
9driver which is (c) Copyright 2000 Jakob Oestergaard <jakob@ostenfeld.dk>
10
11This document describes the state of the Linux 2.4.18 kernel.
12
13Introduction:
14
15A Watchdog Timer (WDT) is a hardware circuit that can reset the
16computer system in case of a software fault.  You probably knew that
17already.
18
19Usually a userspace daemon will notify the kernel watchdog driver via the
20/dev/watchdog special device file that userspace is still alive, at
21regular intervals.  When such a notification occurs, the driver will
22usually tell the hardware watchdog that everything is in order, and
23that the watchdog should wait for yet another little while to reset
24the system.  If userspace fails (RAM error, kernel bug, whatever), the
25notifications cease to occur, and the hardware watchdog will reset the
26system (causing a reboot) after the timeout occurs.
27
28The Linux watchdog API is a rather ad-hoc construction and different
29drivers implement different, and sometimes incompatible, parts of it.
30This file is an attempt to document the existing usage and allow
31future driver writers to use it as a reference.
32
33The simplest API:
34
35All drivers support the basic mode of operation, where the watchdog
36activates as soon as /dev/watchdog is opened and will reboot unless
37the watchdog is pinged within a certain time, this time is called the
38timeout or margin.  The simplest way to ping the watchdog is to write
39some data to the device.  So a very simple watchdog daemon would look
40like this source file:  see Documentation/watchdog/src/watchdog-simple.c
41
42A more advanced driver could for example check that a HTTP server is
43still responding before doing the write call to ping the watchdog.
44
45When the device is closed, the watchdog is disabled, unless the "Magic
46Close" feature is supported (see below).  This is not always such a
47good idea, since if there is a bug in the watchdog daemon and it
48crashes the system will not reboot.  Because of this, some of the
49drivers support the configuration option "Disable watchdog shutdown on
50close", CONFIG_WATCHDOG_NOWAYOUT.  If it is set to Y when compiling
51the kernel, there is no way of disabling the watchdog once it has been
52started.  So, if the watchdog daemon crashes, the system will reboot
53after the timeout has passed. Watchdog devices also usually support
54the nowayout module parameter so that this option can be controlled at
55runtime.
56
57Magic Close feature:
58
59If a driver supports "Magic Close", the driver will not disable the
60watchdog unless a specific magic character 'V' has been sent to
61/dev/watchdog just before closing the file.  If the userspace daemon
62closes the file without sending this special character, the driver
63will assume that the daemon (and userspace in general) died, and will
64stop pinging the watchdog without disabling it first.  This will then
65cause a reboot if the watchdog is not re-opened in sufficient time.
66
67The ioctl API:
68
69All conforming drivers also support an ioctl API.
70
71Pinging the watchdog using an ioctl:
72
73All drivers that have an ioctl interface support at least one ioctl,
74KEEPALIVE.  This ioctl does exactly the same thing as a write to the
75watchdog device, so the main loop in the above program could be
76replaced with:
77
78	while (1) {
79		ioctl(fd, WDIOC_KEEPALIVE, 0);
80		sleep(10);
81	}
82
83the argument to the ioctl is ignored.
84
85Setting and getting the timeout:
86
87For some drivers it is possible to modify the watchdog timeout on the
88fly with the SETTIMEOUT ioctl, those drivers have the WDIOF_SETTIMEOUT
89flag set in their option field.  The argument is an integer
90representing the timeout in seconds.  The driver returns the real
91timeout used in the same variable, and this timeout might differ from
92the requested one due to limitation of the hardware.
93
94    int timeout = 45;
95    ioctl(fd, WDIOC_SETTIMEOUT, &timeout);
96    printf("The timeout was set to %d seconds\n", timeout);
97
98This example might actually print "The timeout was set to 60 seconds"
99if the device has a granularity of minutes for its timeout.
100
101Starting with the Linux 2.4.18 kernel, it is possible to query the
102current timeout using the GETTIMEOUT ioctl.
103
104    ioctl(fd, WDIOC_GETTIMEOUT, &timeout);
105    printf("The timeout was is %d seconds\n", timeout);
106
107Pretimeouts:
108
109Some watchdog timers can be set to have a trigger go off before the
110actual time they will reset the system.  This can be done with an NMI,
111interrupt, or other mechanism.  This allows Linux to record useful
112information (like panic information and kernel coredumps) before it
113resets.
114
115    pretimeout = 10;
116    ioctl(fd, WDIOC_SETPRETIMEOUT, &pretimeout);
117
118Note that the pretimeout is the number of seconds before the time
119when the timeout will go off.  It is not the number of seconds until
120the pretimeout.  So, for instance, if you set the timeout to 60 seconds
121and the pretimeout to 10 seconds, the pretimeout will go off in 50
122seconds.  Setting a pretimeout to zero disables it.
123
124There is also a get function for getting the pretimeout:
125
126    ioctl(fd, WDIOC_GETPRETIMEOUT, &timeout);
127    printf("The pretimeout was is %d seconds\n", timeout);
128
129Not all watchdog drivers will support a pretimeout.
130
131Get the number of seconds before reboot:
132
133Some watchdog drivers have the ability to report the remaining time
134before the system will reboot. The WDIOC_GETTIMELEFT is the ioctl
135that returns the number of seconds before reboot.
136
137    ioctl(fd, WDIOC_GETTIMELEFT, &timeleft);
138    printf("The timeout was is %d seconds\n", timeleft);
139
140Environmental monitoring:
141
142All watchdog drivers are required return more information about the system,
143some do temperature, fan and power level monitoring, some can tell you
144the reason for the last reboot of the system.  The GETSUPPORT ioctl is
145available to ask what the device can do:
146
147	struct watchdog_info ident;
148	ioctl(fd, WDIOC_GETSUPPORT, &ident);
149
150the fields returned in the ident struct are:
151
152        identity		a string identifying the watchdog driver
153	firmware_version	the firmware version of the card if available
154	options			a flags describing what the device supports
155
156the options field can have the following bits set, and describes what
157kind of information that the GET_STATUS and GET_BOOT_STATUS ioctls can
158return.   [FIXME -- Is this correct?]
159
160	WDIOF_OVERHEAT		Reset due to CPU overheat
161
162The machine was last rebooted by the watchdog because the thermal limit was
163exceeded
164
165	WDIOF_FANFAULT		Fan failed
166
167A system fan monitored by the watchdog card has failed
168
169	WDIOF_EXTERN1		External relay 1
170
171External monitoring relay/source 1 was triggered. Controllers intended for
172real world applications include external monitoring pins that will trigger
173a reset.
174
175	WDIOF_EXTERN2		External relay 2
176
177External monitoring relay/source 2 was triggered
178
179	WDIOF_POWERUNDER	Power bad/power fault
180
181The machine is showing an undervoltage status
182
183	WDIOF_CARDRESET		Card previously reset the CPU
184
185The last reboot was caused by the watchdog card
186
187	WDIOF_POWEROVER		Power over voltage
188
189The machine is showing an overvoltage status. Note that if one level is
190under and one over both bits will be set - this may seem odd but makes
191sense.
192
193	WDIOF_KEEPALIVEPING	Keep alive ping reply
194
195The watchdog saw a keepalive ping since it was last queried.
196
197	WDIOF_SETTIMEOUT	Can set/get the timeout
198
199The watchdog can do pretimeouts.
200
201	WDIOF_PRETIMEOUT	Pretimeout (in seconds), get/set
202
203
204For those drivers that return any bits set in the option field, the
205GETSTATUS and GETBOOTSTATUS ioctls can be used to ask for the current
206status, and the status at the last reboot, respectively.  
207
208    int flags;
209    ioctl(fd, WDIOC_GETSTATUS, &flags);
210
211    or
212
213    ioctl(fd, WDIOC_GETBOOTSTATUS, &flags);
214
215Note that not all devices support these two calls, and some only
216support the GETBOOTSTATUS call.
217
218Some drivers can measure the temperature using the GETTEMP ioctl.  The
219returned value is the temperature in degrees fahrenheit.
220
221    int temperature;
222    ioctl(fd, WDIOC_GETTEMP, &temperature);
223
224Finally the SETOPTIONS ioctl can be used to control some aspects of
225the cards operation.
226
227    int options = 0;
228    ioctl(fd, WDIOC_SETOPTIONS, &options);
229
230The following options are available:
231
232	WDIOS_DISABLECARD	Turn off the watchdog timer
233	WDIOS_ENABLECARD	Turn on the watchdog timer
234	WDIOS_TEMPPANIC		Kernel panic on temperature trip
235
236[FIXME -- better explanations]
237
238