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

1 files changed, 139 insertions, 43 deletions

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