watchdog-api.rst 9.4 KB

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