1 .. Copyright (c) 2019 Intel
3 .. Licensed under the Apache License, Version 2.0 (the "License");
4 .. you may not use this file except in compliance with the License.
5 .. You may obtain a copy of the License at
7 .. http://www.apache.org/licenses/LICENSE-2.0
9 .. Unless required by applicable law or agreed to in writing, software
10 .. distributed under the License is distributed on an "AS IS" BASIS,
11 .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 .. See the License for the specific language governing permissions and
13 .. limitations under the License.
22 Precision Time Protocol (PTP) provides an efficient way to synchronize
23 time on the network nodes. This protocol uses Master-Slave architecture.
24 Grandmaster Clock (Master) is a reference clock for the other nodes,
25 which adapt their clocks to the master.
27 Using Physical Hardware Clock (PHC) from the Grandmaster Clock, NIC port
28 precision timestamp packets can be served for other network nodes. Slave
29 nodes adjust their PHC to the master following the IEEE 1588
32 There are existing implementations of PTP protocol that are widely used
33 in the industry. One of them is PTP for Linux, which is a set of tools
34 providing necessary PTP functionality. There is no need to re-implement
35 the 1588 protocol because PTP for Linux is precise and efficient enough
36 to be used out of the box.
38 To meet O-RAN requirements, two tools from PTP for Linux package are
39 required: ptp4l and phc2sys.
41 PTP for Linux\* Requirements
42 ============================
44 PTP for Linux\* introduces some software and hardware requirements. The
45 machine on which the tools will be run needs to use at least a 3.10
46 Kernel version (built-in PTP support). Several Kernel options need to be
47 enabled in Kernel configuration:
51 - CONFIG_NETWORK_PHY_TIMESTAMPING
55 Be sure that the Kernel is compiled with these options.
57 For the best precision, PTP uses hardware timestamping. NIC has its own
58 clock, called Physical Hardware Clock (PHC), to read current time just a
59 moment before the packet is sent to minimalize the delays added by the
60 Kernel processing the packet. Not every NIC supports that feature. To
61 confirm that currently attached NIC support Hardware Timestamps, use
62 ethtool with the command:
66 Where the eth0 is the potential PHC port. The output from the command
67 should say that there is Hardware Timestamps support.
69 To set up PTP for Linux*:
71 1.Download source code::
73 git clone http://git.code.sf.net/p/linuxptp/code linuxptp
76 *Note* Apply patch (this is required to work around an issue with some of the GM PTP packet sizes.) ::
78 diff --git a/msg.c b/msg.c
81 index d1619d4..40d1538
84 @@ -399,9 +399,11 @@ int msg_post_recv(struct ptp_message *m, int cnt)
85 port_id_post_recv(&m->pdelay_resp.requestingPortIdentity);
89 timestamp_post_recv(m, &m->follow_up.preciseOriginTimestamp);
93 timestamp_post_recv(m, &m->delay_resp.receiveTimestamp);
94 port_id_post_recv(&m->delay_resp.requestingPortIdentity);
97 2. Build and install ptp41. ::
99 # make && make install
101 3. Modify configs/default.cfg to control frequency of Sync interval to
109 This tool handles all PTP traffic on the provided NIC port and updated
110 PHC. It also determines the Grandmaster Clock and tracks synchronization
111 status. This tool can be run as a daemon or as a regular Linux\*
112 application. When the synchronization is reached, it gives output on the
113 screen for precision tracking. The configuration file of ptp4l contains
114 many options that can be set to get the best synchronization precision.
115 Although, even with default.cfg the synchronization quality is
118 To start the synchronization process run::
121 ./ptp4l -f ./configs/default.cfg -2 -i <if_name> -m
123 The output below shows what the output on non-master node should look
124 like when synchronization is started. This means that PHC on this
125 machine is synchronized to the master PHC. ::
127 ptp4l[1434165.358]: port 1: INITIALIZING to LISTENING on INIT_COMPLETE
128 ptp4l[1434165.358]: port 0: INITIALIZING to LISTENING on INIT_COMPLETE
129 ptp4l[1434166.384]: port 1: new foreign master fcaf6a.fffe.029708-1
130 ptp4l[1434170.352]: selected best master clock fcaf6a.fffe.029708
131 ptp4l[1434170.352]: updating UTC offset to 37
132 ptp4l[1434170.352]: port 1: LISTENING to UNCALIBRATED on RS_SLAVE
133 ptp4l[1434171.763]: master offset -5873 s0 freq -18397 path delay 2778
134 ptp4l[1434172.763]: master offset -6088 s2 freq -18612 path delay 2778
135 ptp4l[1434172.763]: port 1: UNCALIBRATED to SLAVE on MASTER_CLOCK_SELECTED
136 ptp4l[1434173.763]: master offset -5886 s2 freq -24498 path delay 2732
137 ptp4l[1434174.763]: master offset 221 s2 freq -20157 path delay 2728
138 ptp4l[1434175.763]: master offset 1911 s2 freq -18401 path delay 2724
139 ptp4l[1434176.763]: master offset 1774 s2 freq -17964 path delay 2728
140 ptp4l[1434177.763]: master offset 1198 s2 freq -18008 path delay 2728
141 ptp4l[1434178.763]: master offset 746 s2 freq -18101 path delay 2755
142 ptp4l[1434179.763]: master offset 218 s2 freq -18405 path delay 2792
143 ptp4l[1434180.763]: master offset 103 s2 freq -18454 path delay 2792
144 ptp4l[1434181.763]: master offset -13 s2 freq -18540 path delay 2813
145 ptp4l[1434182.763]: master offset 9 s2 freq -18521 path delay 2813
146 ptp4l[1434183.763]: master offset 11 s2 freq -18517 path delay 2813
151 The PHC clock is independent from the system clock. Synchronizing only
152 PHC does not make the system clock exactly the same as the master. The
153 xRAN library requires use of the system clock to determine a common
154 point in time on two machines (O-DU and RU) to start transmission at the
155 same moment and keep time frames defined by O-RAN Fronthaul
158 This application keeps the system clock updated to PHC. It makes it
159 possible to use POSIX timers as a time reference in xRAN application.
161 Run phc2sys with the command::
164 ./phc2sys -s enp25s0f0 -w -m -R 8
166 Command output will look like::
168 ptp4l[1434165.342]: selected /dev/ptp4 as PTP
169 phc2sys[1434344.651]: CLOCK_REALTIME phc offset 450 s2 freq -39119 delay 1354
170 phc2sys[1434344.776]: CLOCK_REALTIME phc offset 499 s2 freq -38620 delay 1344
171 phc2sys[1434344.902]: CLOCK_REALTIME phc offset 485 s2 freq -38484 delay 1347
172 phc2sys[1434345.027]: CLOCK_REALTIME phc offset 476 s2 freq -38348 delay 1346
173 phc2sys[1434345.153]: CLOCK_REALTIME phc offset 392 s2 freq -38289 delay 1340
174 phc2sys[1434345.278]: CLOCK_REALTIME phc offset 319 s2 freq -38244 delay 1340
175 phc2sys[1434345.404]: CLOCK_REALTIME phc offset 278 s2 freq -38190 delay 1349
176 phc2sys[1434345.529]: CLOCK_REALTIME phc offset 221 s2 freq -38163 delay 1343
177 phc2sys[1434345.654]: CLOCK_REALTIME phc offset 97 s2 freq -38221 delay 1342
178 phc2sys[1434345.780]: CLOCK_REALTIME phc offset 67 s2 freq -38222 delay 1344
179 phc2sys[1434345.905]: CLOCK_REALTIME phc offset 68 s2 freq -38201 delay 1341
180 phc2sys[1434346.031]: CLOCK_REALTIME phc offset 104 s2 freq -38144 delay 1340
181 phc2sys[1434346.156]: CLOCK_REALTIME phc offset 58 s2 freq -38159 delay 1340
182 phc2sys[1434346.281]: CLOCK_REALTIME phc offset 12 s2 freq -38188 delay 1343
183 phc2sys[1434346.407]: CLOCK_REALTIME phc offset -36 s2 freq -38232 delay 1342
184 phc2sys[1434346.532]: CLOCK_REALTIME phc offset -103 s2 freq -38310 delay 1348
189 Configuration C3 27 can be simulated for O-DU using a separate server
190 acting as Fronthaul Network and O-RU at the same time. O-RU server can
191 be configured to relay PTP and act as PTP master for O-DU. Settings
192 below can be used to instantiate this scenario. The difference is that
193 on the O-DU side, the Fronthaul port can be used as the source of PTP as
194 well as for U-plane and C-plane traffic.
196 1. Follow the steps in Appendix *B.1.1, PTP for Linux\* Requirements* to
197 install PTP on the O-RU server.
199 2. Copy configs/default.cfg to configs/default_slave.cfg and modify the
200 copied file as below::
202 diff --git a/configs/default.cfg b/configs/default.cfg
205 index e23dfd7..f1ecaf1
206 --- a/configs/default.cfg
207 +++ b/configs/default.cfg
222 offsetScaledLogVariance 0xFFFF
227 -dataset_comparison ieee1588
228 +dataset_comparison G.8275.x
229 G.8275.defaultDS.localPriority 128
234 logAnnounceInterval 1
237 operLogSyncInterval 0
238 logMinDelayReqInterval 0
239 logMinPdelayReqInterval 0
240 @@ -37,7 +37,7 @@ G.8275.portDS.localPriority 128
244 -inhibit_pdelay_req 0
245 +#inhibit_pdelay_req 0
251 3. Start slave port toward PTP GM::
253 ./ptp4l -f ./configs/default_slave.cfg -2 -i enp25s0f0 –m
257 ./ptp4l -f ./configs/default_slave.cfg -2 -i enp25s0f0 -m
258 ptp4l[3904470.256]: selected /dev/ptp6 as PTP clock
259 ptp4l[3904470.274]: port 1: INITIALIZING to LISTENING on INIT_COMPLETE
260 ptp4l[3904470.275]: port 0: INITIALIZING to LISTENING on INIT_COMPLETE
261 ptp4l[3904471.085]: port 1: new foreign master fcaf6a.fffe.029708-1
262 ptp4l[3904475.053]: selected best master clock fcaf6a.fffe.029708
263 ptp4l[3904475.053]: updating UTC offset to 37
264 ptp4l[3904475.053]: port 1: LISTENING to UNCALIBRATED on RS_SLAVE
265 ptp4l[3904477.029]: master offset 196 s0 freq -18570 path delay 1109
266 ptp4l[3904478.029]: master offset 212 s2 freq -18554 path delay 1109
267 ptp4l[3904478.029]: port 1: UNCALIBRATED to SLAVE on MASTER_CLOCK_SELECTED
268 ptp4l[3904479.029]: master offset 86 s2 freq -18468 path delay 1109
269 ptp4l[3904480.029]: master offset 23 s2 freq -18505 path delay 1124
270 ptp4l[3904481.029]: master offset 3 s2 freq -18518 path delay 1132
271 ptp4l[3904482.029]: master offset -169 s2 freq -18689 path delay 1141
273 4. Synchronize local timer clock on O-RU for sample application ::
275 ./phc2sys -s enp25s0f0 -w -m -R 8
279 ./phc2sys -s enp25s0f0 -w -m -R 8
280 phc2sys[3904510.892]: CLOCK_REALTIME phc offset 343 s0 freq -38967 delay 1530
281 phc2sys[3904511.017]: CLOCK_REALTIME phc offset 368 s2 freq -38767 delay 1537
282 phc2sys[3904511.142]: CLOCK_REALTIME phc offset 339 s2 freq -38428 delay 1534
283 phc2sys[3904511.267]: CLOCK_REALTIME phc offset 298 s2 freq -38368 delay 1532
284 phc2sys[3904511.392]: CLOCK_REALTIME phc offset 239 s2 freq -38337 delay 1534
285 phc2sys[3904511.518]: CLOCK_REALTIME phc offset 145 s2 freq -38360 delay 1530
286 phc2sys[3904511.643]: CLOCK_REALTIME phc offset 106 s2 freq -38355 delay 1527
287 phc2sys[3904511.768]: CLOCK_REALTIME phc offset -30 s2 freq -38459 delay 1534
288 phc2sys[3904511.893]: CLOCK_REALTIME phc offset -92 s2 freq -38530 delay 1530
289 phc2sys[3904512.018]: CLOCK_REALTIME phc offset -173 s2 freq -38639 delay 1528
290 phc2sys[3904512.143]: CLOCK_REALTIME phc offset -246 s2 freq -38764 delay 1530
291 phc2sys[3904512.268]: CLOCK_REALTIME phc offset -300 s2 freq -38892 delay 1532
293 5. Modify configs/default.cfg as shown below to run PTP master on Fronthaul of O-RU. ::
295 diff --git a/configs/default.cfg b/configs/default.cfg
298 index e23dfd7..c9e9d4c
299 --- a/configs/default.cfg
300 +++ b/configs/default.cfg
301 @@ -15,14 +15,14 @@ free_running 0
305 -dataset_comparison ieee1588
306 +dataset_comparison G.8275.x
307 G.8275.defaultDS.localPriority 128
312 logAnnounceInterval 1
315 operLogSyncInterval 0
316 logMinDelayReqInterval 0
317 logMinPdelayReqInterval 0
318 @@ -37,7 +37,7 @@ G.8275.portDS.localPriority 128
322 -inhibit_pdelay_req 0
323 +#inhibit_pdelay_req 0
328 6. Start PTP master toward O-DU::
330 ./ptp4l -f ./configs/default.cfg -2 -i enp175s0f1 –m
334 ./ptp4l -f ./configs/default.cfg -2 -i enp175s0f1 -m
335 ptp4l[3903857.249]: selected /dev/ptp3 as PTP clock
336 ptp4l[3903857.266]: port 1: INITIALIZING to LISTENING on INIT_COMPLETE
337 ptp4l[3903857.267]: port 0: INITIALIZING to LISTENING on INIT_COMPLETE
338 ptp4l[3903863.734]: port 1: LISTENING to MASTER on ANNOUNCE_RECEIPT_TIMEOUT_EXPIRES
339 ptp4l[3903863.734]: selected local clock 3cfdfe.fffe.bd005d as best master
340 ptp4l[3903863.734]: assuming the grand master role
342 7.Synchronize local NIC PTP master clock to local NIC PTP slave clock. ::
344 ./phc2sys -c enp175s0f1 -s enp25s0f0 -w -m -R 8
348 ./phc2sys -c enp175s0f1 -s enp25s0f0 -w -m -R 8
349 phc2sys[3904600.332]: enp175s0f1 phc offset 2042 s0 freq -2445 delay 4525
350 phc2sys[3904600.458]: enp175s0f1 phc offset 2070 s2 freq -2223 delay 4506
351 phc2sys[3904600.584]: enp175s0f1 phc offset 2125 s2 freq -98 delay 4505
352 phc2sys[3904600.710]: enp175s0f1 phc offset 1847 s2 freq +262 delay 4518
353 phc2sys[3904600.836]: enp175s0f1 phc offset 1500 s2 freq +469 delay 4515
354 phc2sys[3904600.961]: enp175s0f1 phc offset 1146 s2 freq +565 delay 4547
355 phc2sys[3904601.086]: enp175s0f1 phc offset 877 s2 freq +640 delay 4542
356 phc2sys[3904601.212]: enp175s0f1 phc offset 517 s2 freq +543 delay 4517
357 phc2sys[3904601.337]: enp175s0f1 phc offset 189 s2 freq +370 delay 4510
358 phc2sys[3904601.462]: enp175s0f1 phc offset -125 s2 freq +113 delay 4554
359 phc2sys[3904601.587]: enp175s0f1 phc offset -412 s2 freq -212 delay 4513
360 phc2sys[3904601.712]: enp175s0f1 phc offset -693 s2 freq -617 delay 4519
361 phc2sys[3904601.837]: enp175s0f1 phc offset -878 s2 freq -1009 delay 4515
362 phc2sys[3904601.962]: enp175s0f1 phc offset -965 s2 freq -1360 delay 4518
363 phc2sys[3904602.088]: enp175s0f1 phc offset -1048 s2 freq -1732 delay 4510
364 phc2sys[3904602.213]: enp175s0f1 phc offset -1087 s2 freq -2086 delay 4531
365 phc2sys[3904602.338]: enp175s0f1 phc offset -1014 s2 freq -2339 delay 4528
366 phc2sys[3904602.463]: enp175s0f1 phc offset -1009 s2 freq -2638 delay 4531
368 8. On O-DU Install PTP for Linux tools from source code the same way as
369 on O-RU above but no need to apply the patch for msg.c
371 9. Start slave port toward PTP master from O-RU using the same
372 default_slave.cfg as on O-RU (see above)::
374 ./ptp4l -f ./configs/default_slave.cfg -2 -i enp181s0f0 –m
378 ./ptp4l -f ./configs/default_slave.cfg -2 -i enp181s0f0 -m
379 ptp4l[809092.918]: selected /dev/ptp6 as PTP clock
380 ptp4l[809092.934]: port 1: INITIALIZING to LISTENING on INIT_COMPLETE
381 ptp4l[809092.934]: port 0: INITIALIZING to LISTENING on INIT_COMPLETE
382 ptp4l[809092.949]: port 1: new foreign master 3cfdfe.fffe.bd005d-1
383 ptp4l[809096.949]: selected best master clock 3cfdfe.fffe.bd005d
384 ptp4l[809096.950]: port 1: LISTENING to UNCALIBRATED on RS_SLAVE
385 ptp4l[809098.363]: port 1: UNCALIBRATED to SLAVE on MASTER_CLOCK_SELECTED
386 ptp4l[809099.051]: rms 38643 max 77557 freq +719 +/- 1326 delay 1905 +/- 0
387 ptp4l[809100.051]: rms 1134 max 1935 freq -103 +/- 680 delay 1891 +/- 4
388 ptp4l[809101.051]: rms 453 max 855 freq +341 +/- 642 delay 1888 +/- 0
389 ptp4l[809102.052]: rms 491 max 772 freq +1120 +/- 752 delay 1702 +/- 0
390 ptp4l[809103.052]: rms 423 max 654 freq +1352 +/- 653 delay 1888 +/- 0
391 ptp4l[809104.052]: rms 412 max 579 freq +1001 +/- 672 delay 1702 +/- 0
392 ptp4l[809105.053]: rms 441 max 672 freq +807 +/- 709 delay 1826 +/- 88
393 ptp4l[809106.053]: rms 422 max 607 freq +1353 +/- 636 delay 1702 +/- 0
394 ptp4l[809107.054]: rms 401 max 466 freq +946 +/- 646 delay 1702 +/- 0
395 ptp4l[809108.055]: rms 401 max 502 freq +912 +/- 659
397 10. Synchronize local clock on O-DU for sample application or l1
400 ./phc2sys -s enp181s0f0 -w -m -R 8
404 ./phc2sys -s enp181s0f0 -w -m -R 8
405 phc2sys[809127.123]: CLOCK_REALTIME phc offset 675 s0 freq -37379 delay 1646
406 phc2sys[809127.249]: CLOCK_REALTIME phc offset 696 s2 freq -37212 delay 1654
407 phc2sys[809127.374]: CLOCK_REALTIME phc offset 630 s2 freq -36582 delay 1648
408 phc2sys[809127.500]: CLOCK_REALTIME phc offset 461 s2 freq -36562 delay 1642
409 phc2sys[809127.625]: CLOCK_REALTIME phc offset 374 s2 freq -36510 delay 1643
410 phc2sys[809127.751]: CLOCK_REALTIME phc offset 122 s2 freq -36650 delay 1649
411 phc2sys[809127.876]: CLOCK_REALTIME phc offset 34 s2 freq -36702 delay 1650
412 phc2sys[809128.002]: CLOCK_REALTIME phc offset -112 s2 freq -36837 delay 1645
413 phc2sys[809128.127]: CLOCK_REALTIME phc offset -160 s2 freq -36919 delay 1643
414 phc2sys[809128.252]: CLOCK_REALTIME phc offset -270 s2 freq -37077 delay 1657
415 phc2sys[809128.378]: CLOCK_REALTIME phc offset -285 s2 freq -37173 delay 1644
416 phc2sys[809128.503]: CLOCK_REALTIME phc offset -349 s2 freq -37322 delay 1644
417 phc2sys[809128.629]: CLOCK_REALTIME phc offset -402 s2 freq -37480 delay 1641
418 phc2sys[809128.754]: CLOCK_REALTIME phc offset -377 s2 freq -37576 delay 1648
419 phc2sys[809128.879]: CLOCK_REALTIME phc offset -467 s2 freq -37779 delay 1650
420 phc2sys[809129.005]: CLOCK_REALTIME phc offset -408 s2 freq -37860 delay 1648
421 phc2sys[809129.130]: CLOCK_REALTIME phc offset -480 s2 freq -38054 delay 1655
422 phc2sys[809129.256]: CLOCK_REALTIME phc offset -350 s2 freq -38068 delay 1650
424 Support in xRAN Library
425 =======================
427 The xRAN library provides an API to check whether PTP for Linux is
428 running correctly. There is a function called xran_is_synchronized(). It
429 checks if ptp4l and phc2sys are running in the system by making PMC tool
430 requests for the current port state and comparing it with the expected
431 value. This verification should be done before initialization.
433 - “SLAVE” is the only expected value in this release; only a non-master scenario is supported currently.