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

	* user/clock.t: 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

2 files changed, 287 insertions, 26 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 18fdbcd635..441626c925 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,14 @@
+2008-03-11	Joel Sherrill <joel.sherrill@oarcorp.com>
+
+	* user/clock.t: 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
+
+
 2008-02-29	Joel Sherrill <joel.sherrill@oarcorp.com>
 
 	* shell/general.t: Add sleep and echo commands.
diff --git a/doc/user/clock.t b/doc/user/clock.t
index 93a609cce9..4c5829fbcf 100644
--- a/doc/user/clock.t
+++ b/doc/user/clock.t
@@ -1,5 +1,5 @@
 @c
-@c  COPYRIGHT (c) 1988-2007
+@c  COPYRIGHT (c) 1988-2008
 @c  On-Line Applications Research Corporation (OAR).
 @c  All rights reserved.
 @c
@@ -17,8 +17,13 @@ and other time related capabilities.  The directives provided by
 the clock manager are:
 
 @itemize @bullet
-@item @code{@value{DIRPREFIX}clock_set} - Set system date and time
-@item @code{@value{DIRPREFIX}clock_get} - Get system date and time information
+@item @code{@value{DIRPREFIX}clock_set} - Set date and time
+@item @code{@value{DIRPREFIX}clock_get} - Get date and time information
+@item @code{@value{DIRPREFIX}clock_get_tod} - Get date and time in TOD format
+@item @code{@value{DIRPREFIX}clock_get_tod_timeval} - Get date and time in timeval format
+@item @code{@value{DIRPREFIX}clock_get_seconds_since_epoch} - Get seconds since epoch 
+@item @code{@value{DIRPREFIX}clock_get_ticks_per_second} - Get ticks per second
+@item @code{@value{DIRPREFIX}clock_get_ticks_since_boot} - Get ticks since boot
 @item @code{@value{DIRPREFIX}clock_get_uptime} - Get time since boot
 @item @code{@value{DIRPREFIX}clock_set_nanoseconds_extension} - Install the nanoseconds since last tick handler
 @item @code{@value{DIRPREFIX}clock_tick} - Announce a clock tick
@@ -238,7 +243,7 @@ and status codes.
 @c
 @c
 @page
-@subsection CLOCK_SET - Set system date and time
+@subsection CLOCK_SET - Set date and time
 
 @subheading CALLING SEQUENCE:
 
@@ -295,7 +300,7 @@ the system date and time to application specific specifications.
 @c
 @c
 @page
-@subsection CLOCK_GET - Get system date and time information
+@subsection CLOCK_GET - Get date and time information
 
 @cindex obtain the time of day
 
@@ -396,52 +401,245 @@ system date and time to application specific specifications.
 @c
 @c
 @page
-@subsection CLOCK_SET_NANOSECONDS_EXTENSION - Install the nanoseconds since last tick handler
+@subsection CLOCK_GET_TOD - Get date and time in TOD format
 
-@cindex clock set nanoseconds extension
-@cindex nanoseconds extension
-@cindex nanoseconds time accuracy
+@cindex obtain the time of day
 
 @subheading CALLING SEQUENCE:
 
 @ifset is-C
-@findex rtems_clock_set_nanoseconds_extension
+@findex rtems_clock_get_tod
 @example
