File syn_hpclock.h¶

FileList > drivers > syn_hpclock.h

High-precision clock — 64-bit system-clock-precision timestamps. More...

#include "../common/syn_compiler.h"
#include "../common/syn_defs.h"
#include "../port/syn_port_hpclock.h"
#include <stdbool.h>
#include <stdint.h>

Classes¶

Type	Name
struct	SYN_HPTimestamp Raw high-precision timestamp — three-word snapshot.

Public Functions¶

Type	Name
uint64_t	syn_hpclock_elapsed (const SYN_HPTimestamp * start, const SYN_HPTimestamp * end) Compute elapsed ticks between two timestamps.
uint64_t	syn_hpclock_resolve (const SYN_HPTimestamp * ts) Resolve a raw timestamp into a 64-bit tick count.
uint64_t	syn_hpclock_ticks_to_ns (uint64_t ticks) Convert a tick count to nanoseconds.

Public Static Functions¶

Type	Name
bool	syn_hpclock_is_zero (const SYN_HPTimestamp * ts) Check if a timestamp is zero (uninitialized).

Macros¶

Type	Name
define	SYN_HPCLOCK_CAPTURE (ts) `/* multi line expression /` Snapshot the high-precision clock into a timestamp struct.*
define	SYN_HPTIMESTAMP_INIT `{0, 0, 0}` Static initializer for SYN_HPTimestamp (all zeros).

Detailed Description¶

Provides a zero-overhead timestamp capture primitive and deferred resolution. The capture is a macro that performs three volatile reads with no branching — suitable for use inside ISRs where every cycle counts. Resolution is a pure function called lazily in main context.

Design philosophy¶

Capture fast, resolve later. The timestamp struct stores the raw snapshot; the overflow ambiguity is resolved only when you ask for the 64-bit tick value. This keeps ISR latency deterministic and independent of the resolution logic.

Read sequence: msb_1, lsb, msb_2¶

The overflow counter is read before and after the hardware counter. Resolution uses the two MSB values to detect overflow:

msb_1 == msb_2: No overflow during the window. Use either.
msb_1 != msb_2: Overflow occurred. The LSB value tells us whether it was captured before or after the wrap:
lsb < 0x80000000: Counter already wrapped → use msb_2.
lsb >= 0x80000000: Counter hasn't wrapped → use msb_1.

The half-range check is safe because the three reads complete in ~10 CPU cycles, while half a 32-bit counter period at system clock is billions of cycles. The LSB value is always unambiguously on one side of the boundary.

ISR priority constraint¶

The timer overflow ISR must have the highest interrupt priority in the system. See syn_port_hpclock.h for details.

Usage¶

// In an ISR or anywhere timing-critical:
SYN_HPTimestamp ts;
SYN_HPCLOCK_CAPTURE(ts);

// Later, in main context:
uint64_t ticks = syn_hpclock_resolve(&ts);
uint64_t ns    = syn_hpclock_ticks_to_ns(ticks);

// Elapsed time between two events:
uint64_t dt_ticks = syn_hpclock_elapsed(&ts_start, &ts_end);

Public Functions Documentation¶

function syn_hpclock_elapsed¶

Compute elapsed ticks between two timestamps.

uint64_t syn_hpclock_elapsed (
    const SYN_HPTimestamp * start,
    const SYN_HPTimestamp * end
)

Resolves both timestamps and returns the difference. Assumes end was captured after start.

Parameters:

start Earlier timestamp.
end Later timestamp.

Returns:

Elapsed ticks (end - start).

function syn_hpclock_resolve¶

Resolve a raw timestamp into a 64-bit tick count.

uint64_t syn_hpclock_resolve (
    const SYN_HPTimestamp * ts
)

If msb_1 == msb_2, no overflow occurred and either MSB is correct. If they differ, the overflow happened during the capture window and the LSB value determines which side of the wrap it was captured on: a small LSB (< 0x80000000) means post-wrap (use msb_2), a large LSB means pre-wrap (use msb_1).

This is a pure function — no side effects, no hardware access.

Parameters:

ts Pointer to a captured timestamp.

Returns:

64-bit tick count at system clock precision.

function syn_hpclock_ticks_to_ns¶

Convert a tick count to nanoseconds.

uint64_t syn_hpclock_ticks_to_ns (
    uint64_t ticks
)

Uses integer-only arithmetic: ns = ticks * 1000000000 / freq_hz. The division is performed with 64-bit precision to avoid overflow.

Parameters:

ticks Tick count from syn_hpclock_resolve().

Returns:

Equivalent time in nanoseconds.

Public Static Functions Documentation¶

function syn_hpclock_is_zero¶

Check if a timestamp is zero (uninitialized).

static inline bool syn_hpclock_is_zero (
    const SYN_HPTimestamp * ts
)

Parameters:

ts Timestamp to check.

Returns:

true if all fields are zero.

Macro Definition Documentation¶

define SYN_HPCLOCK_CAPTURE¶

Snapshot the high-precision clock into a timestamp struct.

#define SYN_HPCLOCK_CAPTURE (
    ts
) `/* multi line expression */`

Three volatile reads, no branching, no function call overhead. Safe to call from ISR context (provided the overflow ISR has a higher priority — see syn_port_hpclock.h).

Compiler barriers between the MSB (SRAM) and LSB (peripheral bus) reads prevent the compiler from reordering the accesses.

Parameters:

ts An SYN_HPTimestamp lvalue (not a pointer).

define SYN_HPTIMESTAMP_INIT¶

Static initializer for SYN_HPTimestamp (all zeros).

#define SYN_HPTIMESTAMP_INIT `{0, 0, 0}`

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