Support for converting between time domains with the same resolution but unstable clocks. More...

#include <nrfcxx/clock.hpp>

Public Types
using	time_type = uint64_t
	Type for unsigned 32 KiHz ticks since the epoch of a time system. More...

using	diff_type = std::make_signed< time_type >::type
	The signed version of time_type. More...

Public Member Functions
void	update_sync (time_type now_ctt, time_type now_utt) noexcept
	Provide a new synchronization pair. More...

bool	synchronized () const noexcept
	Indicates whether a synchronization point has been provided. More...

time_type	convert_ctt (time_type now_utt) noexcept
	Best effort conversion from local time to civil time. More...

unsigned int	rate () const noexcept
	The differential rate of the civil time clock relative to the local clock. More...

time_type	offset () const noexcept
	The nominal offset between the civil time and local clocks at the time of the last synchronization point.

Static Public Attributes
static constexpr unsigned int	RATE_DENOM = (1U << 16)
	The implicit denominator of rate().

Detailed Description

Support for converting between time domains with the same resolution but unstable clocks.

This class is designed to support conversion from the local uptime clock (32 KiHz ticks since power-up) to civil time (32 KiHz ticks since the POSIX epoch 1970-01-01T00:00:00Z). It operates on synchronizations composed of matched samples of civil time and local time.

The concept is that until a civil time sample is available the converted time will remain the uptime clock. Once a synchronization is available, the uptime clock will be shifted based on the offset from that sample. Once a second synchronization is available the relative rate difference between clocks is recorded and used to adjust the transformation.

The goal here is to get something reasonably close to civil time on the device, "good enough" to locally retain windowed sample statistics (min/max/mean) that are roughly aligned with civil time boundaries (e.g. 1 minute or 1 h windows). Errors on the order of a few seconds are assumed to be tolerable, so we don't get all fancy with multiple sources.

Member Typedef Documentation

◆ diff_type

using nrfcxx::clock::clock_shift::diff_type = std::make_signed<time_type>::type

The signed version of time_type.

Used solely for the nominally unsupported case of converting a time that was prior to the latest synchronization.

◆ time_type

using nrfcxx::clock::clock_shift::time_type = uint64_t

Type for unsigned 32 KiHz ticks since the epoch of a time system.

This type is selected to support a 17 Ma era, and we know that civil time will always be greater than local time, so we're not going to fuss about the potential of integer overflow or underflow.

Member Function Documentation

◆ convert_ctt()

time_type nrfcxx::clock::clock_shift::convert_ctt ( time_type now_utt )

noexcept

Best effort conversion from local time to civil time.

Parameters

now_utt the local time for which civil time is desired.

Returns: the civil time corresponding to now_utt based on the most recent synchronization data.

Warning: This system does not guarantee monotonic converted timestamp. That is, update_sync() can change the offset and rate so that an invocation of convert_ctt(t) produced a value greater than convert_ctt(t+d) does d time units later.

◆ rate()

unsigned int nrfcxx::clock::clock_shift::rate ( ) const

inlinenoexcept

The differential rate of the civil time clock relative to the local clock.

This is the numerator of a fractional value using RATE_DENOM as the implicit denominator.

◆ synchronized()

bool nrfcxx::clock::clock_shift::synchronized ( ) const

inlinenoexcept

Indicates whether a synchronization point has been provided.

Until this returns true convert_ctt() will simply return its argument.

◆ update_sync()

void nrfcxx::clock::clock_shift::update_sync	(	time_type	now_ctt,
		time_type	now_utt
	)

noexcept

Provide a new synchronization pair.