Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | The Linux Watchdog driver API. |
2 | ||
3 | Copyright 2002 Christer Weingel <wingel@nano-system.com> | |
4 | ||
5 | Some parts of this document are copied verbatim from the sbc60xxwdt | |
6 | driver which is (c) Copyright 2000 Jakob Oestergaard <jakob@ostenfeld.dk> | |
7 | ||
8 | This document describes the state of the Linux 2.4.18 kernel. | |
9 | ||
10 | Introduction: | |
11 | ||
12 | A Watchdog Timer (WDT) is a hardware circuit that can reset the | |
13 | computer system in case of a software fault. You probably knew that | |
14 | already. | |
15 | ||
16 | Usually a userspace daemon will notify the kernel watchdog driver via the | |
17 | /dev/watchdog special device file that userspace is still alive, at | |
18 | regular intervals. When such a notification occurs, the driver will | |
19 | usually tell the hardware watchdog that everything is in order, and | |
20 | that the watchdog should wait for yet another little while to reset | |
21 | the system. If userspace fails (RAM error, kernel bug, whatever), the | |
22 | notifications cease to occur, and the hardware watchdog will reset the | |
23 | system (causing a reboot) after the timeout occurs. | |
24 | ||
25 | The Linux watchdog API is a rather AD hoc construction and different | |
26 | drivers implement different, and sometimes incompatible, parts of it. | |
27 | This file is an attempt to document the existing usage and allow | |
28 | future driver writers to use it as a reference. | |
29 | ||
30 | The simplest API: | |
31 | ||
32 | All drivers support the basic mode of operation, where the watchdog | |
33 | activates as soon as /dev/watchdog is opened and will reboot unless | |
34 | the watchdog is pinged within a certain time, this time is called the | |
35 | timeout or margin. The simplest way to ping the watchdog is to write | |
36 | some data to the device. So a very simple watchdog daemon would look | |
56fb9e53 | 37 | like this source file: see Documentation/watchdog/src/watchdog-simple.c |
1da177e4 LT |
38 | |
39 | A more advanced driver could for example check that a HTTP server is | |
40 | still responding before doing the write call to ping the watchdog. | |
41 | ||
42 | When the device is closed, the watchdog is disabled. This is not | |
43 | always such a good idea, since if there is a bug in the watchdog | |
44 | daemon and it crashes the system will not reboot. Because of this, | |
45 | some of the drivers support the configuration option "Disable watchdog | |
46 | shutdown on close", CONFIG_WATCHDOG_NOWAYOUT. If it is set to Y when | |
47 | compiling the kernel, there is no way of disabling the watchdog once | |
2fe0ae78 | 48 | it has been started. So, if the watchdog daemon crashes, the system |
1da177e4 LT |
49 | will reboot after the timeout has passed. |
50 | ||
51 | Some other drivers will not disable the watchdog, unless a specific | |
52 | magic character 'V' has been sent /dev/watchdog just before closing | |
53 | the file. If the userspace daemon closes the file without sending | |
54 | this special character, the driver will assume that the daemon (and | |
55 | userspace in general) died, and will stop pinging the watchdog without | |
56 | disabling it first. This will then cause a reboot. | |
57 | ||
58 | The ioctl API: | |
59 | ||
60 | All conforming drivers also support an ioctl API. | |
61 | ||
62 | Pinging the watchdog using an ioctl: | |
63 | ||
64 | All drivers that have an ioctl interface support at least one ioctl, | |
65 | KEEPALIVE. This ioctl does exactly the same thing as a write to the | |
66 | watchdog device, so the main loop in the above program could be | |
67 | replaced with: | |
68 | ||
69 | while (1) { | |
70 | ioctl(fd, WDIOC_KEEPALIVE, 0); | |
71 | sleep(10); | |
72 | } | |
73 | ||
74 | the argument to the ioctl is ignored. | |
75 | ||
76 | Setting and getting the timeout: | |
77 | ||
78 | For some drivers it is possible to modify the watchdog timeout on the | |
79 | fly with the SETTIMEOUT ioctl, those drivers have the WDIOF_SETTIMEOUT | |
80 | flag set in their option field. The argument is an integer | |
81 | representing the timeout in seconds. The driver returns the real | |
82 | timeout used in the same variable, and this timeout might differ from | |
83 | the requested one due to limitation of the hardware. | |
84 | ||
85 | int timeout = 45; | |
86 | ioctl(fd, WDIOC_SETTIMEOUT, &timeout); | |
87 | printf("The timeout was set to %d seconds\n", timeout); | |
88 | ||
89 | This example might actually print "The timeout was set to 60 seconds" | |
90 | if the device has a granularity of minutes for its timeout. | |
91 | ||
92 | Starting with the Linux 2.4.18 kernel, it is possible to query the | |
93 | current timeout using the GETTIMEOUT ioctl. | |
94 | ||
95 | ioctl(fd, WDIOC_GETTIMEOUT, &timeout); | |
96 | printf("The timeout was is %d seconds\n", timeout); | |
97 | ||
e05b59fe CM |
98 | Pretimeouts: |
99 | ||
100 | Some watchdog timers can be set to have a trigger go off before the | |
101 | actual time they will reset the system. This can be done with an NMI, | |
102 | interrupt, or other mechanism. This allows Linux to record useful | |
103 | information (like panic information and kernel coredumps) before it | |
104 | resets. | |
105 | ||
106 | pretimeout = 10; | |
107 | ioctl(fd, WDIOC_SETPRETIMEOUT, &pretimeout); | |
108 | ||
109 | Note that the pretimeout is the number of seconds before the time | |
110 | when the timeout will go off. It is not the number of seconds until | |
111 | the pretimeout. So, for instance, if you set the timeout to 60 seconds | |
112 | and the pretimeout to 10 seconds, the pretimout will go of in 50 | |
113 | seconds. Setting a pretimeout to zero disables it. | |
114 | ||
115 | There is also a get function for getting the pretimeout: | |
116 | ||
117 | ioctl(fd, WDIOC_GETPRETIMEOUT, &timeout); | |
118 | printf("The pretimeout was is %d seconds\n", timeout); | |
119 | ||
120 | Not all watchdog drivers will support a pretimeout. | |
121 | ||
58b519f3 WVS |
122 | Get the number of seconds before reboot: |
123 | ||
124 | Some watchdog drivers have the ability to report the remaining time | |
125 | before the system will reboot. The WDIOC_GETTIMELEFT is the ioctl | |
126 | that returns the number of seconds before reboot. | |
127 | ||
128 | ioctl(fd, WDIOC_GETTIMELEFT, &timeleft); | |
129 | printf("The timeout was is %d seconds\n", timeleft); | |
130 | ||
e05b59fe | 131 | Environmental monitoring: |
1da177e4 LT |
132 | |
133 | All watchdog drivers are required return more information about the system, | |
134 | some do temperature, fan and power level monitoring, some can tell you | |
135 | the reason for the last reboot of the system. The GETSUPPORT ioctl is | |
136 | available to ask what the device can do: | |
137 | ||
138 | struct watchdog_info ident; | |
139 | ioctl(fd, WDIOC_GETSUPPORT, &ident); | |
140 | ||
141 | the fields returned in the ident struct are: | |
142 | ||
143 | identity a string identifying the watchdog driver | |
144 | firmware_version the firmware version of the card if available | |
145 | options a flags describing what the device supports | |
146 | ||
147 | the options field can have the following bits set, and describes what | |
148 | kind of information that the GET_STATUS and GET_BOOT_STATUS ioctls can | |
149 | return. [FIXME -- Is this correct?] | |
150 | ||
151 | WDIOF_OVERHEAT Reset due to CPU overheat | |
152 | ||
153 | The machine was last rebooted by the watchdog because the thermal limit was | |
154 | exceeded | |
155 | ||
156 | WDIOF_FANFAULT Fan failed | |
157 | ||
158 | A system fan monitored by the watchdog card has failed | |
159 | ||
160 | WDIOF_EXTERN1 External relay 1 | |
161 | ||
162 | External monitoring relay/source 1 was triggered. Controllers intended for | |
163 | real world applications include external monitoring pins that will trigger | |
164 | a reset. | |
165 | ||
166 | WDIOF_EXTERN2 External relay 2 | |
167 | ||
168 | External monitoring relay/source 2 was triggered | |
169 | ||
170 | WDIOF_POWERUNDER Power bad/power fault | |
171 | ||
172 | The machine is showing an undervoltage status | |
173 | ||
174 | WDIOF_CARDRESET Card previously reset the CPU | |
175 | ||
176 | The last reboot was caused by the watchdog card | |
177 | ||
178 | WDIOF_POWEROVER Power over voltage | |
179 | ||
180 | The machine is showing an overvoltage status. Note that if one level is | |
181 | under and one over both bits will be set - this may seem odd but makes | |
182 | sense. | |
183 | ||
184 | WDIOF_KEEPALIVEPING Keep alive ping reply | |
185 | ||
186 | The watchdog saw a keepalive ping since it was last queried. | |
187 | ||
188 | WDIOF_SETTIMEOUT Can set/get the timeout | |
189 | ||
e05b59fe CM |
190 | The watchdog can do pretimeouts. |
191 | ||
192 | WDIOF_PRETIMEOUT Pretimeout (in seconds), get/set | |
193 | ||
1da177e4 LT |
194 | |
195 | For those drivers that return any bits set in the option field, the | |
196 | GETSTATUS and GETBOOTSTATUS ioctls can be used to ask for the current | |
197 | status, and the status at the last reboot, respectively. | |
198 | ||
199 | int flags; | |
200 | ioctl(fd, WDIOC_GETSTATUS, &flags); | |
201 | ||
202 | or | |
203 | ||
204 | ioctl(fd, WDIOC_GETBOOTSTATUS, &flags); | |
205 | ||
206 | Note that not all devices support these two calls, and some only | |
207 | support the GETBOOTSTATUS call. | |
208 | ||
209 | Some drivers can measure the temperature using the GETTEMP ioctl. The | |
a2ffd275 | 210 | returned value is the temperature in degrees fahrenheit. |
1da177e4 LT |
211 | |
212 | int temperature; | |
213 | ioctl(fd, WDIOC_GETTEMP, &temperature); | |
214 | ||
215 | Finally the SETOPTIONS ioctl can be used to control some aspects of | |
216 | the cards operation; right now the pcwd driver is the only one | |
fa00e7e1 | 217 | supporting this ioctl. |
1da177e4 LT |
218 | |
219 | int options = 0; | |
220 | ioctl(fd, WDIOC_SETOPTIONS, options); | |
221 | ||
222 | The following options are available: | |
223 | ||
224 | WDIOS_DISABLECARD Turn off the watchdog timer | |
225 | WDIOS_ENABLECARD Turn on the watchdog timer | |
226 | WDIOS_TEMPPANIC Kernel panic on temperature trip | |
227 | ||
228 | [FIXME -- better explanations] | |
229 | ||
230 | Implementations in the current drivers in the kernel tree: | |
231 | ||
232 | Here I have tried to summarize what the different drivers support and | |
233 | where they do strange things compared to the other drivers. | |
234 | ||
235 | acquirewdt.c -- Acquire Single Board Computer | |
236 | ||
237 | This driver has a hardcoded timeout of 1 minute | |
238 | ||
239 | Supports CONFIG_WATCHDOG_NOWAYOUT | |
240 | ||
241 | GETSUPPORT returns KEEPALIVEPING. GETSTATUS will return 1 if | |
242 | the device is open, 0 if not. [FIXME -- isn't this rather | |
243 | silly? To be able to use the ioctl, the device must be open | |
244 | and so GETSTATUS will always return 1]. | |
245 | ||
246 | advantechwdt.c -- Advantech Single Board Computer | |
247 | ||
248 | Timeout that defaults to 60 seconds, supports SETTIMEOUT. | |
249 | ||
250 | Supports CONFIG_WATCHDOG_NOWAYOUT | |
251 | ||
252 | GETSUPPORT returns WDIOF_KEEPALIVEPING and WDIOF_SETTIMEOUT. | |
253 | The GETSTATUS call returns if the device is open or not. | |
254 | [FIXME -- silliness again?] | |
255 | ||
a2f40ccd KG |
256 | booke_wdt.c -- PowerPC BookE Watchdog Timer |
257 | ||
258 | Timeout default varies according to frequency, supports | |
259 | SETTIMEOUT | |
260 | ||
84eb8d06 | 261 | Watchdog cannot be turned off, CONFIG_WATCHDOG_NOWAYOUT |
a2f40ccd KG |
262 | does not make sense |
263 | ||
264 | GETSUPPORT returns the watchdog_info struct, and | |
265 | GETSTATUS returns the supported options. GETBOOTSTATUS | |
266 | returns a 1 if the last reset was caused by the | |
84eb8d06 | 267 | watchdog and a 0 otherwise. This watchdog cannot be |
a2f40ccd KG |
268 | disabled once it has been started. The wdt_period kernel |
269 | parameter selects which bit of the time base changing | |
270 | from 0->1 will trigger the watchdog exception. Changing | |
271 | the timeout from the ioctl calls will change the | |
272 | wdt_period as defined above. Finally if you would like to | |
273 | replace the default Watchdog Handler you can implement the | |
274 | WatchdogHandler() function in your own code. | |
275 | ||
1da177e4 LT |
276 | eurotechwdt.c -- Eurotech CPU-1220/1410 |
277 | ||
278 | The timeout can be set using the SETTIMEOUT ioctl and defaults | |
279 | to 60 seconds. | |
280 | ||
281 | Also has a module parameter "ev", event type which controls | |
282 | what should happen on a timeout, the string "int" or anything | |
283 | else that causes a reboot. [FIXME -- better description] | |
284 | ||
285 | Supports CONFIG_WATCHDOG_NOWAYOUT | |
286 | ||
287 | GETSUPPORT returns CARDRESET and WDIOF_SETTIMEOUT but | |
288 | GETSTATUS is not supported and GETBOOTSTATUS just returns 0. | |
289 | ||
290 | i810-tco.c -- Intel 810 chipset | |
291 | ||
292 | Also has support for a lot of other i8x0 stuff, but the | |
293 | watchdog is one of the things. | |
294 | ||
295 | The timeout is set using the module parameter "i810_margin", | |
296 | which is in steps of 0.6 seconds where 2<i810_margin<64. The | |
297 | driver supports the SETTIMEOUT ioctl. | |
298 | ||
299 | Supports CONFIG_WATCHDOG_NOWAYOUT. | |
300 | ||
301 | GETSUPPORT returns WDIOF_SETTIMEOUT. The GETSTATUS call | |
302 | returns some kind of timer value which ist not compatible with | |
303 | the other drivers. GETBOOT status returns some kind of | |
304 | hardware specific boot status. [FIXME -- describe this] | |
305 | ||
306 | ib700wdt.c -- IB700 Single Board Computer | |
307 | ||
308 | Default timeout of 30 seconds and the timeout is settable | |
309 | using the SETTIMEOUT ioctl. Note that only a few timeout | |
310 | values are supported. | |
311 | ||
312 | Supports CONFIG_WATCHDOG_NOWAYOUT | |
313 | ||
314 | GETSUPPORT returns WDIOF_KEEPALIVEPING and WDIOF_SETTIMEOUT. | |
315 | The GETSTATUS call returns if the device is open or not. | |
316 | [FIXME -- silliness again?] | |
317 | ||
318 | machzwd.c -- MachZ ZF-Logic | |
319 | ||
320 | Hardcoded timeout of 10 seconds | |
321 | ||
322 | Has a module parameter "action" that controls what happens | |
323 | when the timeout runs out which can be 0 = RESET (default), | |
324 | 1 = SMI, 2 = NMI, 3 = SCI. | |
325 | ||
326 | Supports CONFIG_WATCHDOG_NOWAYOUT and the magic character | |
327 | 'V' close handling. | |
328 | ||
329 | GETSUPPORT returns WDIOF_KEEPALIVEPING, and the GETSTATUS call | |
330 | returns if the device is open or not. [FIXME -- silliness | |
331 | again?] | |
332 | ||
333 | mixcomwd.c -- MixCom Watchdog | |
334 | ||
335 | [FIXME -- I'm unable to tell what the timeout is] | |
336 | ||
337 | Supports CONFIG_WATCHDOG_NOWAYOUT | |
338 | ||
339 | GETSUPPORT returns WDIOF_KEEPALIVEPING, GETSTATUS returns if | |
340 | the device is opened or not [FIXME -- I'm not really sure how | |
341 | this works, there seems to be some magic connected to | |
342 | CONFIG_WATCHDOG_NOWAYOUT] | |
343 | ||
344 | pcwd.c -- Berkshire PC Watchdog | |
345 | ||
346 | Hardcoded timeout of 1.5 seconds | |
347 | ||
348 | Supports CONFIG_WATCHDOG_NOWAYOUT | |
349 | ||
350 | GETSUPPORT returns WDIOF_OVERHEAT|WDIOF_CARDRESET and both | |
351 | GETSTATUS and GETBOOTSTATUS return something useful. | |
352 | ||
353 | The SETOPTIONS call can be used to enable and disable the card | |
354 | and to ask the driver to call panic if the system overheats. | |
355 | ||
356 | sbc60xxwdt.c -- 60xx Single Board Computer | |
357 | ||
358 | Hardcoded timeout of 10 seconds | |
359 | ||
360 | Does not support CONFIG_WATCHDOG_NOWAYOUT, but has the magic | |
361 | character 'V' close handling. | |
362 | ||
363 | No bits set in GETSUPPORT | |
364 | ||
365 | scx200.c -- National SCx200 CPUs | |
366 | ||
367 | Not in the kernel yet. | |
368 | ||
369 | The timeout is set using a module parameter "margin" which | |
370 | defaults to 60 seconds. The timeout can also be set using | |
371 | SETTIMEOUT and read using GETTIMEOUT. | |
372 | ||
373 | Supports a module parameter "nowayout" that is initialized | |
374 | with the value of CONFIG_WATCHDOG_NOWAYOUT. Also supports the | |
375 | magic character 'V' handling. | |
376 | ||
377 | shwdt.c -- SuperH 3/4 processors | |
378 | ||
379 | [FIXME -- I'm unable to tell what the timeout is] | |
380 | ||
381 | Supports CONFIG_WATCHDOG_NOWAYOUT | |
382 | ||
383 | GETSUPPORT returns WDIOF_KEEPALIVEPING, and the GETSTATUS call | |
384 | returns if the device is open or not. [FIXME -- silliness | |
385 | again?] | |
386 | ||
387 | softdog.c -- Software watchdog | |
388 | ||
389 | The timeout is set with the module parameter "soft_margin" | |
390 | which defaults to 60 seconds, the timeout is also settable | |
391 | using the SETTIMEOUT ioctl. | |
392 | ||
393 | Supports CONFIG_WATCHDOG_NOWAYOUT | |
394 | ||
395 | WDIOF_SETTIMEOUT bit set in GETSUPPORT | |
396 | ||
397 | w83877f_wdt.c -- W83877F Computer | |
398 | ||
399 | Hardcoded timeout of 30 seconds | |
400 | ||
401 | Does not support CONFIG_WATCHDOG_NOWAYOUT, but has the magic | |
402 | character 'V' close handling. | |
403 | ||
404 | No bits set in GETSUPPORT | |
405 | ||
406 | w83627hf_wdt.c -- w83627hf watchdog | |
407 | ||
408 | Timeout that defaults to 60 seconds, supports SETTIMEOUT. | |
409 | ||
410 | Supports CONFIG_WATCHDOG_NOWAYOUT | |
411 | ||
412 | GETSUPPORT returns WDIOF_KEEPALIVEPING and WDIOF_SETTIMEOUT. | |
413 | The GETSTATUS call returns if the device is open or not. | |
414 | ||
415 | wdt.c -- ICS WDT500/501 ISA and | |
416 | wdt_pci.c -- ICS WDT500/501 PCI | |
417 | ||
418 | Default timeout of 60 seconds. The timeout is also settable | |
419 | using the SETTIMEOUT ioctl. | |
420 | ||
421 | Supports CONFIG_WATCHDOG_NOWAYOUT | |
422 | ||
423 | GETSUPPORT returns with bits set depending on the actual | |
424 | card. The WDT501 supports a lot of external monitoring, the | |
425 | WDT500 much less. | |
426 | ||
427 | wdt285.c -- Footbridge watchdog | |
428 | ||
429 | The timeout is set with the module parameter "soft_margin" | |
430 | which defaults to 60 seconds. The timeout is also settable | |
431 | using the SETTIMEOUT ioctl. | |
432 | ||
433 | Does not support CONFIG_WATCHDOG_NOWAYOUT | |
434 | ||
435 | WDIOF_SETTIMEOUT bit set in GETSUPPORT | |
436 | ||
437 | wdt977.c -- Netwinder W83977AF chip | |
438 | ||
439 | Hardcoded timeout of 3 minutes | |
440 | ||
441 | Supports CONFIG_WATCHDOG_NOWAYOUT | |
442 | ||
443 | Does not support any ioctls at all. | |
444 |