wms_time.h File Reference

Detailed Description

The Time library provides functions for keeping track of time, in various levels of granularity. It also has functions to do time arithmetic and comparisons with a high-precision timestamp type that is specific to each platform.

Library services are accessed via lib_time handle.

Definition in file wms_time.h.

Go to the source code of this file.

Typedefs
typedef uint32_t	app_lib_time_timestamp_hp_t
	Highest-precision timestamp type available on the platform. More...
typedef uint32_t	app_lib_time_timestamp_coarse_t
	Coarse timestamp type. More...
typedef app_lib_time_timestamp_hp_t(*	app_lib_time_get_timestamp_hp_f) (void)
	Get current time as a high-precision timestamp. More...
typedef app_lib_time_timestamp_coarse_t(*	app_lib_time_get_timestamp_coarse_f) (void)
	Get current time as a coarse timestamp. More...
typedef uint32_t(*	app_lib_time_get_timestamp_s_f) (void)
	Get current time as a number of seconds since the node started up. More...
typedef app_lib_time_timestamp_hp_t(*	app_lib_time_add_us_to_timestamp_hp_f) (app_lib_time_timestamp_hp_t base, uint32_t time_to_add_us)
	Add a given number of microseconds to a high-precision timestamp base. More...
typedef bool(*	app_lib_time_is_timestamp_hp_before_f) (app_lib_time_timestamp_hp_t time1, app_lib_time_timestamp_hp_t time2)
	Compare two high-precision timestamps. More...
typedef uint32_t(*	app_lib_time_get_time_difference_us_f) (app_lib_time_timestamp_hp_t time1, app_lib_time_timestamp_hp_t time2)
	Calculate the difference between two high-precision timestamps in microseconds. More...
typedef uint32_t(*	app_lib_time_get_max_delay_hp_us_f) (void)
	Return the maximum valid period for high-precision timestamps comparison. More...

Data Structures
struct	app_lib_time_t
	List of library functions. More...

Macros
#define	APP_LIB_TIME_NAME   0x0013c24d
	Library symbolic name. More...
#define	APP_LIB_TIME_VERSION   0x200
	Maximum supported library version. More...

Typedef Documentation

app_lib_time_add_us_to_timestamp_hp_f

typedef app_lib_time_timestamp_hp_t(* app_lib_time_add_us_to_timestamp_hp_f) (app_lib_time_timestamp_hp_t base, uint32_t time_to_add_us)

Add a given number of microseconds to a high-precision timestamp base.

As the high-precision timestamp app_lib_time_timestamp_hp_t implementation depends on the platform, all arithmetic and comparisons must be done using functions in this library.

Parameters

base	The base high-precision timestamp
time_to_add_us	The time to add in us

Returns

The new high-precision timestamp

Example:

// It can be used to implement busy wait loop for short period
static void user_delay_ms(uint32_t period_ms)
{
    app_lib_time_timestamp_hp_t end;
    end = lib_time->addUsToHpTimestamp(lib_time->getTimestampHp(),
                                       period_ms * 1000);
 
    // Active wait until period is elapsed
    while (lib_time->isHpTimestampBefore(lib_time->getTimestampHp(),
                                         end));
}
 
...
// Busy wait loop of 1 ms
user_delay_ms(1);
...

Definition at line 130 of file wms_time.h.

app_lib_time_get_max_delay_hp_us_f

typedef uint32_t(* app_lib_time_get_max_delay_hp_us_f) (void)

Return the maximum valid period for high-precision timestamps comparison.

It can be used to check maximum range for valid results with arithmetic and comparisons functions lib_time->isHpTimestampBefore() and lib_time->getTimeDiffUs().

Returns

The maximum possible time in us for timestamps comparison or time difference

Note

if this time is not enough, consider using the coarse or second timestamps instead

Definition at line 187 of file wms_time.h.

app_lib_time_get_time_difference_us_f

typedef uint32_t(* app_lib_time_get_time_difference_us_f) (app_lib_time_timestamp_hp_t time1, app_lib_time_timestamp_hp_t time2)

Calculate the difference between two high-precision timestamps in microseconds.

Parameters

time1	The first timestamp
time2	The second timestamp

Returns

The time in us between time1 and time2

