From fd6dc8c8de4dbc7ecf8a82a597cd5b43476fc8e3 Mon Sep 17 00:00:00 2001 From: Amar Takhar Date: Sun, 17 Jan 2016 19:19:43 -0500 Subject: Split document into seperate files by section. --- c_user/timespec_helpers.rst | 503 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 503 insertions(+) create mode 100644 c_user/timespec_helpers.rst (limited to 'c_user/timespec_helpers.rst') diff --git a/c_user/timespec_helpers.rst b/c_user/timespec_helpers.rst new file mode 100644 index 0000000..f7c9802 --- /dev/null +++ b/c_user/timespec_helpers.rst @@ -0,0 +1,503 @@ +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. + -- cgit v1.2.3