Add a header file that defines a standard watchdog timer driver

git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@4603 42af7a65-404d-4744-a932-0658087f49c3

ChangeLog

@@ -2649,3 +2649,5 @@
 	* include/nuttx/usb/usbdev.h, drivers/usbdev/*, arch/*/src/*/*usb*.c:
 	  Extend the USB device side interface so that EP0 OUT data can be passed
 	  with OUT SETUP requests.
+	* include/nuttx/watchdog.h:  Add the definition of a standard watchdog
+	  driver interface.

Documentation/NuttxPortingGuide.html

@@ -12,7 +12,7 @@
       <h1><big><font color="#3c34ec">
         <i>NuttX RTOS Porting Guide</i>
       </font></big></h1>
-      <p>Last Updated: March 23, 2011</p>
+      <p>Last Updated: April 13, 2011</p>
     </td>
   </tr>
 </table>
@@ -129,7 +129,8 @@
        <a href="#analogdrivers">6.3.11 Analog (ADC/DAC) Drivers</a><br>
        <a href="#pwmdrivers">6.3.12 PWM Drivers</a><br>
        <a href="#candrivers">6.3.13 CAN Drivers</a><br>
-       <a href="#quadencoder">6.3.14 Quadrature Encoder Drivers</a>
+       <a href="#quadencoder">6.3.14 Quadrature Encoder Drivers</a><br>
+       <a href="#wdogdriver">6.3.15 Watchdog Timer Drivers</a>
     </ul>
     <a href="#pwrmgmt">6.4 Power Management</a>
     <ul>
@@ -3261,7 +3262,7 @@ extern void up_ledoff(int led);
 
 <h3><a name="quadencoder">6.3.14 Quadrature Encoder Drivers</a></h3>
 <p>
-  NuttX supports only a low-level, two-part Quadrature Driver driver.
+  NuttX supports a low-level, two-part Quadrature Encoder driver.
 </p>
 <ol>
   <li>
@@ -3288,6 +3289,35 @@ extern void up_ledoff(int led);
   </li>
 </ul>
 
+<h3><a name="wdogdriver">6.3.15 Watchdog Timer Drivers</a></h3>
+<p>
+  NuttX supports a low-level, two-part watchdog timer driver.
+</p>
+<ol>
+  <li>
+    An &quot;upper half&quot;, generic driver that provides the comman watchdog timer interface to application level code, and
+  </li>
+  <li>
+    A &quot;lower half&quot;, platform-specific driver that implements the low-level timer controls to implement the watchdog timer functionality.
+  </li>
+</ol>
+<p>
+  Files supporting the watchdog timer can be found in the following locations:
+</p>
+<ul>
+  <li><b>Interface Definition</b>.
+    The header file for the NuttX watchdog timer driver reside at <code>include/nuttx/watchdog.h</code>.
+    This header file includes both the application level interface to the watchdog timer driver as well as the interface between the &quot;upper half&quot; and &quot;lower half&quot; drivers.
+    The watchdog timer driver uses a standard character driver framework.
+  </li>
+  <li><b>&quot;Upper Half&quot; Driver</b>.
+    The generic, &quot;upper half&quot; watchdog timer driver resides at <code>drivers/watchdog.c</code>.
+  </li>
+  <li><b>&quot;Lower Half&quot; Drivers</b>.
+    Platform-specific watchdog timer drivers reside in <code>arch/</code><i>&lt;architecture&gt;</i><code>/src/</code><i>&lt;chip&gt;</i> directory for the specific processor <i>&lt;architecture&gt;</i> and for the specific <i>&lt;chip&gt;</i> watchdog timer peripheral devices.
+  </li>
+</ul>
+
 <h2><a name="pwrmgmt">6.4 Power Management</a></h2>
 
 <h3><a name="pmoverview">6.4.1 Overview</a></h3>

include/nuttx/fs/ioctl.h

@@ -89,8 +89,6 @@
 #define _WDIOCVALID(c)  (_IOC_TYPE(c)==_WDIOCBASE)
 #define _WDIOC(nr)      _IOC(_WDIOCBASE,nr)
 
-#define WDIOC_KEEPALIVE _WDIOC(0x0001)    /* Restart the watchdog timer */
-
 /* NuttX file system ioctl definitions **************************************/
 
 #define _FIOCVALID(c)   (_IOC_TYPE(c)==_FIOCBASE)

include/nuttx/pwm.h

