Zephyr OS SNTP Fractions: Pin the Configuration Before Converting Subseconds

A field called fraction is not automatically a count of microseconds. Before converting a Zephyr OS SNTP result into an application timestamp, check the implementation and resolved configuration that produced it. In the v4.4.0 source examined here, the uncertainty-disabled and uncertainty-enabled response paths assign that field differently.

This article provides a source-based integration check, not a claim of measured clock accuracy or an executed time synchronization test. The worked conversion below is deliberately limited to the uncertainty-disabled path. A product enabling uncertainty reporting needs its own verified interpretation of the selected implementation.

Establish the source and configuration boundary

The versioned SNTP header exposes seconds and a 32-bit fractional field, with additional fields when CONFIG_SNTP_UNCERTAINTY is enabled. The public structure alone does not reveal every implementation detail of those assignments. Record the resolved option alongside the exact Zephyr revision before writing a generic time adapter.

In the v4.4.0 response parser, the uncertainty-disabled branch assigns the server transmit fractional word directly after network-to-host conversion. The enabled branch instead assigns a microsecond remainder from its calculated time. This observed source difference means a single unconditional conversion cannot be justified by the member name alone. It is not a reason to silently change a released product's timestamps without validation.

If the project uses the enabled path, inspect the complete branch, its epoch handling and its relationship to the application clock API. Preserve the original returned values while investigating. Do not assume that adding another scaling factor or subtracting an epoch constant will repair all cases.

Convert the disabled-path fraction deliberately

For the uncertainty-disabled branch described above, the fractional word represents a binary fraction of a second. To obtain a truncated microsecond subsecond value, use a sufficiently wide intermediate for the fraction multiplied by one million, then divide by 2 to the power of 32. Do not interpret the original word directly as microseconds or divide by one billion merely because the destination uses nanoseconds elsewhere.

As an illustrative arithmetic check, a fractional word of hexadecimal 80000000 represents one half second and converts to 500000 microseconds. This is a calculation example, not an SNTP observation. A near-maximum fractional word remains below one full second under truncation.

Keep the seconds and subsecond conversion separate until the destination type's range has been checked. Multiplying an epoch-scale second count into a narrow integer can overflow even though converting the fractional part alone was correct. Define truncation or rounding explicitly so a later refactor does not introduce an unintended carry into the seconds field.

Preserve what the timestamp actually describes

A response-derived time is not automatically the exact time at which a downstream worker processes the result. The worker may run later, and transport delay or clock policy can matter. Decide which event the stored timestamp represents and what uncertainty accompanies it rather than copying the value into a field labelled current time without qualification.

Likewise, successful protocol parsing does not establish the server's trustworthiness or the application's synchronization accuracy. Those conclusions require their own network, clock and security design. This article's source inspection does not provide them.

Make the adapter testable

Use synthetic fractional values of zero, one half and a value near the maximum to test the disabled-path conversion and destination range. Preserve the expected integer results in unit tests. Then test the actual selected configuration against an appropriate independent time observation before relying on it operationally.

Include the configuration setting in regression coverage. A firmware change that enables uncertainty reporting should trigger a review of the adapter, not inherit a conversion based on the previous branch. The useful deliverable is a versioned timestamp contract with units and scope, rather than a plausible-looking decimal printed from an ambiguously interpreted field.