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 | ||
45 | When the device is closed, the watchdog is disabled. This is not | |
46 | always such a good idea, since if there is a bug in the watchdog | |
47 | daemon and it crashes the system will not reboot. Because of this, | |
48 | some of the drivers support the configuration option "Disable watchdog | |
49 | shutdown on close", CONFIG_WATCHDOG_NOWAYOUT. If it is set to Y when | |
50 | compiling the kernel, there is no way of disabling the watchdog once | |
2fe0ae78 | 51 | it has been started. So, if the watchdog daemon crashes, the system |
4d389dce AC |
52 | will reboot after the timeout has passed. Watchdog devices also usually |
53 | support the nowayout module parameter so that this option can be controlled | |
54 | at runtime. | |
1da177e4 | 55 | |
4d389dce AC |
56 | Drivers will not disable the watchdog, unless a specific magic character 'V' |
57 | has been sent /dev/watchdog just before closing the file. If the userspace | |
58 | daemon closes the file without sending this special character, the driver | |
59 | will assume that the daemon (and userspace in general) died, and will stop | |
60 | pinging the watchdog without disabling it first. This will then cause a | |
61 | reboot if the watchdog is not re-opened in sufficient time. | |
1da177e4 LT |
62 | |
63 | The ioctl API: | |
64 | ||
65 | All conforming drivers also support an ioctl API. | |
66 | ||
67 | Pinging the watchdog using an ioctl: | |
68 | ||
69 | All drivers that have an ioctl interface support at least one ioctl, | |
70 | KEEPALIVE. This ioctl does exactly the same thing as a write to the | |
71 | watchdog device, so the main loop in the above program could be | |
72 | replaced with: | |
73 | ||
74 | while (1) { | |
75 | ioctl(fd, WDIOC_KEEPALIVE, 0); | |
76 | sleep(10); | |
77 | } | |
78 | ||
79 | the argument to the ioctl is ignored. | |
80 | ||
81 | Setting and getting the timeout: | |
82 | ||
83 | For some drivers it is possible to modify the watchdog timeout on the | |
84 | fly with the SETTIMEOUT ioctl, those drivers have the WDIOF_SETTIMEOUT | |
85 | flag set in their option field. The argument is an integer | |
86 | representing the timeout in seconds. The driver returns the real | |
87 | timeout used in the same variable, and this timeout might differ from | |
88 | the requested one due to limitation of the hardware. | |
89 | ||
90 | int timeout = 45; | |
91 | ioctl(fd, WDIOC_SETTIMEOUT, &timeout); | |
92 | printf("The timeout was set to %d seconds\n", timeout); | |
93 | ||
94 | This example might actually print "The timeout was set to 60 seconds" | |
95 | if the device has a granularity of minutes for its timeout. | |
96 | ||
97 | Starting with the Linux 2.4.18 kernel, it is possible to query the | |
98 | current timeout using the GETTIMEOUT ioctl. | |
99 | ||
100 | ioctl(fd, WDIOC_GETTIMEOUT, &timeout); | |
101 | printf("The timeout was is %d seconds\n", timeout); | |
102 | ||
e05b59fe CM |
103 | Pretimeouts: |
104 | ||
105 | Some watchdog timers can be set to have a trigger go off before the | |
106 | actual time they will reset the system. This can be done with an NMI, | |
107 | interrupt, or other mechanism. This allows Linux to record useful | |
108 | information (like panic information and kernel coredumps) before it | |
109 | resets. | |
110 | ||
111 | pretimeout = 10; | |
112 | ioctl(fd, WDIOC_SETPRETIMEOUT, &pretimeout); | |
113 | ||
114 | Note that the pretimeout is the number of seconds before the time | |
115 | when the timeout will go off. It is not the number of seconds until | |
116 | the pretimeout. So, for instance, if you set the timeout to 60 seconds | |
117 | and the pretimeout to 10 seconds, the pretimout will go of in 50 | |
118 | seconds. Setting a pretimeout to zero disables it. | |
119 | ||
120 | There is also a get function for getting the pretimeout: | |
121 | ||
122 | ioctl(fd, WDIOC_GETPRETIMEOUT, &timeout); | |
123 | printf("The pretimeout was is %d seconds\n", timeout); | |
124 | ||
125 | Not all watchdog drivers will support a pretimeout. | |
126 | ||
58b519f3 WVS |
127 | Get the number of seconds before reboot: |
128 | ||
129 | Some watchdog drivers have the ability to report the remaining time | |
130 | before the system will reboot. The WDIOC_GETTIMELEFT is the ioctl | |
131 | that returns the number of seconds before reboot. | |
132 | ||
133 | ioctl(fd, WDIOC_GETTIMELEFT, &timeleft); | |
134 | printf("The timeout was is %d seconds\n", timeleft); | |
135 | ||
e05b59fe | 136 | Environmental monitoring: |
1da177e4 LT |
137 | |
138 | All watchdog drivers are required return more information about the system, | |
139 | some do temperature, fan and power level monitoring, some can tell you | |
140 | the reason for the last reboot of the system. The GETSUPPORT ioctl is | |
141 | available to ask what the device can do: | |
142 | ||
143 | struct watchdog_info ident; | |
144 | ioctl(fd, WDIOC_GETSUPPORT, &ident); | |
145 | ||
146 | the fields returned in the ident struct are: | |
147 | ||
148 | identity a string identifying the watchdog driver | |
149 | firmware_version the firmware version of the card if available | |
150 | options a flags describing what the device supports | |
151 | ||
152 | the options field can have the following bits set, and describes what | |
153 | kind of information that the GET_STATUS and GET_BOOT_STATUS ioctls can | |
154 | return. [FIXME -- Is this correct?] | |
155 | ||
156 | WDIOF_OVERHEAT Reset due to CPU overheat | |
157 | ||
158 | The machine was last rebooted by the watchdog because the thermal limit was | |
159 | exceeded | |
160 | ||
161 | WDIOF_FANFAULT Fan failed | |
162 | ||
163 | A system fan monitored by the watchdog card has failed | |
164 | ||
165 | WDIOF_EXTERN1 External relay 1 | |
166 | ||
167 | External monitoring relay/source 1 was triggered. Controllers intended for | |
168 | real world applications include external monitoring pins that will trigger | |
169 | a reset. | |
170 | ||
171 | WDIOF_EXTERN2 External relay 2 | |
172 | ||
173 | External monitoring relay/source 2 was triggered | |
174 | ||
175 | WDIOF_POWERUNDER Power bad/power fault | |
176 | ||
177 | The machine is showing an undervoltage status | |
178 | ||
179 | WDIOF_CARDRESET Card previously reset the CPU | |
180 | ||
181 | The last reboot was caused by the watchdog card | |
182 | ||
183 | WDIOF_POWEROVER Power over voltage | |
184 | ||
185 | The machine is showing an overvoltage status. Note that if one level is | |
186 | under and one over both bits will be set - this may seem odd but makes | |
187 | sense. | |
188 | ||
189 | WDIOF_KEEPALIVEPING Keep alive ping reply | |
190 | ||
191 | The watchdog saw a keepalive ping since it was last queried. | |
192 | ||
193 | WDIOF_SETTIMEOUT Can set/get the timeout | |
194 | ||
e05b59fe CM |
195 | The watchdog can do pretimeouts. |
196 | ||
197 | WDIOF_PRETIMEOUT Pretimeout (in seconds), get/set | |
198 | ||
1da177e4 LT |
199 | |
200 | For those drivers that return any bits set in the option field, the | |
201 | GETSTATUS and GETBOOTSTATUS ioctls can be used to ask for the current | |
202 | status, and the status at the last reboot, respectively. | |
203 | ||
204 | int flags; | |
205 | ioctl(fd, WDIOC_GETSTATUS, &flags); | |
206 | ||
207 | or | |
208 | ||
209 | ioctl(fd, WDIOC_GETBOOTSTATUS, &flags); | |
210 | ||
211 | Note that not all devices support these two calls, and some only | |
212 | support the GETBOOTSTATUS call. | |
213 | ||
214 | Some drivers can measure the temperature using the GETTEMP ioctl. The | |
a2ffd275 | 215 | returned value is the temperature in degrees fahrenheit. |
1da177e4 LT |
216 | |
217 | int temperature; | |
218 | ioctl(fd, WDIOC_GETTEMP, &temperature); | |
219 | ||
220 | Finally the SETOPTIONS ioctl can be used to control some aspects of | |
221 | the cards operation; right now the pcwd driver is the only one | |
fa00e7e1 | 222 | supporting this ioctl. |
1da177e4 LT |
223 | |
224 | int options = 0; | |
225 | ioctl(fd, WDIOC_SETOPTIONS, options); | |
226 | ||
227 | The following options are available: | |
228 | ||
229 | WDIOS_DISABLECARD Turn off the watchdog timer | |
230 | WDIOS_ENABLECARD Turn on the watchdog timer | |
231 | WDIOS_TEMPPANIC Kernel panic on temperature trip | |
232 | ||
233 | [FIXME -- better explanations] | |
234 |