Skip to content

Commit 449501a

Browse files
aireillyaireilly
authored
Merge pull request #79493 from aireilly/TELCODOCS-1879-leap-seconds
TELCODOCS-1879 - Adding docs for PTP Operator T-GM leap seconds feature
2 parents ff38edf + 58cb100 commit 449501a

10 files changed

+170
-466
lines changed

‎modules/nw-ptp-configuring-linuxptp-services-as-grandmaster-clock-dual-nic.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ See "Configuring the PTP fast event notifications publisher" for more informatio
4646
====
4747
[source,yaml]
4848
----
49-
include::snippets/ptp_PtpConfigDualCardGmWpc.yaml[]
49+
include::snippets/ztp_PtpConfigDualCardGmWpc.yaml[]
5050
----
5151
====
5252
+

‎modules/nw-ptp-configuring-linuxptp-services-as-grandmaster-clock.adoc

Lines changed: 1 addition & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -36,26 +36,12 @@ See "Configuring the PTP fast event notifications publisher" for more informatio
3636
.. Depending on your requirements, use one of the following T-GM configurations for your deployment.
3737
Save the YAML in the `grandmaster-clock-ptp-config.yaml` file:
3838
+
39-
.Example PTP grandmaster clock configuration
40-
[%collapsible]
41-
=====
42-
[source,yaml]
43-
----
44-
include::snippets/ptp_PtpConfigGmWpc.yaml[]
45-
----
46-
47-
[NOTE]
48-
====
49-
The example PTP grandmaster clock configuration is for test purposes only and is not intended for production.
50-
====
51-
=====
52-
+
5339
.PTP grandmaster clock configuration for E810 NIC
5440
[%collapsible]
5541
====
5642
[source,yaml]
5743
----
58-
include::snippets/ptp_PtpConfigGmWpc.yaml[]
44+
include::snippets/ztp_PtpConfigGmWpc.yaml[]
5945
----
6046
====
6147
+

