+++ /dev/null
-.\" 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