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 Documentation/watchdog/src/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