@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