From 66dacbfb8efe777f963a027dcd0645a6fefb2d5b Mon Sep 17 00:00:00 2001 From: "Joel Sherrill joel.sherrill@oarcorp.com" Date: Thu, 30 Aug 2012 18:38:50 -0500 Subject: timespec: Add documentation for struct timespec Helpers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- 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(-) create mode 100644 doc/user/timespec.t 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 @@ -179,11 +180,16 @@ 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 + -- cgit v1.2.3