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