OS Time¶
The system time for the Mynewt OS.
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 os_time_t
value.
Wallclock time is represented using the struct os_timeval
and
struct os_timezone
tuple.
struct os_timeval
represents the number of seconds elapsed since
00:00:00 Jan 1, 1970 UTC.
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 */
struct 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.
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 |
---|---|
Increments the OS time tick for the system. |
|
Put the current task to sleep for the given number of ticks. |
|
Get the current value of OS time. |
|
Converts milliseconds to os ticks. |
|
Gets the time duration since boot. |
|
Populate the given timeval and timezone structs with current time data. |
|
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.
OS_TIME_TICK_LT
– evaluates to true if t1 is before t2 in time.OS_TIME_TICK_GT
– evaluates to true if t1 is after t2 in timeOS_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
struct os_timeval
. All parameters to the following macros are
pointers to struct os_timeval
.
os_timeradd
– Adduvp
totvp
and store result invvp
.os_timersub
– Subtractuvp
fromtvp
and store result invvp
.
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 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¶
-
typedef uint32_t
os_time_t
¶
-
typedef int32_t
os_stime_t
¶
-
typedef void
os_time_change_fn
(const struct os_time_change_info *info, void *arg)¶ Callback that is executed when the time-of-day is set.
- Parameters
info
: Describes the time change that just occurred.arg
: Optional argument correponding to listener.
-
void
os_time_advance
(int ticks)¶ Move OS time forward ticks.
- Parameters
ticks
: The number of ticks to move time forward.
-
void
os_time_delay
(os_time_t osticks)¶ Puts the current task to sleep for the specified number of os ticks.
There is no delay if ticks is 0.
- Parameters
osticks
: Number of ticks to delay (0 means no delay).
-
int
os_settimeofday
(struct os_timeval *utctime, struct os_timezone *tz)¶ Set the time of day.
This does not modify os time, but rather just modifies the offset by which we are tracking real time against os time. This function notifies all registered time change listeners.
- Return
0 on success, non-zero on failure.
- Parameters
utctime
: A timeval representing the UTC time we are settingtz
: The time-zone to apply against the utctime being set.
-
int
os_gettimeofday
(struct os_timeval *utctime, struct os_timezone *tz)¶ Get the current time of day.
Returns the time of day in UTC into the tv argument, and returns the timezone (if set) into tz.
- Return
0 on success, non-zero on failure
- Parameters
tv
: The structure to put the UTC time of day intotz
: The structure to put the timezone information into
-
bool
os_time_is_set
(void)¶ Indicates whether the time has been set.
- Return
true if time is set; false otherwise.
-
int64_t
os_get_uptime_usec
(void)¶ Get time since boot in microseconds.
- Return
time since boot in microseconds
-
void
os_get_uptime
(struct os_timeval *tvp)¶ Get time since boot as os_timeval.
- Parameters
tv
: Structure to put the time since boot.
-
int
os_time_ms_to_ticks
(uint32_t ms, os_time_t *out_ticks)¶ Converts milliseconds to OS ticks.
- Return
0 on success; OS_EINVAL if the result is too large to fit in a uint32_t.
- Parameters
ms
: The milliseconds input.out_ticks
: The OS ticks output.
-
int
os_time_ticks_to_ms
(os_time_t ticks, uint32_t *out_ms)¶ Converts OS ticks to milliseconds.
- Return
0 on success; OS_EINVAL if the result is too large to fit in a uint32_t.
- Parameters
ticks
: The OS ticks input.out_ms
: The milliseconds output.
-
static inline os_time_t
os_time_ms_to_ticks32
(uint32_t ms)¶ Converts milliseconds to OS ticks.
This function does not check if conversion overflows and should be only used in cases where input is known to be small enough not to overflow.
- Return
result on success
- Parameters
ms
: The milliseconds input.
-
static inline uint32_t
os_time_ticks_to_ms32
(os_time_t ticks)¶ Converts OS ticks to milliseconds.
This function does not check if conversion overflows and should be only used in cases where input is known to be small enough not to overflow.
- Return
result on success
- Parameters
ticks
: The OS ticks input.
-
void
os_time_change_listen
(struct os_time_change_listener *listener)¶ Registers a time change listener.
Whenever the time is set, all registered listeners are notified. The provided pointer is added to an internal list, so the listener’s lifetime must extend indefinitely (or until the listener is removed).
NOTE: This function is not thread safe. The following operations must be kept exclusive: o Addition of listener o Removal of listener o Setting time
- Parameters
listener
: The listener to register.
-
int
os_time_change_remove
(const struct os_time_change_listener *listener)¶ Unregisters a time change listener.
NOTE: This function is not thread safe. The following operations must be kept exclusive: o Addition of listener o Removal of listener o Setting time
- Parameters
listener
: The listener to unregister.
-
INT32_MAX
¶
-
OS_TIME_MAX
¶
-
OS_STIME_MAX
¶
-
OS_TIMEOUT_NEVER
¶
-
OS_TIME_TICK_LT
(__t1, __t2)¶
-
OS_TIME_TICK_GT
(__t1, __t2)¶
-
OS_TIME_TICK_GEQ
(__t1, __t2)¶
-
OS_TIMEVAL_LT
(__t1, __t2)¶
-
OS_TIMEVAL_LEQ
(__t1, __t2)¶
-
OS_TIMEVAL_GT
(__t1, __t2)¶
-
OS_TIMEVAL_GEQ
(__t1, __t2)¶
-
os_timeradd
(tvp, uvp, vvp)¶ Add first two timeval arguments and place results in third timeval argument.
-
os_timersub
(tvp, uvp, vvp)¶ Subtract first two timeval arguments and place results in third timeval argument.
-
struct
os_timeval
¶ - #include <os_time.h>
Structure representing time since Jan 1 1970 with microsecond granularity.
-
struct
os_timezone
¶ - #include <os_time.h>
Structure representing a timezone offset.
-
struct
os_time_change_info
¶ - #include <os_time.h>
Represents a time change.
Passed to time change listeners when the current time-of-day is set.
Public Members
-
const struct os_timeval *
tci_prev_tv
¶ UTC time prior to change.
-
const struct os_timezone *
tci_prev_tz
¶ Time zone prior to change.
-
const struct os_timeval *
tci_cur_tv
¶ UTC time after change.
-
const struct os_timezone *
tci_cur_tz
¶ Time zone after change.
-
bool
tci_newly_synced
¶ True if the time was not set prior to change.
-
const struct os_timeval *
-
struct
os_time_change_listener
¶ - #include <os_time.h>
Time change listener.
Notified when the time-of-day is set.