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