diff options
Diffstat (limited to 'doc/user/timespec.t')
| -rw-r--r-- | doc/user/timespec.t | 553 |
1 files changed, 0 insertions, 553 deletions
diff --git a/doc/user/timespec.t b/doc/user/timespec.t deleted file mode 100644 index 57ed2f3a03..0000000000 --- a/doc/user/timespec.t +++ /dev/null @@ -1,553 +0,0 @@ -@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 - |