‎modules/ptp-configuring-dynamic-leap-seconds-handling-for-tgm.adoc

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * networking/ptp/configuring-ptp.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="ptp-configuring-dynamic-leap-seconds-handling-for-tgm_{context}"]
7+
= Configuring dynamic leap seconds handling for PTP grandmaster clocks
8+
9+
The PTP Operator container image includes the latest `leap-seconds.list` file that is available at the time of release.
10+
You can configure the PTP Operator to automatically update the leap second file by using Global Positioning System (GPS) announcements.
11+
12+
Leap second information is stored in an automatically generated `ConfigMap` resource named `leap-configmap` in the `openshift-ptp` namespace.
13+
The PTP Operator mounts the `leap-configmap` resource as a volume in the `linuxptp-daemon` pod that is accessible by the `ts2phc` process.
14+
15+
If the GPS satellite broadcasts new leap second data, the PTP Operator updates the `leap-configmap` resource with the new data.
16+
The `ts2phc` process picks up the changes automatically.
17+
18+
[NOTE]
19+
====
20+
The following procedure is provided as reference.
21+
The {product-version} version of the PTP Operator enables automatic leap second management by default.
22+
====
23+
24+
.Prerequisites
25+
26+
* You have installed the OpenShift CLI (`oc`).
27+
28+
* You have logged in as a user with `cluster-admin` privileges.
29+
30+
* You have installed the PTP Operator and configured a PTP grandmaster clock (T-GM) in the cluster.
31+
32+
.Procedure
33+
34+
. Configure automatic leap second handling in the `phc2sysOpts` section of the `PtpConfig` CR.
35+
Set the following options:
36+
+
37+
[source,yaml]
38+
----
39+
phc2sysOpts: -r -u 0 -m -w -N 8 -R 16 -S 2 -s ens2f0 -n 24 <1>
40+
----
41+
<1> Set `-w` to force `phc2sys` to wait until `ptp4l` has synchronized the system hardware clock before starting its own synchronization process.
42+
+
43+
[NOTE]
44+
====
45+
Previously, the T-GM required an offset adjustment in the `phc2sys` configuration (`-O -37`) to account for historical leap seconds.
46+
This is no longer needed.
47+
====
48+
49+
. Configure the Intel e810 NIC to enable periodical reporting of `NAV-TIMELS` messages by the GPS receiver in the `spec.profile.plugins.e810.ublxCmds` section of the `PtpConfig` CR.
50+
For example:
51+
+
52+
[source,yaml]
53+
----
54+
- args: #ubxtool -P 29.20 -p CFG-MSG,1,38,248
55+
- "-P"
56+
- "29.20"
57+
- "-p"
58+
- "CFG-MSG,1,38,248"
59+
----
60+
61+
.Verification
62+
63+
. Validate that the configured T-GM is receiving `NAV-TIMELS` messages from the connected GPS.
64+
Run the following command:
65+
+
66+
[source,terminal]
67+
----
68+
$ oc -n openshift-ptp -c linuxptp-daemon-container exec -it $(oc -n openshift-ptp get pods -o name | grep daemon) -- ubxtool -t -p NAV-TIMELS -P 29.20
69+
----
70+
+
71+
.Example output
72+
[source,terminal]
73+
----
74+
1722509534.4417
75+
UBX-NAV-STATUS:
76+
iTOW 384752000 gpsFix 5 flags 0xdd fixStat 0x0 flags2 0x8
77+
ttff 18261, msss 1367642864
78+
79+
1722509534.4419
80+
UBX-NAV-TIMELS:
81+
iTOW 384752000 version 0 reserved2 0 0 0 srcOfCurrLs 2
82+
currLs 18 srcOfLsChange 2 lsChange 0 timeToLsEvent 70376866
83+
dateOfLsGpsWn 2441 dateOfLsGpsDn 7 reserved2 0 0 0
84+
valid x3
85+
86+
1722509534.4421
87+
UBX-NAV-CLOCK:
88+
iTOW 384752000 clkB 784281 clkD 435 tAcc 3 fAcc 215
89+
90+
1722509535.4477
91+
UBX-NAV-STATUS:
92+
iTOW 384753000 gpsFix 5 flags 0xdd fixStat 0x0 flags2 0x8
93+
ttff 18261, msss 1367643864
94+
95+
1722509535.4479
96+
UBX-NAV-CLOCK:
97+
iTOW 384753000 clkB 784716 clkD 435 tAcc 3 fAcc 218
98+
----
99+
100+
. Validate that the `leap-configmap` resource has been successfully generated by the PTP Operator and is up to date with the latest version of the link:https://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list[leap-seconds.list].
101+
Run the following command:
102+
+
103+
[source,terminal]
104+
----
105+
$ oc -n openshift-ptp get configmap leap-configmap -o jsonpath='{.data.<node_name>}' <1>
106+
----
107+
<1> Replace `<node_name>` with the node where you have installed and configured the PTP T-GM clock with automatic leap second management.
108+
Escape special characters in the node name.
109+
For example, `node-1\.example\.com`.
110+
111+
+
112+
.Example output
113+
[source,terminal]
114+
----
115+
# Do not edit
116+
# This file is generated automatically by linuxptp-daemon
117+
#$ 3913697179
118+
#@ 4291747200
119+
2272060800 10 # 1 Jan 1972
120+
2287785600 11 # 1 Jul 1972
121+
2303683200 12 # 1 Jan 1973
122+
2335219200 13 # 1 Jan 1974
123+
2366755200 14 # 1 Jan 1975
124+
2398291200 15 # 1 Jan 1976
125+
2429913600 16 # 1 Jan 1977
126+
2461449600 17 # 1 Jan 1978
127+
2492985600 18 # 1 Jan 1979
128+
2524521600 19 # 1 Jan 1980
129+
2571782400 20 # 1 Jul 1981
130+
2603318400 21 # 1 Jul 1982
131+
2634854400 22 # 1 Jul 1983
132+
2698012800 23 # 1 Jul 1985
133+
2776982400 24 # 1 Jan 1988
134+
2840140800 25 # 1 Jan 1990
135+
2871676800 26 # 1 Jan 1991
136+
2918937600 27 # 1 Jul 1992
137+
2950473600 28 # 1 Jul 1993
138+
2982009600 29 # 1 Jul 1994
139+
3029443200 30 # 1 Jan 1996
140+
3076704000 31 # 1 Jul 1997
141+
3124137600 32 # 1 Jan 1999
142+
3345062400 33 # 1 Jan 2006
143+
3439756800 34 # 1 Jan 2009
144+
3550089600 35 # 1 Jul 2012
145+
3644697600 36 # 1 Jul 2015
146+
3692217600 37 # 1 Jan 2017
147+
148+
#h e65754d4 8f39962b aa854a61 661ef546 d2af0bfa
149+
----

