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