Documentation/watchdog/watchdog-api.rst

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