Add clock_synchronize() which may be used to re-synchonize the system time with an RTC after recovering from a low power state

git-svn-id: https://nuttx.svn.sourceforge.net/svnroot/nuttx/trunk@4503 7fd9a85b-ad96-42d3-883c-3090e2eb8679

nuttx/ChangeLog

@@ -2583,3 +2583,8 @@
 	  include/nuttx/fs.
 	* include/nuttx/serial: Move all serial-driver related files from include/nuttx to
 	  include/nuttx/serial.
+	* include/nuttx/clock.h and sched/clock_initialize.c:  Add a new OS interface
+	  called clock_sychronize() that can be used to re-synchronize the NuttX
+	  system time with a hardware RTC.  This function is called normally at power
+	  up but may also need to be called when recovering from certain low-power
+	  usage states where the system time is no longer accurate.

nuttx/include/nuttx/clock.h

@@ -1,8 +1,8 @@
 /****************************************************************************
  * include/nuttx/clock.h
  *
- *   Copyright (C) 2007-2009, 2011 Gregory Nutt. All rights reserved.
+ *   Copyright (C) 2007-2009, 2011-2012 Gregory Nutt. All rights reserved.
- *   Author: Gregory Nutt <spudmonkey@racsa.co.cr>
+ *   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
@@ -33,8 +33,8 @@
  *
  ****************************************************************************/
 
-#ifndef __NUTTX_CLOCK_H
+#ifndef _INCLUDE_NUTTX_CLOCK_H
-#define __NUTTX_CLOCK_H
+#define _INCLUDE_NUTTX_CLOCK_H
 
 /****************************************************************************
  * Included Files
@@ -160,6 +160,38 @@ extern "C" {
 #define EXTERN extern
 #endif
 
+/****************************************************************************
+ * Function:  clock_synchronize
+ *
+ * Description:
+ *   Synchronize the system timer to a hardware RTC.  This operation is
+ *   normally performed automatically by the system during clock
+ *   initialization.  However, the user may also need to explicitly re-
+ *   synchronize the system timer to the RTC under certain conditions where
+ *   the system timer is known to be in error.  For example, in certain low-
+ *   power states, the system timer may be stopped but the RTC will continue
+ *   keep correct time.  After recovering from such low-power state, this
+ *   function should be called to restore the correct system time.
+ *
+ *   Calling this function could result in system time going "backward" in
+ *   time, especially with certain lower resolution RTC implementations.
+ *   Time going backward could have bad consequences if there are ongoing
+ *   timers and delays.  So use this interface with care.
+ *
+ * Parameters:
+ *   None
+ *
+ * Return Value:
+ *   None
+ *
+ * Assumptions:
+ *
+ ****************************************************************************/
+
+#ifdef CONFIG_RTC
+EXTERN void clock_synchronize(void);
+#endif
+
 /****************************************************************************
  * Function:  clock_systimer
  *
@@ -216,4 +248,4 @@ EXTERN uint64_t clock_systimer64(void);
 #endif
 
 #endif /* !CONFIG_DISABLE_CLOCK */
-#endif /* __NUTTX_CLOCK_H */
+#endif /* _INCLUDE_NUTTX_CLOCK_H */

nuttx/sched/clock_initialize.c

@@ -1,8 +1,8 @@
 /****************************************************************************
  * sched/clock_initialize.c
  *
- *   Copyright (C) 2007, 2009, 2011 Gregory Nutt. All rights reserved.
+ *   Copyright (C) 2007, 2009, 2011-2012 Gregory Nutt. All rights reserved.
- *   Author: Gregory Nutt <spudmonkey@racsa.co.cr>
+ *   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
@@ -45,6 +45,10 @@
 #include <errno.h>
 #include <debug.h>
 
+#ifdef CONFIG_RTC
+#  include <arch/irq.h>
+#endif
+
 #include <nuttx/clock.h>
 #include <nuttx/time.h>
 #include <nuttx/rtc.h>
@@ -95,7 +99,7 @@ struct timespec   g_basetime;
  **************************************************************************/
 
 /****************************************************************************
- * Function: clock_inittime
+ * Function: clock_basetime
  *
  * Description:
  *   Get the initial time value from the best source available.
@@ -106,7 +110,7 @@ struct timespec   g_basetime;
 #if defined(CONFIG_RTC_DATETIME)
 /* Initialize the system time using a broken out date/time structure */
 
