File syn_timesync.h¶

FileList > drivers > syn_timesync.h

High-precision time discipline and clock synchronization service. More...

#include "../common/syn_defs.h"
#include "syn_hpclock.h"
#include <stdbool.h>
#include <stdint.h>

Classes¶

Type	Name
struct	SYN_TimeSync Time sync discipline state context (caller-allocated).
struct	SYN_UTCTimestamp Universal UTC timestamp with error bound and quality tier.

Public Types¶

Type	Name
enum	SYN_TimeSource Quality tier of a resolved UTC timestamp.

Public Functions¶

Type	Name
SYN_Status	syn_timesync_bind_pps (SYN_TimeSync * tsync, const SYN_HPTimestamp * pps_ts, uint64_t utc_sec) Bind a captured PPS timestamp to its corresponding UTC second.
void	syn_timesync_init (SYN_TimeSync * tsync) Initialize a time discipline context.
bool	syn_timesync_is_pps_locked (const SYN_TimeSync * tsync) Check if active PPS lock is present.
SYN_Status	syn_timesync_resolve_utc (const SYN_TimeSync * tsync, const SYN_HPTimestamp * event_ts, SYN_UTCTimestamp * out_utc) Resolve an arbitrary high-precision timestamp into UTC.
uint64_t	syn_timesync_to_epoch_ns (const SYN_TimeSync * tsync, const SYN_HPTimestamp * event_ts) Helper: resolve event timestamp directly to total 64-bit UTC nanoseconds.

Macros¶

Type	Name
define	SYN_TIMESYNC_DEFAULT_HOLDOVER_S `60U`
define	SYN_TIMESYNC_DEFAULT_JITTER_NS `50U`
define	SYN_TIMESYNC_HAS_RTC `0`

Detailed Description¶

syn_timesync converts raw high-precision hardware timestamps (SYN_HPTimestamp from syn_hpclock) into universal UTC wall-clock time with quantified uncertainty bounds (± nanoseconds).

It combines an asynchronous 1 Hz pulse reference (such as a GPS PPS signal) with an epoch date/time source (such as NMEA UTC sentences), estimates hardware crystal oscillator drift in Parts-Per-Million (PPM), and provides a 4-tier quality fallback hierarchy:

SYN_TIME_SOURCE_GPS_PPS Active PPS lock (sub-microsecond UTC)
SYN_TIME_SOURCE_GPS_HOLDOVER PPS pulse lost; extrapolating with drift PPM
SYN_TIME_SOURCE_RTC_SYNCED Long outage; using hardware RTC (if enabled)
SYN_TIME_SOURCE_UNSYNCED No time reference; raw monotonic uptime

Usage Example¶

static SYN_TimeSync tsync;
syn_timesync_init(&tsync);

// In PPS ISR:
SYN_HPCLOCK_CAPTURE(pps_ts);

// In GPS UART task (after NMEA UTC second parsed):
syn_timesync_bind_pps(&tsync, &pps_ts, utc_epoch_seconds);

// Resolving an event timestamp:
SYN_UTCTimestamp utc;
syn_timesync_resolve_utc(&tsync, &event_ts, &utc);
if (utc.source == SYN_TIME_SOURCE_GPS_PPS && utc.uncertainty_ns < 1000) {
    // High-precision event processing
}

Public Types Documentation¶

enum SYN_TimeSource¶

Quality tier of a resolved UTC timestamp.

enum SYN_TimeSource {
    SYN_TIME_SOURCE_UNSYNCED = 0,
    SYN_TIME_SOURCE_RTC_SYNCED = 1,
    SYN_TIME_SOURCE_GPS_HOLDOVER = 2,
    SYN_TIME_SOURCE_GPS_PPS = 3
};

Public Functions Documentation¶

function syn_timesync_bind_pps¶

Bind a captured PPS timestamp to its corresponding UTC second.

SYN_Status syn_timesync_bind_pps (
    SYN_TimeSync * tsync,
    const SYN_HPTimestamp * pps_ts,
    uint64_t utc_sec
)

Call this when an asynchronous epoch time sentence (e.g. NMEA $GPZDA) is received, pairing the integer UTC second with the PPS timestamp captured at the top of that second.

Measures crystal drift PPM against nominal syn_port_hpclock_freq_hz().

Parameters:

tsync TimeSync context. Must not be NULL.
pps_ts Timestamp snapshot captured by ISR at PPS rising edge.
utc_sec Universal UTC epoch second corresponding to this PPS pulse.

Returns:

SYN_OK on success, SYN_INVALID_PARAM if pps_ts is NULL.

function syn_timesync_init¶

Initialize a time discipline context.

void syn_timesync_init (
    SYN_TimeSync * tsync
)

Sets default jitter (50 ns) and max holdover (60 s). If hardware RTC is enabled (SYN_USE_RTC), checks if the RTC is valid.

Parameters:

tsync Context to initialize. Must not be NULL.

function syn_timesync_is_pps_locked¶

Check if active PPS lock is present.

bool syn_timesync_is_pps_locked (
    const SYN_TimeSync * tsync
)

Parameters:

tsync TimeSync context.

Returns:

true if PPS lock is active (received within last 1.1s).

function syn_timesync_resolve_utc¶

Resolve an arbitrary high-precision timestamp into UTC.

SYN_Status syn_timesync_resolve_utc (
    const SYN_TimeSync * tsync,
    const SYN_HPTimestamp * event_ts,
    SYN_UTCTimestamp * out_utc
)

Converts a raw SYN_HPTimestamp (captured in an ISR or main thread) into absolute UTC time, calculating the sub-second offset, active quality tier, and linear error accumulation bound (uncertainty_ns).

Handles event timestamps occurring before or after the reference PPS pulse.

Parameters:

tsync TimeSync context. Must not be NULL.
event_ts Event timestamp to resolve. Must not be NULL.
out_utc Output UTC timestamp. Must not be NULL.

Returns:

SYN_OK on success, SYN_INVALID_PARAM if args are NULL.

function syn_timesync_to_epoch_ns¶

Helper: resolve event timestamp directly to total 64-bit UTC nanoseconds.

uint64_t syn_timesync_to_epoch_ns (
    const SYN_TimeSync * tsync,
    const SYN_HPTimestamp * event_ts
)

Parameters:

tsync TimeSync context.
event_ts Event timestamp to resolve.

Returns:

Total nanoseconds since Unix epoch (1970-01-01 00:00:00 UTC).

Macro Definition Documentation¶

define SYN_TIMESYNC_DEFAULT_HOLDOVER_S¶

#define SYN_TIMESYNC_DEFAULT_HOLDOVER_S `60U`

Default max holdover duration before degrading to RTC (60 seconds).

define SYN_TIMESYNC_DEFAULT_JITTER_NS¶

#define SYN_TIMESYNC_DEFAULT_JITTER_NS `50U`

Default assumed PPS reference jitter (50 nanoseconds).

define SYN_TIMESYNC_HAS_RTC¶

#define SYN_TIMESYNC_HAS_RTC `0`

The documentation for this class was generated from the following file src/syntropic/drivers/syn_timesync.h