Split document into seperate files by section.

1 files changed, 503 insertions, 0 deletions

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.
+