Line data Source code
1 1 : /*
2 : * Copyright (c) 2018 Intel Corporation.
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /**
8 : * @file
9 : * @brief Public functions for the Precision Time Protocol time specification.
10 : *
11 : * References are to version 2019 of IEEE 1588, ("PTP")
12 : * and version 2020 of IEEE 802.1AS ("gPTP").
13 : */
14 :
15 : #ifndef ZEPHYR_INCLUDE_NET_PTP_TIME_H_
16 : #define ZEPHYR_INCLUDE_NET_PTP_TIME_H_
17 :
18 : /**
19 : * @brief Precision Time Protocol time specification
20 : * @defgroup ptp_time PTP time
21 : * @since 1.13
22 : * @version 0.8.0
23 : * @ingroup networking
24 : * @{
25 : */
26 :
27 : #include <zephyr/net/net_core.h>
28 : #include <zephyr/net/net_time.h>
29 : #include <zephyr/toolchain.h>
30 :
31 : #ifdef __cplusplus
32 : extern "C" {
33 : #endif
34 :
35 : /**
36 : * @brief (Generalized) Precision Time Protocol Timestamp format.
37 : *
38 : * @details This structure represents a timestamp according to the Precision
39 : * Time Protocol standard ("PTP", IEEE 1588, section 5.3.3), the Generalized
40 : * Precision Time Protocol standard ("gPTP", IEEE 802.1AS, section 6.4.3.4), or
41 : * any other well-defined context in which precision structured timestamps are
42 : * required on network messages in Zephyr.
43 : *
44 : * Seconds are encoded as a 48 bits unsigned integer. Nanoseconds are encoded
45 : * as a 32 bits unsigned integer.
46 : *
47 : * In the context of (g)PTP, @em timestamps designate the time, relative to a
48 : * local clock ("LocalClock") at which the message timestamp point passes a
49 : * reference plane marking the boundary between the PTP Instance and the network
50 : * medium (IEEE 1855, section 7.3.4.2; IEEE 802.1AS, section 8.4.3).
51 : *
52 : * The exact definitions of the <em>message timestamp point</em> and
53 : * <em>reference plane</em> depends on the network medium and use case.
54 : *
55 : * For (g)PTP the media-specific message timestamp points and reference planes
56 : * are defined in the standard. In non-PTP contexts specific to Zephyr,
57 : * timestamps are measured relative to the same local clock but with a
58 : * context-specific message timestamp point and reference plane, defined below
59 : * per use case.
60 : *
61 : * A @em "LocalClock" is a freerunning clock, embedded into a well-defined
62 : * entity (e.g. a PTP Instance) and provides a common time to that entity
63 : * relative to an arbitrary epoch (IEEE 1855, section 3.1.26, IEEE 802.1AS,
64 : * section 3.16).
65 : *
66 : * In Zephyr, the local clock is usually any instance of a kernel system clock
67 : * driver, counter driver, RTC API driver or low-level counter/timer peripheral
68 : * (e.g. an ethernet peripheral with hardware timestamp support or a radio
69 : * timer) with sufficient precision for the context in which it is used.
70 : *
71 : * See IEEE 802.1AS, Annex B for specific performance requirements regarding
72 : * conformance of local clocks in the gPTP context. See IEEE 1588, Annex A,
73 : * section A5.4 for general performance requirements regarding PTP local clocks.
74 : * See IEEE 802.15.4-2020, section 15.7 for requirements in the context of
75 : * ranging applications and ibid., section 6.7.6 for the relation between guard
76 : * times and clock accuracy which again influence the precision required for
77 : * subprotocols like CSL, TSCH, RIT, etc.
78 : *
79 : * Applications that use timestamps across different subsystems or media must
80 : * ensure that they understand the definition of the respective reference planes
81 : * and interpret timestamps accordingly. Applications must further ensure that
82 : * timestamps are either all referenced to the same local clock or convert
83 : * between clocks based on sufficiently precise conversion algorithms.
84 : *
85 : * Timestamps may be measured on ingress (RX timestamps) or egress (TX
86 : * timestamps) of network messages. Timestamps can also be used to schedule a
87 : * network message to a well-defined point in time in the future at which it is
88 : * to be sent over the medium (timed TX). A future timestamp and a duration,
89 : * both referenced to the local clock, may be given to specify a time window at
90 : * which a network device should expect incoming messages (RX window).
91 : *
92 : * In Zephyr this timestamp structure is currently used in the following
93 : * contexts:
94 : * * gPTP for Full Duplex Point-to-Point IEEE 802.3 links (IEEE 802.1AS,
95 : * section 11): the reference plane and message timestamp points are as
96 : * defined in the standard.
97 : * * IEEE 802.15.4 timed TX and RX: Timestamps designate the point in time at
98 : * which the end of the last symbol of the start-of-frame delimiter (SFD) (or
99 : * equivalently, the start of the first symbol of the PHY header) is at the
100 : * local antenna. The standard also refers to this as the "RMARKER" (IEEE
101 : * 802.15.4-2020, section 6.9.1) or "symbol boundary" (ibid., section 6.5.2),
102 : * depending on the context. In the context of beacon timestamps, the
103 : * difference between the timestamp measurement plane and the reference plane
104 : * is defined by the MAC PIB attribute "macSyncSymbolOffset", ibid., section
105 : * 8.4.3.1, table 8-94.
106 : *
107 : * If further use cases are added to Zephyr using this timestamp structure,
108 : * their clock performance requirements, message timestamp points and reference
109 : * plane definition SHALL be added to the above list.
110 : */
111 1 : struct net_ptp_time {
112 : /** Seconds encoded on 48 bits. */
113 : union {
114 :
115 : /** @cond INTERNAL_HIDDEN */
116 : struct {
117 : #ifdef CONFIG_LITTLE_ENDIAN
118 : uint32_t low;
119 : uint16_t high;
120 : uint16_t unused;
121 : #else
122 : uint16_t unused;
123 : uint16_t high;
124 : uint32_t low;
125 : #endif
126 : } _sec;
127 : /** @endcond */
128 :
129 : /** Second value. */
130 1 : uint64_t second;
131 1 : };
132 :
133 : /** Nanoseconds. */
134 1 : uint32_t nanosecond;
135 : };
136 :
137 : #ifdef __cplusplus
138 : }
139 : #endif
140 :
141 : /**
142 : * @brief Generalized Precision Time Protocol Extended Timestamp format.
143 : *
144 : * @details This structure represents an extended timestamp according to the
145 : * Generalized Precision Time Protocol standard (IEEE 802.1AS), see section
146 : * 6.4.3.5.
147 : *
148 : * Seconds are encoded as 48 bits unsigned integer. Fractional nanoseconds are
149 : * encoded as 48 bits, their unit is 2*(-16) ns.
150 : *
151 : * A precise definition of PTP timestamps and their uses in Zephyr is given in
152 : * the description of @ref net_ptp_time.
153 : */
154 1 : struct net_ptp_extended_time {
155 : /** Seconds encoded on 48 bits. */
156 : union {
157 :
158 : /** @cond INTERNAL_HIDDEN */
159 : struct {
160 : #ifdef CONFIG_LITTLE_ENDIAN
161 : uint32_t low;
162 : uint16_t high;
163 : uint16_t unused;
164 : #else
165 : uint16_t unused;
166 : uint16_t high;
167 : uint32_t low;
168 : #endif
169 : } _sec;
170 : /** @endcond */
171 :
172 : /** Second value. */
173 1 : uint64_t second;
174 1 : };
175 :
176 : /** Fractional nanoseconds on 48 bits. */
177 : union {
178 :
179 : /** @cond INTERNAL_HIDDEN */
180 : struct {
181 : #ifdef CONFIG_LITTLE_ENDIAN
182 : uint32_t low;
183 : uint16_t high;
184 : uint16_t unused;
185 : #else
186 : uint16_t unused;
187 : uint16_t high;
188 : uint32_t low;
189 : #endif
190 : } _fns;
191 : /** @endcond */
192 :
193 : /** Fractional nanoseconds value. */
194 1 : uint64_t fract_nsecond;
195 1 : };
196 : } __packed;
197 :
198 : /**
199 : * @brief Convert a PTP timestamp to a nanosecond precision timestamp, both
200 : * related to the local network reference clock.
201 : *
202 : * @note Only timestamps representing up to ~290 years can be converted to
203 : * nanosecond timestamps. Larger timestamps will return the maximum
204 : * representable nanosecond precision timestamp.
205 : *
206 : * @param ts the PTP timestamp
207 : *
208 : * @return the corresponding nanosecond precision timestamp
209 : */
210 1 : static inline net_time_t net_ptp_time_to_ns(struct net_ptp_time *ts)
211 : {
212 : if (!ts) {
213 : return 0;
214 : }
215 :
216 : if (ts->second >= NET_TIME_SEC_MAX) {
217 : return NET_TIME_MAX;
218 : }
219 :
220 : return ((int64_t)ts->second * NSEC_PER_SEC) + ts->nanosecond;
221 : }
222 :
223 : /**
224 : * @brief Convert a nanosecond precision timestamp to a PTP timestamp, both
225 : * related to the local network reference clock.
226 : *
227 : * @param nsec a nanosecond precision timestamp
228 : *
229 : * @return the corresponding PTP timestamp
230 : */
231 1 : static inline struct net_ptp_time ns_to_net_ptp_time(net_time_t nsec)
232 : {
233 : struct net_ptp_time ts;
234 :
235 : __ASSERT_NO_MSG(nsec >= 0);
236 :
237 : ts.second = nsec / NSEC_PER_SEC;
238 : ts.nanosecond = nsec % NSEC_PER_SEC;
239 : return ts;
240 : }
241 :
242 : /**
243 : * @}
244 : */
245 :
246 : #endif /* ZEPHYR_INCLUDE_NET_PTP_TIME_H_ */
|
