- make watchdog driver work on systems with an IPB clock frequency of 133 MHz (watchdog expired to fast there). - now all three watchdog chain entries could be used. - fix some typos. Patch by Martin Krause, 23 Jun 2005master
parent
94085698d0
commit
aecd902aed
@ -0,0 +1,214 @@ |
||||
.\" Hey Emacs! This file is -*- nroff -*- source. |
||||
.\" |
||||
.\" Copyright 2002 Detlev Zundel (dzu@denx.de) |
||||
.\" |
||||
.\" Permission is granted to make and distribute verbatim copies of this |
||||
.\" manual provided the copyright notice and this permission notice are |
||||
.\" preserved on all copies. |
||||
.\" |
||||
.\" Permission is granted to copy and distribute modified versions of this |
||||
.\" manual under the conditions for verbatim copying, provided that the |
||||
.\" entire resulting derived work is distributed under the terms of a |
||||
.\" permission notice identical to this one |
||||
.\" |
||||
.TH WDT_MPC5XXX "Denx specific extensions" |
||||
.SH NAME |
||||
wdt_mpc5xxx \- Watchdog driver |
||||
.SH SYNOPSIS |
||||
.B #include <linux/asm/wdt_mpc5xxx.h> |
||||
.SH DESCRIPTION |
||||
The |
||||
.B wdt_mpc5xxx |
||||
driver implements a character device with major number 10 and minor |
||||
number 130. It is a software abstraction of the hardware watchdog |
||||
with two different APIs. While the driver periodically triggers the |
||||
hardware watchdog, the software can setup independent timeout periods. |
||||
|
||||
.SH "REGULAR API" |
||||
The regular API provides a facility to setup a watchdog behaviour |
||||
.I shared |
||||
by all processes using the driver. This interface uses read(2), |
||||
write(2) and the first two ioctl(2) calls listed below. The |
||||
parameterless ioctl(2) calls select the operational mode of the |
||||
driver, which can be |
||||
.I open-only |
||||
or |
||||
.I always. |
||||
|
||||
In open-only mode, the watchdog will not expire if the device file is |
||||
not opened by any process, while in always |
||||
mode the behaviour is independent of the device file being opened. |
||||
|
||||
Reading from the device file will return an unsigned integer denoting |
||||
the number of seconds left till the watchdog expires. Writing an |
||||
unsigned integer to the device file will set the expiration period in |
||||
seconds. Note that the hardware watchdog will be triggered |
||||
independently with a configurable period. See the section |
||||
CONFIGURATION for details. |
||||
|
||||
An expiration of the watchdog will trigger a hard-reset of the machine. |
||||
|
||||
.SH "CHAIN API" |
||||
The second API, which is implemented only through calls to ioctl(2), |
||||
can be used to register configurable |
||||
.I watchdog chains |
||||
from either user or kernel space. A watchdog chain |
||||
is identified by an unsigned integer and can contain up to three |
||||
.I action stages. |
||||
A |
||||
.I time interval |
||||
in seconds and an |
||||
.I action |
||||
is associated with each stage. When the chain is not reset before the |
||||
interval elapses, the associated action is triggered and the chain |
||||
moves on to the next stage. |
||||
|
||||
A chain can request to kill the registering process if the interval |
||||
elapses. In this case a restarted process can register with the |
||||
driver giving the same identifier and reset the chain. This is the |
||||
main reason why there is no association between chains and processes |
||||
or open device files. |
||||
|
||||
For a detailed description of the possible chain configurations, see |
||||
the description of the |
||||
.B WDT_REGISTER |
||||
ioctl call. |
||||
|
||||
Note that when mixing the two interfaces, the second API takes |
||||
precedence. That is, expiry of the interval set by writing to the |
||||
device file while a chain is registered, will not trigger any actions. |
||||
|
||||
Also note that the default operational mode of the driver, |
||||
i.e. open-only or always can only be configured in the source-code. |
||||
|
||||
.SH IOCTLS |
||||
.TP |
||||
WDT_OPEN_ONLY |
||||
This parameterless call selects the |
||||
.I open-only |
||||
operational mode of the driver as described above. |
||||
|
||||
.TP |
||||
WDT_ALWAYS |
||||
Also a parameterless call, this sets the driver to the |
||||
.I always |
||||
operational mode. |
||||
|
||||
.TP |
||||
WDT_REGISTER |
||||
This and the two following ioctls constitute the |
||||
.I chain interface |
||||
described above. The parameter given to the call is a pointer to a |
||||
structure with the following layout: |
||||
|
||||
typedef struct wdt_param { |
||||
unsigned chainid; |
||||
unsigned long timer_count[3]; |
||||
int action[3]; |
||||
int signal; |
||||
} wdt_param_t; |
||||
|
||||
Each stage is configured with entries in the arrays |
||||
.I timer_count |
||||
and |
||||
.I action. |
||||
The timer_count contains the length of the interval in seconds |
||||
while action contains one of the constants |
||||
.B WDT_ACTION_SIGNAL, WDT_ACTION_KILL, |
||||
.B WDT_ACTION_REBOOT |
||||
and |
||||
.B WDT_ACTION_RESET. |
||||
A timer_count of zero signals the end of the chain. |
||||
|
||||
The ACTION_SIGNAL will send the configurable signal with number |
||||
.I signal |
||||
to the registering process, while ACTION_KILL signals SIGKILL which |
||||
can not be caught by the registered process. |
||||
ACTION_REBOOT tries a soft reboot and ACTION_RESET |
||||
triggers a hard-reset of the machine. |
||||
|
||||
When stages of the chain are to be left unused, they should be filled |
||||
with zero entries. |
||||
|
||||
Note that internally a hard-reset stage is appended as a stop entry |
||||
ensuring a chain will never exceed its stages. |
||||
|
||||
.TP |
||||
WDT_RESET |
||||
This call resets the chain denoted by the unsigned integer passed to |
||||
it. When reset, a chain will expire beginning with stage zero again. |
||||
|
||||
.TP |
||||
WDT_UNREGISTER |
||||
As closing the device file will not have any effect on chains, a |
||||
process must unregister a chain if the service is no longer needed. |
||||
This can be done with this ioctl taking an unsigned integer as a |
||||
parameter denoting the chain to be unregistered. |
||||
|
||||
.SH "IOCTL RESULT VALUES" |
||||
On successful completion, the above calls to ioctl(2) return 0. When |
||||
invalid parameters are provided or an error occurs, a negative value |
||||
will be returned and |
||||
.B errno |
||||
set accordingly. Specifically |
||||
.B "EINVAL, EFAULT, ENOMEM" |
||||
can be returned. |
||||
|
||||
.SH "KERNEL INTERFACE" |
||||
Modules can also register with the chain API of the watchdog driver. |
||||
For this the three functions |
||||
.B wdt_register_mon_chain, wdt_reset_mon_chain |
||||
and |
||||
.B wdt_unregister_mon_chain |
||||
are exported from the driver. The first function takes one argument, |
||||
namely a pointer to a |
||||
.I wdt_param |
||||
structure. The other two calls take a pointer to an unsigned integer |
||||
as a parameter, namely the chain id of the chain to be reset or |
||||
unregistered. |
||||
|
||||
.SH CONFIGURATION |
||||
The driver is configurable through parameters passed to the driver |
||||
through the Linux commandline as |
||||
.B "wdt=<opts>". |
||||
Multiple options can be seperated by |
||||
commas, as usual. |
||||
|
||||
.B timeout:<n> |
||||
will set the expiry period of the regular driver API to <n> seconds. |
||||
|
||||
.B period:<n> |
||||
sets the period with which the hardware watchdog is triggered to <n> |
||||
jiffies. This usually means 1/100th of a second. The default for the |
||||
MPC5xxx is (1*HZ), resulting in 1 watchdog trigger per second. |
||||
|
||||
.B off |
||||
will disable the software APIs of the driver but still trigger the |
||||
hardware watchdog as described previously. |
||||
|
||||
.SH EXAMPLE |
||||
The following code snippet registers a watchdog chain whose first |
||||
stage will expire after 3 seconds and send the SIGUSR1 signal to the |
||||
process. When 5 seconds after this the chain is not reset, the |
||||
machine will do a hard-reset. |
||||
|
||||
wdt_param_t param; |
||||
|
||||
/* Setup signal handling */ |
||||
signal(SIGUSR1, got_signal); |
||||
|
||||
param.chainid=823; |
||||
param.timer_count[0]=3; |
||||
param.action[0]=WDT_ACTION_KILL; |
||||
param.signal=SIGUSR1; |
||||
param.timer_count[1]=5; |
||||
param.action[1]=WDT_ACTION_RESET; |
||||
|
||||
/* Register chain */ |
||||
ioctl(fd, WDT_REGISTER, ¶m); |
||||
.. |
||||
/* Reset chain */ |
||||
ioctl(fd, WDT_RESET, ¶m.chainid); |
||||
|
||||
.SH FILES |
||||
/dev/watchdog |
Loading…
Reference in new issue