fedora core 6 1.2949 + vserver 2.2.0

[linux-2.6.git] / Documentation / watchdog / watchdog-api.txt

diff --git a/Documentation/watchdog/watchdog-api.txt b/Documentation/watchdog/watchdog-api.txt
index 28388aa..8d16f6f 100644 (file)
--- a/Documentation/watchdog/watchdog-api.txt
+++ b/Documentation/watchdog/watchdog-api.txt
@@ -34,19 +34,7 @@ activates as soon as /dev/watchdog is opened and will reboot unless
 the watchdog is pinged within a certain time, this time is called the
 timeout or margin.  The simplest way to ping the watchdog is to write
 some data to the device.  So a very simple watchdog daemon would look
 the watchdog is pinged within a certain time, this time is called the
 timeout or margin.  The simplest way to ping the watchdog is to write
 some data to the device.  So a very simple watchdog daemon would look

-like this:
-
-int main(int argc, const char *argv[]) {
-       int fd=open("/dev/watchdog",O_WRONLY);
-       if (fd==-1) {
-               perror("watchdog");
-               exit(1);
-       }
-       while(1) {
-               write(fd, "\0", 1);
-               sleep(10);
-       }
-}
+like this source file:  see Documentation/watchdog/src/watchdog-simple.c

 
 A more advanced driver could for example check that a HTTP server is
 still responding before doing the write call to ping the watchdog.
 
 A more advanced driver could for example check that a HTTP server is
 still responding before doing the write call to ping the watchdog.


@@ -57,7 +45,7 @@ daemon and it crashes the system will not reboot.  Because of this,
 some of the drivers support the configuration option "Disable watchdog
 shutdown on close", CONFIG_WATCHDOG_NOWAYOUT.  If it is set to Y when
 compiling the kernel, there is no way of disabling the watchdog once
 some of the drivers support the configuration option "Disable watchdog
 shutdown on close", CONFIG_WATCHDOG_NOWAYOUT.  If it is set to Y when
 compiling the kernel, there is no way of disabling the watchdog once

-it has been started.  So, if the watchdog dameon crashes, the system
+it has been started.  So, if the watchdog daemon crashes, the system

 will reboot after the timeout has passed.
 
 Some other drivers will not disable the watchdog, unless a specific
 will reboot after the timeout has passed.
 
 Some other drivers will not disable the watchdog, unless a specific


@@ -107,7 +95,40 @@ current timeout using the GETTIMEOUT ioctl.
     ioctl(fd, WDIOC_GETTIMEOUT, &timeout);
     printf("The timeout was is %d seconds\n", timeout);
 
     ioctl(fd, WDIOC_GETTIMEOUT, &timeout);
     printf("The timeout was is %d seconds\n", timeout);
 

-Envinronmental monitoring:
+Pretimeouts:
+
+Some watchdog timers can be set to have a trigger go off before the
+actual time they will reset the system.  This can be done with an NMI,
+interrupt, or other mechanism.  This allows Linux to record useful
+information (like panic information and kernel coredumps) before it
+resets.
+
+    pretimeout = 10;
+    ioctl(fd, WDIOC_SETPRETIMEOUT, &pretimeout);
+
+Note that the pretimeout is the number of seconds before the time
+when the timeout will go off.  It is not the number of seconds until
+the pretimeout.  So, for instance, if you set the timeout to 60 seconds
+and the pretimeout to 10 seconds, the pretimout will go of in 50
+seconds.  Setting a pretimeout to zero disables it.
+
+There is also a get function for getting the pretimeout:
+
+    ioctl(fd, WDIOC_GETPRETIMEOUT, &timeout);
+    printf("The pretimeout was is %d seconds\n", timeout);
+
+Not all watchdog drivers will support a pretimeout.
+
+Get the number of seconds before reboot:
+
+Some watchdog drivers have the ability to report the remaining time
+before the system will reboot. The WDIOC_GETTIMELEFT is the ioctl
+that returns the number of seconds before reboot.
+
+    ioctl(fd, WDIOC_GETTIMELEFT, &timeleft);
+    printf("The timeout was is %d seconds\n", timeleft);
+
+Environmental monitoring:

 
 All watchdog drivers are required return more information about the system,
 some do temperature, fan and power level monitoring, some can tell you
 
 All watchdog drivers are required return more information about the system,
 some do temperature, fan and power level monitoring, some can tell you


@@ -166,6 +187,10 @@ The watchdog saw a keepalive ping since it was last queried.
 
        WDIOF_SETTIMEOUT        Can set/get the timeout
 
 
        WDIOF_SETTIMEOUT        Can set/get the timeout
 

+The watchdog can do pretimeouts.
+
+       WDIOF_PRETIMEOUT        Pretimeout (in seconds), get/set
+

 
 For those drivers that return any bits set in the option field, the
 GETSTATUS and GETBOOTSTATUS ioctls can be used to ask for the current
 
 For those drivers that return any bits set in the option field, the
 GETSTATUS and GETBOOTSTATUS ioctls can be used to ask for the current


@@ -182,14 +207,14 @@ Note that not all devices support these two calls, and some only
 support the GETBOOTSTATUS call.
 
 Some drivers can measure the temperature using the GETTEMP ioctl.  The
 support the GETBOOTSTATUS call.
 
 Some drivers can measure the temperature using the GETTEMP ioctl.  The

-returned value is the temperature in degrees farenheit.
+returned value is the temperature in degrees fahrenheit.

 
     int temperature;
     ioctl(fd, WDIOC_GETTEMP, &temperature);
 
 Finally the SETOPTIONS ioctl can be used to control some aspects of
 the cards operation; right now the pcwd driver is the only one
 
     int temperature;
     ioctl(fd, WDIOC_GETTEMP, &temperature);
 
 Finally the SETOPTIONS ioctl can be used to control some aspects of
 the cards operation; right now the pcwd driver is the only one

-supporting thiss ioctl.
+supporting this ioctl.

 
     int options = 0;
     ioctl(fd, WDIOC_SETOPTIONS, options);
 
     int options = 0;
     ioctl(fd, WDIOC_SETOPTIONS, options);


@@ -228,6 +253,26 @@ advantechwdt.c -- Advantech Single Board Computer
        The GETSTATUS call returns if the device is open or not.
        [FIXME -- silliness again?]
        
        The GETSTATUS call returns if the device is open or not.
        [FIXME -- silliness again?]
        

+booke_wdt.c -- PowerPC BookE Watchdog Timer
+
+       Timeout default varies according to frequency, supports
+       SETTIMEOUT
+
+       Watchdog cannot be turned off, CONFIG_WATCHDOG_NOWAYOUT
+       does not make sense
+
+       GETSUPPORT returns the watchdog_info struct, and
+       GETSTATUS returns the supported options. GETBOOTSTATUS
+       returns a 1 if the last reset was caused by the
+       watchdog and a 0 otherwise. This watchdog cannot be
+       disabled once it has been started. The wdt_period kernel
+       parameter selects which bit of the time base changing
+       from 0->1 will trigger the watchdog exception. Changing
+       the timeout from the ioctl calls will change the
+       wdt_period as defined above. Finally if you would like to
+       replace the default Watchdog Handler you can implement the
+       WatchdogHandler() function in your own code.
+

 eurotechwdt.c -- Eurotech CPU-1220/1410
 
        The timeout can be set using the SETTIMEOUT ioctl and defaults
 eurotechwdt.c -- Eurotech CPU-1220/1410
 
        The timeout can be set using the SETTIMEOUT ioctl and defaults