Merge tag 'v5.1-rc1' into regulator-5.2
[sfrench/cifs-2.6.git] / Documentation / watchdog / watchdog-api.txt
1 Last reviewed: 10/05/2007
2
3
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
28 The Linux watchdog API is a rather ad-hoc construction and different
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
40 like this source file:  see samples/watchdog/watchdog-simple.c
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, 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.
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
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
121 and the pretimeout to 10 seconds, the pretimeout will go off in 50
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
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
140 Environmental monitoring:
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
199 The watchdog can do pretimeouts.
200
201         WDIOF_PRETIMEOUT        Pretimeout (in seconds), get/set
202
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
219 returned value is the temperature in degrees fahrenheit.
220
221     int temperature;
222     ioctl(fd, WDIOC_GETTEMP, &temperature);
223
224 Finally the SETOPTIONS ioctl can be used to control some aspects of
225 the cards operation.
226
227     int options = 0;
228     ioctl(fd, WDIOC_SETOPTIONS, &options);
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