Linux Hardware Receive Timestamps: Qualify Packet Coverage Before Calculating Acquisition Latency

An Ethernet gateway may synchronize its hardware clock successfully while ordinary sensor packets arrive without hardware timestamps. Before using those packets to calculate acquisition latency, qualify the complete receive path: packet classification, driver configuration, socket reporting and clock interpretation. A working PTP exchange covers only part of that path.

This guide uses the Linux 6.12 timestamping interfaces as its reference. The example gateway receives UDP measurements and records their arrival. The workflow and numerical worksheet are proposed engineering fixtures; no NIC, driver, PTP daemon or physical timing capture was exercised for this article.

Name the packet and the timed event

Begin with one representative measurement datagram. Record its transport, destination, relevant encapsulation and application sequence field. Keep it distinct from the PTP packets used to discipline clocks. A device that timestamps selected synchronization messages has not thereby demonstrated timestamp coverage for that measurement stream.

Define the event the product needs: physical sensor sampling, packet arrival at a particular hardware boundary, or delivery to the application. The same datagram can carry a sensor timestamp and receive an independent gateway timestamp. Preserve both meanings. Gateway receive time alone cannot reveal how long the sensor buffered a measurement before sending it.

For a latency requirement, draw the two endpoints before selecting an API. If the first endpoint is a conversion inside an instrument, the project also needs evidence relating that event to the instrument’s exported timestamp.

Qualify device selection and socket selection separately

Linux’s 6.12 timestamping guide separates timestamp generation from reporting. For receive hardware timestamps, review SOF_TIMESTAMPING_RX_HARDWARE and SOF_TIMESTAMPING_RAW_HARDWARE together. Hardware timestamping also requires device-driver configuration; the socket request does not establish that the device can timestamp the desired packets.

The pinned net_tstamp.h interface defines distinct receive filters, including all packets and PTP-specific classes. SIOCSHWTSTAMP returns the actual configuration through hwtstamp_config, which may be more permissive than requested. Preserve that returned result and any failure, rather than recording only the requested filter.

Use an authorized test environment when changing device-wide settings. Assign one owner for that configuration so a timing service and acquisition application do not silently overwrite each other’s choices. Capture interface identity, driver, firmware, kernel build, requested filter and applied filter in the run record.

Original receive-evidence architecture. Arrows show dependencies, not measured delays or synchronized clocks.

Retain timestamp availability as data

For received packets, the kernel guide’s data interface delivers timestamps with normal recvmsg ancillary data. Its timestamp array uses ts[0] for software time and ts[2] for hardware time; ts[1] is deprecated. The guide recommends SO_TIMESTAMPING_NEW for the fixed-width timestamp representation, especially relevant to 32-bit products.

Design the parser to retain the timestamp kind rather than returning one unlabelled number. Distinguish a usable hardware timestamp, a software-only observation, absent metadata and a malformed or truncated control-data result. Validate ancillary lengths against the ABI actually requested before accessing fields.

Define what the application does with each classification. A production counter may still accept an untimed measurement, while a latency-analysis stream excludes it and increments a separate coverage counter. Never replace a missing hardware timestamp with the current time while keeping the original field name. That silently changes the capture event.

Attach a clock identity to the hardware value

The Linux PTP infrastructure exposes hardware clocks as character devices and supports reading and adjusting them. Availability of that interface does not certify the clock’s relationship to the gateway’s system or monotonic clocks.

Record the hardware clock associated with the timestamp path and the evidence for that association. Where a switch or timestamping PHY sits ahead of the host interface, inspect the actual topology instead of assuming the host MAC supplied the value. Keep the documented capture point with the hardware identity.

For a proposed event record, retain source sequence, optional sensor time, hardware receive time, clock identity, application receipt time, timestamp classification and clock-quality state. If a calibrated mapping is used, include its generation and valid interval. A comparison crossing an unqualified clock step or mapping change should be marked unavailable, not averaged into the normal latency distribution.

Count coverage before reporting latency

Use an independent sender ledger and match measurement identities at the receiver. Report missing packets separately from received packets lacking usable timing. Otherwise, dropping the difficult cases can make both delivery reliability and the latency distribution appear better than the evidence supports.

Consider a hypothetical run with 10,000 received measurement packets: 9,985 carry usable hardware timestamps, ten have software-only observations and five lack usable timestamp metadata. Hardware timestamp coverage among received packets is 99.85%. This invented worksheet is not a benchmark, and it does not account for packets absent from the receiver altogether.

If the product requires hardware timing for every accepted measurement, those fifteen packets require an explicit failure or degraded-data decision. A low latency percentile computed from the other packets cannot satisfy that coverage requirement.

Exercise the missing paths deliberately

Build the acceptance campaign around the deployed measurement traffic, not only PTP messages. Include representative packet sizes, network encapsulation and sustained traffic, then add controlled CPU and receive-path load. Preserve raw classifications and source identities alongside summary counters.

Test startup before clock qualification, link loss and recovery, application restart and a controlled clock correction. Confirm that configuration ownership and quality state remain understandable after each transition. If support is absent, report the unsupported packet class instead of inventing a software fallback with equivalent accuracy.

Release a coverage report, parser contract, clock-provenance record and endpoint definition together. Only observations passing all required gates belong in the claimed latency result. This makes the measurement reproducible even when the gateway contains several clocks and several kinds of received traffic.