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