1 .\" Hey Emacs! This file is -*- nroff -*- source.
3 .\" Copyright 2002 Detlev Zundel (dzu@denx.de)
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.
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
14 .TH WDT_MPC5XXX "Denx specific extensions"
16 wdt_mpc5xxx \- Watchdog driver
18 .B #include <linux/asm/wdt_mpc5xxx.h>
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.
28 The regular API provides a facility to setup a watchdog behaviour
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
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.
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.
49 An expiration of the watchdog will trigger a hard-reset of the machine.
52 The second API, which is implemented only through calls to ioctl(2),
53 can be used to register configurable
55 from either user or kernel space. A watchdog chain
56 is identified by an unsigned integer and can contain up to three
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.
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
72 For a detailed description of the possible chain configurations, see
73 the description of the
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.
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.
87 This parameterless call selects the
89 operational mode of the driver as described above.
93 Also a parameterless call, this sets the driver to the
99 This and the two following ioctls constitute the
101 described above. The parameter given to the call is a pointer to a
102 structure with the following layout:
104 typedef struct wdt_param {
106 unsigned long timer_count[3];
111 Each stage is configured with entries in the arrays
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,
121 A timer_count of zero signals the end of the chain.
123 The ACTION_SIGNAL will send the configurable signal with number
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.
130 When stages of the chain are to be left unused, they should be filled
133 Note that internally a hard-reset stage is appended as a stop entry
134 ensuring a chain will never exceed its stages.
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.
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.
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
153 set accordingly. Specifically
154 .B "EINVAL, EFAULT, ENOMEM"
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
162 .B wdt_unregister_mon_chain
163 are exported from the driver. The first function takes one argument,
164 namely a pointer to a
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
171 The driver is configurable through parameters passed to the driver
172 through the Linux commandline as
174 Multiple options can be seperated by
178 will set the expiry period of the regular driver API to <n> seconds.
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.
186 will disable the software APIs of the driver but still trigger the
187 hardware watchdog as described previously.
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.
197 /* Setup signal handling */
198 signal(SIGUSR1, got_signal);
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;
208 ioctl(fd, WDT_REGISTER, ¶m);
211 ioctl(fd, WDT_RESET, ¶m.chainid);