2008-03-11 Joel Sherrill <joel.sherrill@oarcorp.com>

	* rtems/Makefile.am, rtems/include/rtems/rtems/clock.h,
	rtems/src/clockget.c:
	* rtems/src/clockgetsecondssinceepoch.c,
	rtems/src/clockgettickspersecond.c,
	rtems/src/clockgettickssinceboot.c, rtems/src/clockgettod.c,
	rtems/src/clockgettodtimeval.c: New files.
	Refactored rtems_clock_get into 5 methods which are single purpose
	and more strongly typed.  They are:
	    rtems_clock_get_tod - Get TOD in Classic API structure
	    rtems_clock_get_tod_timeval - Get TOD in struct timeval
	    rtems_clock_get_seconds_since_epoch - Get TOD as seconds since 1988
	    rtems_clock_get_ticks_since_boot - Get ticks since boot
	    rtems_clock_get_ticks_per_second - Get ticks per second

8 files changed, 347 insertions, 94 deletions

diff --git a/cpukit/rtems/Makefile.am b/cpukit/rtems/Makefile.am
index 0b7f68a6ca..7f4fa2ce97 100644
--- a/cpukit/rtems/Makefile.am
+++ b/cpukit/rtems/Makefile.am
@@ -86,8 +86,10 @@ librtems_a_SOURCES += src/barrier.c src/barriercreate.c src/barrierdelete.c \
    src/barrierwait.c src/barrierdata.c
 
 ## CLOCK_C_FILES
-librtems_a_SOURCES += src/rtclock.c src/clockget.c src/clockset.c \
-    src/clocktick.c src/clocksetnsecshandler.c src/clockgetuptime.c \
+librtems_a_SOURCES += src/clockget.c src/clockgetsecondssinceepoch.c \
+    src/clockgettickspersecond.c src/clockgettickssinceboot.c \
+    src/clockgettod.c src/clockgettodtimeval.c src/clockgetuptime.c \
+    src/clockset.c src/clocksetnsecshandler.c src/clocktick.c \
     src/clocktodtoseconds.c src/clocktodvalidate.c
 
 ## TIMER_C_FILES
diff --git a/cpukit/rtems/include/rtems/rtems/clock.h b/cpukit/rtems/include/rtems/rtems/clock.h
index a6f7de5dce..d467f353fd 100644
--- a/cpukit/rtems/include/rtems/rtems/clock.h
+++ b/cpukit/rtems/include/rtems/rtems/clock.h
@@ -13,8 +13,9 @@
  *     + obtain the current date and time
  *     + set the nanoseconds since last clock tick handler
  *     + announce a clock tick
+ *     + obtain the system uptime
  *
- *  COPYRIGHT (c) 1989-2007.
+ *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
  *  The license and distribution terms for this file may be
