timespec: Add documentation for struct timespec Helpers

Joel editted the documentation for clarity, grammar and technical
correctness. I also moved it in the manual and added @findex
entries. The core work was just polished.

Author: Krzysztof Mięsowicz <krzysztof.miesowicz@gmail.com>

4 files changed, 565 insertions, 2 deletions

diff --git a/doc/ada_user/ada_user.texi b/doc/ada_user/ada_user.texi
index 216d86a5d9..c86b595582 100644
--- a/doc/ada_user/ada_user.texi
+++ b/doc/ada_user/ada_user.texi
@@ -109,6 +109,7 @@
 @include user/cpuuse.texi
 @include user/object.texi
 @include user/chains.texi
+@include user/timespec.texi
 @include user/cbs.texi
 @include user/dirstat.texi
 @include example.texi
@@ -147,6 +148,7 @@
 * CPU Usage Statistics::
 * Object Services::
 * Chains::
+* Timespec Helpers::
 * Constant Bandwidth Server Scheduler API::
 * Directive Status Codes::
 * Example Application::
diff --git a/doc/user/Makefile.am b/doc/user/Makefile.am
index 21f5a42ff8..ddf2f07db8 100644
--- a/doc/user/Makefile.am
+++ b/doc/user/Makefile.am
@@ -14,7 +14,8 @@ GENERATED_FILES = overview.texi concepts.texi datatypes.texi init.texi \
     task.texi intr.texi clock.texi timer.texi sem.texi msg.texi event.texi \
     signal.texi part.texi region.texi dpmem.texi io.texi fatal.texi \
     schedule.texi rtmon.texi barrier.texi bsp.texi userext.texi conf.texi \
-    mp.texi stackchk.texi cpuuse.texi object.texi chains.texi cbs.texi
+    mp.texi stackchk.texi cpuuse.texi object.texi chains.texi timespec.texi \
+    cbs.texi
 
 COMMON_FILES += $(top_srcdir)/common/cpright.texi
 
@@ -180,10 +181,15 @@ object.texi: object.t
 chains.texi: chains.t
 	$(BMENU2) -p "Object Services OBJECT_GET_CLASS_INFORMATION - Obtain Class Information" \
 	    -u "Top" \
+	    -n "Timespec Helpers" < $< > $@
+
+timespec.texi: timespec.t
+	$(BMENU2) -p "Chains Prepend a Node" \
+	    -u "Top" \
 	    -n "Constant Bandwidth Server Scheduler API" < $< > $@
 
 cbs.texi: cbs.t
-	$(BMENU2) -p "Chains Prepend a Node" \
+	$(BMENU2) -p "Timespec Helpers TIMESPEC_FROM_TICKS - Convert Ticks to struct timespec Representation" \
 	    -u "Top" \
 	    -n "Directive Status Codes" < $< > $@
 
diff --git a/doc/user/c_user.texi b/doc/user/c_user.texi
index e70649cec6..123ade20f9 100644
--- a/doc/user/c_user.texi
+++ b/doc/user/c_user.texi
@@ -108,6 +108,7 @@
 @include cpuuse.texi
 @include object.texi
 @include chains.texi
+@include timespec.texi
 @include cbs.texi
 @include dirstat.texi
 @include example.texi
@@ -146,6 +147,7 @@
 * CPU Usage Statistics::
 * Object Services::
 * Chains::
+* Timespec Helpers::
 * Constant Bandwidth Server Scheduler API::
 * Directive Status Codes::
 * Example Application::
