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