@@ -79,7 +79,7 @@
  
 /* IOCTL Commands ***********************************************************/
 /* The PWM module uses a standard character driver framework.  However, since
- * the PWM driver is a devices control interface and not a data transfer
+ * the PWM driver is a device control interface and not a data transfer
  * interface, the majority of the functionality is implemented in driver
  * ioctl calls.  The PWM ioctl commands are lised below:
  *

include/nuttx/watchdog.h

@@ -0,0 +1,250 @@
+/****************************************************************************
+ * include/nuttx/watchdog.h
+ *
+ *   Copyright (C) 2012 Gregory Nutt. All rights reserved.
+ *   Author: Gregory Nutt <gnutt@nuttx.org>
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in
+ *    the documentation and/or other materials provided with the
+ *    distribution.
+ * 3. Neither the name NuttX nor the names of its contributors may be
+ *    used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+ * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+ * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+ * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+ * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
+ * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
+ * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ *
+ ****************************************************************************/
+
+#ifndef __INCLUDE_NUTTX_WATCHDOG_H
+#define __INCLUDE_NUTTX_WATCHDOG_H
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+#include <nuttx/fs/ioctl.h>
+
+#ifdef CONFIG_WATCHDOG
+
+/****************************************************************************
+ * Pre-processor Definitions
+ ****************************************************************************/
+/* IOCTL Commands ***********************************************************/
+/* The watchdog driver uses a standard character driver framework.  However,
+ * since the watchdog driver is a device control interface and not a data
+ * transfer interface, the majority of the functionality is implemented in
+ * driver ioctl calls.  The watchdog ioctl commands are lised below:
+ *
+ * WDIOC_START      - Start the watchdog timer
+ *                    Argument: Ignored
+ * WDIOC_START      - Stop the watchdog timer
+ *                    Argument: Ignored
+ * WDIOC_GETSTATUS  - Get the status of the watchdog timer.
+ *                    Argument:  A writeable pointer to struct watchdog_status_s.
+ * WDIOC_SETTIMEOUT - Reset the watchdog timeout to this value
+ *                    Argument: A 32-bit timeout value in milliseconds.
+ * WDIOC_CAPTURE    - Do not reset.  Instead, called this handler.
+ *                    Argument: A pointer to struct watchdog_capture_s.
+ * WDIOC_KEEPALIVE  - Reset the watchdog timer ("ping", "pet the dog");
+ *                    Argument: Ignored
+ */
+
+#define WDIOC_START      _WDIOC(0x001)
+#define WDIOC_STOP       _WDIOC(0x002)
+#define WDIOC_GETSTATUS  _WDIOC(0x003)
+#define WDIOC_SETTIMEOUT _WDIOC(0x004)
+#define WDIOC_CAPTURE    _WDIOC(0x005)
+#define WDIOC_KEEPALIVE  _WDIOC(0x006)
+
+/* Bit Settings *************************************************************/
+/* Bit settings for the struct watchdog_status_s flags field */
+
+#define WDFLAGS_ACTIVE   (1 << 0) /* 1=The watchdog timer is running */
+#define WDFLAGS_RESET    (1 << 1) /* 1=Reset when the watchog timer expires */
+#define WDFLAGS_CAPTURE  (1 << 2) /* 1=Call the user function when the
+                                   *   watchdog timer expires */
+
+/****************************************************************************
+ * Public Types
+ ****************************************************************************/
+/* This is the type of the argument passed to the WDIOC_CAPTURE ioctl */
+
+struct watchdog_capture_s
+{
+  CODE xcpt_t newhandler;   /* The new watchdog capture handler */
+  CODE xcpt_t oldhandler;   /* The previous watchdog capture handler (if any) */
+};
+
+/* This is the type of the argument passed to the WDIOC_GETSTATUS ioctl and
+ * and returned by the "lower half" getstatus() method.
+ */
+
+struct watchdog_status_s 
+{
+  uint32_t  flags;          /* See WDFLAGS_* definitions above */
+  uint32_t  timeout;        /* The current timeout setting (in milliseconds) */
+  uint32_t  timeleft;       /* Time left until the watchdog expiration
+                             * (in milliseconds) */
+};
+
+/* This structure provides the "lower-half" driver operations available to
+ * the "upper-half" driver.
+ */
+
+struct watchdog_lowerhalf_s;
+struct watchdog_ops_s 
+{
+  /* Required methods ********************************************************/
+  /* Start the watchdog timer, resetting the time to the current timeout */
+
+  CODE int (*start)(FAR struct watchdog_lowerhalf_s *lower);
+
+  /* Stop the watchdog timer */
+
+  CODE int (*stop)(FAR struct watchdog_lowerhalf_s *lower);
+
+  /* Optional methods ********************************************************/
+  /* Reset the watchdog timer to the current timeout value, prevent any
+   * imminent watchdog timeouts.  This is sometimes referred as "pinging" the
+   * watchdog timer or "petting the dog".
+   */
+
+  CODE int (*keepalive)(FAR struct watchdog_lowerhalf_s *lower);
+
+  /* Get the current watchdog timer status */
+
+  CODE int (*getstatus)(FAR struct watchdog_lowerhalf_s *lower,
+                        FAR watchdog_state_s *status);
+
+  /* Set a new timeout value (and reset the watchdog timer) */
+
+  CODE int (*settimeout)(FAR struct watchdog_lowerhalf_s *lower,
+                         uint32_t timeout);
+
+  /* Don't reset on watchdog timer timeout; instead, call this user provider
+   * timeout handler.  NOTE:  Providing handler==NULL will store the reset
+   * behavior.
+   */
+
+  CODE xcpt_t (*capture)(FAR struct watchdog_lowerhalf_s *lower,
+                         xcpt_t handler);
+
+  /* An ioctl commands that are not recognized by the "upper-half" driver
+   * are forwarded to the lower half driver through this method.
+   */
+
+  CODE int (*ioctl)(FAR struct watchdog_lowerhalf_s *lower, int cmd,
+                    unsigned long arg);
+};
+
+/* This structure provides the publicly visible representation of the
+ * "lower-half" driver state structure.  "lower half" drivers will have an
+ * internal structure definition that will be cast-compatible with this
+ * structure definitions.
+ */
+
+struct watchdog_lowerhalf_s
+{
+  /* Publicly visible portion of the "lower-half" driver state structure. */
+
+  FAR const struct watchdog_ops_s  *ops;  /* Lower half operations */
+
+  /* The remainder of the structure is used by the "lower-half" driver
+   * for whatever state storage that it may need.
+   */
+};
+
+/****************************************************************************
+ * Public Data
+ ****************************************************************************/
+
+/****************************************************************************
+ * Public Function Prototypes
+ ****************************************************************************/
+
+#ifdef __cplusplus
+#define EXTERN extern "C"
+extern "C" {
+#else
+#define EXTERN extern
+#endif
+
+/****************************************************************************
+ * "Upper-Half" Watchdog Driver Interfaces
+ ****************************************************************************/
+/****************************************************************************
+ * Name: watchdog_register
+ *
+ * Description:
+ *   This function binds an instance of a "lower half" watchdog driver with the
+ *   "upper half" watchdog device and registers that device so that can be used
+ *   by application code.
+ *
+ *   When this function is called, the "lower half" driver should be in the
+ *   disabled state (as if the stop() method had already been called).
+ *
+ * Input parameters:
+ *   dev path - The full path to the driver to be registers in the NuttX
+ *     pseudo-filesystem.  The recommended convention is to name all watchdog
+ *     drivers as "/dev/watchdog0", "/dev/watchdog1", etc.  where the driver
+ *     path differs only in the "minor" number at the end of the device name.
+ *   lower - A pointer to an instance of lower half watchdog driver.  This
+ *     instance is bound to the watchdog driver and must persists as long as
+ *     the driver persists.
+ *
+ * Returned Value:
+ *   On success, a non-NULL handle is returned to the caller.  In the event
+ *   of any failure, a NULL value is returned.
+ *
+ ****************************************************************************/
+
+FAR void *watchdog_register(FAR const char *path,
+                            FAR struct watchdog_lowerhalf_s *lower);
+
+/****************************************************************************
+ * Name: watchdog_unregister
+ *
+ * Description:
+ *   This function can be called to disable and unregister the watchdog
+ *   device driver.
+ *
+ * Input parameters:
+ *   handle - This is the handle that was returned by watchdog_register()
+ *
+ * Returned Value:
+ *   None
+ *
+ ****************************************************************************/
+
+EXTERN void watchdog_unregister(FAR void *handle);
+
+/****************************************************************************
+ * Platform-Independent "Lower-Half" Watchdog Driver Interfaces
+ ****************************************************************************/
+
+#undef EXTERN
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* CONFIG_WATCHDOG */
+#endif  /* __INCLUDE_NUTTX_WATCHDOG_H */