Lines Matching full:time
3 Time Utilities
14 representation of this time.
16 Applications often need to correlate the Zephyr internal time with external
17 time scales used in daily life, such as local time or Coordinated Universal
18 Time. These systems interpret time in different ways and may have
20 local time offsets like daylight saving time.
23 clocks underlying the cycle counter, the offset between time estimated from
24 the Zephyr clock and the actual time in a "real" civil time scale is not
27 The time utilities API supports:
29 * :ref:`converting between time representations <timeutil_repr>`
30 * :ref:`synchronizing and aligning time scales <timeutil_sync>`
35 Time Utility APIs
43 Time scale instants can be represented in multiple ways including:
45 * Seconds since an epoch. POSIX representations of time in this form include
47 representation of `"UNIX Time"
50 * Calendar time as a year, month, day, hour, minutes, and seconds relative to
51 an epoch. POSIX representations of time in this form include ``struct tm``.
53 Keep in mind that these are simply time representations that must be
54 interpreted relative to a time scale which may be local time, UTC, or some
59 converted to ``struct tm`` representing calendar time with `gmtime()
62 the calendar time representation and deal with sub-second offsets separately.
65 information about time zones. Zephyr provides this transformation with
72 Time Scale Synchronization
75 There are several factors that affect synchronizing time scales:
79 :kconfig:option:`CONFIG_SYS_CLOCK_TICKS_PER_SEC` Hertz, while an external time
88 Synchronization or alignment between time scales is done with a multi-step
91 * An instant in a time scale is represented by an (unsigned) 64-bit integer,
94 time scale/source (e.g. TAI) and a local time source
97 instant in both the reference and local time scales.
100 relative errors in the actual rate of each time scale.
102 :c:func:`timeutil_sync_local_from_ref()` convert instants in one time scale
111 Concepts Underlying Time Support in Zephyr
118 * A *time axis* is a representation of time as an ordered sequence of
120 * A *time scale* is a way of representing an instant relative to an origin
122 * A time scale is *monotonic* (increasing) if the representation of successive
123 time instants never decreases in value.
124 * A time scale is *continuous* if the representation has no abrupt changes in
126 * `Civil time <https://en.wikipedia.org/wiki/Civil_time>`__ generally refers
127 to time scales that legally defined by civil authorities, like local
128 governments, often to align local midnight to solar time.
130 Relevant Time Scales
133 `International Atomic Time
134 <https://en.wikipedia.org/wiki/International_Atomic_Time>`__ (TAI) is a time
136 and continuous time scale.
138 `Universal Time <https://en.wikipedia.org/wiki/Universal_Time>`__ (UT) is a
139 time scale based on Earth’s rotation. UT is a discontinuous time scale as it
143 over time. There are several variants of UT, with `UTC
147 UT times are independent of location. UT is the basis for Standard Time
148 (or "local time") which is the time at a particular location. Standard
149 time has a fixed offset from UT at any given instant, primarily
151 saving time") to align standard time to the local solar time. In a sense
152 local time is "more discontinuous" than UT.
154 `POSIX Time <https://tools.ietf.org/html/rfc8536#section-2>`__ is a time scale
156 start of 1970 UTC). `UNIX Time
158 time using negative values to represent times before the POSIX epoch. Both of
163 The continuous analogue is `UNIX Leap Time
164 <https://tools.ietf.org/html/rfc8536#section-2>`__ which is UNIX time plus all
167 Example of Time Scale Differences
177 UTC Date UNIX time TAI Date TAI-UTC UNIX Leap Time
191 The Zephyr tick counter has no concept of leap seconds or standard time
192 offsets and is a continuous time scale. However it can be relatively
196 There are two stages required to support conversion between Zephyr time and
197 common human time scales:
199 * Translation between the continuous but inaccurate Zephyr time scale and an
200 accurate external stable time scale;
201 * Translation between the stable time scale and the (possibly discontinuous)
202 civil time scale.
205 of converting between continuous time scales.
208 seconds and local time offset changes. This may be best provided by an
209 external library, and is not currently part of the time utility APIs.
211 Selecting an External Source and Time Scale
214 If an application requires civil time accuracy within several seconds then UTC
215 could be used as the stable time source. However, if the external source
216 adjusts to a leap second there will be a discontinuity: the elapsed time
224 - GPS time: epoch of 1980-01-06T00:00:00Z, continuous following TAI with an
226 - Bluetooth Mesh time: epoch of 2000-01-01T00:00:00Z, continuous following TAI
228 - UNIX Leap Time: epoch of 1970-01-01T00:00:00Z, continuous following TAI with
232 calendar time representations using the UNIX epoch, UNIX Leap Time is an ideal
233 choice for the external time scale.