@@ -36,37 +37,38 @@ extern "C" {
 #include <rtems/rtems/status.h>
 #include <rtems/rtems/types.h>
 
-/*
+/**
  *  List of things which can be returned by the rtems_clock_get directive.
  */
-
 typedef enum {
+  /** This value indicates obtain TOD in Classic API format. */
   RTEMS_CLOCK_GET_TOD,
+  /** This value indicates obtain the number of seconds since the epoch. */
   RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH,
+  /** This value indicates obtain the number of ticks since system boot. */
   RTEMS_CLOCK_GET_TICKS_SINCE_BOOT,
+  /** This value indicates obtain the number of ticks per second. */
   RTEMS_CLOCK_GET_TICKS_PER_SECOND,
+  /** This value indicates obtain the TOD in struct timeval format. */
   RTEMS_CLOCK_GET_TIME_VALUE
 } rtems_clock_get_options;
 
-/*
+/**
  *  Standard flavor style to return TOD in for a rtems_clock_get option.
  */
-
 typedef struct {
   uint32_t    seconds;
   uint32_t    microseconds;
 } rtems_clock_time_value;
 
-/*
+/**
  *  Type for the nanoseconds since last tick BSP extension.
  */
 typedef Watchdog_Nanoseconds_since_last_tick_routine
   rtems_nanoseconds_extension_routine;
 
-/*
- *  rtems_clock_get
- *
- *  DESCRIPTION:
+/**
+ *  @brief Obtain Current Time of Day 
  *
  *  This routine implements the rtems_clock_get directive.  It returns
  *  one of the following:
@@ -74,86 +76,180 @@ typedef Watchdog_Nanoseconds_since_last_tick_routine
  *    + seconds since epoch
  *    + ticks since boot
  *    + ticks per second
+ *
+ *  @param[in] option is the format of time to return
+ *  @param[in] time_buffer points to the output area
+ *
+ *  @return This method returns RTEMS_SUCCESSFUL if there was not an
+ *          error.  Otherwise, a status code is returned indicating the
+ *          source of the error.
  */
-
 rtems_status_code rtems_clock_get(
   rtems_clock_get_options  option,
-  void              *time_buffer
+  void                    *time_buffer
 );
 
-/*
- *  rtems_clock_set
+/**
+ *  @brief Obtain Current Time of Day (Classic TOD)
  *
- *  DESCRIPTION:
+ *  This routine implements the rtems_clock_get_tod directive.  It returns
+ *  the current time of day in the format defined by RTEID.
+ *
+ *  @param[in] time_buffer points to the time of day structure
+ *
+ *  @return This method returns RTEMS_SUCCESSFUL if there was not an
+ *          error.  Otherwise, a status code is returned indicating the
+ *          source of the error.  If successful, the time_buffer will
+ *          be filled in with the current time of day.
+ */
+rtems_status_code rtems_clock_get_tod(
+  rtems_time_of_day *time_buffer
+);
+
+/**
+ *  @brief Obtain TOD in struct timeval Format
+ *
+ *  This routine implements the rtems_clock_get_tod_timeval
+ *  directive.
+ *
+ *  @param[in] time points to the struct timeval variable to fill in
+ *
+ *  @return This method returns RTEMS_SUCCESSFUL if there was not an
+ *          error.  Otherwise, a status code is returned indicating the
+ *          source of the error.  If successful, the time will
+ *          be filled in with the current time of day.
+ */
+rtems_status_code rtems_clock_get_tod_timeval(
+  struct timeval *time
+);
+
+/**
+ *  @brief Obtain Seconds Since Epoch
+ *
+ *  This routine implements the rtems_clock_get_seconds_since_epoch
+ *  directive.
+ *
+ *  @param[in] the_interval points to the interval variable to fill in
+ *
+ *  @return This method returns RTEMS_SUCCESSFUL if there was not an
+ *          error.  Otherwise, a status code is returned indicating the
+ *          source of the error.  If successful, the time_buffer will
+ *          be filled in with the current time of day.
+ */
+rtems_status_code rtems_clock_get_seconds_since_epoch(
+  rtems_interval *the_interval
+);
+
+/**
+ *  @brief Obtain Ticks Since Boot
+ *
+ *  This routine implements the rtems_clock_get_ticks_since_boot
+ *  directive.
+ *
+ *  @return This method returns the number of ticks since boot.  It cannot
+ *          fail since RTEMS always keeps a running count of ticks since boot.
+ */
+rtems_interval rtems_clock_get_ticks_since_boot(void);
+
+/**
+ *  @brief Obtain Ticks Per Seconds
+ *
+ *  This routine implements the rtems_clock_get_ticks_per_second
+ *  directive.
+ *
+ *  @return This method returns the number of ticks since boot.  It cannot
+ *          fail since RTEMS is always configured to know the number of
+ *          ticks per second.
+ */
+rtems_interval rtems_clock_get_ticks_per_second(void);
+
+/**
+ *  @brief Set the Current TOD
  *
  *  This routine implements the rtems_clock_set directive.  It sets
  *  the current time of day to that in the time_buffer record.
+ *
+ *  @param[in] time_buffer points to the new TOD
+ *
+ *  @return This method returns RTEMS_SUCCESSFUL if there was not an
+ *          error.  Otherwise, a status code is returned indicating the
+ *          source of the error.
+ *
+ *  @note Activities scheduled based upon the current time of day
+ *        may be executed immediately if the time is moved forward.
  */
-
 rtems_status_code rtems_clock_set(
   rtems_time_of_day *time_buffer
 );
 
-/*
- *  rtems_clock_tick
- *
- *  DESCRIPTION:
+/**
+ *  @brief Announce a Clock Tick
  *
  *  This routine implements the rtems_clock_tick directive.  It is invoked
  *  to inform RTEMS of the occurrence of a clock tick.
+ *
+ *  @return This directive always returns RTEMS_SUCCESSFUL.
+ *
+ *  @note This method is typically called from an ISR and is the basis
+ *        for all timeouts and delays.
  */
-
 rtems_status_code rtems_clock_tick( void );
 
-/*
- *  rtems_clock_set_nanoseconds_extension
- *
- *  DESCRIPTION:
+/**
+ *  @brief Set the BSP specific Nanoseconds Extension
  *
  *  This directive sets the BSP provided nanoseconds since last tick
  *  extension.
  *
- *  Input parameters:
- *    routine - pointer to the extension routine
+ *  @param[in] routine is a pointer to the extension routine
  *
- *  Output parameters:
- *    RTEMS_SUCCESSFUL - if successful
- *    error code       - if unsuccessful
+ *  @return This method returns RTEMS_SUCCESSFUL if there was not an
+ *          error.  Otherwise, a status code is returned indicating the
+ *          source of the error.
  */
 rtems_status_code rtems_clock_set_nanoseconds_extension(
   rtems_nanoseconds_extension_routine routine
 );
 
-/*
- *  rtems_clock_get_uptime
- *
- *  DESCRIPTION:
+/**
+ *  @brief Obtain the System Uptime
  *
  *  This directive returns the system uptime.
  *
- *  Input parameters:
- *    routine - pointer to the time structure 
+ *  @param[in] uptime is a pointer to the time structure 
  *
- *  Output parameters:
- *    RTEMS_SUCCESSFUL - if successful
- *    error code       - if unsuccessful
+ *  @return This method returns RTEMS_SUCCESSFUL if there was not an
+ *          error.  Otherwise, a status code is returned indicating the
+ *          source of the error.  If successful, the uptime will be 
+ *          filled in.
  */
 rtems_status_code rtems_clock_get_uptime(
   struct timespec *uptime
 );
 
-/** @brief _TOD_Validate
+/**
+ *  @brief _TOD_Validate
  *
- *  This function returns TRUE if THE_TOD contains
+ *  This support function returns TRUE if @a the_tod contains
  *  a valid time of day, and FALSE otherwise.
+ *
+ *  @param[in] the_tod is the TOD structure to validate
+ *
+ *  @return This method returns TRUE if the TOD is valid and FALSE otherwise.
  */
 boolean _TOD_Validate(
   rtems_time_of_day *the_tod
 );
 
-/** @brief _TOD_To_seconds
+/**
+ *  @brief _TOD_To_seconds
+ *
+ *  This function returns the number seconds between the epoch and @a the_tod.
+ *
+ *  @param[in] the_tod is the TOD structure to convert to seconds
  *
- *  This function returns the number seconds between the epoch and THE_TOD.
+ *  @return This method returns the number of seconds since epoch represented
+ *          by @a the_tod
  */
 Watchdog_Interval _TOD_To_seconds(
   rtems_time_of_day *the_tod
diff --git a/cpukit/rtems/src/clockget.c b/cpukit/rtems/src/clockget.c
index ba0fabf8e5..0009d47fb3 100644
--- a/cpukit/rtems/src/clockget.c
+++ b/cpukit/rtems/src/clockget.c
@@ -1,7 +1,7 @@
 /*
  *  Clock Manager
  *
- *  COPYRIGHT (c) 1989-2007.
+ *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
  *  The license and distribution terms for this file may be
@@ -50,65 +50,29 @@ rtems_status_code rtems_clock_get(
     return RTEMS_INVALID_ADDRESS;
 
   switch ( option ) {
-    case RTEMS_CLOCK_GET_TOD: {
-      struct tm time;
-      struct timeval now;
-      rtems_time_of_day *tmbuf = (rtems_time_of_day *)time_buffer;
+    case RTEMS_CLOCK_GET_TOD:
+      return rtems_clock_get_tod( (rtems_time_of_day *)time_buffer ); 
 
-      if ( !_TOD_Is_set )
-        return RTEMS_NOT_DEFINED;
-
-      /* Obtain the current time */
-      _TOD_Get_timeval( &now );
-
-      /* Split it into a closer format */
-      gmtime_r( &now.tv_sec, &time );
-
-      /* Now adjust it to the RTEMS format */
-      tmbuf->year   = time.tm_year + 1900;
-      tmbuf->month  = time.tm_mon + 1;
-      tmbuf->day    = time.tm_mday;
-      tmbuf->hour   = time.tm_hour;
-      tmbuf->minute = time.tm_min;
-      tmbuf->second = time.tm_sec;
-      tmbuf->ticks  = now.tv_usec / _TOD_Microseconds_per_tick;
-     
-      return RTEMS_SUCCESSFUL;
-    }
-    case RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH: {
-      rtems_interval *interval = (rtems_interval *)time_buffer;
-
-      if ( !_TOD_Is_set )
-        return RTEMS_NOT_DEFINED;
-
-      *interval = _TOD_Seconds_since_epoch;
-      return RTEMS_SUCCESSFUL;
-    }
+    case RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH:
+      return rtems_clock_get_seconds_since_epoch((rtems_interval *)time_buffer);
 
     case RTEMS_CLOCK_GET_TICKS_SINCE_BOOT: {
       rtems_interval *interval = (rtems_interval *)time_buffer;
-
-      *interval = _Watchdog_Ticks_since_boot;
+  
+      *interval = rtems_clock_get_ticks_since_boot();
       return RTEMS_SUCCESSFUL;
     }
-
     case RTEMS_CLOCK_GET_TICKS_PER_SECOND: {
       rtems_interval *interval = (rtems_interval *)time_buffer;
-
-      *interval = TOD_MICROSECONDS_PER_SECOND / _TOD_Microseconds_per_tick;
+  
+      *interval = rtems_clock_get_ticks_per_second();
       return RTEMS_SUCCESSFUL;
     }
+    case RTEMS_CLOCK_GET_TIME_VALUE:
+      return rtems_clock_get_tod_timeval( (struct timeval *)time_buffer );
 
-    case RTEMS_CLOCK_GET_TIME_VALUE: {
-      struct timeval *time = (struct timeval *)time_buffer;
-
-      if ( !_TOD_Is_set )
-        return RTEMS_NOT_DEFINED;
-
-      _TOD_Get_timeval( time );
-
-      return RTEMS_SUCCESSFUL;
-    }
+    default:
+      break;
   }
 
   return RTEMS_INVALID_NUMBER;
diff --git a/cpukit/rtems/src/clockgetsecondssinceepoch.c b/cpukit/rtems/src/clockgetsecondssinceepoch.c
new file mode 100644
index 0000000000..9c1badfe99
--- /dev/null
+++ b/cpukit/rtems/src/clockgetsecondssinceepoch.c
@@ -0,0 +1,38 @@
+/*
+ *  Clock Manager - Get Seconds Since Epoch
+ *
+ *  COPYRIGHT (c) 1989-2008.
+ *  On-Line Applications Research Corporation (OAR).
+ *
+ *  The license and distribution terms for this file may be
+ *  found in the file LICENSE in this distribution or at
+ *  http://www.rtems.com/license/LICENSE.
+ *
+ *  $Id$
+ */
+
+#if HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#include <rtems/system.h>
+#include <rtems/rtems/status.h>
+#include <rtems/rtems/clock.h>
+#include <rtems/score/isr.h>
+#include <rtems/score/thread.h>
+#include <rtems/score/tod.h>
+#include <rtems/score/watchdog.h>
+
+rtems_status_code rtems_clock_get_seconds_since_epoch(
+  rtems_interval *the_interval
+)
+{
+  if ( !the_interval )
+    return RTEMS_INVALID_ADDRESS;
+
+  if ( !_TOD_Is_set )
+    return RTEMS_NOT_DEFINED;
+
+  *the_interval = _TOD_Seconds_since_epoch;
+  return RTEMS_SUCCESSFUL;
+}
diff --git a/cpukit/rtems/src/clockgettickspersecond.c b/cpukit/rtems/src/clockgettickspersecond.c
new file mode 100644
index 0000000000..9a4bd1ccad
--- /dev/null
+++ b/cpukit/rtems/src/clockgettickspersecond.c
@@ -0,0 +1,29 @@
+/*
+ *  Clock Manager - Get Ticks Per Second
+ *
+ *  COPYRIGHT (c) 1989-2008.
+ *  On-Line Applications Research Corporation (OAR).
+ *
+ *  The license and distribution terms for this file may be
+ *  found in the file LICENSE in this distribution or at
+ *  http://www.rtems.com/license/LICENSE.
+ *
+ *  $Id$
+ */
+
+#if HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#include <rtems/system.h>
+#include <rtems/rtems/status.h>
+#include <rtems/rtems/clock.h>
+#include <rtems/score/isr.h>
+#include <rtems/score/thread.h>
+#include <rtems/score/tod.h>
+#include <rtems/score/watchdog.h>
+
+rtems_interval rtems_clock_get_ticks_per_second(void)
+{
+  return TOD_MICROSECONDS_PER_SECOND / _TOD_Microseconds_per_tick;
+}
diff --git a/cpukit/rtems/src/clockgettickssinceboot.c b/cpukit/rtems/src/clockgettickssinceboot.c
new file mode 100644
index 0000000000..a97e40106e
--- /dev/null
+++ b/cpukit/rtems/src/clockgettickssinceboot.c
@@ -0,0 +1,29 @@
+/*
+ *  Clock Manager - Get Ticks Since Boot
+ *
+ *  COPYRIGHT (c) 1989-2008.
+ *  On-Line Applications Research Corporation (OAR).
+ *
+ *  The license and distribution terms for this file may be
+ *  found in the file LICENSE in this distribution or at
+ *  http://www.rtems.com/license/LICENSE.
+ *
+ *  $Id$
+ */
+
+#if HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#include <rtems/system.h>
+#include <rtems/rtems/status.h>
+#include <rtems/rtems/clock.h>
+#include <rtems/score/isr.h>
+#include <rtems/score/thread.h>
+#include <rtems/score/tod.h>
+#include <rtems/score/watchdog.h>
+
+rtems_interval rtems_clock_get_ticks_since_boot(void)
+{
+  return _Watchdog_Ticks_since_boot;
+}
diff --git a/cpukit/rtems/src/clockgettod.c b/cpukit/rtems/src/clockgettod.c
new file mode 100644
index 0000000000..9347d797ee
--- /dev/null
+++ b/cpukit/rtems/src/clockgettod.c
@@ -0,0 +1,56 @@
+/*
+ *  Clock Manager - rtems_clock_get_tod
+ *
+ *  COPYRIGHT (c) 1989-2007.
+ *  On-Line Applications Research Corporation (OAR).
+ *
+ *  The license and distribution terms for this file may be
+ *  found in the file LICENSE in this distribution or at
+ *  http://www.rtems.com/license/LICENSE.
+ *
+ *  $Id$
+ */
+
+#if HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#include <rtems/system.h>
+#include <rtems/rtems/status.h>
+#include <rtems/rtems/clock.h>
+#include <rtems/score/isr.h>
+#include <rtems/score/thread.h>
+#include <rtems/score/tod.h>
+#include <rtems/score/watchdog.h>
+
+rtems_status_code rtems_clock_get_tod(
+  rtems_time_of_day  *time_buffer
+)
+{
+  rtems_time_of_day *tmbuf = time_buffer;
+  struct tm time;
+  struct timeval now;
+
+  if ( !time_buffer )
+    return RTEMS_INVALID_ADDRESS;
+
+  if ( !_TOD_Is_set )
+    return RTEMS_NOT_DEFINED;
+
+  /* Obtain the current time */
+  _TOD_Get_timeval( &now );
+
+  /* Split it into a closer format */
+  gmtime_r( &now.tv_sec, &time );
+
+  /* Now adjust it to the RTEMS format */
+  tmbuf->year   = time.tm_year + 1900;
+  tmbuf->month  = time.tm_mon + 1;
+  tmbuf->day    = time.tm_mday;
+  tmbuf->hour   = time.tm_hour;
+  tmbuf->minute = time.tm_min;
+  tmbuf->second = time.tm_sec;
+  tmbuf->ticks  = now.tv_usec / _TOD_Microseconds_per_tick;
+ 
+  return RTEMS_SUCCESSFUL;
+}
diff --git a/cpukit/rtems/src/clockgettodtimeval.c b/cpukit/rtems/src/clockgettodtimeval.c
new file mode 100644
index 0000000000..71e53ffd24
--- /dev/null
+++ b/cpukit/rtems/src/clockgettodtimeval.c
@@ -0,0 +1,39 @@
+/*
+ *  Clock Manager - Get TOD in Time Value Format
+ *
+ *  COPYRIGHT (c) 1989-2008.
+ *  On-Line Applications Research Corporation (OAR).
+ *
+ *  The license and distribution terms for this file may be
+ *  found in the file LICENSE in this distribution or at
+ *  http://www.rtems.com/license/LICENSE.
+ *
+ *  $Id$
+ */
+
+#if HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#include <rtems/system.h>
+#include <rtems/rtems/status.h>
+#include <rtems/rtems/clock.h>
+#include <rtems/score/isr.h>
+#include <rtems/score/thread.h>
+#include <rtems/score/tod.h>
+#include <rtems/score/watchdog.h>
+
+rtems_status_code rtems_clock_get_tod_timeval(
+  struct timeval  *time
+)
+{
+  if ( !time )
+    return RTEMS_INVALID_ADDRESS;
+
+  if ( !_TOD_Is_set )
+    return RTEMS_NOT_DEFINED;
+
+  _TOD_Get_timeval( time );
+
+  return RTEMS_SUCCESSFUL;
+}