Note

High-precision timestamps have limited range. When two high-precision timestamps are too far apart in time, this function no longer gives correct results. Function lib_time->getMaxHpDelay() can be used to query the maximum time between two high-precision timestamps that can be used in arithmetic and comparisons.

Definition at line 170 of file wms_time.h.

app_lib_time_get_timestamp_coarse_f

typedef app_lib_time_timestamp_coarse_t(* app_lib_time_get_timestamp_coarse_f) (void)

Get current time as a coarse timestamp.

The value starts counting from zero when the node starts up and wraps back to zero in about 388 days.

Returns

A coarse timestamp

Example:

app_lib_time_timestamp_coarse_t currtime;
currtime = lib_time->getTimestampCoarse();

Definition at line 83 of file wms_time.h.

app_lib_time_get_timestamp_hp_f

typedef app_lib_time_timestamp_hp_t(* app_lib_time_get_timestamp_hp_f) (void)

Get current time as a high-precision timestamp.

The time starts counting from zero when the node starts up.

Returns

a timestamp with high precision

Note

This timestamp is the highest precision you can have on the platform. It doesn't have unity and must be handled with associated services.

This timestamp wraps quite often. Please check lib_time->getMaxHpDelay() to get this wrapping period

Definition at line 66 of file wms_time.h.

app_lib_time_get_timestamp_s_f

typedef uint32_t(* app_lib_time_get_timestamp_s_f) (void)

Get current time as a number of seconds since the node started up.

The wrap cycle is long enough (136 years) to be of no concern.

Returns

the current timestamp in s

Definition at line 93 of file wms_time.h.

app_lib_time_is_timestamp_hp_before_f

typedef bool(* app_lib_time_is_timestamp_hp_before_f) (app_lib_time_timestamp_hp_t time1, app_lib_time_timestamp_hp_t time2)

Compare two high-precision timestamps.

See app_lib_time_add_us_to_timestamp_hp_f for code example

Parameters

time1	The first timestamp
time2	The second timestamp

Returns

true if time1 is before time2

Note

High-precision timestamps have limited range. When two high-precision timestamps are too far apart in time, this function no longer gives correct results. Function lib_time->getMaxHpDelay() can be used to query the maximum time between two high-precision timestamps that can be used in arithmetic and comparisons.

Definition at line 151 of file wms_time.h.

app_lib_time_timestamp_coarse_t

typedef uint32_t app_lib_time_timestamp_coarse_t

Coarse timestamp type.

The coarse timestamp type has a resolution of 1 / 128 s. This timestamp resolution is used e.g. by the Data library for reporting buffering and end-to-end delays.

Definition at line 50 of file wms_time.h.

app_lib_time_timestamp_hp_t

typedef uint32_t app_lib_time_timestamp_hp_t

Highest-precision timestamp type available on the platform.

As implementation of this timestamp depends on the platform, direct manipulation of the timestamp value in the application is not possible. Instead, functions for arithmetic (lib_time->addUsToHpTimestamp() and lib_time->getTimeDiffUs()) and comparisons (lib_time->isHpTimestampBefore()) are provided in this library.

Definition at line 41 of file wms_time.h.

---

Data Structure Documentation

app_lib_time_t

struct app_lib_time_t

List of library functions.

Definition at line 192 of file wms_time.h.

Data Fields
app_lib_time_add_us_to_timestamp_hp_f	addUsToHpTimestamp
app_lib_time_get_max_delay_hp_us_f	getMaxHpDelay
app_lib_time_get_time_difference_us_f	getTimeDiffUs
app_lib_time_get_timestamp_coarse_f	getTimestampCoarse
app_lib_time_get_timestamp_hp_f	getTimestampHp
app_lib_time_get_timestamp_s_f	getTimestampS
app_lib_time_is_timestamp_hp_before_f	isHpTimestampBefore

Macro Definition Documentation

APP_LIB_TIME_NAME

#define APP_LIB_TIME_NAME   0x0013c24d

Library symbolic name.

"TIME"

Definition at line 26 of file wms_time.h.

APP_LIB_TIME_VERSION

#define APP_LIB_TIME_VERSION   0x200

Maximum supported library version.

Definition at line 29 of file wms_time.h.