From 2d1bdc8f797db5ab6e3ba6945befaf73d9062798 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Tue, 24 Dec 2013 16:38:42 +1100 Subject: cpukit/rtems: Add rtems_clock_get_uptime_nanoseconds to the RTEMS API. Add Timestamp support in the score to return a timestamp in nanoseconds. Add a test. Update the RTEMS API documentation. --- doc/user/clock.t | 62 +++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 46 insertions(+), 16 deletions(-) (limited to 'doc') diff --git a/doc/user/clock.t b/doc/user/clock.t index 368e2874e8..fdbd91db21 100644 --- a/doc/user/clock.t +++ b/doc/user/clock.t @@ -18,12 +18,13 @@ the clock manager are: @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_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_get_uptime_timeval} - Get time since boot in timeval format @item @code{@value{DIRPREFIX}clock_get_uptime_seconds} - Get seconds since boot +@item @code{@value{DIRPREFIX}clock_get_uptime_nanoseconds} - Get nanoseconds 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 @end itemize @@ -85,11 +86,11 @@ type Time_Of_Day is The native date and time format is the only format supported when setting the system date and time using the @code{@value{DIRPREFIX}clock_set} directive. Some applications -expect to operate on a "UNIX-style" date and time data structure. The +expect to operate on a "UNIX-style" date and time data structure. The @code{@value{DIRPREFIX}clock_get_tod_timeval} always returns -the date and time in @code{struct timeval} format. The +the date and time in @code{struct timeval} format. The @code{@value{DIRPREFIX}clock_get} directive can optionally return -the current date and time in this format. +the current date and time in this format. The @code{struct timeval} data structure has two fields: @code{tv_sec} and @code{tv_usec} which are seconds and microseconds, respectively. @@ -142,8 +143,8 @@ created when the timeout option is used on the @code{@value{DIRPREFIX}message_queue_receive}, @code{@value{DIRPREFIX}event_receive}, @code{@value{DIRPREFIX}semaphore_obtain} and -@code{@value{DIRPREFIX}region_get_segment} directives. -Each task may have one and only one timeout active at a time. +@code{@value{DIRPREFIX}region_get_segment} directives. +Each task may have one and only one timeout active at a time. When a timeout expires, it unblocks the task with a timeout status code. @section Operations @@ -192,7 +193,7 @@ is specified using one of the following constants associated with the enumerated type @code{@value{DIRPREFIX}clock_get_options}: -@findex rtems_clock_get_options +@findex rtems_clock_get_options @itemize @bullet @item @code{@value{RPREFIX}CLOCK_GET_TOD} - obtain native style date and time @@ -322,7 +323,7 @@ option is set to either @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH}, @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE}) and 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. +@code{@value{RPREFIX}NOT_DEFINED} status code is returned. The caller can always obtain the number of ticks per second (option is @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND}) and the number of ticks since the executive was initialized option is @@ -333,7 +334,7 @@ type @code{rtems_clock_get_options}. The data type expected for @code{time_buffer} is based on the value of @code{option} as indicated below: -@findex rtems_clock_get_options +@findex rtems_clock_get_options @ifset is-C @itemize @bullet @item @code{@value{RPREFIX}CLOCK_GET_TOD} - (rtems_time_of_day *) @@ -417,7 +418,7 @@ procedure Clock_Get_TOD ( 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. +@code{@value{RPREFIX}NOT_DEFINED} status code is returned. @subheading NOTES: @@ -468,7 +469,7 @@ 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. +@code{@value{RPREFIX}NOT_DEFINED} status code is returned. @subheading NOTES: @@ -519,7 +520,7 @@ 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. +@code{@value{RPREFIX}NOT_DEFINED} status code is returned. @subheading NOTES: @@ -620,7 +621,7 @@ time to be reset to an uninitialized state. Another call to 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 +@code{@value{DIRPREFIX}clock_tick} has been invoked since the system was booted. @c @@ -732,6 +733,36 @@ This directive returns the seconds since the system was booted. This directive may be called from an ISR. +@c +@c +@c +@page +@subsection CLOCK_GET_UPTIME_NANOSECONDS - Get the nanoseconds since boot + +@cindex clock get nanoseconds uptime +@cindex uptime + +@subheading CALLING SEQUENCE: + +@ifset is-C +@findex rtems_clock_get_uptime_nanoseconds +@example +uint64_t rtems_clock_get_uptime_nanoseconds(void); +@end example +@end ifset + +@subheading DIRECTIVE STATUS CODES: + +The system uptime in nanoseconds. + +@subheading DESCRIPTION: + +This directive returns the nanoseconds since the system was booted. + +@subheading NOTES: + +This directive may be called from an ISR. + @c @c @c @@ -765,7 +796,7 @@ NOT SUPPORTED FROM Ada BINDING @subheading DESCRIPTION: -This directive is used by the Clock device driver to install the +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. @@ -780,7 +811,7 @@ on the device used as a clock source. This directive may be called from an ISR. -This directive is called as part of every service to obtain the +This directive is called as part of every service to obtain the current date and time as well as timestamps. @c @@ -828,4 +859,3 @@ The @code{microseconds_per_tick} and @code{ticks_per_timeslice} parameters in the Configuration Table contain the number of microseconds per tick and number of ticks per timeslice, respectively. - -- cgit v1.2.3