‎modules/ptp-overview-of-gnss-grandmaster-clock.adoc

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,3 +28,14 @@ Digital Phase-Locked Loop (DPLL)::
2828
DPLL provides clock synchronization between different PTP nodes in the network.
2929
DPLL compares the phase of the local system clock signal with the phase of the incoming synchronization signal, for example, PTP messages from the PTP grandmaster clock.
3030
The DPLL continuously adjusts the local clock frequency and phase to minimize the phase difference between the local clock and the reference clock.
31+
32+
[discrete]
33+
[id="handling-leap-second-events-in-gnss_{context}"]
34+
== Handling leap second events in GNSS-synced PTP grandmaster clocks
35+
36+
A leap second is a one-second adjustment that is occasionally applied to Coordinated Universal Time (UTC) to keep it synchronized with International Atomic Time (TAI).
37+
UTC leap seconds are unpredictable.
38+
Internationally agreed leap seconds are listed in link:https://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list[leap-seconds.list].
39+
This file is regularly updated by the International Earth Rotation and Reference Systems Service (IERS).
40+
An unhandled leap second can have a significant impact on far edge RAN networks.
41+
It can cause the far edge RAN application to immediately disconnect voice calls and data sessions.

‎networking/ptp/configuring-ptp.adoc

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ toc::[]
88

99
The PTP Operator adds the `NodePtpDevice.ptp.openshift.io` custom resource definition (CRD) to {product-title}.
1010

11-
When installed, the PTP Operator searches your cluster for PTP-capable network devices on each node. It creates and updates a `NodePtpDevice` custom resource (CR) object for each node that provides a compatible PTP-capable network device.
11+
When installed, the PTP Operator searches your cluster for Precision Time Protocol (PTP) capable network devices on each node. It creates and updates a `NodePtpDevice` custom resource (CR) object for each node that provides a compatible PTP-capable network device.
1212

1313
include::modules/nw-ptp-installing-operator-cli.adoc[leveloffset=+1]
1414

@@ -35,6 +35,8 @@ include::modules/nw-ptp-e810-hardware-configuration-reference.adoc[leveloffset=+
3535

3636
include::modules/nw-ptp-dual-wpc-hardware-config-reference.adoc[leveloffset=+2]
3737

38+
include::modules/ptp-configuring-dynamic-leap-seconds-handling-for-tgm.adoc[leveloffset=+1]
39+
3840
include::modules/nw-ptp-configuring-linuxptp-services-as-boundary-clock.adoc[leveloffset=+1]
3941

4042
[role="_additional-resources"]

‎networking/ptp/using-ptp-events.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ include::_attributes/common-attributes.adoc[]
77
toc::[]
88

99
Cloud native applications such as virtual RAN (vRAN) require access to notifications about hardware timing events that are critical to the functioning of the overall network.
10-
PTP clock synchronization errors can negatively affect the performance and reliability of your low-latency application, for example, a vRAN application running in a distributed unit (DU).
10+
Precision Time Protocol (PTP) clock synchronization errors can negatively affect the performance and reliability of your low-latency application, for example, a vRAN application running in a distributed unit (DU).
1111

1212
include::modules/cnf-about-ptp-and-clock-synchronization.adoc[leveloffset=+1]
1313

0 commit comments

Comments
 (0)