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