Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
Time Synchronization APIs

Data Structures

struct  timeutil_sync_config
 Immutable state for synchronizing two clocks. More...
 
struct  timeutil_sync_instant
 Representation of an instant in two time scales. More...
 
struct  timeutil_sync_state
 State required to convert instants between time scales. More...
 

Functions

int timeutil_sync_state_update (struct timeutil_sync_state *tsp, const struct timeutil_sync_instant *inst)
 Record a new instant in the time synchronization state.
 
int timeutil_sync_state_set_skew (struct timeutil_sync_state *tsp, float skew, const struct timeutil_sync_instant *base)
 Update the state with a new skew and possibly base value.
 
float timeutil_sync_estimate_skew (const struct timeutil_sync_state *tsp)
 Estimate the skew based on current state.
 
int timeutil_sync_ref_from_local (const struct timeutil_sync_state *tsp, uint64_t local, uint64_t *refp)
 Interpolate a reference timescale instant from a local instant.
 
int timeutil_sync_local_from_ref (const struct timeutil_sync_state *tsp, uint64_t ref, int64_t *localp)
 Interpolate a local timescale instant from a reference instant.
 
int32_t timeutil_sync_skew_to_ppb (float skew)
 Convert from a skew to an error in parts-per-billion.
 

Detailed Description

Function Documentation

◆ timeutil_sync_estimate_skew()

float timeutil_sync_estimate_skew ( const struct timeutil_sync_state * tsp)

#include <zephyr/sys/timeutil.h>

Estimate the skew based on current state.

Using the base and latest syncpoints from the state determine the skew of the local clock relative to the reference clock. See timeutil_sync_state::skew.

Parameters
tsppointer to a time synchronization state. The base and latest syncpoints must be present and the latest syncpoint must be after the base point in the local time scale.
Returns
the estimated skew, or zero if skew could not be estimated.

◆ timeutil_sync_local_from_ref()

int timeutil_sync_local_from_ref ( const struct timeutil_sync_state * tsp,
uint64_t ref,
int64_t * localp )

#include <zephyr/sys/timeutil.h>

Interpolate a local timescale instant from a reference instant.

Parameters
tsppointer to a time synchronization state. This must have a base and a skew installed.
refan instant measured in the reference timescale. This may be before or after the base instant.
localpwhere the corresponding instant in the local timescale should be stored. An interpolated value before local time 0 is provided without error. If interpolation fails the referenced object is not modified.
Return values
0if successful with a skew of 1
1if successful with a skew not equal to 1
-EINVAL
  • the time synchronization state is not adequately initialized
  • refp is null

◆ timeutil_sync_ref_from_local()

int timeutil_sync_ref_from_local ( const struct timeutil_sync_state * tsp,
uint64_t local,
uint64_t * refp )

#include <zephyr/sys/timeutil.h>

Interpolate a reference timescale instant from a local instant.

Parameters
tsppointer to a time synchronization state. This must have a base and a skew installed.
localan instant measured in the local timescale. This may be before or after the base instant.
refpwhere the corresponding instant in the reference timescale should be stored. A negative interpolated reference time produces an error. If interpolation fails the referenced object is not modified.
Return values
0if interpolated using a skew of 1
1if interpolated using a skew not equal to 1
-EINVAL
  • the times synchronization state is not adequately initialized
  • refp is null
-ERANGEthe interpolated reference time would be negative

◆ timeutil_sync_skew_to_ppb()

int32_t timeutil_sync_skew_to_ppb ( float skew)

#include <zephyr/sys/timeutil.h>

Convert from a skew to an error in parts-per-billion.

A skew of 1.0 has zero error. A skew less than 1 has a positive error (clock is faster than it should be). A skew greater than one has a negative error (clock is slower than it should be).

Note that due to the limited precision of float compared with double the smallest error that can be represented is about 120 ppb. A "precise" time source may have error on the order of 2000 ppb.

A skew greater than 3.14748 may underflow the 32-bit representation; this represents a clock running at less than 1/3 its nominal rate.

Returns
skew error represented as parts-per-billion, or INT32_MIN if the skew cannot be represented in the return type.

◆ timeutil_sync_state_set_skew()

int timeutil_sync_state_set_skew ( struct timeutil_sync_state * tsp,
float skew,
const struct timeutil_sync_instant * base )

#include <zephyr/sys/timeutil.h>

Update the state with a new skew and possibly base value.

Set the skew from a value retrieved from persistent storage, or calculated based on recent skew estimations including from timeutil_sync_estimate_skew().

Optionally update the base timestamp. If the base is replaced the latest instant will be cleared until timeutil_sync_state_update() is invoked.

Parameters
tsppointer to a time synchronization state.
skewthe skew to be used. The value must be positive and shouldn't be too far away from 1.
baseoptional new base to be set. If provided this becomes the base timestamp that will be used along with skew to convert between reference and local timescale instants. Setting the base clears the captured latest value.
Returns
0 if skew was updated
-EINVAL if skew was not valid

◆ timeutil_sync_state_update()

int timeutil_sync_state_update ( struct timeutil_sync_state * tsp,
const struct timeutil_sync_instant * inst )

#include <zephyr/sys/timeutil.h>

Record a new instant in the time synchronization state.

Note that this updates only the latest persisted instant. The skew is not adjusted automatically.

Parameters
tsppointer to a timeutil_sync_state object.
instthe new instant to be recorded. This becomes the base instant if there is no base instant, otherwise the value must be strictly after the base instant in both the reference and local time scales.
Return values
0if installation succeeded in providing a new base
1if installation provided a new latest instant
-EINVALif the new instant is not compatible with the base instant