wdt_mpc5xxx.4 6.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214
  1. .\" Hey Emacs! This file is -*- nroff -*- source.
  2. .\"
  3. .\" Copyright 2002 Detlev Zundel (dzu@denx.de)
  4. .\"
  5. .\" Permission is granted to make and distribute verbatim copies of this
  6. .\" manual provided the copyright notice and this permission notice are
  7. .\" preserved on all copies.
  8. .\"
  9. .\" Permission is granted to copy and distribute modified versions of this
  10. .\" manual under the conditions for verbatim copying, provided that the
  11. .\" entire resulting derived work is distributed under the terms of a
  12. .\" permission notice identical to this one
  13. .\"
  14. .TH WDT_MPC5XXX "Denx specific extensions"
  15. .SH NAME
  16. wdt_mpc5xxx \- Watchdog driver
  17. .SH SYNOPSIS
  18. .B #include <linux/asm/wdt_mpc5xxx.h>
  19. .SH DESCRIPTION
  20. The
  21. .B wdt_mpc5xxx
  22. driver implements a character device with major number 10 and minor
  23. number 130. It is a software abstraction of the hardware watchdog
  24. with two different APIs. While the driver periodically triggers the
  25. hardware watchdog, the software can setup independent timeout periods.
  26. .SH "REGULAR API"
  27. The regular API provides a facility to setup a watchdog behaviour
  28. .I shared
  29. by all processes using the driver. This interface uses read(2),
  30. write(2) and the first two ioctl(2) calls listed below. The
  31. parameterless ioctl(2) calls select the operational mode of the
  32. driver, which can be
  33. .I open-only
  34. or
  35. .I always.
  36. In open-only mode, the watchdog will not expire if the device file is
  37. not opened by any process, while in always
  38. mode the behaviour is independent of the device file being opened.
  39. Reading from the device file will return an unsigned integer denoting
  40. the number of seconds left till the watchdog expires. Writing an
  41. unsigned integer to the device file will set the expiration period in
  42. seconds. Note that the hardware watchdog will be triggered
  43. independently with a configurable period. See the section
  44. CONFIGURATION for details.
  45. An expiration of the watchdog will trigger a hard-reset of the machine.
  46. .SH "CHAIN API"
  47. The second API, which is implemented only through calls to ioctl(2),
  48. can be used to register configurable
  49. .I watchdog chains
  50. from either user or kernel space. A watchdog chain
  51. is identified by an unsigned integer and can contain up to three
  52. .I action stages.
  53. A
  54. .I time interval
  55. in seconds and an
  56. .I action
  57. is associated with each stage. When the chain is not reset before the
  58. interval elapses, the associated action is triggered and the chain
  59. moves on to the next stage.
  60. A chain can request to kill the registering process if the interval
  61. elapses. In this case a restarted process can register with the
  62. driver giving the same identifier and reset the chain. This is the
  63. main reason why there is no association between chains and processes
  64. or open device files.
  65. For a detailed description of the possible chain configurations, see
  66. the description of the
  67. .B WDT_REGISTER
  68. ioctl call.
  69. Note that when mixing the two interfaces, the second API takes
  70. precedence. That is, expiry of the interval set by writing to the
  71. device file while a chain is registered, will not trigger any actions.
  72. Also note that the default operational mode of the driver,
  73. i.e. open-only or always can only be configured in the source-code.
  74. .SH IOCTLS
  75. .TP
  76. WDT_OPEN_ONLY
  77. This parameterless call selects the
  78. .I open-only
  79. operational mode of the driver as described above.
  80. .TP
  81. WDT_ALWAYS
  82. Also a parameterless call, this sets the driver to the
  83. .I always
  84. operational mode.
  85. .TP
  86. WDT_REGISTER
  87. This and the two following ioctls constitute the
  88. .I chain interface
  89. described above. The parameter given to the call is a pointer to a
  90. structure with the following layout:
  91. typedef struct wdt_param {
  92. unsigned chainid;
  93. unsigned long timer_count[3];
  94. int action[3];
  95. int signal;
  96. } wdt_param_t;
  97. Each stage is configured with entries in the arrays
  98. .I timer_count
  99. and
  100. .I action.
  101. The timer_count contains the length of the interval in seconds
  102. while action contains one of the constants
  103. .B WDT_ACTION_SIGNAL, WDT_ACTION_KILL,
  104. .B WDT_ACTION_REBOOT
  105. and
  106. .B WDT_ACTION_RESET.
  107. A timer_count of zero signals the end of the chain.
  108. The ACTION_SIGNAL will send the configurable signal with number
  109. .I signal
  110. to the registering process, while ACTION_KILL signals SIGKILL which
  111. can not be caught by the registered process.
  112. ACTION_REBOOT tries a soft reboot and ACTION_RESET
  113. triggers a hard-reset of the machine.
  114. When stages of the chain are to be left unused, they should be filled
  115. with zero entries.
  116. Note that internally a hard-reset stage is appended as a stop entry
  117. ensuring a chain will never exceed its stages.
  118. .TP
  119. WDT_RESET
  120. This call resets the chain denoted by the unsigned integer passed to
  121. it. When reset, a chain will expire beginning with stage zero again.
  122. .TP
  123. WDT_UNREGISTER
  124. As closing the device file will not have any effect on chains, a
  125. process must unregister a chain if the service is no longer needed.
  126. This can be done with this ioctl taking an unsigned integer as a
  127. parameter denoting the chain to be unregistered.
  128. .SH "IOCTL RESULT VALUES"
  129. On successful completion, the above calls to ioctl(2) return 0. When
  130. invalid parameters are provided or an error occurs, a negative value
  131. will be returned and
  132. .B errno
  133. set accordingly. Specifically
  134. .B "EINVAL, EFAULT, ENOMEM"
  135. can be returned.
  136. .SH "KERNEL INTERFACE"
  137. Modules can also register with the chain API of the watchdog driver.
  138. For this the three functions
  139. .B wdt_register_mon_chain, wdt_reset_mon_chain
  140. and
  141. .B wdt_unregister_mon_chain
  142. are exported from the driver. The first function takes one argument,
  143. namely a pointer to a
  144. .I wdt_param
  145. structure. The other two calls take a pointer to an unsigned integer
  146. as a parameter, namely the chain id of the chain to be reset or
  147. unregistered.
  148. .SH CONFIGURATION
  149. The driver is configurable through parameters passed to the driver
  150. through the Linux commandline as
  151. .B "wdt=<opts>".
  152. Multiple options can be seperated by
  153. commas, as usual.
  154. .B timeout:<n>
  155. will set the expiry period of the regular driver API to <n> seconds.
  156. .B period:<n>
  157. sets the period with which the hardware watchdog is triggered to <n>
  158. jiffies. This usually means 1/100th of a second. The default for the
  159. MPC5xxx is (1*HZ), resulting in 1 watchdog trigger per second.
  160. .B off
  161. will disable the software APIs of the driver but still trigger the
  162. hardware watchdog as described previously.
  163. .SH EXAMPLE
  164. The following code snippet registers a watchdog chain whose first
  165. stage will expire after 3 seconds and send the SIGUSR1 signal to the
  166. process. When 5 seconds after this the chain is not reset, the
  167. machine will do a hard-reset.
  168. wdt_param_t param;
  169. /* Setup signal handling */
  170. signal(SIGUSR1, got_signal);
  171. param.chainid=823;
  172. param.timer_count[0]=3;
  173. param.action[0]=WDT_ACTION_KILL;
  174. param.signal=SIGUSR1;
  175. param.timer_count[1]=5;
  176. param.action[1]=WDT_ACTION_RESET;
  177. /* Register chain */
  178. ioctl(fd, WDT_REGISTER, &param);
  179. ..
  180. /* Reset chain */
  181. ioctl(fd, WDT_RESET, &param.chainid);
  182. .SH FILES
  183. /dev/watchdog