Removed all of the old, malformed RTC interface definitions from include/nuttx/rtc.h. The necessary prototypes have been removed, renamed, scattered to the wind, hidden under rocks, -- whatever it takes to make it clear that there is no RTC interface callable from application code.

2 files changed, 324 insertions, 0 deletions

diff --git a/nuttx/include/nuttx/fs/ioctl.h b/nuttx/include/nuttx/fs/ioctl.h
index 8f0835755..25ca1c9ef 100644
--- a/nuttx/include/nuttx/fs/ioctl.h
+++ b/nuttx/include/nuttx/fs/ioctl.h
@@ -74,6 +74,7 @@
 #define _DJOYBASE       (0x1500) /* Discrete joystick ioctl commands */
 #define _AJOYBASE       (0x1600) /* Analog joystick ioctl commands */
 #define _PIPEBASE       (0x1700) /* FIFO/pipe ioctl commands */
+#define _RTCBASE        (0x1800) /* RTC ioctl commands */
 
 /* Macros used to manage ioctl commands */
 
@@ -329,6 +330,12 @@
                                               *     1=fre when empty
                                               * OUT: None */
 
+/* RTC driver ioctl definitions *********************************************/
+/* (see nuttx/include/rtc.h */
+
+#define _RTCIOCVALID(c)   (_IOC_TYPE(c)==_RTCBASE)
+#define _RTCIOC(nr)       _IOC(_RTCBASE,nr)
+
 /****************************************************************************
  * Public Type Definitions
  ****************************************************************************/
diff --git a/nuttx/include/nuttx/rtc.h b/nuttx/include/nuttx/rtc.h
index 09440f08e..20d498c48 100644
--- a/nuttx/include/nuttx/rtc.h
+++ b/nuttx/include/nuttx/rtc.h
@@ -46,6 +46,10 @@
  ****************************************************************************/
 
 #include <nuttx/config.h>
+#include <nuttx/compiler.h>
+#include <nuttx/fs/ioctl.h>
+
+#ifdef CONFIG_RTC
 
 /****************************************************************************
  * Pre-processor Definitions
@@ -80,6 +84,8 @@
  *
  * CONFIG_RTC_ALARM - Enable if the RTC hardware supports setting of an
  *   alarm.  A callback function will be executed when the alarm goes off
+ *
+ * CONFIG_RTC_DRIVER - Enable building the upper-half RTC driver
  */
 
 #ifdef CONFIG_RTC_HIRES
@@ -98,9 +104,307 @@
 #  endif
 #endif
 