-rtems_status_code rtems_clock_set_nanoseconds_extension(
-  rtems_nanoseconds_extension_routine routine
+rtems_status_code rtems_clock_get_tod(
+  rtems_time_of_day *time_buffer
 );
 @end example
 @end ifset
 
 @ifset is-Ada
 @example
-NOT SUPPORTED FROM Ada BINDING
+procedure Clock_Get_TOD (
+   Time_Buffer : in     RTEMS.Time_Of_Day;
+   Result      :    out RTEMS.Status_Codes
+);
 @end example
 @end ifset
 
 @subheading DIRECTIVE STATUS CODES:
-@code{@value{RPREFIX}SUCCESSFUL} - clock tick processed successfully@*
+@code{@value{RPREFIX}SUCCESSFUL} - current time obtained successfully@*
+@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@*
 @code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL
 
 @subheading DESCRIPTION:
 
-This directive is used by the Clock device driver to install the 
-@code{routine} which will be invoked by the internal RTEMS method used to
-obtain a highly accurate time of day.  It is usually called during
-the initialization of the driver.
+This directive obtains the system date and time.  If the date and time
+has not been set with a previous call to
+@code{@value{DIRPREFIX}clock_set}, then the
+@code{@value{RPREFIX}NOT_DEFINED} status code is returned. 
 
-When the @code{routine} is invoked, it will determine the number of
-nanoseconds which have elapsed since the last invocation of
-the @code{@value{DIRPREFIX}clock_tick} directive.  It should do
-this as quickly as possible with as little impact as possible
-on the device used as a clock source.
+@subheading NOTES:
+
+This directive is callable from an ISR.
+
+This directive will not cause the running task to be
+preempted.  Re-initializing RTEMS causes the system date and
+time to be reset to an uninitialized state.  Another call to
+@code{@value{DIRPREFIX}clock_set} is required to re-initialize the
+system date and time to application specific specifications.
+
+@c
+@c
+@c
+@page
+@subsection CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format
+
+@cindex obtain the time of day
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@findex rtems_clock_get_tod_timeval
+@example
+rtems_status_code rtems_clock_get_tod(
+  struct timeval  *time
+);
+@end example
+@end ifset
+
+@ifset is-Ada
+@example
+procedure Clock_Get_TOD_Timeval (
+   Time   : in     RTEMS.Timeval;
+   Result :    out RTEMS.Status_Codes
+);
+@end example
+@end ifset
+
+@subheading DIRECTIVE STATUS CODES:
+@code{@value{RPREFIX}SUCCESSFUL} - current time obtained successfully@*
+@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@*
+@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time} is NULL
+
+@subheading DESCRIPTION:
+
+This directive obtains the system date and time in POSIX
+@code{struct timeval} format.  If the date and time
+has not been set with a previous call to
+@code{@value{DIRPREFIX}clock_set}, then the
+@code{@value{RPREFIX}NOT_DEFINED} status code is returned. 
 
 @subheading NOTES:
 
-This directive may be called from an ISR.
+This directive is callable from an ISR.
 
