[rtems commit] timespec: Add documentation for struct timespec Helpers
Joel Sherrill
joel at rtems.org
Thu Aug 30 23:36:30 UTC 2012
Module: rtems
Branch: master
Commit: 66dacbfb8efe777f963a027dcd0645a6fefb2d5b
Changeset: http://git.rtems.org/rtems/commit/?id=66dacbfb8efe777f963a027dcd0645a6fefb2d5b
Author: Joel Sherrill joel.sherrill at oarcorp.com <joel at monaco.(none)>
Date: Thu Aug 30 18:38:50 2012 -0500
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 at gmail.com>
---
doc/ada_user/ada_user.texi | 2 +
doc/user/Makefile.am | 10 +-
doc/user/c_user.texi | 2 +
doc/user/timespec.t | 553 ++++++++++++++++++++++++++++++++++++++++++++
4 files changed, 565 insertions(+), 2 deletions(-)
diff --git a/doc/ada_user/ada_user.texi b/doc/ada_user/ada_user.texi
index 216d86a..c86b595 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
+ at 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 21f5a42..ddf2f07 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 e70649c..123ade2 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
+ at 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 0000000..57ed2f3
--- /dev/null
+++ b/doc/user/timespec.t
@@ -0,0 +1,553 @@
+ at c
+ at c COPYRIGHT (c) 1988-2012.
+ at c On-Line Applications Research Corporation (OAR).
+ at c All rights reserved.
+
+
+ at chapter Timespec Helpers
+
+ at 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:
+
+ at itemize @bullet
+ at item @code{rtems_timespec_set} - Set timespec's value
+ at item @code{rtems_timespec_zero} - Zero timespec's value
+ at item @code{rtems_timespec_is_valid} - Check if timespec is valid
+ at item @code{rtems_timespec_add_to} - Add two timespecs
+ at item @code{rtems_timespec_subtract} - Subtract two timespecs
+ at item @code{rtems_timespec_divide} - Divide two timespecs
+ at item @code{rtems_timespec_divide_by_integer} - Divide timespec by integer
+ at item @code{rtems_timespec_less_than} - Less than operator
+ at item @code{rtems_timespec_greater_than} - Greater than operator
+ at item @code{rtems_timespec_equal_to} - Check if two timespecs are equal
+ at item @code{rtems_timespec_get_seconds} - Obtain seconds portion of timespec
+ at item @code{rtems_timespec_get_nanoseconds} - Obtain nanoseconds portion of timespec
+ at item @code{rtems_timespec_to_ticks} - Convert timespec to number of ticks
+ at item @code{rtems_timespec_from_ticks} - Convert ticks to timespec
+ at end itemize
+
+ at section Background
+
+ at 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
+ at code{struct timeval} structure is simular and consists of seconds (stored
+in @code{tv_sec}) and microseconds (stored in @code{tv_usec}). Either
+ at code{struct timespec} or @code{struct timeval} can be used to represent
+elapsed time, time of executing some operations, or time of day.
+
+ at section Operations
+
+ at 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
+ at 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
+ at code{rtems_timespec_get_nanoseconds} methods, respectively.
+
+ at 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.
+
+ at itemize @bullet
+ at item Adding two @code{struct timespec} can be done using the
+ at code{rtems_timespec_add_to} directive. This directive is used mainly
+to calculate total amount of time consumed by multiple operations.
+
+ at item The @code{rtems_timespec_subtract} is used to subtract two
+ at code{struct timespecs} instances and determine the elapsed time between
+those two points in time.
+
+ at item The @code{rtems_timespec_divide} is used to use to divide one
+ at code{struct timespec} instance by another. This calculates the percentage
+with a precision to three decimal points.
+
+ at item The @code{rtems_timespec_divide_by_integer} is used to divide a
+ at code{struct timespec} instance by an integer. It is commonly used in
+benchmark calculations to dividing duration by the number of iterations
+performed.
+
+ at end itemize
+
+ at subsection Comparing struct timespec Instances
+
+A user can compare two @code{struct timespec} instances using the
+ at code{rtems_timespec_less_than}, @code{rtems_timespec_greater_than}
+or @code{rtems_timespec_equal_to} routines.
+
+ at subsection Conversions and Validity Check
+
+Conversion to and from clock ticks may be performed by using the
+ at code{rtems_timespec_to_ticks} and @code{rtems_timespec_from_ticks}
+directives.
+
+User can also check validity of timespec with
+ at code{rtems_timespec_is_valid} routine.
+
+ at 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.
+
+ at page
+ at subsection TIMESPEC_SET - Set struct timespec Instance
+
+ at subheading CALLING SEQUENCE:
+
+ at ifset is-C
+ at example
+void rtems_timespec_set(
+ struct timespec *time,
+ time_t seconds,
+ uint32_t nanoseconds
+);
+ at end example
+ at findex rtems_timespec_set
+ at end ifset
+
+ at ifset is-Ada
+Not Currently Supported In Ada
+ at end ifset
+
+ at subheading STATUS CODES:
+
+NONE
+
+ at subheading DESCRIPTION:
+
+This directive sets the @code{struct timespec} @code{time} value to the
+desired @code{seconds} and @code{nanoseconds} values.
+
+
+ at subheading NOTES:
+
+This method does NOT check if @code{nanoseconds} is less than the
+maximum number of nanoseconds in a second.
+
+ at page
+ at subsection TIMESPEC_ZERO - Zero struct timespec Instance
+
+ at subheading CALLING SEQUENCE:
+
+ at ifset is-C
+ at example
+void rtems_timespec_zero(
+ struct timespec *time
+);
+ at end example
+ at findex rtems_timespec_zero
+ at end ifset
+
+ at ifset is-Ada
+Not Currently Supported In Ada
+ at end ifset
+
+ at subheading STATUS CODES:
+NONE
+
+ at subheading DESCRIPTION:
+
+This routine sets the contents of the @code{struct timespec} instance
+ at code{time} to zero.
+
+ at subheading NOTES:
+NONE
+
+ at page
+ at subsection TIMESPEC_IS_VALID - Check validity of a struct timespec instance
+
+ at subheading CALLING SEQUENCE:
+
+ at ifset is-C
+ at example
+bool rtems_timespec_is_valid(
+ const struct timespec *time
+);
+ at end example
+ at findex rtems_timespec_is_valid
+ at end ifset
+
+ at ifset is-Ada
+Not Currently Supported In Ada
+ at end ifset
+
+ at subheading STATUS CODES:
+This method returns @code{true} if the instance is valid, and @code{false}
+otherwise.
+
+ at 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).
+
+ at subheading NOTES:
+
+ at page
+ at subsection TIMESPEC_ADD_TO - Add Two struct timespec Instances
+
+ at subheading CALLING SEQUENCE:
+
+ at ifset is-C
+ at example
+uint32_t rtems_timespec_add_to(
+ struct timespec *time,
+ const struct timespec *add
+);
+ at end example
+ at findex rtems_timespec_add_to
+ at end ifset
+
+ at ifset is-Ada
+Not Currently Supported In Ada
+ at end ifset
+
+ at subheading STATUS CODES:
+The method returns the number of seconds @code{time} increased by.
+
+ at 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.
+
+ at subheading NOTES:
+NONE
+ at page
+ at subsection TIMESPEC_SUBTRACT - Subtract Two struct timespec Instances
+
+ at subheading CALLING SEQUENCE:
+
+ at ifset is-C
+ at example
+void rtems_timespec_subtract(
+ const struct timespec *start,
+ const struct timespec *end,
+ struct timespec *result
+);
+ at end example
+ at findex rtems_timespec_subtract
+ at end ifset
+
+ at ifset is-Ada
+Not Currently Supported In Ada
+ at end ifset
+
+ at subheading STATUS CODES:
+NONE
+
+ at 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.
+
+ at 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!
+
+ at page
+ at subsection TIMESPEC_DIVIDE - Divide Two struct timespec Instances
+
+ at subheading CALLING SEQUENCE:
+
+ at ifset is-C
+ at example
+void rtems_timespec_divide(
+ const struct timespec *lhs,
+ const struct timespec *rhs,
+ uint32_t *ival_percentage,
+ uint32_t *fval_percentage
+);
+ at end example
+ at findex rtems_timespec_divide
+ at end ifset
+
+ at ifset is-Ada
+Not Currently Supported In Ada
+ at end ifset
+
+ at subheading STATUS CODES:
+
+NONE
+
+ at 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.
+
+ at 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.
+
+ at page
+ at subsection TIMESPEC_DIVIDE_BY_INTEGER - Divide a struct timespec Instance by an Integer
+
+ at subheading CALLING SEQUENCE:
+
+ at ifset is-C
+ at example
+int rtems_timespec_divide_by_integer(
+ const struct timespec *time,
+ uint32_t iterations,
+ struct timespec *result
+);
+ at end example
+ at findex rtems_timespec_divide_by_integer
+ at end ifset
+
+ at ifset is-Ada
+Not Currently Supported In Ada
+ at end ifset
+
+ at subheading STATUS CODES:
+
+NONE
+
+ at 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}.
+
+ at 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.
+
+ at page
+ at subsection TIMESPEC_LESS_THAN - Less than operator
+
+ at subheading CALLING SEQUENCE:
+
+ at ifset is-C
+ at example
+bool rtems_timespec_less_than(
+ const struct timespec *lhs,
+ const struct timespec *rhs
+);
+ at end example
+ at findex rtems_timespec_less_than
+ at end ifset
+
+ at ifset is-Ada
+Not Currently Supported In Ada
+ at end ifset
+
+ at subheading STATUS CODES:
+
+This method returns @code{struct true} if @code{lhs} is less than
+ at code{rhs} and @code{struct false} otherwise.
+
+ at 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.
+
+ at subheading NOTES:
+NONE
+ at page
+ at subsection TIMESPEC_GREATER_THAN - Greater than operator
+
+ at subheading CALLING SEQUENCE:
+
+ at ifset is-C
+ at example
+bool rtems_timespec_greater_than(
+ const struct timespec *_lhs,
+ const struct timespec *_rhs
+);
+ at end example
+ at findex rtems_timespec_greater_than
+ at end ifset
+
+ at ifset is-Ada
+Not Currently Supported In Ada
+ at end ifset
+
+ at subheading STATUS CODES:
+
+This method returns @code{struct true} if @code{lhs} is greater than
+ at code{rhs} and @code{struct false} otherwise.
+
+ at subheading DESCRIPTION:
+
+This method is greater than operator for @code{struct timespec} instances.
+
+ at subheading NOTES:
+NONE
+
+ at page
+ at subsection TIMESPEC_EQUAL_TO - Check equality of timespecs
+
+ at subheading CALLING SEQUENCE:
+
+ at ifset is-C
+ at example
+bool rtems_timespec_equal_to(
+ const struct timespec *lhs,
+ const struct timespec *rhs
+);
+ at end example
+ at findex rtems_timespec_equal_to
+ at end ifset
+
+ at ifset is-Ada
+Not Currently Supported In Ada
+ at end ifset
+
+ at subheading STATUS CODES:
+
+This method returns @code{struct true} if @code{lhs} is equal to
+ at code{rhs} and @code{struct false} otherwise.
+
+
+ at subheading DESCRIPTION:
+
+This method is equality operator for @code{struct timespec} instances.
+
+ at subheading NOTES:
+NONE
+
+ at page
+ at subsection TIMESPEC_GET_SECONDS - Get Seconds Portion of struct timespec Instance
+
+ at subheading CALLING SEQUENCE:
+
+ at ifset is-C
+ at example
+time_t rtems_timespec_get_seconds(
+ struct timespec *time
+);
+ at end example
+ at findex rtems_timespec_get_seconds
+ at end ifset
+
+ at ifset is-Ada
+Not Currently Supported In Ada
+ at end ifset
+
+ at subheading STATUS CODES:
+
+This method returns the seconds portion of the specified @code{struct
+timespec} instance.
+
+ at subheading DESCRIPTION:
+
+This method returns the seconds portion of the specified @code{struct timespec} instance @code{time}.
+
+ at subheading NOTES:
+NONE
+ at page
+ at subsection TIMESPEC_GET_NANOSECONDS - Get Nanoseconds Portion of the struct timespec Instance
+
+ at subheading CALLING SEQUENCE:
+
+ at ifset is-C
+ at example
+uint32_t rtems_timespec_get_nanoseconds(
+ struct timespec *_time
+);
+ at end example
+ at findex rtems_timespec_get_nanoseconds
+ at end ifset
+
+ at ifset is-Ada
+Not Currently Supported In Ada
+ at end ifset
+
+ at subheading STATUS CODES:
+
+This method returns the nanoseconds portion of the specified @code{struct
+timespec} instance.
+
+ at subheading DESCRIPTION:
+This method returns the nanoseconds portion of the specified timespec
+which is pointed by @code{_time}.
+
+ at subheading NOTES:
+
+ at page
+ at subsection TIMESPEC_TO_TICKS - Convert struct timespec Instance to Ticks
+
+ at subheading CALLING SEQUENCE:
+
+ at ifset is-C
+ at example
+uint32_t rtems_timespec_to_ticks(
+ const struct timespec *time
+);
+ at end example
+ at findex rtems_timespec_to_ticks
+ at end ifset
+
+ at ifset is-Ada
+Not Currently Supported In Ada
+ at end ifset
+
+ at subheading STATUS CODES:
+
+This directive returns the number of ticks computed.
+
+ at subheading DESCRIPTION:
+
+This directive converts the @code{time} timespec to the corresponding number of clock ticks.
+
+ at subheading NOTES:
+NONE
+
+ at page
+ at subsection TIMESPEC_FROM_TICKS - Convert Ticks to struct timespec Representation
+
+ at subheading CALLING SEQUENCE:
+
+ at ifset is-C
+ at example
+void rtems_timespec_from_ticks(
+ uint32_t ticks,
+ struct timespec *time
+);
+ at end example
+ at findex rtems_timespec_from_ticks
+ at end ifset
+
+ at ifset is-Ada
+Not Currently Supported In Ada
+ at end ifset
+
+ at subheading STATUS CODES:
+
+NONE
+
+ at subheading DESCRIPTION:
+
+This routine converts the @code{ticks} to the corresponding @code{struct timespec} representation and stores it in @code{time}.
+
+ at subheading NOTES:
+NONE
+
More information about the vc
mailing list