net_ptp_time Struct Reference

(Generalized) Precision Time Protocol Timestamp format. More...

#include <ptp_time.h>

Data Fields
union {
uint64_t   second
	Second value. More...
};
	Seconds encoded on 48 bits.
uint32_t	nanosecond
	Nanoseconds.

Detailed Description

(Generalized) Precision Time Protocol Timestamp format.

This structure represents a timestamp according to the Precision Time Protocol standard ("PTP", IEEE 1588, section 5.3.3), the Generalized Precision Time Protocol standard ("gPTP", IEEE 802.1AS, section 6.4.3.4), or any other well-defined context in which precision structured timestamps are required on network messages in Zephyr.

Seconds are encoded as a 48 bits unsigned integer. Nanoseconds are encoded as a 32 bits unsigned integer.

In the context of (g)PTP, timestamps designate the time, relative to a local clock ("LocalClock") at which the message timestamp point passes a reference plane marking the boundary between the PTP Instance and the network medium (IEEE 1855, section 7.3.4.2; IEEE 802.1AS, section 8.4.3).

The exact definitions of the message timestamp point and reference plane depends on the network medium and use case.

For (g)PTP the media-specific message timestamp points and reference planes are defined in the standard. In non-PTP contexts specific to Zephyr, timestamps are measured relative to the same local clock but with a context-specific message timestamp point and reference plane, defined below per use case.

A "LocalClock" is a freerunning clock, embedded into a well-defined entity (e.g. a PTP Instance) and provides a common time to that entity relative to an arbitrary epoch (IEEE 1855, section 3.1.26, IEEE 802.1AS, section 3.16).

In Zephyr, the local clock is usually any instance of a kernel system clock driver, counter driver, RTC API driver or low-level counter/timer peripheral (e.g. an ethernet peripheral with hardware timestamp support or a radio timer) with sufficient precision for the context in which it is used.

See IEEE 802.1AS, Annex B for specific performance requirements regarding conformance of local clocks in the gPTP context. See IEEE 1588, Annex A, section A5.4 for general performance requirements regarding PTP local clocks. See IEEE 802.15.4-2020, section 15.7 for requirements in the context of ranging applications and ibid., section 6.7.6 for the relation between guard times and clock accuracy which again influence the precision required for subprotocols like CSL, TSCH, RIT, etc.

Applications that use timestamps across different subsystems or media must ensure that they understand the definition of the respective reference planes and interpret timestamps accordingly. Applications must further ensure that timestamps are either all referenced to the same local clock or convert between clocks based on sufficiently precise conversion algorithms.

Timestamps may be measured on ingress (RX timestamps) or egress (TX timestamps) of network messages. Timestamps can also be used to schedule a network message to a well-defined point in time in the future at which it is to be sent over the medium (timed TX). A future timestamp and a duration, both referenced to the local clock, may be given to specify a time window at which a network device should expect incoming messages (RX window).

In Zephyr this timestamp structure is currently used in the following contexts:

• gPTP for Full Duplex Point-to-Point IEEE 802.3 links (IEEE 802.1AS, section 11): the reference plane and message timestamp points are as defined in the standard.
• IEEE 802.15.4 timed TX and RX: Timestamps designate the point in time at which the end of the last symbol of the start-of-frame delimiter (SFD) (or equivalently, the start of the first symbol of the PHY header) is at the local antenna. The standard also refers to this as the "RMARKER" (IEEE 802.15.4-2020, section 6.9.1) or "symbol boundary" (ibid., section 6.5.2), depending on the context. In the context of beacon timestamps, the difference between the timestamp measurement plane and the reference plane is defined by the MAC PIB attribute "macSyncSymbolOffset", ibid., section 8.4.3.1, table 8-94.

If further use cases are added to Zephyr using this timestamp structure, their clock performance requirements, message timestamp points and reference plane definition SHALL be added to the above list.

Field Documentation

[union]

union { ... } net_ptp_time

Seconds encoded on 48 bits.

nanosecond

uint32_t net_ptp_time::nanosecond

Nanoseconds.

second

uint64_t net_ptp_time::second

Second value.

---

The documentation for this struct was generated from the following file:

• include/zephyr/net/ptp_time.h