Fix MPC52xx watchdog driver

- 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 2005

1 files changed, 214 insertions, 0 deletions

diff --git a/Documentation/man4/wdt_mpc5xxx.4 b/Documentation/man4/wdt_mpc5xxx.4
new file mode 100755
index 0000000..ca41e28
--- /dev/null
+++ b/Documentation/man4/wdt_mpc5xxx.4
@@ -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, &param);
+  ..
+  /* Reset chain    */
+  ioctl(fd, WDT_RESET, &param.chainid);
+
+.SH FILES
+ /dev/watchdog