-static inline void clock_inittime(FAR struct timespec *tp)
+static inline void clock_basetime(FAR struct timespec *tp)
 {
   struct tm rtctime;
 
@@ -124,7 +128,7 @@ static inline void clock_inittime(FAR struct timespec *tp)
 
 /* Initialize the system time using a high-resolution structure */
 
-static inline void clock_inittime(FAR struct timespec *tp)
+static inline void clock_basetime(FAR struct timespec *tp)
 {
   /* Get the complete time from the hi-res RTC. */
 
@@ -135,7 +139,7 @@ static inline void clock_inittime(FAR struct timespec *tp)
 
 /* Initialize the system time using seconds only */
 
-static inline void clock_inittime(FAR struct timespec *tp)
+static inline void clock_basetime(FAR struct timespec *tp)
 {
   /* Get the seconds (only) from the lo-resolution RTC */
 
@@ -146,7 +150,7 @@ static inline void clock_inittime(FAR struct timespec *tp)
 #endif /* CONFIG_RTC_HIRES */
 #else /* CONFIG_RTC */
 
-static inline void clock_inittime(FAR struct timespec *tp)
+static inline void clock_basetime(FAR struct timespec *tp)
 {
   time_t jdn = 0;
 
@@ -165,6 +169,22 @@ static inline void clock_inittime(FAR struct timespec *tp)
 
 #endif /* CONFIG_RTC */
 
+/****************************************************************************
+ * Function: clock_inittime
+ *
+ * Description:
+ *   Get the initial time value from the best source available.
+ *
+ ****************************************************************************/
+
+static void clock_inittime(void)
+{
+  /* (Re-)initialize the time value to match the RTC*/
+
+  clock_basetime(&g_basetime);
+  g_system_timer = 0;
+  g_tickbias     = 0;
+}
 
 /****************************************************************************
  * Public Functions
@@ -186,13 +206,52 @@ void clock_initialize(void)
   up_rtcinitialize();
 #endif
 
-  /* Initialize the time value to match */
+  /* Initialize the time value to match the RTC */
 
-  clock_inittime(&g_basetime);
+  clock_inittime();
-  g_system_timer = 0;
-  g_tickbias     = 0;
 }
 
+/****************************************************************************
+ * Function:  clock_synchronize
+ *
+ * Description:
+ *   Synchronize the system timer to a hardware RTC.  This operation is
+ *   normally performed automatically by the system during clock
+ *   initialization.  However, the user may also need to explicitly re-
+ *   synchronize the system timer to the RTC under certain conditions where
+ *   the system timer is known to be in error.  For example, in certain low-
+ *   power states, the system timer may be stopped but the RTC will continue
+ *   keep correct time.  After recovering from such low-power state, this
+ *   function should be called to restore the correct system time.
+ *
+ *   Calling this function could result in system time going "backward" in
+ *   time, especially with certain lower resolution RTC implementations.
+ *   Time going backward could have bad consequences if there are ongoing
+ *   timers and delays.  So use this interface with care.
+ *
+ * Parameters:
+ *   None
+ *
+ * Return Value:
+ *   None
+ *
+ * Assumptions:
+ *
+ ****************************************************************************/
+
+#ifdef CONFIG_RTC
+void clock_synchronize(void)
+{
+  irqstate_t flags;
+
+  /* Re-initialize the time value to match the RTC */
+
+  flags = irqsave();
+  clock_inittime();
+  irqrestore(flags);
+}
+#endif
+
 /****************************************************************************
  * Function: clock_timer
  *