OS Time
=======

The system time for the Mynewt OS.

.. contents::
  :local:
  :depth: 2

Description
-----------

The Mynewt OS contains an incrementing time that drives the OS scheduler
and time delays. The time is a fixed size (e.g. 32 bits) and will
eventually wrap back to zero. The time to wrap from zero back to zero is
called the **OS time epoch**.

The frequency of the OS time tick is specified in the
architecture-specific OS code ``os_arch.h`` and is named
``OS_TICKS_PER_SEC``.

The Mynewt OS also provides APIs for setting and retrieving the
wallclock time (also known as local time or time-of-day in other
operating systems).

Data Structures
---------------

Time is stored in Mynewt as an :c:type:`os_time_t` value.

Wallclock time is represented using the :c:data:`struct os_timeval <os_timeval>` and
:c:data:`struct os_timezone <os_timezone>` tuple.

:c:data:`struct os_timeval <os_timeval>` represents the number of seconds elapsed since
00:00:00 Jan 1, 1970 UTC.

.. code-block:: c

   struct os_timeval {
       int64_t tv_sec;  /* seconds since Jan 1 1970 UTC */
       int32_t tv_usec; /* fractional seconds */
   };

   struct os_timeval tv = { 1457400000, 0 };  /* 01:20:00 Mar 8 2016 UTC */

:c:data:`struct os_timezone <os_timezone>` is used to specify the offset of local time from
UTC and whether daylight savings is in effect. Note that ``tz_minuteswest`` is a positive number
if the local time is *behind* UTC and a negative number if the local time is *ahead* of UTC.

.. code-block:: c

   struct os_timezone {
       int16_t tz_minuteswest;
       int16_t tz_dsttime;
   };

   /* Pacific Standard Time is 08:00 hours west of UTC */
   struct os_timezone PST = { 480, 0 };
   struct os_timezone PDT = { 480, 1 };

   /* Indian Standard Time is 05:30 hours east of UTC */
   struct os_timezone IST = { -330, 0 };

Functions
-----------------

=============================== ====================
Function            	          Description
=============================== ====================
:c:func:`os_time_advance()`	    Increments the OS time tick for the system.
:c:func:`os_time_delay()`	    Put the current task to sleep for the given number of ticks.
:c:func:`os_time_get()`	        Get the current value of OS time.
:c:func:`os_time_ms_to_ticks()`	Converts milliseconds to os ticks.
:c:func:`os_get_uptime_usec()`	Gets the time duration since boot.
:c:func:`os_gettimeofday()`	    Populate the given timeval and timezone structs with current time data.
:c:func:`os_settimeofday()`	    Set the current time of day to the given time structs.
=============================== ====================

Macros
--------------

Several macros help with the evalution of times with respect to each
other.

-  :c:macro:`OS_TIME_TICK_LT` -- evaluates to true if t1 is before t2 in
   time.
-  :c:macro:`OS_TIME_TICK_GT` -- evaluates to true if t1 is after t2 in
   time
-  :c:macro:`OS_TIME_TICK_GEQ` -- evaluates to true if t1 is on or after
   t2 in time.

NOTE: For all of these macros the calculations are done modulo
'os_time_t'.

Ensure that comparison of OS time always uses the macros above (to
compensate for the possible wrap of OS time).

The following macros help adding or subtracting time when represented as
:c:data:`struct os_timeval <os_timeval>`. All parameters to the following macros are
pointers to :c:data:`struct os_timeval <os_timeval>`.

-  :c:macro:`os_timeradd` -- Add ``uvp`` to ``tvp`` and store
   result in ``vvp``.
-  :c:macro:`os_timersub` -- Subtract ``uvp`` from ``tvp`` and
   store result in ``vvp``.

Special Notes
-------------

Its important to understand how quickly the time wraps especially when
doing time comparison using the macros above (or by any other means).

For example, if a tick is 1 millisecond and :c:type:`os_time_t` is 32-bits the
OS time will wrap back to zero in about 49.7 days or stated another way,
the OS time epoch is 49.7 days.

If two times are more than 1/2 the OS time epoch apart, any time
comparison will be incorrect. Ensure at design time that comparisons
will not occur between times that are more than half the OS time epoch.


API
-----

.. doxygengroup:: OSTime
    :content-only:
    :members: