123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214 |
- .\" 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
|