WDT_MPC8XX(Liebherr specific extensions)

NAME
wdt_mpc8xx - Watchdog driver

SYNOPSIS
#include <linux/asm/wdt_mpc8xx.h>

DESCRIPTION
The wdt_mpc8xx 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.

REGULAR API
The regular API provides a facility to setup a watchdog behaviour 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 open-only or 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.

CHAIN API
The second API, which is implemented only through calls to ioctl(2), can be used to register configurable watchdog chains from either user or kernel space. A watchdog chain is identified by an unsigned integer and can contain up to three action stages. A time interval in seconds and an 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 WDT_MPC8XX_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.

IOCTLS

WDT_MPC8XX_OPEN_ONLY
    This parameterless call selects the open-only operational mode of the driver as described above.

WDT_MPC8XX_ALWAYS
    Also a parameterless call, this sets the driver to the always operational mode.

WDT_MPC8XX_REGISTER
    This and the two following ioctls constitute the chain interface described above. The parameter given to the call is a pointer to a structure with the following layout:
     typedef struct wdt_mpc8xx_param {
       unsigned chainid;
       unsigned long timer_count[3];
       int action[3];
       int signal;
     } wdt_mpc8xx_param_t; Each stage is configured with entries in the arrays timer_count and action. The timer_count contains the length of the interval in seconds while action contains one of the constants WDT_MPC8XX_ACTION_SIGNAL, WDT_MPC8XX_ACTION_KILL, WDT_MPC8XX_ACTION_REBOOT and WDT_MPC8XX_ACTION_RESET. A timer_count of zero signals the end of the chain. The ACTION_SIGNAL will send the configurable signal with number 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.

WDT_MPC8XX_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.

WDT_MPC8XX_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 inter as a parameter denoting the chain to be unregistered.

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 errno set accordingly. Specifically EINVAL, EFAULT, ENOMEM can be returned.

KERNEL INTERFACE
Modules can also register with the chain API of the watchdog driver. For this the three functions wdt_mpc8xx_register_mon_chain, wdt_mpc8xx_reset_mon_chain and wdt_mpc8xx_unregister_mon_chain are exported from the driver. The first function takes one argument, namely a pointer to a wdt_mpc8xx_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.

CONFIGURATION
The driver is configurable through parameters passed to the driver through the Linux commandline as wdt_8xx=<opts> . Multiple options can be seperated by commas, as usual. timeout:<n> will set the expiry period of the regular driver API to <n> seconds. 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 LWMON board is 10, resulting in 10 watchdog triggers per second. no will disable the software APIs of the driver but still trigger the hardware watchdog as described previously.

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_mpc8xx_param_t param;
  /* Setup signal handling */
  signal(SIGUSR1, got_signal);
  param.chainid=823;
  param.timer_count[0]=3;
  param.action[0]=WDT_MPC8XX_ACTION_KILL;
  param.signal=SIGUSR1;
  param.timer_count[1]=5;
  param.action[1]=WDT_MPC8XX_ACTION_RESET;
  /* Register chain */
  ioctl(fd, WDT_MPC8XX_REGISTER, &param);
  ..
  /* Reset chain */
  ioctl(fd, WDT_MPC8XX_RESET, &param.chainid);

FILES
 /dev/watchdog