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