Zephyr API Documentation 4.0.0-rc2
A Scalable Open Source RTOS
|
(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. | ||
(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:
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.
union { ... } net_ptp_time |
Seconds encoded on 48 bits.
uint32_t net_ptp_time::nanosecond |
Nanoseconds.
uint64_t net_ptp_time::second |
Second value.