+/* The remainder of the contain of this header file is only valid if the
+ * RTC upper half driver is built.
+ */
+
+#if CONFIG_RTC_DRIVER
+
+/* IOCTL Commands ***********************************************************/
+/* RTC driver IOCTL commands.  These are Linux compatible command names, not
+ * all of these commands are supported by all RTC drivers, however.
+ */
+
+/* RTC_RD_TIME returns the current RTC time.
+ *
+ * Argument: A writeable reference to a struct rtc_time to receive the RTC's
+ * time.
+ */
+
+#define RTC_RD_TIME        _RTCIOC(0x0001)
+
+/* RTC_SET_TIME sets the RTC's time
+ *
+ * Argument: A read-only reference to a struct rtc_time containing the the
+ *           new time to be set.
+ */
+
+#define RTC_SET_TIME       _RTCIOC(0x0002)
+ 
+/* RTC_ALM_READ reads the alarm time (for RTCs that support alarms)
+ *
+ * Argument: A writeable reference to a struct rtc_time to receive the RTC's
+ *           alarm time.
+ */
+ 
+#define RTC_ALM_READ       _RTCIOC(0x0003)
+
+/* RTC_ALM_SET sets the alarm time (for RTCs that support alarms).
+ *
+ * Argument: A read-only reference to a struct rtc_time containing the the
+ *           new alarm time to be set.
+ */
+
+#define RTC_ALM_SET        _RTCIOC(0x0004)
+
+/* RTC_IRQP_READ read the frequency for periodic interrupts (for RTCs that
+ * support periodic interrupts)
+ *
+ * Argument: A pointer to a writeable unsigned long value in which to
+ *           receive the frequency value.
+ */
+
+#define RTC_IRQP_READ      _RTCIOC(0x0005)
+
+/* RTC_IRQP_SET set the frequency for periodic interrupts (for RTCs that
+ * support periodic interrupts)
+ *
+ * Argument: An unsigned long value providing the new periodic frequency
+ */
+
+#define RTC_IRQP_SET       _RTCIOC(0x0006)
+
+/* RTC_AIE_ON enable alarm interrupts (for RTCs that support alarms)
+ *
+ * Argument: None
+ */
+
+#define RTC_AIE_ON         _RTCIOC(0x0007)
+
+/* RTC_AIE_OFF disable the alarm interrupt (for RTCs that support alarms)
+ *
+ * Argument: None
+ */
+ 
+#define RTC_AIE_OFF        _RTCIOC(0x0008)
+
+/* RTC_UIE_ON enable the interrupt on every clock update (for RTCs that
+ * support this once-per-second interrupt).
+ *
+ * Argument: None
+ */
+
+#define RTC_UIE_ON         _RTCIOC(0x0009)
+
+/* RTC_UIE_OFF disable the interrupt on every clock update (for RTCs that
+ * support this once-per-second interrupt).
+ *
+ * Argument: None
+ */
+
+#define RTC_UIE_OFF        _RTCIOC(0x000a)
+ 
+/* RTC_PIE_ON enable the periodic interrupt (for RTCs that support these
+ * periodic interrupts).
+ *
+ * Argument: None
+ */
+
+#define RTC_PIE_ON         _RTCIOC(0x000b)
+ 
+/* RTC_PIE_OFF disable the periodic interrupt (for RTCs that support these
+ * periodic interrupts).
+ *
+ * Argument: None
+ */
+
+#define RTC_PIE_OFF        _RTCIOC(0x000c)
+ 
+/* RTC_EPOCH_READ and RTC_EPOCH_SET.
+ *
+ * Many RTCs encode the year in an 8-bit register which is either interpreted
+ * as an 8-bit binary number or as a BCD number. In both cases, the number is
+ * interpreted relative to this RTC's Epoch. The RTC's Epoch is initialized to
+ * 1900 on most systems but on Alpha and MIPS it might also be initialized to
+ * 1952, 1980, or 2000, depending on the value of an RTC register for the year.
+ * With some RTCs, these operations can be used to read or to set the RTC's
+ * Epoch, respectively.
+ */
+
+/* RTC_EPOCH_READ read the Epoch.
+ *
+ * Argument: A reference to a writeable unsigned low variable that will
+ *           receive the the Epoch value.
+ */
+
+#define RTC_EPOCH_READ     _RTCIOC(0x000d)
+ 
+/* RTC_EPOCH_SET set the Epoch
+ *
+ * Argument: An unsigned long value containing the new Epoch value to be set.
+ */
+
+#define RTC_EPOCH_SET      _RTCIOC(0x000e)
+
+/* RTC_WKALM_RD and RTC_WKALM_SET.
+ *
+ * Some RTCs support a more powerful alarm interface, using these ioctls to
+ * read or write the RTC's alarm time (respectively) with the rtc_wkalrm.
+ */
+
+/* RTC_WKALM_RD read the current alarm
+ *
+ * Argument: A writeable reference to struct rtc_wkalrm to receive the
+ *           current alarm settings.
+ */
+
+#define RTC_WKALM_RD       _RTCIOC(0x000f)
+
+/* RTC_WKALM_SET set the alarm.
+ *
+ * Argument: A read-only reference to struct rtc_wkalrm containing the
+ *           new alarm settings.
+ */
+
+#define RTC_WKALM_SET      _RTCIOC(0x0010)
+
 /****************************************************************************
  * Public Types
  ****************************************************************************/