-This directive is called as part of every service to obtain the 
-current date and time as well as timestamps.
+This directive will not cause the running task to be
+preempted.  Re-initializing RTEMS causes the system date and
+time to be reset to an uninitialized state.  Another call to
+@code{@value{DIRPREFIX}clock_set} is required to re-initialize the
+system date and time to application specific specifications.
+
+@c
+@c
+@c
+@page
+@subsection CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch
+
+@cindex obtain seconds since epoch
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@findex rtems_clock_get_seconds_since_epoch
+@example
+rtems_status_code rtems_clock_get_seconds_since_epoch(
+  rtems_interval *the_interval
+);
+@end example
+@end ifset
+
+@ifset is-Ada
+@example
+procedure Clock_Get_Seconds_Since_Epoch(
+   The_Interval :    out RTEMS.Interval;
+   Result       :    out RTEMS.Status_Codes
+);
+@end example
+@end ifset
+
+@subheading DIRECTIVE STATUS CODES:
+@code{@value{RPREFIX}SUCCESSFUL} - current time obtained successfully@*
+@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@*
+@code{@value{RPREFIX}INVALID_ADDRESS} - @code{the_interval} is NULL
+
+@subheading DESCRIPTION:
+
+This directive returns the number of seconds since the RTEMS
+epoch and the current system date and time.  If the date and time
+has not been set with a previous call to
+@code{@value{DIRPREFIX}clock_set}, then the
+@code{@value{RPREFIX}NOT_DEFINED} status code is returned. 
+
+@subheading NOTES:
+
+This directive is callable from an ISR.
+
+This directive will not cause the running task to be
+preempted.  Re-initializing RTEMS causes the system date and
+time to be reset to an uninitialized state.  Another call to
+@code{@value{DIRPREFIX}clock_set} is required to re-initialize the
+system date and time to application specific specifications.
+
+@c
+@c
+@c
+@page
+@subsection CLOCK_GET_TICKS_PER_SECOND - Get ticks per second
+
+@cindex obtain seconds since epoch
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@findex rtems_clock_get_ticks_per_second
+@example
+rtems_interval rtems_clock_get_ticks_per_seconds(void);
+@end example
+@end ifset
+
+@ifset is-Ada
+@example
+function Clock_Get_Ticks_Per_Seconds
+return RTEMS.Interval;
+@end example
+@end ifset
+
+@subheading DIRECTIVE STATUS CODES:
+NONE
+
+@subheading DESCRIPTION:
+
+This directive returns the number of clock ticks per second.  This
+is strictly based upon the microseconds per clock tick that the
+application has configured.
+
+@subheading NOTES:
+
+This directive is callable from an ISR.
+
+This directive will not cause the running task to be
+preempted.  Re-initializing RTEMS causes the system date and
+time to be reset to an uninitialized state.  Another call to
+@code{@value{DIRPREFIX}clock_set} is required to re-initialize the
+system date and time to application specific specifications.
+
+@c
+@c
+@c
+@page
+@subsection CLOCK_GET_TICKS_SINCE_BOOT - Get ticks since boot
+
+@cindex obtain ticks since boot
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@findex rtems_clock_get_ticks_since_boot
+@example
+rtems_interval rtems_clock_get_ticks_since_boot(void);
+@end example
+@end ifset
+
+@ifset is-Ada
+@example
+function Clock_Get_Ticks_Since_Boot
+return RTEMS.Interval;
+@end example
+@end ifset
+
+@subheading DIRECTIVE STATUS CODES:
+NONE
+
+@subheading DESCRIPTION:
+
+This directive returns the number of clock ticks that have elapsed
+since the system was booted.  This is the historical measure of uptime
+in an RTEMS system.  The newer service
+@code{@value{DIRPREFIX}clock_get_uptime} is another and potentially
+more accurate way of obtaining similar information.
+
+@subheading NOTES:
+
+This directive is callable from an ISR.
+
+This directive will not cause the running task to be
+preempted.  Re-initializing RTEMS causes the system date and
+time to be reset to an uninitialized state.  Another call to
+@code{@value{DIRPREFIX}clock_set} is required to re-initialize the
+system date and time to application specific specifications.
+
+This directive simply returns the number of times the dirivective
+@code{@value{DIRPREFIX}clock_tick} has been invoked since the 
+system was booted.
 
 @c
 @c
@@ -487,6 +685,58 @@ call.
 
 This directive may be called from an ISR.
 
+
+@c
+@c
+@c
+@page
+@subsection CLOCK_SET_NANOSECONDS_EXTENSION - Install the nanoseconds since last tick handler
+
+@cindex clock set nanoseconds extension
+@cindex nanoseconds extension
+@cindex nanoseconds time accuracy
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@findex rtems_clock_set_nanoseconds_extension
+@example
+rtems_status_code rtems_clock_set_nanoseconds_extension(
+  rtems_nanoseconds_extension_routine routine
+);
+@end example
+@end ifset
+
+@ifset is-Ada
+@example
+NOT SUPPORTED FROM Ada BINDING
+@end example
+@end ifset
+
+@subheading DIRECTIVE STATUS CODES:
+@code{@value{RPREFIX}SUCCESSFUL} - clock tick processed successfully@*
+@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL
+
+@subheading DESCRIPTION:
+
+This directive is used by the Clock device driver to install the 
+@code{routine} which will be invoked by the internal RTEMS method used to
+obtain a highly accurate time of day.  It is usually called during
+the initialization of the driver.
+
+When the @code{routine} is invoked, it will determine the number of
+nanoseconds which have elapsed since the last invocation of
+the @code{@value{DIRPREFIX}clock_tick} directive.  It should do
+this as quickly as possible with as little impact as possible
+on the device used as a clock source.
+
+@subheading NOTES:
+
+This directive may be called from an ISR.
+
+This directive is called as part of every service to obtain the 
+current date and time as well as timestamps.
+
 @c
 @c
 @c