First round of documentation cleanup for oran_e_maintenance_release_v1.0
[o-du/phy.git] / docs / PTP-configuration_fh.rst
1 ..    Copyright (c) 2019 Intel
2 ..
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
6 ..
7 ..      http://www.apache.org/licenses/LICENSE-2.0
8 ..
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.
14
15
16 PTP Configuration
17 =================
18
19 PTP Synchronization
20 ===================
21
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.
26
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
30 specification.
31
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.
37
38 To meet O-RAN requirements, two tools from PTP for Linux package are
39 required: ptp4l and phc2sys.
40
41 PTP for Linux\* Requirements
42 ============================
43
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:
48
49 -  CONFIG_PPS
50
51 -  CONFIG_NETWORK_PHY_TIMESTAMPING
52
53 -  PTP_1588_CLOCK
54
55 Be sure that the Kernel is compiled with these options.
56
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::
63
64     ethtool -T eth0
65
66 Where the eth0 is the potential PHC port. The output from the command
67 should say that there is Hardware Timestamps support.
68
69 To set up PTP for Linux*:
70
71 1.Download source code::
72
73     git clone http://git.code.sf.net/p/linuxptp/code linuxptp
74     git checkout v2.0
75     
76 *Note* Apply patch (this is required to work around an issue with some of the GM PTP packet sizes.) ::
77
78     diff --git a/msg.c b/msg.c
79     old mode 100644
80     new mode 100755
81     index d1619d4..40d1538
82     --- a/msg.c
83     +++ b/msg.c
84     @@ -399,9 +399,11 @@ int msg_post_recv(struct ptp_message *m, int cnt)
85     port_id_post_recv(&m->pdelay_resp.requestingPortIdentity);
86     break;
87     case FOLLOW_UP:
88     + cnt -= 4;
89     timestamp_post_recv(m, &m->follow_up.preciseOriginTimestamp);
90     break;
91     case DELAY_RESP:
92     + cnt -= 4;
93     timestamp_post_recv(m, &m->delay_resp.receiveTimestamp);
94     port_id_post_recv(&m->delay_resp.requestingPortIdentity);
95     break;
96
97 2. Build and install ptp41. ::
98
99    # make && make install
100
101 22. Modify configs/default.cfg to control frequency of Sync interval to 0.0625 s. ::
102
103         logSyncInterval -4
104
105 ptp4l 
106 =====
107
108 This tool handles all PTP traffic on the provided NIC port and updated
109 PHC. It also determines the Grandmaster Clock and tracks synchronization
110 status. This tool can be run as a daemon or as a regular Linux\*
111 application. When the synchronization is reached, it gives output on the
112 screen for precision tracking. The configuration file of ptp4l contains
113 many options that can be set to get the best synchronization precision.
114 Although, even with default.cfg the synchronization quality is
115 excellent.
116
117 To start the synchronization process run::
118
119     cd linuxptp
120     ./ptp4l -f ./configs/default.cfg -2 -i <if_name> -m
121
122 The output below shows what the output on non-master node should look
123 like when synchronization is started. This means that PHC on this
124 machine is synchronized to the master PHC. ::
125
126     ptp4l[1434165.358]: port 1: INITIALIZING to LISTENING on INIT_COMPLETE
127     ptp4l[1434165.358]: port 0: INITIALIZING to LISTENING on INIT_COMPLETE
128         ptp4l[1434166.384]: port 1: new foreign master fcaf6a.fffe.029708-1
129         ptp4l[1434170.352]: selected best master clock fcaf6a.fffe.029708
130     ptp4l[1434170.352]: updating UTC offset to 37
131     ptp4l[1434170.352]: port 1: LISTENING to UNCALIBRATED on RS_SLAVE
132         ptp4l[1434171.763]: master offset -5873 s0 freq -18397 path delay 2778
133         ptp4l[1434172.763]: master offset -6088 s2 freq -18612 path delay 2778
134         ptp4l[1434172.763]: port 1: UNCALIBRATED to SLAVE on MASTER_CLOCK_SELECTED
135         ptp4l[1434173.763]: master offset -5886 s2 freq -24498 path delay 2732
136         ptp4l[1434174.763]: master offset 221 s2 freq -20157 path delay 2728
137         ptp4l[1434175.763]: master offset 1911 s2 freq -18401 path delay 2724
138         ptp4l[1434176.763]: master offset 1774 s2 freq -17964 path delay 2728
139         ptp4l[1434177.763]: master offset 1198 s2 freq -18008 path delay 2728
140         ptp4l[1434178.763]: master offset 746 s2 freq -18101 path delay 2755
141         ptp4l[1434179.763]: master offset 218 s2 freq -18405 path delay 2792
142         ptp4l[1434180.763]: master offset 103 s2 freq -18454 path delay 2792
143         ptp4l[1434181.763]: master offset -13 s2 freq -18540 path delay 2813
144         ptp4l[1434182.763]: master offset 9 s2 freq -18521 path delay 2813
145         ptp4l[1434183.763]: master offset 11 s2 freq -18517 path delay 2813
146     
147 phc2sys
148 =======
149
150 The PHC clock is independent from the system clock. Synchronizing only
151 PHC does not make the system clock exactly the same as the master. The
152 xRAN library requires use of the system clock to determine a common
153 point in time on two machines (O-DU and RU) to start transmission at the
154 same moment and keep time frames defined by O-RAN Fronthaul
155 specification.
156
157 This application keeps the system clock updated to PHC. It makes it
158 possible to use POSIX timers as a time reference in xRAN application.
159
160 Run phc2sys with the command::
161
162     cd linuxptp
163     ./phc2sys -s enp25s0f0 -w -m -R 8
164
165 Command output will look like::
166
167     ptp4l[1434165.342]: selected /dev/ptp4 as PTP
168     phc2sys[1434344.651]: CLOCK_REALTIME phc offset       450 s2 freq  -39119 delay   1354
169     phc2sys[1434344.776]: CLOCK_REALTIME phc offset       499 s2 freq  -38620 delay   1344
170     phc2sys[1434344.902]: CLOCK_REALTIME phc offset       485 s2 freq  -38484 delay   1347
171     phc2sys[1434345.027]: CLOCK_REALTIME phc offset       476 s2 freq  -38348 delay   1346
172     phc2sys[1434345.153]: CLOCK_REALTIME phc offset       392 s2 freq  -38289 delay   1340
173     phc2sys[1434345.278]: CLOCK_REALTIME phc offset       319 s2 freq  -38244 delay   1340
174     phc2sys[1434345.404]: CLOCK_REALTIME phc offset       278 s2 freq  -38190 delay   1349
175     phc2sys[1434345.529]: CLOCK_REALTIME phc offset       221 s2 freq  -38163 delay   1343
176     phc2sys[1434345.654]: CLOCK_REALTIME phc offset        97 s2 freq  -38221 delay   1342
177     phc2sys[1434345.780]: CLOCK_REALTIME phc offset        67 s2 freq  -38222 delay   1344
178     phc2sys[1434345.905]: CLOCK_REALTIME phc offset        68 s2 freq  -38201 delay   1341
179     phc2sys[1434346.031]: CLOCK_REALTIME phc offset       104 s2 freq  -38144 delay   1340
180     phc2sys[1434346.156]: CLOCK_REALTIME phc offset        58 s2 freq  -38159 delay   1340
181     phc2sys[1434346.281]: CLOCK_REALTIME phc offset        12 s2 freq  -38188 delay   1343
182     phc2sys[1434346.407]: CLOCK_REALTIME phc offset       -36 s2 freq  -38232 delay   1342
183     phc2sys[1434346.532]: CLOCK_REALTIME phc offset      -103 s2 freq  -38310 delay   1348
184
185 Configuration C3
186 ================
187
188 Configuration C3 27 can be simulated for O-DU using a separate server
189 acting as Fronthaul Network and O-RU at the same time. O-RU server can
190 be configured to relay PTP and act as PTP master for O-DU. Settings
191 below can be used to instantiate this scenario. The difference is that
192 on the O-DU side, the Fronthaul port can be used as the source of PTP as
193 well as for U-plane and C-plane traffic.
194
195 1. Follow the steps in Appendix *B.1.1,* *PTP for Linux\* Requirements*
196 to install PTP on the O-RU server.
197
198 2.Copy configs/default.cfg to configs/default_slave.cfg and modify the
199 Copied file as below::
200
201     diff --git a/configs/default.cfg b/configs/default.cfg
202     old mode 100644
203     new mode 100755
204     index e23dfd7..f1ecaf1
205     --- a/configs/default.cfg
206     +++ b/configs/default.cfg
207     @@ -3,26 +3,26 @@
208     # Default Data Set
209     #
210     twoStepFlag 1
211     -slaveOnly 0
212     +slaveOnly 1
213     priority1 128
214     -priority2 128
215     +priority2 255
216     domainNumber 0
217     #utc_offset 37
218     -clockClass 248
219     +clockClass 255
220     clockAccuracy 0xFE
221     offsetScaledLogVariance 0xFFFF
222     free_running 0
223     freq_est_interval 1
224     dscp_event 0
225     dscp_general 0
226     -dataset_comparison ieee1588
227     +dataset_comparison G.8275.x
228     G.8275.defaultDS.localPriority 128
229     maxStepsRemoved 255
230     #
231     # Port Data Set
232     #
233     logAnnounceInterval 1
234     -logSyncInterval 0
235     +logSyncInterval -4
236     operLogSyncInterval 0
237     logMinDelayReqInterval 0
238     logMinPdelayReqInterval 0
239     @@ -37,7 +37,7 @@ G.8275.portDS.localPriority 128
240     asCapable auto
241     BMCA ptp
242     inhibit_announce 0
243     -inhibit_pdelay_req 0
244     +#inhibit_pdelay_req 0
245     ignore_source_id 0
246     #
247     # Run time options
248
249
250 3. Start slave port toward PTP GM::
251
252     ./ptp4l -f ./configs/default_slave.cfg -2 -i enp25s0f0 –m
253
254 Example of output::
255
256     ./ptp4l -f ./configs/default_slave.cfg -2 -i enp25s0f0 -m
257     ptp4l[3904470.256]: selected /dev/ptp6 as PTP clock
258     ptp4l[3904470.274]: port 1: INITIALIZING to LISTENING on INIT_COMPLETE
259     ptp4l[3904470.275]: port 0: INITIALIZING to LISTENING on INIT_COMPLETE
260     ptp4l[3904471.085]: port 1: new foreign master fcaf6a.fffe.029708-1
261     ptp4l[3904475.053]: selected best master clock fcaf6a.fffe.029708
262     ptp4l[3904475.053]: updating UTC offset to 37
263     ptp4l[3904475.053]: port 1: LISTENING to UNCALIBRATED on RS_SLAVE
264     ptp4l[3904477.029]: master offset        196 s0 freq  -18570 path delay      1109
265     ptp4l[3904478.029]: master offset        212 s2 freq  -18554 path delay      1109
266     ptp4l[3904478.029]: port 1: UNCALIBRATED to SLAVE on MASTER_CLOCK_SELECTED
267     ptp4l[3904479.029]: master offset         86 s2 freq  -18468 path delay      1109
268     ptp4l[3904480.029]: master offset         23 s2 freq  -18505 path delay      1124
269     ptp4l[3904481.029]: master offset          3 s2 freq  -18518 path delay      1132
270     ptp4l[3904482.029]: master offset       -169 s2 freq  -18689 path delay      1141
271     
272 4. Synchronize local timer clock on O-RU for sample application ::
273
274    ./phc2sys -s enp25s0f0 -w -m -R 8
275
276 Example of output::
277
278    ./phc2sys -s enp25s0f0 -w -m -R 8
279     phc2sys[3904510.892]: CLOCK_REALTIME phc offset   343 s0 freq  -38967 delay   1530
280     phc2sys[3904511.017]: CLOCK_REALTIME phc offset   368 s2 freq  -38767 delay   1537
281     phc2sys[3904511.142]: CLOCK_REALTIME phc offset   339 s2 freq  -38428 delay   1534
282     phc2sys[3904511.267]: CLOCK_REALTIME phc offset   298 s2 freq  -38368 delay   1532
283     phc2sys[3904511.392]: CLOCK_REALTIME phc offset   239 s2 freq  -38337 delay   1534
284     phc2sys[3904511.518]: CLOCK_REALTIME phc offset   145 s2 freq  -38360 delay   1530
285     phc2sys[3904511.643]: CLOCK_REALTIME phc offset   106 s2 freq  -38355 delay   1527
286     phc2sys[3904511.768]: CLOCK_REALTIME phc offset   -30 s2 freq  -38459 delay   1534
287     phc2sys[3904511.893]: CLOCK_REALTIME phc offset   -92 s2 freq  -38530 delay   1530
288     phc2sys[3904512.018]: CLOCK_REALTIME phc offset  -173 s2 freq  -38639 delay   1528
289     phc2sys[3904512.143]: CLOCK_REALTIME phc offset  -246 s2 freq  -38764 delay   1530
290     phc2sys[3904512.268]: CLOCK_REALTIME phc offset  -300 s2 freq  -38892 delay   1532
291    
292 5. Modify configs/default.cfg as shown below to run PTP master on Fronthaul of O-RU. ::
293
294     diff --git a/configs/default.cfg b/configs/default.cfg
295     old mode 100644
296     new mode 100755
297     index e23dfd7..c9e9d4c
298     --- a/configs/default.cfg
299     +++ b/configs/default.cfg
300     @@ -15,14 +15,14 @@ free_running 0
301     freq_est_interval 1
302     dscp_event 0
303     dscp_general 0
304     -dataset_comparison ieee1588
305     +dataset_comparison G.8275.x
306     G.8275.defaultDS.localPriority 128
307     maxStepsRemoved 255
308     #
309     # Port Data Set
310     #
311     logAnnounceInterval 1
312     -logSyncInterval 0
313     +logSyncInterval -4
314     operLogSyncInterval 0
315     logMinDelayReqInterval 0
316     logMinPdelayReqInterval 0
317     @@ -37,7 +37,7 @@ G.8275.portDS.localPriority 128
318     asCapable auto
319     BMCA ptp
320     inhibit_announce 0
321     -inhibit_pdelay_req 0
322     +#inhibit_pdelay_req 0
323     ignore_source_id 0
324     #
325     # Run time options
326
327 6. Start PTP master toward O-DU::
328
329    ./ptp4l -f ./configs/default.cfg -2 -i enp175s0f1 –m
330
331 Example of output::
332
333    ./ptp4l -f ./configs/default.cfg -2 -i enp175s0f1 -m
334    ptp4l[3903857.249]: selected /dev/ptp3 as PTP clock
335    ptp4l[3903857.266]: port 1: INITIALIZING to LISTENING on INIT_COMPLETE
336    ptp4l[3903857.267]: port 0: INITIALIZING to LISTENING on INIT_COMPLETE
337     ptp4l[3903863.734]: port 1: LISTENING to MASTER on ANNOUNCE_RECEIPT_TIMEOUT_EXPIRES
338     ptp4l[3903863.734]: selected local clock 3cfdfe.fffe.bd005d as best master
339     ptp4l[3903863.734]: assuming the grand master role
340    
341 7. Synchronize local NIC PTP master clock to local NIC PTP slave clock. ::
342
343    ./phc2sys -c enp175s0f1 -s enp25s0f0 -w -m -R 8
344
345 Example of output::
346
347    ./phc2sys -c enp175s0f1 -s enp25s0f0 -w -m -R 8
348     phc2sys[3904600.332]: enp175s0f1 phc offset      2042 s0 freq   -2445 delay   4525
349     phc2sys[3904600.458]: enp175s0f1 phc offset      2070 s2 freq   -2223 delay   4506
350    phc2sys[3904600.584]: enp175s0f1 phc offset 2125 s2 freq -98 delay 4505
351    phc2sys[3904600.710]: enp175s0f1 phc offset 1847 s2 freq +262 delay 4518
352    phc2sys[3904600.836]: enp175s0f1 phc offset 1500 s2 freq +469 delay 4515
353    phc2sys[3904600.961]: enp175s0f1 phc offset 1146 s2 freq +565 delay 4547
354    phc2sys[3904601.086]: enp175s0f1 phc offset 877 s2 freq +640 delay 4542
355    phc2sys[3904601.212]: enp175s0f1 phc offset 517 s2 freq +543 delay 4517
356    phc2sys[3904601.337]: enp175s0f1 phc offset 189 s2 freq +370 delay 4510
357    phc2sys[3904601.462]: enp175s0f1 phc offset -125 s2 freq +113 delay 4554
358    phc2sys[3904601.587]: enp175s0f1 phc offset -412 s2 freq -212 delay 4513
359    phc2sys[3904601.712]: enp175s0f1 phc offset -693 s2 freq -617 delay 4519
360     phc2sys[3904601.837]: enp175s0f1 phc offset      -878 s2 freq   -1009 delay   4515
361     phc2sys[3904601.962]: enp175s0f1 phc offset      -965 s2 freq   -1360 delay   4518
362     phc2sys[3904602.088]: enp175s0f1 phc offset     -1048 s2 freq   -1732 delay   4510
363     phc2sys[3904602.213]: enp175s0f1 phc offset     -1087 s2 freq   -2086 delay   4531
364     phc2sys[3904602.338]: enp175s0f1 phc offset     -1014 s2 freq   -2339 delay   4528
365     phc2sys[3904602.463]: enp175s0f1 phc offset     -1009 s2 freq   -2638 delay   4531
366    
367 8. On O-DU Install PTP for Linux tools from source code the same way as
368 on O-RU above but no need to apply the patch for msg.c
369
370 9. Start slave port toward PTP master from O-RU using the same
371 default_slave.cfg as on O-RU (see above)::
372
373     ./ptp4l -f ./configs/default_slave.cfg -2 -i enp181s0f0 –m
374
375 Example of output::
376
377     ./ptp4l -f ./configs/default_slave.cfg -2 -i enp181s0f0 -m
378     ptp4l[809092.918]: selected /dev/ptp6 as PTP clock
379     ptp4l[809092.934]: port 1: INITIALIZING to LISTENING on INIT_COMPLETE
380     ptp4l[809092.934]: port 0: INITIALIZING to LISTENING on INIT_COMPLETE
381     ptp4l[809092.949]: port 1: new foreign master 3cfdfe.fffe.bd005d-1
382     ptp4l[809096.949]: selected best master clock 3cfdfe.fffe.bd005d
383     ptp4l[809096.950]: port 1: LISTENING to UNCALIBRATED on RS_SLAVE
384     ptp4l[809098.363]: port 1: UNCALIBRATED to SLAVE on MASTER_CLOCK_SELECTED
385     ptp4l[809099.051]: rms 38643 max 77557 freq   +719 +/- 1326 delay  1905 +/-   0
386     ptp4l[809100.051]: rms 1134 max 1935 freq -103 +/- 680 delay 1891 +/- 4
387     ptp4l[809101.051]: rms 453 max 855 freq +341 +/- 642 delay 1888 +/- 0
388     ptp4l[809102.052]: rms 491 max 772 freq +1120 +/- 752 delay 1702 +/- 0
389     ptp4l[809103.052]: rms 423 max 654 freq +1352 +/- 653 delay 1888 +/- 0
390     ptp4l[809104.052]: rms 412 max 579 freq +1001 +/- 672 delay 1702 +/- 0
391     ptp4l[809105.053]: rms 441 max 672 freq +807 +/- 709 delay 1826 +/- 88
392     ptp4l[809106.053]: rms 422 max 607 freq +1353 +/- 636 delay 1702 +/- 0
393     ptp4l[809107.054]: rms 401 max 466 freq +946 +/- 646 delay 1702 +/- 0
394     ptp4l[809108.055]: rms 401 max 502 freq +912 +/- 659
395
396 10. Synchronize local clock on O-DU for sample application or l1
397 Application. ::
398
399     ./phc2sys -s enp181s0f0 -w -m -R 8
400
401 Example of output::
402
403    ./phc2sys -s enp181s0f0 -w -m -R 8
404     phc2sys[809127.123]: CLOCK_REALTIME phc offset    675 s0 freq  -37379 delay   1646
405     phc2sys[809127.249]: CLOCK_REALTIME phc offset    696 s2 freq  -37212 delay   1654
406     phc2sys[809127.374]: CLOCK_REALTIME phc offset    630 s2 freq  -36582 delay   1648
407     phc2sys[809127.500]: CLOCK_REALTIME phc offset    461 s2 freq  -36562 delay   1642
408     phc2sys[809127.625]: CLOCK_REALTIME phc offset    374 s2 freq  -36510 delay   1643
409     phc2sys[809127.751]: CLOCK_REALTIME phc offset    122 s2 freq  -36650 delay   1649
410     phc2sys[809127.876]: CLOCK_REALTIME phc offset     34 s2 freq  -36702 delay   1650
411     phc2sys[809128.002]: CLOCK_REALTIME phc offset   -112 s2 freq  -36837 delay   1645
412     phc2sys[809128.127]: CLOCK_REALTIME phc offset   -160 s2 freq  -36919 delay   1643
413     phc2sys[809128.252]: CLOCK_REALTIME phc offset   -270 s2 freq  -37077 delay   1657
414     phc2sys[809128.378]: CLOCK_REALTIME phc offset   -285 s2 freq  -37173 delay   1644
415     phc2sys[809128.503]: CLOCK_REALTIME phc offset   -349 s2 freq  -37322 delay   1644
416     phc2sys[809128.629]: CLOCK_REALTIME phc offset   -402 s2 freq  -37480 delay   1641
417     phc2sys[809128.754]: CLOCK_REALTIME phc offset   -377 s2 freq  -37576 delay   1648
418     phc2sys[809128.879]: CLOCK_REALTIME phc offset   -467 s2 freq  -37779 delay   1650
419     phc2sys[809129.005]: CLOCK_REALTIME phc offset   -408 s2 freq  -37860 delay   1648
420     phc2sys[809129.130]: CLOCK_REALTIME phc offset   -480 s2 freq  -38054 delay   1655
421     phc2sys[809129.256]: CLOCK_REALTIME phc offset   -350 s2 freq  -38068 delay   1650
422
423 Support in xRAN Library
424 =======================
425
426 The xRAN library provides an API to check whether PTP for Linux is
427 running correctly. There is a function called xran_is_synchronized(). It
428 checks if ptp4l and phc2sys are running in the system by making PMC tool
429 requests for the current port state and comparing it with the expected
430 value. This verification should be done before initialization.
431
432 -  “SLAVE” is the only expected value in this release; only a non-master scenario is supported currently.
433