+/* IOCTL data structures */
+
+/* Broken-out time representation used with RTC IOCTL commands:
+ *
+ * The fields in this structure have the same meaning and ranges as for the
+ * tm structure described in gmtime(). 
+ */
+
+struct rtc_time 
+{
+  int tm_sec;
+  int tm_min;
+  int tm_hour;
+  int tm_mday;
+  int tm_mon;
+  int tm_year;
+  int tm_wday;     /* unused */
+  int tm_yday;     /* unused */
+  int tm_isdst;    /* unused */
+};
+
+/* Structure used with the RTC_WKALM_RD and RTC_WKALM_SET IOCTL commands.
+ *
+ * The enabled flag is used to enable or disable the alarm interrupt, or to
+ * read its current status; when using these calls, RTC_AIE_ON and
+ * RTC_AIE_OFF are not used. The pending flag is used by RTC_WKALM_RD to
+ * report a pending interrupt . The time field is as used with RTC_ALM_READ
+ * and RTC_ALM_SET except that the tm_mday, tm_mon, and tm_year fields are
+ * also valid.
+ */
+
+struct rtc_wkalrm
+{
+  unsigned char enabled;
+  unsigned char pending;
+  struct rtc_time time;
+};
+
+/* The RTC driver is implemented as a common, upper-half character driver
+ * that provides the RTC driver structure and a lower-level, hardware
+ * specific implementation that performs the actual RTC operations.
+ *
+ * struct rtc_ops_s defines the callable interface from the common upper-
+ * half driver into lower half implementation.  Each method in this
+ * structure corresponds to one of the RTC IOCTL commands.  All IOCTL
+ * command logic is implemented in the lower-half driver.
+ *
+ * A NULL value should be provided for any unsupported  methods.
+ */
+
+struct rtc_lowerhalf_f;
+struct rtc_ops_s
+{
+  
+  /* rdtime() returns the current RTC time. */
+
+  CODE int (*rdtime)(FAR struct rtc_lowerhalf_f *lower,
+                     FAR struct rtc_time *rtctime);
+
+  /* settime sets the RTC's time */
+
+  CODE int (*settime)(FAR struct rtc_lowerhalf_f *lower,
+                      FAR const struct rtc_time *rtctime);
+
+ 
+  /* almread reads the alarm time (for RTCs that support alarms) */
+
+  CODE int (*almread)(FAR struct rtc_lowerhalf_f *lower,
+                      FAR struct rtc_time *almtime);
+ 
+  /* almset sets the alarm time (for RTCs that support alarms). */
+
+  CODE int (*almset)(FAR struct rtc_lowerhalf_f *lower,
+                     FAR const struct rtc_time *almtime);
+
+  /* irqpread the frequency for periodic interrupts (for RTCs that support
+   * periodic interrupts)
+   */
+
+  CODE int (*irqpread)(FAR struct rtc_lowerhalf_f *lower,
+                       FAR unsigned long *irqpfreq);
+
+  /* irqpset set the frequency for periodic interrupts (for RTCs that
+   * support periodic interrupts)
+   */
+
+  CODE int (*irqpset)(FAR struct rtc_lowerhalf_f *lower,
+                      unsigned long irqpfreq);
+
+  /* aie enable/disable alarm interrupts (for RTCs that support alarms) */
+
+  CODE int (*aie)(FAR struct rtc_lowerhalf_f *lower, bool enable);
+
+  /* uie enable/disable the interrupt on every clock update (for RTCs that
+   * support this once-per-second interrupt).
+   */
+
+  CODE int (*uie)(FAR struct rtc_lowerhalf_f *lower, bool enable);
+
+  /* pie enable the periodic interrupt (for RTCs that support these periodic
+   * interrupts).
+   */
+
+  CODE int (*pie)(FAR struct rtc_lowerhalf_f *lower, bool enable);
+
+  /* rdepoch read the Epoch. */
+
+  CODE int (*rdepoch)(FAR struct rtc_lowerhalf_f *lower,
+                      FAR unsigned long *epoch);
+ 
+  /* setepoch set the Epoch */
+
+  CODE int (*setepoch)(FAR struct rtc_lowerhalf_f *lower,
+                       unsigned long epoch);
+
+  /* rdwkalm read the current alarm */
+
+  CODE int (*rdwkalm)(FAR struct rtc_lowerhalf_f *lower,
+                      FAR struct rtc_time *rtc_wkalrm);
+
+  /* setwkalm set the alarm. */
+
+  CODE int (*setwkalm)(FAR struct rtc_lowerhalf_f *lower,
+                       FAR const struct rtc_time *rtc_wkalrm);
+};
+
+/* When the RTC driver is instantiated, a reference to struct
+ * rtc_lowerhalf_s is passed to the initialization function and bound to
+ * the driver.  The actual content of the state structure used by different
+ * lower half drivers will vary from implementation to implementation.  But
+ * each implementation must be cast compatible with this definition of
+ * struct rtc_lowerhalf_s that is understood by the upper half driver.
+ */
+
+struct rtc_lowerhalf_s
+{
+  /* This is the contained reference to the read-only, lower-half
+   * operations vtable (which may lie in FLASH or ROM)
+   */
+
+  FAR const struct rtc_ops_s *ops;
+
+  /* Data following this can vary from RTC driver to driver */
+};
 
 /****************************************************************************
  * Public Data
@@ -119,10 +423,23 @@ extern "C"
  * Public Functions
  ****************************************************************************/
 
+/****************************************************************************
+ * Name: rtc_initialize
+ *
+ * Description:
+ *   Create an RTC driver by binding to the lower half RTC driver instance
+ *   provided to this function.  The resulting RTC driver will be registered
+ *   at /dev/rtcN where N is the minor number provided to this function.
+ *
+ ****************************************************************************/
+
+int rtc_initialize(int minor, FAR struct rtc_lowerhalf_s *lower);
 
 #undef EXTERN
 #if defined(__cplusplus)
 }
 #endif
 
+#enif /* CONFIG_RTC_DRIVER */
+#enif /* CONFIG_RTC */
 #endif /* __INCLUDE_NUTTX_RTC_H */