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