linux/Documentation/watchdog/watchdog-api.txt
<<
>>
Prefs
   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