rtems/doc/user/timespec.t

@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