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