diff options
Diffstat (limited to 'c-user/timespec_helpers.rst')
| -rw-r--r-- | c-user/timespec_helpers.rst | 548 |
1 files changed, 548 insertions, 0 deletions
diff --git a/c-user/timespec_helpers.rst b/c-user/timespec_helpers.rst new file mode 100644 index 0000000..b24a63d --- /dev/null +++ b/c-user/timespec_helpers.rst @@ -0,0 +1,548 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2011. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +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. + +.. _rtems_timespec_set: + +TIMESPEC_SET - Set struct timespec Instance +------------------------------------------- +.. index:: set struct timespec instance + +**CALLING SEQUENCE:** + +.. index:: rtems_timespec_set + +.. code-block:: c + + void rtems_timespec_set( + struct timespec *time, + time_t seconds, + uint32_t nanoseconds + ); + +**STATUS CODES:** + +NONE + +**DESCRIPTION:** + +This directive sets the ``struct timespec`` *time* 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. + +.. _rtems_timespec_zero: + +TIMESPEC_ZERO - Zero struct timespec Instance +--------------------------------------------- + +**CALLING SEQUENCE:** + +.. index:: rtems_timespec_zero + +.. code-block:: c + + void rtems_timespec_zero( + struct timespec *time + ); + +**STATUS CODES:** + +NONE + +**DESCRIPTION:** + +This routine sets the contents of the ``struct timespec`` instance ``time`` to +zero. + +**NOTES:** + +NONE + +.. _rtems_timespec_is_valid: + +TIMESPEC_IS_VALID - Check validity of a struct timespec instance +---------------------------------------------------------------- + +**CALLING SEQUENCE:** + +.. index:: rtems_timespec_is_valid + +.. code-block:: c + + bool rtems_timespec_is_valid( + const struct timespec *time + ); + +**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:** + +.. _rtems_timespec_add_to: + +TIMESPEC_ADD_TO - Add Two struct timespec Instances +--------------------------------------------------- + +**CALLING SEQUENCE:** + +.. index:: rtems_timespec_add_to + +.. code-block:: c + + uint32_t rtems_timespec_add_to( + struct timespec *time, + const struct timespec *add + ); + +**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 + +.. _rtems_timespec_subtract: + +TIMESPEC_SUBTRACT - Subtract Two struct timespec Instances +---------------------------------------------------------- + +**CALLING SEQUENCE:** + +.. index:: rtems_timespec_subtract + +.. code-block:: c + + void rtems_timespec_subtract( + const struct timespec *start, + const struct timespec *end, + struct timespec *result + ); + +**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! + +.. _rtems_timespec_divide: + +TIMESPEC_DIVIDE - Divide Two struct timespec Instances +------------------------------------------------------ + +**CALLING SEQUENCE:** + +.. index:: rtems_timespec_divide + +.. code-block:: c + + void rtems_timespec_divide( + const struct timespec *lhs, + const struct timespec *rhs, + uint32_t *ival_percentage, + uint32_t *fval_percentage + ); + +**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. + +.. _rtems_timespec_divide_by_integer: + +TIMESPEC_DIVIDE_BY_INTEGER - Divide a struct timespec Instance by an Integer +---------------------------------------------------------------------------- + +**CALLING SEQUENCE:** + +.. index:: rtems_timespec_divide_by_integer + +.. code-block:: c + + int rtems_timespec_divide_by_integer( + const struct timespec *time, + uint32_t iterations, + struct timespec *result + ); + +**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. + +.. _rtems_timespec_less_than: + +TIMESPEC_LESS_THAN - Less than operator +--------------------------------------- + +**CALLING SEQUENCE:** + +.. index:: rtems_timespec_less_than + +.. code-block:: c + + bool rtems_timespec_less_than( + const struct timespec *lhs, + const struct timespec *rhs + ); + +**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 + +.. _rtems_timespec_greater_than: + +TIMESPEC_GREATER_THAN - Greater than operator +--------------------------------------------- + +**CALLING SEQUENCE:** + +.. index:: rtems_timespec_greater_than + +.. code-block:: c + + bool rtems_timespec_greater_than( + const struct timespec *_lhs, + const struct timespec *_rhs + ); + +**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 + +.. _rtems_timespec_equal_to: + +TIMESPEC_EQUAL_TO - Check equality of timespecs +----------------------------------------------- + +**CALLING SEQUENCE:** + +.. index:: rtems_timespec_equal_to + +.. code-block:: c + + bool rtems_timespec_equal_to( + const struct timespec *lhs, + const struct timespec *rhs + ); + +**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 + +.. _rtems_timespec_get_seconds: + +TIMESPEC_GET_SECONDS - Get Seconds Portion of struct timespec Instance +---------------------------------------------------------------------- + +**CALLING SEQUENCE:** + +.. index:: rtems_timespec_get_seconds + +.. code-block:: c + + time_t rtems_timespec_get_seconds( + struct timespec *time + ); + +**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 + +.. _rtems_timespec_get_nanoseconds: + +TIMESPEC_GET_NANOSECONDS - Get Nanoseconds Portion of the struct timespec Instance +---------------------------------------------------------------------------------- + +**CALLING SEQUENCE:** + +.. index:: rtems_timespec_get_nanoseconds + +.. code-block:: c + + uint32_t rtems_timespec_get_nanoseconds( + struct timespec *_time + ); + +**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:** + +.. _rtems_timespec_to_ticks: + +TIMESPEC_TO_TICKS - Convert struct timespec Instance to Ticks +------------------------------------------------------------- + +**CALLING SEQUENCE:** + +.. index:: rtems_timespec_to_ticks + +.. code-block:: c + + uint32_t rtems_timespec_to_ticks( + const struct timespec *time + ); + +**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 + +.. _rtems_timespec_from_ticks: + +TIMESPEC_FROM_TICKS - Convert Ticks to struct timespec Representation +--------------------------------------------------------------------- + +**CALLING SEQUENCE:** + +.. index:: rtems_timespec_from_ticks + +.. code-block:: 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 |