5 files changed, 126 insertions, 111 deletions

diff --git a/Documentation/watchdog/pcwd-watchdog.txt b/Documentation/watchdog/pcwd-watchdog.txt
index 12187a33e310..d9ee6336c1d4 100644
--- a/Documentation/watchdog/pcwd-watchdog.txt
+++ b/Documentation/watchdog/pcwd-watchdog.txt
@@ -22,78 +22,9 @@
  to run the program with an "&" to run it in the background!)
 
  If you want to write a program to be compatible with the PC Watchdog
- driver, simply do the following:
-
--- Snippet of code --
-/*
- * Watchdog Driver Test Program
- */
-
-#include <stdio.h>
-#include <stdlib.h>
-#include <string.h>
-#include <unistd.h>
-#include <fcntl.h>
-#include <sys/ioctl.h>
-#include <linux/types.h>
-#include <linux/watchdog.h>
-
-int fd;
-
-/*
- * This function simply sends an IOCTL to the driver, which in turn ticks
- * the PC Watchdog card to reset its internal timer so it doesn't trigger
- * a computer reset.
- */
-void keep_alive(void)
-{
-    int dummy;
-
-    ioctl(fd, WDIOC_KEEPALIVE, &dummy);
-}
-
-/*
- * The main program.  Run the program with "-d" to disable the card,
- * or "-e" to enable the card.
- */
-int main(int argc, char *argv[])
-{
-    fd = open("/dev/watchdog", O_WRONLY);
-
-    if (fd == -1) {
-        fprintf(stderr, "Watchdog device not enabled.\n");
-        fflush(stderr);
-        exit(-1);
-    }
-
-    if (argc > 1) {
-        if (!strncasecmp(argv[1], "-d", 2)) {
-            ioctl(fd, WDIOC_SETOPTIONS, WDIOS_DISABLECARD);
-            fprintf(stderr, "Watchdog card disabled.\n");
-            fflush(stderr);
-            exit(0);
-        } else if (!strncasecmp(argv[1], "-e", 2)) {
-            ioctl(fd, WDIOC_SETOPTIONS, WDIOS_ENABLECARD);
-            fprintf(stderr, "Watchdog card enabled.\n");
-            fflush(stderr);
-            exit(0);
-        } else {
-            fprintf(stderr, "-d to disable, -e to enable.\n");
-            fprintf(stderr, "run by itself to tick the card.\n");
-            fflush(stderr);
-            exit(0);
-        }
-    } else {
-        fprintf(stderr, "Watchdog Ticking Away!\n");
-        fflush(stderr);
-    }
-
-    while(1) {
-        keep_alive();
-        sleep(1);
-    }
-}
--- End snippet --
+ driver, simply use of modify the watchdog test program:
+ Documentation/watchdog/src/watchdog-test.c
+
 
  Other IOCTL functions include:
 
diff --git a/Documentation/watchdog/src/watchdog-simple.c b/Documentation/watchdog/src/watchdog-simple.c
new file mode 100644
index 000000000000..85cf17c48669
--- /dev/null
+++ b/Documentation/watchdog/src/watchdog-simple.c
@@ -0,0 +1,15 @@
+#include <stdlib.h>
+#include <fcntl.h>
+
+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);
+                fsync(fd);
+                sleep(10);
+        }
+}
diff --git a/Documentation/watchdog/src/watchdog-test.c b/Documentation/watchdog/src/watchdog-test.c
new file mode 100644
index 000000000000..65f6c19cb865
--- /dev/null
+++ b/Documentation/watchdog/src/watchdog-test.c
@@ -0,0 +1,68 @@
+/*
+ * Watchdog Driver Test Program
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+#include <fcntl.h>
+#include <sys/ioctl.h>
+#include <linux/types.h>
+#include <linux/watchdog.h>
+
+int fd;
+
+/*
+ * This function simply sends an IOCTL to the driver, which in turn ticks
+ * the PC Watchdog card to reset its internal timer so it doesn't trigger
+ * a computer reset.
+ */
+void keep_alive(void)
+{
+    int dummy;
+
+    ioctl(fd, WDIOC_KEEPALIVE, &dummy);
+}
+
+/*
+ * The main program.  Run the program with "-d" to disable the card,
+ * or "-e" to enable the card.
+ */
+int main(int argc, char *argv[])
+{
+    fd = open("/dev/watchdog", O_WRONLY);
+
+    if (fd == -1) {
+        fprintf(stderr, "Watchdog device not enabled.\n");
+        fflush(stderr);
+        exit(-1);
+    }
+
+    if (argc > 1) {
+        if (!strncasecmp(argv[1], "-d", 2)) {
+            ioctl(fd, WDIOC_SETOPTIONS, WDIOS_DISABLECARD);
+            fprintf(stderr, "Watchdog card disabled.\n");
+            fflush(stderr);
+            exit(0);
+        } else if (!strncasecmp(argv[1], "-e", 2)) {
+            ioctl(fd, WDIOC_SETOPTIONS, WDIOS_ENABLECARD);
+            fprintf(stderr, "Watchdog card enabled.\n");
+            fflush(stderr);
+            exit(0);
+        } else {
+            fprintf(stderr, "-d to disable, -e to enable.\n");
+            fprintf(stderr, "run by itself to tick the card.\n");
+            fflush(stderr);
+            exit(0);
+        }
+    } else {
+        fprintf(stderr, "Watchdog Ticking Away!\n");
+        fflush(stderr);
+    }
+
+    while(1) {
+        keep_alive();
+        sleep(1);
+    }
+}
diff --git a/Documentation/watchdog/watchdog-api.txt b/Documentation/watchdog/watchdog-api.txt
index 21ed51173662..958ff3d48be3 100644
--- a/Documentation/watchdog/watchdog-api.txt
+++ b/Documentation/watchdog/watchdog-api.txt
@@ -34,22 +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
-like this:
-
-#include <stdlib.h>
-#include <fcntl.h>
-
-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.
@@ -110,7 +95,40 @@ current timeout using the GETTIMEOUT ioctl.
     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
@@ -169,6 +187,10 @@ The watchdog saw a keepalive ping since it was last queried.
 
         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
diff --git a/Documentation/watchdog/watchdog.txt b/Documentation/watchdog/watchdog.txt
index dffda29c8799..4b1ff69cc19a 100644
--- a/Documentation/watchdog/watchdog.txt
+++ b/Documentation/watchdog/watchdog.txt
@@ -65,28 +65,7 @@ The external event interfaces on the WDT boards are not currently supported.
 Minor numbers are however allocated for it.
 
 
-Example Watchdog Driver
------------------------
-
-#include <stdio.h>
-#include <unistd.h>
-#include <fcntl.h>
-
-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);
-                fsync(fd);
-                sleep(10);
-        }
-}
+Example Watchdog Driver:  see Documentation/watchdog/src/watchdog-simple.c
 
 
 Contact Information