git.sur5r.net Git - u-boot/blob - Documentation/man4/wdt_mpc5xxx.4

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