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-sy
10
11 Some parts of this document are copied verbati
12 driver which is (c) Copyright 2000 Jakob Oeste<
13
14 This document describes the state of the Linux
15
16 Introduction
17 ============
18
19 A Watchdog Timer (WDT) is a hardware circuit t
20 computer system in case of a software fault.
21 already.
22
23 Usually a userspace daemon will notify the ker
24 /dev/watchdog special device file that userspa
25 regular intervals. When such a notification o
26 usually tell the hardware watchdog that everyt
27 that the watchdog should wait for yet another
28 the system. If userspace fails (RAM error, ke
29 notifications cease to occur, and the hardware
30 system (causing a reboot) after the timeout oc
31
32 The Linux watchdog API is a rather ad-hoc cons
33 drivers implement different, and sometimes inc
34 This file is an attempt to document the existi
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 operatio
41 activates as soon as /dev/watchdog is opened a
42 the watchdog is pinged within a certain time,
43 timeout or margin. The simplest way to ping t
44 some data to the device. So a very simple wat
45 like this source file: see samples/watchdog/w
46
47 A more advanced driver could for example check
48 still responding before doing the write call t
49
50 When the device is closed, the watchdog is dis
51 Close" feature is supported (see below). This
52 good idea, since if there is a bug in the watc
53 crashes the system will not reboot. Because o
54 drivers support the configuration option "Disa
55 close", CONFIG_WATCHDOG_NOWAYOUT. If it is se
56 the kernel, there is no way of disabling the w
57 started. So, if the watchdog daemon crashes,
58 after the timeout has passed. Watchdog devices
59 the nowayout module parameter so that this opt
60 runtime.
61
62 Magic Close feature
63 ===================
64
65 If a driver supports "Magic Close", the driver
66 watchdog unless a specific magic character 'V'
67 /dev/watchdog just before closing the file. I
68 closes the file without sending this special c
69 will assume that the daemon (and userspace in
70 stop pinging the watchdog without disabling it
71 cause a reboot if the watchdog is not re-opene
72
73 The ioctl API
74 =============
75
76 All conforming drivers also support an ioctl A
77
78 Pinging the watchdog using an ioctl:
79
80 All drivers that have an ioctl interface suppo
81 KEEPALIVE. This ioctl does exactly the same t
82 watchdog device, so the main loop in the above
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
96 fly with the SETTIMEOUT ioctl, those drivers h
97 flag set in their option field. The argument
98 representing the timeout in seconds. The driv
99 timeout used in the same variable, and this ti
100 the requested one due to limitation of the har
101
102 int timeout = 45;
103 ioctl(fd, WDIOC_SETTIMEOUT, &timeout);
104 printf("The timeout was set to %d seconds\
105
106 This example might actually print "The timeout
107 if the device has a granularity of minutes for
108
109 Starting with the Linux 2.4.18 kernel, it is p
110 current timeout using the GETTIMEOUT ioctl::
111
112 ioctl(fd, WDIOC_GETTIMEOUT, &timeout);
113 printf("The timeout was is %d seconds\n",
114
115 Pretimeouts
116 ===========
117
118 Some watchdog timers can be set to have a trig
119 actual time they will reset the system. This
120 interrupt, or other mechanism. This allows Li
121 information (like panic information and kernel
122 resets::
123
124 pretimeout = 10;
125 ioctl(fd, WDIOC_SETPRETIMEOUT, &pretimeout
126
127 Note that the pretimeout is the number of seco
128 when the timeout will go off. It is not the n
129 the pretimeout. So, for instance, if you set
130 and the pretimeout to 10 seconds, the pretimeo
131 seconds. Setting a pretimeout to zero disable
132
133 There is also a get function for getting the p
134
135 ioctl(fd, WDIOC_GETPRETIMEOUT, &timeout);
136 printf("The pretimeout was is %d seconds\n
137
138 Not all watchdog drivers will support a pretim
139
140 Get the number of seconds before reboot
141 =======================================
142
143 Some watchdog drivers have the ability to repo
144 before the system will reboot. The WDIOC_GETTI
145 that returns the number of seconds before rebo
146
147 ioctl(fd, WDIOC_GETTIMELEFT, &timeleft);
148 printf("The timeout was is %d seconds\n",
149
150 Environmental monitoring
151 ========================
152
153 All watchdog drivers are required return more
154 some do temperature, fan and power level monit
155 the reason for the last reboot of the system.
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 ident
165 firmware_version the firmware v
166 options a flags descri
167 ================ ==============
168
169 the options field can have the following bits
170 kind of information that the GET_STATUS and GE
171 return.
172
173 ================ ==============
174 WDIOF_OVERHEAT Reset due to C
175 ================ ==============
176
177 The machine was last rebooted by the watchdog
178 exceeded:
179
180 ============== ==========
181 WDIOF_FANFAULT Fan failed
182 ============== ==========
183
184 A system fan monitored by the watchdog card ha
185
186 ============= ==============
187 WDIOF_EXTERN1 External relay
188 ============= ==============
189
190 External monitoring relay/source 1 was trigger
191 real world applications include external monit
192 a reset.
193
194 ============= ==============
195 WDIOF_EXTERN2 External relay
196 ============= ==============
197
198 External monitoring relay/source 2 was trigger
199
200 ================ ==============
201 WDIOF_POWERUNDER Power bad/powe
202 ================ ==============
203
204 The machine is showing an undervoltage status
205
206 =============== ==============
207 WDIOF_CARDRESET Card previousl
208 =============== ==============
209
210 The last reboot was caused by the watchdog car
211
212 ================ ==============
213 WDIOF_POWEROVER Power over vol
214 ================ ==============
215
216 The machine is showing an overvoltage status.
217 under and one over both bits will be set - thi
218 sense.
219
220 =================== ==============
221 WDIOF_KEEPALIVEPING Keep alive pin
222 =================== ==============
223
224 The watchdog saw a keepalive ping since it was
225
226 ================ ==============
227 WDIOF_SETTIMEOUT Can set/get th
228 ================ ==============
229
230 The watchdog can do pretimeouts.
231
232 ================ ==============
233 WDIOF_PRETIMEOUT Pretimeout (in
234 ================ ==============
235
236
237 For those drivers that return any bits set in
238 GETSTATUS and GETBOOTSTATUS ioctls can be used
239 status, and the status at the last reboot, res
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 ca
249 support the GETBOOTSTATUS call.
250
251 Some drivers can measure the temperature using
252 returned value is the temperature in degrees F
253
254 int temperature;
255 ioctl(fd, WDIOC_GETTEMP, &temperature);
256
257 Finally the SETOPTIONS ioctl can be used to co
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 w
267 WDIOS_ENABLECARD Turn on the wa
268 WDIOS_TEMPPANIC Kernel panic o
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.