summaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2011-07-29 23:28:47 -0700
committerLinus Torvalds <torvalds@linux-foundation.org>2011-07-29 23:28:47 -0700
commit2313bcdcc9ff1e42f51b200dc65ddaae14c347f4 (patch)
treefdb0e3f953841cdd661e36c40a965c9e044d82f5 /Documentation
parent59ed2bb27492f74ab898ee1e26c69dfd78444640 (diff)
parent3f43f68e29f1dcb853d70280c7412fc0ef9a0da6 (diff)
downloadlinux-2313bcdcc9ff1e42f51b200dc65ddaae14c347f4.tar.bz2
Merge git://git.kernel.org/pub/scm/linux/kernel/git/wim/linux-watchdog
* git://git.kernel.org/pub/scm/linux/kernel/git/wim/linux-watchdog: (25 commits) watchdog: WatchDog Timer Driver Core - Add minimum and max timeout watchdog: WatchDog Timer Driver Core - Add ioctl call watchdog: WatchDog Timer Driver Core - Add nowayout feature watchdog: WatchDog Timer Driver Core - Add Magic Close feature watchdog: WatchDog Timer Driver Core - Add WDIOC_SETTIMEOUT and WDIOC_GETTIMEOUT ioctl watchdog: WatchDog Timer Driver Core - Add WDIOC_SETOPTIONS ioctl watchdog: WatchDog Timer Driver Core - Add WDIOC_KEEPALIVE ioctl watchdog: WatchDog Timer Driver Core - Add basic ioctl functionality watchdog: WatchDog Timer Driver Core - Add basic framework watchdog: hpwdt: add next gen HP servers watchdog: it8712f_wdt.c: improve includes watchdog: at91sam9/wdt: move register header to drivers watchdog: Add Xilinx watchdog timer driver watchdog: remove empty pm-functions watchdog: sp805: Flush posted writes in enable/disable. watchdog: sp805: Don't write 0 to the load value register. watchdog: imx2_wdt: add device tree probe support watchdog: s3c2410: Add support for device tree based probe watchdog: mpcore_wdt: Add suspend/resume support. watchdog: mtx1-wdt: use dev_{err,info} instead of printk() ...
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/devicetree/bindings/watchdog/fsl-imx-wdt.txt14
-rw-r--r--Documentation/devicetree/bindings/watchdog/samsung-wdt.txt11
-rw-r--r--Documentation/watchdog/00-INDEX2
-rw-r--r--Documentation/watchdog/watchdog-kernel-api.txt162
4 files changed, 189 insertions, 0 deletions
diff --git a/Documentation/devicetree/bindings/watchdog/fsl-imx-wdt.txt b/Documentation/devicetree/bindings/watchdog/fsl-imx-wdt.txt
new file mode 100644
index 000000000000..2144af1a5264
--- /dev/null
+++ b/Documentation/devicetree/bindings/watchdog/fsl-imx-wdt.txt
@@ -0,0 +1,14 @@
+* Freescale i.MX Watchdog Timer (WDT) Controller
+
+Required properties:
+- compatible : Should be "fsl,<soc>-wdt"
+- reg : Should contain WDT registers location and length
+- interrupts : Should contain WDT interrupt
+
+Examples:
+
+wdt@73f98000 {
+ compatible = "fsl,imx51-wdt", "fsl,imx21-wdt";
+ reg = <0x73f98000 0x4000>;
+ interrupts = <58>;
+};
diff --git a/Documentation/devicetree/bindings/watchdog/samsung-wdt.txt b/Documentation/devicetree/bindings/watchdog/samsung-wdt.txt
new file mode 100644
index 000000000000..79ead8263ae4
--- /dev/null
+++ b/Documentation/devicetree/bindings/watchdog/samsung-wdt.txt
@@ -0,0 +1,11 @@
+* Samsung's Watchdog Timer Controller
+
+The Samsung's Watchdog controller is used for resuming system operation
+after a preset amount of time during which the WDT reset event has not
+occured.
+
+Required properties:
+- compatible : should be "samsung,s3c2410-wdt"
+- reg : base physical address of the controller and length of memory mapped
+ region.
+- interrupts : interrupt number to the cpu.
diff --git a/Documentation/watchdog/00-INDEX b/Documentation/watchdog/00-INDEX
index ee994513a9b1..fc51128071c2 100644
--- a/Documentation/watchdog/00-INDEX
+++ b/Documentation/watchdog/00-INDEX
@@ -8,6 +8,8 @@ src/
- directory holding watchdog related example programs.
watchdog-api.txt
- description of the Linux Watchdog driver API.
+watchdog-kernel-api.txt
+ - description of the Linux WatchDog Timer Driver Core kernel API.
watchdog-parameters.txt
- information on driver parameters (for drivers other than
the ones that have driver-specific files here)
diff --git a/Documentation/watchdog/watchdog-kernel-api.txt b/Documentation/watchdog/watchdog-kernel-api.txt
new file mode 100644
index 000000000000..4f7c894244d2
--- /dev/null
+++ b/Documentation/watchdog/watchdog-kernel-api.txt
@@ -0,0 +1,162 @@
+The Linux WatchDog Timer Driver Core kernel API.
+===============================================
+Last reviewed: 22-Jul-2011
+
+Wim Van Sebroeck <wim@iguana.be>
+
+Introduction
+------------
+This document does not describe what a WatchDog Timer (WDT) Driver or Device is.
+It also does not describe the API which can be used by user space to communicate
+with a WatchDog Timer. If you want to know this then please read the following
+file: Documentation/watchdog/watchdog-api.txt .
+
+So what does this document describe? It describes the API that can be used by
+WatchDog Timer Drivers that want to use the WatchDog Timer Driver Core
+Framework. This framework provides all interfacing towards user space so that
+the same code does not have to be reproduced each time. This also means that
+a watchdog timer driver then only needs to provide the different routines
+(operations) that control the watchdog timer (WDT).
+
+The API
+-------
+Each watchdog timer driver that wants to use the WatchDog Timer Driver Core
+must #include <linux/watchdog.h> (you would have to do this anyway when
+writing a watchdog device driver). This include file contains following
+register/unregister routines:
+
+extern int watchdog_register_device(struct watchdog_device *);
+extern void watchdog_unregister_device(struct watchdog_device *);
+
+The watchdog_register_device routine registers a watchdog timer device.
+The parameter of this routine is a pointer to a watchdog_device structure.
+This routine returns zero on success and a negative errno code for failure.
+
+The watchdog_unregister_device routine deregisters a registered watchdog timer
+device. The parameter of this routine is the pointer to the registered
+watchdog_device structure.
+
+The watchdog device structure looks like this:
+
+struct watchdog_device {
+ const struct watchdog_info *info;
+ const struct watchdog_ops *ops;
+ unsigned int bootstatus;
+ unsigned int timeout;
+ unsigned int min_timeout;
+ unsigned int max_timeout;
+ void *driver_data;
+ unsigned long status;
+};
+
+It contains following fields:
+* info: a pointer to a watchdog_info structure. This structure gives some
+ additional information about the watchdog timer itself. (Like it's unique name)
+* ops: a pointer to the list of watchdog operations that the watchdog supports.
+* timeout: the watchdog timer's timeout value (in seconds).
+* min_timeout: the watchdog timer's minimum timeout value (in seconds).
+* max_timeout: the watchdog timer's maximum timeout value (in seconds).
+* bootstatus: status of the device after booting (reported with watchdog
+ WDIOF_* status bits).
+* driver_data: a pointer to the drivers private data of a watchdog device.
+ This data should only be accessed via the watchdog_set_drvadata and
+ watchdog_get_drvdata routines.
+* status: this field contains a number of status bits that give extra
+ information about the status of the device (Like: is the watchdog timer
+ running/active, is the nowayout bit set, is the device opened via
+ the /dev/watchdog interface or not, ...).
+
+The list of watchdog operations is defined as:
+
+struct watchdog_ops {
+ struct module *owner;
+ /* mandatory operations */
+ int (*start)(struct watchdog_device *);
+ int (*stop)(struct watchdog_device *);
+ /* optional operations */
+ int (*ping)(struct watchdog_device *);
+ unsigned int (*status)(struct watchdog_device *);
+ int (*set_timeout)(struct watchdog_device *, unsigned int);
+ long (*ioctl)(struct watchdog_device *, unsigned int, unsigned long);
+};
+
+It is important that you first define the module owner of the watchdog timer
+driver's operations. This module owner will be used to lock the module when
+the watchdog is active. (This to avoid a system crash when you unload the
+module and /dev/watchdog is still open).
+Some operations are mandatory and some are optional. The mandatory operations
+are:
+* start: this is a pointer to the routine that starts the watchdog timer
+ device.
+ The routine needs a pointer to the watchdog timer device structure as a
+ parameter. It returns zero on success or a negative errno code for failure.
+* stop: with this routine the watchdog timer device is being stopped.
+ The routine needs a pointer to the watchdog timer device structure as a
+ parameter. It returns zero on success or a negative errno code for failure.
+ Some watchdog timer hardware can only be started and not be stopped. The
+ driver supporting this hardware needs to make sure that a start and stop
+ routine is being provided. This can be done by using a timer in the driver
+ that regularly sends a keepalive ping to the watchdog timer hardware.
+
+Not all watchdog timer hardware supports the same functionality. That's why
+all other routines/operations are optional. They only need to be provided if
+they are supported. These optional routines/operations are:
+* ping: this is the routine that sends a keepalive ping to the watchdog timer
+ hardware.
+ The routine needs a pointer to the watchdog timer device structure as a
+ parameter. It returns zero on success or a negative errno code for failure.
+ Most hardware that does not support this as a separate function uses the
+ start function to restart the watchdog timer hardware. And that's also what
+ the watchdog timer driver core does: to send a keepalive ping to the watchdog
+ timer hardware it will either use the ping operation (when available) or the
+ start operation (when the ping operation is not available).
+ (Note: the WDIOC_KEEPALIVE ioctl call will only be active when the
+ WDIOF_KEEPALIVEPING bit has been set in the option field on the watchdog's
+ info structure).
+* status: this routine checks the status of the watchdog timer device. The
+ status of the device is reported with watchdog WDIOF_* status flags/bits.
+* set_timeout: this routine checks and changes the timeout of the watchdog
+ timer device. It returns 0 on success, -EINVAL for "parameter out of range"
+ and -EIO for "could not write value to the watchdog". On success the timeout
+ value of the watchdog_device will be changed to the value that was just used
+ to re-program the watchdog timer device.
+ (Note: the WDIOF_SETTIMEOUT needs to be set in the options field of the
+ watchdog's info structure).
+* ioctl: if this routine is present then it will be called first before we do
+ our own internal ioctl call handling. This routine should return -ENOIOCTLCMD
+ if a command is not supported. The parameters that are passed to the ioctl
+ call are: watchdog_device, cmd and arg.
+
+The status bits should (preferably) be set with the set_bit and clear_bit alike
+bit-operations. The status bits that are defined are:
+* WDOG_ACTIVE: this status bit indicates whether or not a watchdog timer device
+ is active or not. When the watchdog is active after booting, then you should
+ set this status bit (Note: when you register the watchdog timer device with
+ this bit set, then opening /dev/watchdog will skip the start operation)
+* WDOG_DEV_OPEN: this status bit shows whether or not the watchdog device
+ was opened via /dev/watchdog.
+ (This bit should only be used by the WatchDog Timer Driver Core).
+* WDOG_ALLOW_RELEASE: this bit stores whether or not the magic close character
+ has been sent (so that we can support the magic close feature).
+ (This bit should only be used by the WatchDog Timer Driver Core).
+* WDOG_NO_WAY_OUT: this bit stores the nowayout setting for the watchdog.
+ If this bit is set then the watchdog timer will not be able to stop.
+
+Note: The WatchDog Timer Driver Core supports the magic close feature and
+the nowayout feature. To use the magic close feature you must set the
+WDIOF_MAGICCLOSE bit in the options field of the watchdog's info structure.
+The nowayout feature will overrule the magic close feature.
+
+To get or set driver specific data the following two helper functions should be
+used:
+
+static inline void watchdog_set_drvdata(struct watchdog_device *wdd, void *data)
+static inline void *watchdog_get_drvdata(struct watchdog_device *wdd)
+
+The watchdog_set_drvdata function allows you to add driver specific data. The
+arguments of this function are the watchdog device where you want to add the
+driver specific data to and a pointer to the data itself.
+
+The watchdog_get_drvdata function allows you to retrieve driver specific data.
+The argument of this function is the watchdog device where you want to retrieve
+data from. The function retruns the pointer to the driver specific data.