Timespec Helpers ################ Introduction ============ The Timespec helpers manager provides directives to assist in manipulating instances of the POSIX ``struct timespec`` structure. The directives provided by the timespec helpers manager are: - ``rtems_timespec_set`` - Set timespec’s value - ``rtems_timespec_zero`` - Zero timespec’s value - ``rtems_timespec_is_valid`` - Check if timespec is valid - ``rtems_timespec_add_to`` - Add two timespecs - ``rtems_timespec_subtract`` - Subtract two timespecs - ``rtems_timespec_divide`` - Divide two timespecs - ``rtems_timespec_divide_by_integer`` - Divide timespec by integer - ``rtems_timespec_less_than`` - Less than operator - ``rtems_timespec_greater_than`` - Greater than operator - ``rtems_timespec_equal_to`` - Check if two timespecs are equal - ``rtems_timespec_get_seconds`` - Obtain seconds portion of timespec - ``rtems_timespec_get_nanoseconds`` - Obtain nanoseconds portion of timespec - ``rtems_timespec_to_ticks`` - Convert timespec to number of ticks - ``rtems_timespec_from_ticks`` - Convert ticks to timespec Background ========== Time Storage Conventions ------------------------ Time can be stored in many ways. One of them is the ``struct timespec`` format which is a structure that consists of the fields ``tv_sec`` to represent seconds and ``tv_nsec`` to represent nanoseconds. The``struct timeval`` structure is simular and consists of seconds (stored in ``tv_sec``) and microseconds (stored in ``tv_usec``). Either``struct timespec`` or ``struct timeval`` can be used to represent elapsed time, time of executing some operations, or time of day. Operations ========== Set and Obtain Timespec Value ----------------------------- A user may write a specific time by passing the desired seconds and nanoseconds values and the destination ``struct timespec`` using the``rtems_timespec_set`` directive. The ``rtems_timespec_zero`` directive is used to zero the seconds and nanoseconds portions of a ``struct timespec`` instance. Users may obtain the seconds or nanoseconds portions of a ``struct timespec`` instance with the ``rtems_timespec_get_seconds`` or``rtems_timespec_get_nanoseconds`` methods, respectively. Timespec Math ------------- A user can perform multiple operations on ``struct timespec`` instances. The helpers in this manager assist in adding, subtracting, and performing divison on ``struct timespec`` instances. - Adding two ``struct timespec`` can be done using the``rtems_timespec_add_to`` directive. This directive is used mainly to calculate total amount of time consumed by multiple operations. - The ``rtems_timespec_subtract`` is used to subtract two``struct timespecs`` instances and determine the elapsed time between those two points in time. - The ``rtems_timespec_divide`` is used to use to divide one``struct timespec`` instance by another. This calculates the percentage with a precision to three decimal points. - The ``rtems_timespec_divide_by_integer`` is used to divide a``struct timespec`` instance by an integer. It is commonly used in benchmark calculations to dividing duration by the number of iterations performed. Comparing struct timespec Instances ----------------------------------- A user can compare two ``struct timespec`` instances using the``rtems_timespec_less_than``, ``rtems_timespec_greater_than`` or ``rtems_timespec_equal_to`` routines. Conversions and Validity Check ------------------------------ Conversion to and from clock ticks may be performed by using the``rtems_timespec_to_ticks`` and ``rtems_timespec_from_ticks`` directives. User can also check validity of timespec with``rtems_timespec_is_valid`` routine. 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. TIMESPEC_SET - Set struct timespec Instance ------------------------------------------- **CALLING SEQUENCE:** .. code:: c void rtems_timespec_set( struct timespec \*time, time_t seconds, uint32_t nanoseconds ); .. index:: rtems_timespec_set **STATUS CODES:** NONE **DESCRIPTION:** This directive sets the ``struct timespec`` ``time`` value to the desired ``seconds`` and ``nanoseconds`` values. **NOTES:** This method does NOT check if ``nanoseconds`` is less than the maximum number of nanoseconds in a second. TIMESPEC_ZERO - Zero struct timespec Instance --------------------------------------------- **CALLING SEQUENCE:** .. code:: c void rtems_timespec_zero( struct timespec \*time ); .. index:: rtems_timespec_zero **STATUS CODES:** NONE **DESCRIPTION:** This routine sets the contents of the ``struct timespec`` instance``time`` to zero. **NOTES:** NONE TIMESPEC_IS_VALID - Check validity of a struct timespec instance ---------------------------------------------------------------- **CALLING SEQUENCE:** .. code:: c bool rtems_timespec_is_valid( const struct timespec \*time ); .. index:: rtems_timespec_is_valid **STATUS CODES:** This method returns ``true`` if the instance is valid, and ``false`` otherwise. **DESCRIPTION:** This routine check validity of a ``struct timespec`` instance. It checks if the nanoseconds portion of the ``struct timespec`` instanceis in allowed range (less than the maximum number of nanoseconds per second). **NOTES:** TIMESPEC_ADD_TO - Add Two struct timespec Instances --------------------------------------------------- **CALLING SEQUENCE:** .. code:: c uint32_t rtems_timespec_add_to( struct timespec \*time, const struct timespec \*add ); .. index:: rtems_timespec_add_to **STATUS CODES:** The method returns the number of seconds ``time`` increased by. **DESCRIPTION:** This routine adds two ``struct timespec`` instances. The second argument is added to the first. The parameter ``time`` is the base time to which the ``add`` parameter is added. **NOTES:** NONE TIMESPEC_SUBTRACT - Subtract Two struct timespec Instances ---------------------------------------------------------- **CALLING SEQUENCE:** .. code:: c void rtems_timespec_subtract( const struct timespec \*start, const struct timespec \*end, struct timespec \*result ); .. index:: rtems_timespec_subtract **STATUS CODES:** NONE **DESCRIPTION:** This routine subtracts ``start`` from ``end`` saves the difference in ``result``. The primary use of this directive is to calculate elapsed time. **NOTES:** It is possible to subtract when ``end`` is less than ``start`` and it produce negative ``result``. When doing this you should be careful and remember that only the seconds portion of a ``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! TIMESPEC_DIVIDE - Divide Two struct timespec Instances ------------------------------------------------------ **CALLING SEQUENCE:** .. code:: c void rtems_timespec_divide( const struct timespec \*lhs, const struct timespec \*rhs, uint32_t \*ival_percentage, uint32_t \*fval_percentage ); .. index:: rtems_timespec_divide **STATUS CODES:** NONE **DESCRIPTION:** This routine divides the ``struct timespec`` instance ``lhs`` by the ``struct timespec`` instance ``rhs``. The result is returned in the ``ival_percentage`` and ``fval_percentage``, representing the integer and fractional results of the division respectively. The ``ival_percentage`` is integer value of calculated percentage and ``fval_percentage`` is fractional part of calculated percentage. **NOTES:** The intended use is calculating percentges to three decimal points. When dividing by zero, this routine return both ``ival_percentage`` and ``fval_percentage`` equal zero. The division is performed using exclusively integer operations. TIMESPEC_DIVIDE_BY_INTEGER - Divide a struct timespec Instance by an Integer ---------------------------------------------------------------------------- **CALLING SEQUENCE:** .. code:: c int rtems_timespec_divide_by_integer( const struct timespec \*time, uint32_t iterations, struct timespec \*result ); .. index:: rtems_timespec_divide_by_integer **STATUS CODES:** NONE **DESCRIPTION:** This routine divides the ``struct timespec`` instance ``time`` by the integer value ``iterations``. The result is saved in ``result``. **NOTES:** The expected use is to assist in benchmark calculations where you typically divide a duration (``time``) by a number of iterations what gives average time. TIMESPEC_LESS_THAN - Less than operator --------------------------------------- **CALLING SEQUENCE:** .. code:: c bool rtems_timespec_less_than( const struct timespec \*lhs, const struct timespec \*rhs ); .. index:: rtems_timespec_less_than **STATUS CODES:** This method returns ``struct true`` if ``lhs`` is less than``rhs`` and ``struct false`` otherwise. **DESCRIPTION:** This method is the less than operator for ``struct timespec`` instances. The first parameter is the left hand side and the second is the right hand side of the comparison. **NOTES:** NONE TIMESPEC_GREATER_THAN - Greater than operator --------------------------------------------- **CALLING SEQUENCE:** .. code:: c bool rtems_timespec_greater_than( const struct timespec \*_lhs, const struct timespec \*_rhs ); .. index:: rtems_timespec_greater_than **STATUS CODES:** This method returns ``struct true`` if ``lhs`` is greater than``rhs`` and ``struct false`` otherwise. **DESCRIPTION:** This method is greater than operator for ``struct timespec`` instances. **NOTES:** NONE TIMESPEC_EQUAL_TO - Check equality of timespecs ----------------------------------------------- **CALLING SEQUENCE:** .. code:: c bool rtems_timespec_equal_to( const struct timespec \*lhs, const struct timespec \*rhs ); .. index:: rtems_timespec_equal_to **STATUS CODES:** This method returns ``struct true`` if ``lhs`` is equal to``rhs`` and ``struct false`` otherwise. **DESCRIPTION:** This method is equality operator for ``struct timespec`` instances. **NOTES:** NONE TIMESPEC_GET_SECONDS - Get Seconds Portion of struct timespec Instance ---------------------------------------------------------------------- **CALLING SEQUENCE:** .. code:: c time_t rtems_timespec_get_seconds( struct timespec \*time ); .. index:: rtems_timespec_get_seconds **STATUS CODES:** This method returns the seconds portion of the specified ``struct timespec`` instance. **DESCRIPTION:** This method returns the seconds portion of the specified ``struct timespec`` instance ``time``. **NOTES:** NONE TIMESPEC_GET_NANOSECONDS - Get Nanoseconds Portion of the struct timespec Instance ---------------------------------------------------------------------------------- **CALLING SEQUENCE:** .. code:: c uint32_t rtems_timespec_get_nanoseconds( struct timespec \*_time ); .. index:: rtems_timespec_get_nanoseconds **STATUS CODES:** This method returns the nanoseconds portion of the specified ``struct timespec`` instance. **DESCRIPTION:** This method returns the nanoseconds portion of the specified timespec which is pointed by ``_time``. **NOTES:** TIMESPEC_TO_TICKS - Convert struct timespec Instance to Ticks ------------------------------------------------------------- **CALLING SEQUENCE:** .. code:: c uint32_t rtems_timespec_to_ticks( const struct timespec \*time ); .. index:: rtems_timespec_to_ticks **STATUS CODES:** This directive returns the number of ticks computed. **DESCRIPTION:** This directive converts the ``time`` timespec to the corresponding number of clock ticks. **NOTES:** NONE TIMESPEC_FROM_TICKS - Convert Ticks to struct timespec Representation --------------------------------------------------------------------- **CALLING SEQUENCE:** .. code:: c void rtems_timespec_from_ticks( uint32_t ticks, struct timespec \*time ); .. index:: rtems_timespec_from_ticks **STATUS CODES:** NONE **DESCRIPTION:** This routine converts the ``ticks`` to the corresponding ``struct timespec`` representation and stores it in ``time``. **NOTES:** NONE .. COMMENT: COPYRIGHT (c) 2011. .. COMMENT: On-Line Applications Research Corporation (OAR). .. COMMENT: All rights reserved.