diff --git a/doc/user/timespec.t b/doc/user/timespec.t
new file mode 100644
index 0000000000..57ed2f3a03
--- /dev/null
+++ b/doc/user/timespec.t
@@ -0,0 +1,553 @@
+@c
+@c  COPYRIGHT (c) 1988-2012.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved. 
+
+
+@chapter Timespec Helpers
+
+@section Introduction
+
+The Timespec helpers manager provides directives to assist in manipulating
+instances of the POSIX @code{struct timespec} structure.
+
+The directives provided by the timespec helpers manager are:
+
+@itemize @bullet
+@item @code{rtems_timespec_set} - Set timespec's value
+@item @code{rtems_timespec_zero} - Zero timespec's value
+@item @code{rtems_timespec_is_valid} - Check if timespec is valid 
+@item @code{rtems_timespec_add_to} - Add two timespecs
+@item @code{rtems_timespec_subtract} - Subtract two timespecs
+@item @code{rtems_timespec_divide} - Divide two timespecs
+@item @code{rtems_timespec_divide_by_integer} - Divide timespec by integer
+@item @code{rtems_timespec_less_than} - Less than operator
+@item @code{rtems_timespec_greater_than} - Greater than operator
+@item @code{rtems_timespec_equal_to} - Check if two timespecs are equal
+@item @code{rtems_timespec_get_seconds} - Obtain seconds portion of timespec
+@item @code{rtems_timespec_get_nanoseconds} - Obtain nanoseconds portion of timespec
+@item @code{rtems_timespec_to_ticks} - Convert timespec to number of ticks
+@item @code{rtems_timespec_from_ticks} - Convert ticks to timespec
+@end itemize
+
+@section Background
+
+@subsection Time Storage Conventions
+
+Time can be stored in many ways. One of them is the @code{struct timespec}
+format which is a structure that consists of the fields @code{tv_sec}
+to represent seconds and @code{tv_nsec} to represent nanoseconds.  The
+@code{struct timeval} structure is simular and consists of seconds (stored
+in @code{tv_sec}) and microseconds (stored in @code{tv_usec}). Either
+@code{struct timespec} or @code{struct timeval} can be used to represent
+elapsed time, time of executing some operations, or time of day.
+
+@section Operations
+
+@subsection Set and Obtain Timespec Value
+
+A user may write a specific time by passing the desired seconds and
+nanoseconds values and the destination @code{struct timespec} using the
+@code{rtems_timespec_set} directive.
+
+The @code{rtems_timespec_zero} directive is used to zero the seconds
+and nanoseconds portions of a @code{struct timespec} instance.
+
+Users may obtain the seconds or nanoseconds portions of a @code{struct
+timespec} instance with the @code{rtems_timespec_get_seconds} or
+@code{rtems_timespec_get_nanoseconds} methods, respectively.
+
+@subsection Timespec Math
+
+A user can perform multiple operations on @code{struct timespec}
+instances. The helpers in this manager assist in adding, subtracting, and
+performing divison on @code{struct timespec} instances.
+
+@itemize @bullet
+@item Adding two @code{struct timespec} can be done using the
+@code{rtems_timespec_add_to} directive. This directive is used mainly
+to calculate total amount of time consumed by multiple operations.
+
+@item The @code{rtems_timespec_subtract} is used to subtract two
+@code{struct timespecs} instances and determine the elapsed time between
+those two points in time.
+
+@item The @code{rtems_timespec_divide} is used to use to divide one
+@code{struct timespec} instance by another. This calculates the percentage
+with a precision to three decimal points.
+
+@item The @code{rtems_timespec_divide_by_integer} is used to divide a
+@code{struct timespec} instance by an integer. It is commonly used in
+benchmark calculations to dividing duration by the number of iterations
+performed.
+
+@end itemize
+
+@subsection Comparing struct timespec Instances
+
+A user can compare two @code{struct timespec} instances using the
+@code{rtems_timespec_less_than}, @code{rtems_timespec_greater_than}
+or @code{rtems_timespec_equal_to} routines.
+
+@subsection Conversions and Validity Check
+
+Conversion to and from clock ticks may be performed by using the
+@code{rtems_timespec_to_ticks} and @code{rtems_timespec_from_ticks}
+directives.
+
+User can also check validity of timespec with
+@code{rtems_timespec_is_valid} routine.
+
+@section Directives
+
+This section details the Timespec Helpers manager's directives.
+A subsection is dedicated to each of this manager's directives
+and describes the calling sequence, related constants, usage,
+and status codes.
+
+@page
+@subsection TIMESPEC_SET - Set struct timespec Instance
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@example
+void rtems_timespec_set(
+  struct timespec *time,
+  time_t           seconds,
+  uint32_t         nanoseconds
+);
+@end example
+@findex rtems_timespec_set
+@end ifset
+
+@ifset is-Ada
+Not Currently Supported In Ada
+@end ifset
+
+@subheading STATUS CODES:
+
+NONE
+
+@subheading DESCRIPTION:
+
+This directive sets the @code{struct timespec} @code{time} value to the
+desired @code{seconds} and @code{nanoseconds} values.
+
+
+@subheading NOTES:
+
+This method does NOT check if @code{nanoseconds} is less than the
+maximum number of nanoseconds in a second.
+
+@page
+@subsection TIMESPEC_ZERO - Zero struct timespec Instance
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@example
+void rtems_timespec_zero(
+  struct timespec *time
+);
+@end example
+@findex rtems_timespec_zero
+@end ifset
+
+@ifset is-Ada
+Not Currently Supported In Ada
+@end ifset
+
+@subheading STATUS CODES:
+NONE
+
+@subheading DESCRIPTION:
+
+This routine sets the contents of the @code{struct timespec} instance
+@code{time} to zero.
+
+@subheading NOTES:
+NONE
+
+@page
+@subsection TIMESPEC_IS_VALID - Check validity of a struct timespec instance
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@example
+bool rtems_timespec_is_valid(
+  const struct timespec *time
+);
+@end example
+@findex rtems_timespec_is_valid
+@end ifset
+
+@ifset is-Ada
+Not Currently Supported In Ada
+@end ifset
+
+@subheading STATUS CODES:
+This method returns @code{true} if the instance is valid, and @code{false}
+otherwise.
+
+@subheading DESCRIPTION:
+
+This routine check validity of a @code{struct timespec} instance. It
+checks if the nanoseconds portion of the @code{struct timespec} instanceis
+in allowed range (less than the maximum number of nanoseconds per second).
+
+@subheading NOTES:
+
+@page
+@subsection TIMESPEC_ADD_TO - Add Two struct timespec Instances
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@example
+uint32_t rtems_timespec_add_to(
+  struct timespec       *time,
+  const struct timespec *add
+);
+@end example
+@findex rtems_timespec_add_to
+@end ifset
+
+@ifset is-Ada
+Not Currently Supported In Ada
+@end ifset
+
+@subheading STATUS CODES:
+The method returns the number of seconds @code{time} increased by.
+
+@subheading DESCRIPTION:
+This routine adds two @code{struct timespec} instances. The second argument is added to the first. The parameter @code{time} is the base time to which the @code{add} parameter is added.
+
+@subheading NOTES:
+NONE
+@page
+@subsection TIMESPEC_SUBTRACT - Subtract Two struct timespec Instances
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@example
+void rtems_timespec_subtract(
+  const struct timespec *start,
+  const struct timespec *end,
+  struct timespec       *result
+);
+@end example
+@findex rtems_timespec_subtract
+@end ifset
+
+@ifset is-Ada
+Not Currently Supported In Ada
+@end ifset
+
+@subheading STATUS CODES:
+NONE
+
+@subheading DESCRIPTION:
+This routine subtracts @code{start} from @code{end} saves the difference
+in @code{result}. The primary use of this directive is to calculate
+elapsed time.
+
+@subheading NOTES:
+
+It is possible to subtract when @code{end} is less than @code{start}
+and it produce negative @code{result}. When doing this you should be
+careful and remember that only the seconds portion of a @code{struct
+timespec} instance is signed, which means that nanoseconds portion is
+always increasing. Due to that when your timespec has seconds = -1 and
+nanoseconds=500,000,000 it means that result is -0.5 second, NOT the
+expected -1.5!
+
+@page
+@subsection TIMESPEC_DIVIDE - Divide Two struct timespec Instances
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@example
+void rtems_timespec_divide(
+  const struct timespec *lhs,
+  const struct timespec *rhs,
+  uint32_t              *ival_percentage,
+  uint32_t              *fval_percentage
+);
+@end example
+@findex rtems_timespec_divide
+@end ifset
+
+@ifset is-Ada
+Not Currently Supported In Ada
+@end ifset
+
+@subheading STATUS CODES:
+
+NONE
+
+@subheading DESCRIPTION:
+
+This routine divides the @code{struct timespec} instance @code{lhs} by
+the @code{struct timespec} instance @code{rhs}. The result is returned
+in the @code{ival_percentage} and @code{fval_percentage}, representing
+the integer and fractional results of the division respectively.
+
+The @code{ival_percentage} is integer value of calculated percentage and @code{fval_percentage} is fractional part of calculated percentage.
+
+@subheading NOTES:
+
+The intended use is calculating percentges to three decimal points.
+
+When dividing by zero, this routine return both @code{ival_percentage}
+and @code{fval_percentage} equal zero.
+
+The division is performed using exclusively integer operations.
+
+@page
+@subsection TIMESPEC_DIVIDE_BY_INTEGER - Divide a struct timespec Instance by an Integer
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@example
+int rtems_timespec_divide_by_integer(
+  const struct timespec *time,
+  uint32_t               iterations,
+  struct timespec       *result
+);
+@end example
+@findex rtems_timespec_divide_by_integer
+@end ifset
+
+@ifset is-Ada
+Not Currently Supported In Ada
+@end ifset
+
+@subheading STATUS CODES:
+
+NONE
+
+@subheading DESCRIPTION:
+This routine divides the @code{struct timespec} instance @code{time} by the integer value @code{iterations}.
+The result is saved in @code{result}.
+
+@subheading NOTES:
+
+The expected use is to assist in benchmark calculations where you
+typically divide a duration (@code{time}) by a number of iterations what
+gives average time.
+
+@page
+@subsection TIMESPEC_LESS_THAN - Less than operator
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@example
+bool rtems_timespec_less_than(
+  const struct timespec *lhs,
+  const struct timespec *rhs
+);
+@end example
+@findex rtems_timespec_less_than
+@end ifset
+
+@ifset is-Ada
+Not Currently Supported In Ada
+@end ifset
+
+@subheading STATUS CODES:
+
+This method returns @code{struct true} if @code{lhs} is less than
+@code{rhs} and @code{struct false} otherwise.
+
+@subheading DESCRIPTION:
+
+This method is the less than operator for @code{struct timespec} instances. The first parameter is the left hand side and the second is the right hand side of the comparison.
+
+@subheading NOTES:
+NONE
+@page
+@subsection TIMESPEC_GREATER_THAN - Greater than operator
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@example
+bool rtems_timespec_greater_than(
+  const struct timespec *_lhs,
+  const struct timespec *_rhs
+);
+@end example
+@findex rtems_timespec_greater_than
+@end ifset
+
+@ifset is-Ada
+Not Currently Supported In Ada
+@end ifset
+
+@subheading STATUS CODES:
+
+This method returns @code{struct true} if @code{lhs} is greater than
+@code{rhs} and @code{struct false} otherwise.
+
+@subheading DESCRIPTION:
+
+This method is greater than operator for @code{struct timespec} instances. 
+
+@subheading NOTES:
+NONE
+
+@page
+@subsection TIMESPEC_EQUAL_TO - Check equality of timespecs
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@example
+bool rtems_timespec_equal_to(
+  const struct timespec *lhs,
+  const struct timespec *rhs
+);
+@end example
+@findex rtems_timespec_equal_to
+@end ifset
+
+@ifset is-Ada
+Not Currently Supported In Ada
+@end ifset
+
+@subheading STATUS CODES:
+
+This method returns @code{struct true} if @code{lhs} is equal to
+@code{rhs} and @code{struct false} otherwise.
+
+
+@subheading DESCRIPTION:
+
+This method is equality operator for @code{struct timespec} instances. 
+
+@subheading NOTES:
+NONE
+
+@page
+@subsection TIMESPEC_GET_SECONDS - Get Seconds Portion of struct timespec Instance
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@example
+time_t rtems_timespec_get_seconds(
+  struct timespec *time
+);
+@end example
+@findex rtems_timespec_get_seconds
+@end ifset
+
+@ifset is-Ada
+Not Currently Supported In Ada
+@end ifset
+
+@subheading STATUS CODES:
+
+This method returns the seconds portion of the specified @code{struct
+timespec} instance.
+
+@subheading DESCRIPTION:
+
+This method returns the seconds portion of the specified @code{struct timespec} instance @code{time}.
+
+@subheading NOTES:
+NONE
+@page
+@subsection TIMESPEC_GET_NANOSECONDS - Get Nanoseconds Portion of the struct timespec Instance
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@example
+uint32_t rtems_timespec_get_nanoseconds(
+  struct timespec *_time
+);
+@end example
+@findex rtems_timespec_get_nanoseconds
+@end ifset
+
+@ifset is-Ada
+Not Currently Supported In Ada
+@end ifset
+
+@subheading STATUS CODES:
+
+This method returns the nanoseconds portion of the specified @code{struct
+timespec} instance.
+
+@subheading DESCRIPTION:
+This method returns the nanoseconds portion of the specified timespec
+which is pointed by @code{_time}.
+
+@subheading NOTES:
+
+@page
+@subsection TIMESPEC_TO_TICKS - Convert struct timespec Instance to Ticks
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@example
+uint32_t rtems_timespec_to_ticks(
+  const struct timespec *time
+);
+@end example
+@findex rtems_timespec_to_ticks
+@end ifset
+
+@ifset is-Ada
+Not Currently Supported In Ada
+@end ifset
+
+@subheading STATUS CODES:
+
+This directive returns the number of ticks computed.
+
+@subheading DESCRIPTION:
+
+This directive converts the @code{time} timespec to the corresponding number of clock ticks.
+
+@subheading NOTES:
+NONE
+
+@page
+@subsection TIMESPEC_FROM_TICKS - Convert Ticks to struct timespec Representation
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@example
+void rtems_timespec_from_ticks(
+  uint32_t         ticks,
+  struct timespec *time
+);
+@end example
+@findex rtems_timespec_from_ticks
+@end ifset
+
+@ifset is-Ada
+Not Currently Supported In Ada
+@end ifset
+
+@subheading STATUS CODES:
+
+NONE
+
+@subheading DESCRIPTION:
+
+This routine converts the @code{ticks} to the corresponding @code{struct timespec} representation and stores it in @code{time}. 
+
+@subheading NOTES:
+NONE
+