blob: eb7132ed8bbcb7650bdc20e6a43e3c9222d6621b [file] [log] [blame]
Alan Cox4d389dc2007-05-23 14:43:52 -07001Last reviewed: 10/05/2007
2
3
Linus Torvalds1da177e2005-04-16 15:20:36 -07004The 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
Alan Cox4d389dc2007-05-23 14:43:52 -070028The Linux watchdog API is a rather ad-hoc construction and different
Linus Torvalds1da177e2005-04-16 15:20:36 -070029drivers 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
Randy Dunlap56fb9e52006-05-21 20:58:10 -070040like this source file: see Documentation/watchdog/src/watchdog-simple.c
Linus Torvalds1da177e2005-04-16 15:20:36 -070041
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
Andrew Dyer0d710cb2008-01-08 14:40:37 -060045When 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.
Linus Torvalds1da177e2005-04-16 15:20:36 -070056
Andrew Dyer0d710cb2008-01-08 14:40:37 -060057Magic 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.
Linus Torvalds1da177e2005-04-16 15:20:36 -070066
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
Corey Minyarde05b59f2006-04-19 22:40:53 +0200107Pretimeouts:
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 pretimout will go of 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
Wim Van Sebroeck58b519f2006-05-21 12:48:44 +0200131Get 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
Corey Minyarde05b59f2006-04-19 22:40:53 +0200140Environmental monitoring:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700141
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
Corey Minyarde05b59f2006-04-19 22:40:53 +0200199The watchdog can do pretimeouts.
200
201 WDIOF_PRETIMEOUT Pretimeout (in seconds), get/set
202
Linus Torvalds1da177e2005-04-16 15:20:36 -0700203
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
Matt LaPlantea2ffd272006-10-03 22:49:15 +0200219returned value is the temperature in degrees fahrenheit.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700220
221 int temperature;
222 ioctl(fd, WDIOC_GETTEMP, &temperature);
223
224Finally the SETOPTIONS ioctl can be used to control some aspects of
James Hogandfc33382010-04-05 11:31:29 +0100225the cards operation.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700226
227 int options = 0;
James Hogandfc33382010-04-05 11:31:29 +0100228 ioctl(fd, WDIOC_SETOPTIONS, &options);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700229
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