timestamp

Timestamp functions relating to points in time (including the current time). More...

Typedefs
typedef uint64_t	absolute_time_t
	An opaque 64 bit timestamp in microseconds.

Functions
static uint64_t	to_us_since_boot (absolute_time_t t)
	convert an absolute_time_t into a number of microseconds since boot.
static void	update_us_since_boot (absolute_time_t *t, uint64_t us_since_boot)
	update an absolute_time_t value to represent a given number of microseconds since boot
static absolute_time_t	from_us_since_boot (uint64_t us_since_boot)
	convert a number of microseconds since boot to an absolute_time_t
static absolute_time_t	get_absolute_time (void)
	Return a representation of the current time.
static uint32_t	to_ms_since_boot (absolute_time_t t)
	Convert a timestamp into a number of milliseconds since boot.
static uint64_t	to_ms_64_since_boot (absolute_time_t t)
	Convert a timestamp into a number of 64-bit milliseconds since boot.
static absolute_time_t	delayed_by_us (const absolute_time_t t, uint64_t us)
	Return a timestamp value obtained by adding a number of microseconds to another timestamp.
static absolute_time_t	delayed_by_ms (const absolute_time_t t, uint32_t ms)
	Return a timestamp value obtained by adding a number of milliseconds to another timestamp.
static absolute_time_t	make_timeout_time_us (uint64_t us)
	Convenience method to get the timestamp a number of microseconds from the current time.
static absolute_time_t	make_timeout_time_ms (uint32_t ms)
	Convenience method to get the timestamp a number of milliseconds from the current time.
static int64_t	absolute_time_diff_us (absolute_time_t from, absolute_time_t to)
	Return the difference in microseconds between two timestamps.
static absolute_time_t	absolute_time_min (absolute_time_t a, absolute_time_t b)
	Return the earlier of two timestamps.
static bool	is_at_the_end_of_time (absolute_time_t t)
	Determine if the given timestamp is "at_the_end_of_time".
static bool	is_nil_time (absolute_time_t t)
	Determine if the given timestamp is nil.

Variables
const absolute_time_t	at_the_end_of_time
	The timestamp representing the end of time; this is actually not the maximum possible timestamp, but is set to 0x7fffffff_ffffffff microseconds to avoid sign overflows with time arithmetic. This is almost 300,000 years, so should be sufficient.
const absolute_time_t	nil_time
	The timestamp representing a null timestamp.

Detailed Description

Timestamp functions relating to points in time (including the current time).

These are functions for dealing with timestamps (i.e. instants in time) represented by the type absolute_time_t. This opaque type is provided to help prevent accidental mixing of timestamps and relative time values.

Typedef Documentation

absolute_time_t

typedef uint64_t absolute_time_t

An opaque 64 bit timestamp in microseconds.

The type is used instead of a raw uint64_t to prevent accidentally passing relative times or times in the wrong time units where an absolute time is required.

note: As of SDK 2.0.0 this type defaults to being a uint64_t (i.e. no protection); it is enabled by setting PICO_OPAQUE_ABSOLUTE_TIME_T to 1

See also

to_us_since_boot()

update_us_since_boot()

Function Documentation

absolute_time_diff_us()

int64_t absolute_time_diff_us ( absolute_time_t from, absolute_time_t to )

inlinestatic

Return the difference in microseconds between two timestamps.

Note

Be careful when diffing against large timestamps (e.g. at_the_end_of_time) as the signed integer may overflow.

Parameters

from	the first timestamp
to	the second timestamp

Returns

the number of microseconds between the two timestamps (positive if to is after from except in case of overflow)

absolute_time_min()

absolute_time_t absolute_time_min ( absolute_time_t a, absolute_time_t b )

inlinestatic

Return the earlier of two timestamps.

Parameters

a	the first timestamp
b	the second timestamp

Returns

the earlier of the two timestamps

delayed_by_ms()

absolute_time_t delayed_by_ms ( const absolute_time_t t, uint32_t ms )

inlinestatic

Return a timestamp value obtained by adding a number of milliseconds to another timestamp.

Parameters

t	the base timestamp
ms	the number of milliseconds to add

Returns

the timestamp representing the resulting time

delayed_by_us()

absolute_time_t delayed_by_us ( const absolute_time_t t, uint64_t us )

inlinestatic

Return a timestamp value obtained by adding a number of microseconds to another timestamp.

Parameters

t	the base timestamp
us	the number of microseconds to add

Returns

the timestamp representing the resulting time

from_us_since_boot()

absolute_time_t from_us_since_boot ( uint64_t us_since_boot )

inlinestatic

convert a number of microseconds since boot to an absolute_time_t

fn from_us_since_boot

Parameters

us_since_boot

number of microseconds since boot

Returns

an absolute time equivalent to us_since_boot

get_absolute_time()

absolute_time_t get_absolute_time ( void )

inlinestatic

Return a representation of the current time.

Returns an opaque high fidelity representation of the current time sampled during the call.

Returns

the absolute time (now) of the hardware timer

See also

absolute_time_t

sleep_until()

time_us_64()

is_at_the_end_of_time()

bool is_at_the_end_of_time ( absolute_time_t t )

inlinestatic

Determine if the given timestamp is "at_the_end_of_time".

Parameters

t	the timestamp

Returns

true if the timestamp is at_the_end_of_time

See also

at_the_end_of_time

is_nil_time()

bool is_nil_time ( absolute_time_t t )

inlinestatic

Determine if the given timestamp is nil.

Parameters

t	the timestamp

Returns

true if the timestamp is nil

See also

nil_time

make_timeout_time_ms()

absolute_time_t make_timeout_time_ms ( uint32_t ms )

inlinestatic

Convenience method to get the timestamp a number of milliseconds from the current time.

Parameters

ms	the number of milliseconds to add to the current timestamp

Returns

the future timestamp

make_timeout_time_us()

absolute_time_t make_timeout_time_us ( uint64_t us )

inlinestatic

Convenience method to get the timestamp a number of microseconds from the current time.

Parameters

us	the number of microseconds to add to the current timestamp

Returns

the future timestamp

to_ms_64_since_boot()

uint64_t to_ms_64_since_boot ( absolute_time_t t )

inlinestatic

Convert a timestamp into a number of 64-bit milliseconds since boot.

fn to_ms_64_since_boot

Parameters

t	an absolute_time_t value to convert

Returns

the number of milliseconds since boot represented by t

See also

to_us_since_boot()

to_ms_since_boot()

uint32_t to_ms_since_boot ( absolute_time_t t )

inlinestatic

Convert a timestamp into a number of milliseconds since boot.

fn to_ms_since_boot

Parameters

t	an absolute_time_t value to convert

Returns

the number of milliseconds since boot represented by t

See also

to_us_since_boot()

to_us_since_boot()

uint64_t to_us_since_boot ( absolute_time_t t )

inlinestatic

convert an absolute_time_t into a number of microseconds since boot.

fn to_us_since_boot

Parameters

t	the absolute time to convert

Returns

a number of microseconds since boot, equivalent to t

update_us_since_boot()

void update_us_since_boot ( absolute_time_t * t, uint64_t us_since_boot )

inlinestatic

update an absolute_time_t value to represent a given number of microseconds since boot

fn update_us_since_boot

Parameters

t	the absolute time value to update
us_since_boot	the number of microseconds since boot to represent. Note this should be representable as a signed 64 bit integer