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

os_time_advance()

Increments the OS time tick for the system.

os_time_delay()

Put the current task to sleep for the given number of ticks.

os_time_get()

Get the current value of OS time.

os_time_ms_to_ticks()

Converts milliseconds to os ticks.

os_get_uptime_usec()

Gets the time duration since boot.

os_gettimeofday()

Populate the given timeval and timezone structs with current time data.

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.

  • 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 time

  • 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 struct os_timeval. All parameters to the following macros are pointers to struct os_timeval.

  • os_timeradd – Add uvp to tvp and store result in vvp.

  • 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 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 int32_t os_stime_t

Signed 32-bit system time type definition.

typedef uint32_t os_time_t

Unsigned 32-bit system time type definition.

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.

os_time_t os_time_get(void)

Get the current OS time in ticks.

Return

OS time in ticks

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 setting

  • tz: 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 utctime argument, and returns the timezone (if set) into tz.

Return

0 on success, non-zero on failure

Parameters

  • utctime: The structure to put the UTC time of day into

  • tz: 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

  • tvp: 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

The number of OS ticks.

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

The number of milliseconds.

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

Return

0 on success; non-zero error code on failure

Parameters

  • listener: The listener to unregister.

INT32_MAX

Maximum value of 32-bit signed integer.

OS_TICKS_PER_SEC
OS_TIME_MAX

Maximum value for os_time_t.

OS_STIME_MAX

Maximum value for os_stime_t.

OS_TIMEOUT_NEVER

Used to wait forever for events and mutexs.

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.

Public Members

int64_t tv_sec

Seconds.

int32_t tv_usec

Microseconds within the second.

struct os_timezone
#include <os_time.h>

Structure representing a timezone offset.

Public Members

int16_t tz_minuteswest

Minutes west of GMT.

int16_t tz_dsttime

Daylight savings time correction (if any)

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.

struct os_time_change_listener
#include <os_time.h>

Time change listener.

Notified when the time-of-day is set.

Public Functions

STAILQ_ENTRY (os_time_change_listener) tcl_next

Next listener in the list.

Public Members

os_time_change_fn *tcl_fn

Callback invoked when the time-of-day is set.

void *tcl_arg

Argument to be passed to the callback function.