Skip to content

Commit 7f858cf

Browse files
abhatt-rhabhatt-rh
authored
Merge pull request #55704 from aireilly/TELCODOCS-1039-WESTPORT-CHANNEL-PTP-413
TELCODOCS-1039 - Westport channel NIC PTP grandmaster clock
2 parents d0c5d36 + 5f63714 commit 7f858cf

6 files changed

+378
-4
lines changed

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

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * networking/using-ptp.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="configuring-linuxptp-services-as-grandmaster-clock_{context}"]
7+
= Configuring linuxptp services as a grandmaster clock
8+
9+
You can configure the `linuxptp` services (`ptp4l`, `phc2sys`, `ts2phc`) as grandmaster clock by creating a `PtpConfig` custom resource (CR) that configures the host NIC.
10+
11+
The `ts2phc` utility allows you to synchronize the system clock with the PTP grandmaster clock so that the node can stream precision clock signal to downstream PTP ordinary clocks and boundary clocks.
12+
13+
[NOTE]
14+
====
15+
Use the following example `PtpConfig` CR as the basis to configure `linuxptp` services as the grandmaster clock for your particular hardware and environment.
16+
This example CR does not configure PTP fast events. To configure PTP fast events, set appropriate values for `ptp4lOpts`, `ptp4lConf`, and `ptpClockThreshold`.
17+
`ptpClockThreshold` is used only when events are enabled.
18+
See "Configuring the PTP fast event notifications publisher" for more information.
19+
====
20+
21+
.Prerequisites
22+
23+
* Install an Intel Westport Channel network interface in the bare-metal cluster host.
24+
25+
* Install the OpenShift CLI (`oc`).
26+
27+
* Log in as a user with `cluster-admin` privileges.
28+
29+
* Install the PTP Operator.
30+
31+
.Procedure
32+
33+
. Create the `PtpConfig` resource. For example:
34+
35+
.. Save the following YAML in the `grandmaster-clock-ptp-config.yaml` file:
36+
+
37+
include::snippets/grandmaster-clock-ptp-config.adoc[]
38+
39+
.. Create the CR by running the following command:
40+
+
41+
[source,terminal]
42+
----
43+
$ oc create -f grandmaster-clock-ptp-config.yaml
44+
----
45+
46+
.Verification
47+
48+
. Check that the `PtpConfig` profile is applied to the node.
49+
50+
.. Get the list of pods in the `openshift-ptp` namespace by running the following command:
51+
+
52+
[source,terminal]
53+
----
54+
$ oc get pods -n openshift-ptp -o wide
55+
----
56+
+
57+
.Example output
58+
[source,terminal]
59+
----
60+
NAME READY STATUS RESTARTS AGE IP NODE
61+
linuxptp-daemon-74m2g 3/3 Running 3 4d15h 10.16.230.7 compute-1.example.com
62+
ptp-operator-5f4f48d7c-x7zkf 1/1 Running 1 4d15h 10.128.1.145 compute-1.example.com
63+
----
64+
65+
.. Check that the profile is correct. Examine the logs of the `linuxptp` daemon that corresponds to the node you specified in the `PtpConfig` profile.
66+
Run the following command:
67+
+
68+
[source,terminal]
69+
----
70+
$ oc logs linuxptp-daemon-74m2g -n openshift-ptp -c linuxptp-daemon-container
71+
----
72+
+
73+
.Example output
74+
[source,terminal]
75+
----
76+
ts2phc[94980.334]: [ts2phc.0.config] nmea delay: 98690975 ns
77+
ts2phc[94980.334]: [ts2phc.0.config] ens3f0 extts index 0 at 1676577329.999999999 corr 0 src 1676577330.901342528 diff -1
78+
ts2phc[94980.334]: [ts2phc.0.config] ens3f0 master offset -1 s2 freq -1
79+
ts2phc[94980.441]: [ts2phc.0.config] nmea sentence: GNRMC,195453.00,A,4233.24427,N,07126.64420,W,0.008,,160223,,,A,V
80+
phc2sys[94980.450]: [ptp4l.0.config] CLOCK_REALTIME phc offset 943 s2 freq -89604 delay 504
81+
phc2sys[94980.512]: [ptp4l.0.config] CLOCK_REALTIME phc offset 1000 s2 freq -89264 delay 474
82+
----

‎modules/nw-ptp-grandmaster-clock-configuration-reference.adoc

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * networking/using-ptp.adoc
4+
5+
:_content-type: REFERENCE
6+
[id="nw-ptp-grandmaster-clock-configuration-reference_{context}"]
7+
= Grandmaster clock PtpConfig configuration reference
8+
9+
The following reference information describes the configuration options for the `PtpConfig` custom resource (CR) that configures the `linuxptp` services (`ptp4l`, `phc2sys`, `ts2phc`) as grandmaster clock.
10+
11+
.PtpConfig configuration options for PTP Grandmaster clock
12+
[cols="1,3" options="header"]
13+
|====
14+
|PtpConfig CR field
15+
|Description
16+
17+
|`plugins`
18+
|Specify an array of `.exec.cmdline` options that configure the NIC for grandmaster clock operation. Grandmaster clock configuration requires certain PTP pins to be disabled.
19+
20+
The plugin mechanism allows the PTP Operator to do automated hardware configuration.
21+
For the Intel Westport Channel NIC, when `enableDefaultConfig` is true, The PTP Operator runs a hard-coded script to do the required configuration for the NIC.
22+
23+
|`ptp4lOpts`
24+
|Specify system configuration options for the `ptp4l` service.
25+
The options should not include the network interface name `-i <interface>` and service config file `-f /etc/ptp4l.conf` because the network interface name and the service config file are automatically appended.
26+
27+
|`ptp4lConf`
28+
|Specify the required configuration to start `ptp4l` as grandmaster clock.
29+
For example, the `ens2f1` interface synchronizes downstream connected devices.
30+
For grandmaster clocks, set `clockClass` to `6` and set `clockAccuracy` to `0x27`.
31+
Set `timeSource` to `0x20` for when receiving the timing signal from a Global navigation satellite system (GNSS).
32+
33+
|`tx_timestamp_timeout`
34+
|Specify the maximum amount of time to wait for the transmit (TX) timestamp from the sender before discarding the data.
35+
36+
|`boundary_clock_jbod`
37+
|Specify the JBOD boundary clock time delay value.
38+
This value is used to correct the time values that are passed between the network time devices.
39+
40+
|`phc2sysOpts`
41+
a|Specify system config options for the `phc2sys` service.
42+
If this field is empty the PTP Operator does not start the `phc2sys` service.
43+
[NOTE]
44+
====
45+
Ensure that the network interface listed here is configured as grandmaster and is referenced as required in the `ts2phcConf` and `ptp4lConf` fields.
46+
====
47+
48+
|`ptpSchedulingPolicy`
49+
|Configure the scheduling policy for `ptp4l` and `phc2sys` processes.
50+
Default value is `SCHED_OTHER`.
51+
Use `SCHED_FIFO` on systems that support FIFO scheduling.
52+
53+
|`ptpSchedulingPriority`
54+
|Set an integer value from 1-65 to configure FIFO priority for `ptp4l` and `phc2sys` processes when `ptpSchedulingPolicy` is set to `SCHED_FIFO`.
55+
The `ptpSchedulingPriority` field is not used when `ptpSchedulingPolicy` is set to `SCHED_OTHER`.
56+
57+
|`ptpClockThreshold`
58+
|Optional.
59+
If `ptpClockThreshold` stanza is not present, default values are used for `ptpClockThreshold` fields.
60+
Stanza shows default `ptpClockThreshold` values. `ptpClockThreshold` values configure how long after the PTP master clock is disconnected before PTP events are triggered.
61+
`holdOverTimeout` is the time value in seconds before the PTP clock event state changes to `FREERUN` when the PTP master clock is disconnected.
62+
The `maxOffsetThreshold` and `minOffsetThreshold` settings configure offset values in nanoseconds that compare against the values for `CLOCK_REALTIME` (`phc2sys`) or master offset (`ptp4l`).
63+
When the `ptp4l` or `phc2sys` offset value is outside this range, the PTP clock state is set to `FREERUN`. When the offset value is within this range, the PTP clock state is set to `LOCKED`.
64+
65+
|`ts2phcConf`
66+
a|Sets the configuration for the `ts2phc` command.
67+
68+
`leapfile` is the default path to the current leap seconds definition file in the PTP Operator container image.
69+
70+
`ts2phc.nmea_serialport` is the serial port device that is connected to the NMEA GPS clock source.
71+
When configured, the GNSS receiver is accessible on `/dev/gnss<id>`.
72+
If the host has multiple GNSS receivers, you can find the correct device by enumerating either of the following devices:
73+
74+
* `/sys/class/net/<eth_port>/device/gnss/`
75+
* `/sys/class/gnss/gnss<id>/device/`
76+
77+
|`ts2phcOpts`
78+
|Set options for the `ts2phc` command.
79+
80+
|`recommend`
81+
|Specify an array of one or more `recommend` objects that define rules on how the `profile` should be applied to nodes.
82+
83+
|`.recommend.profile`
84+
|Specify the `.recommend.profile` object name that is defined in the `profile` section.
85+
86+
|`.recommend.priority`
87+
|Specify the `priority` with an integer value between `0` and `99`.
88+
A larger number gets lower priority, so a priority of `99` is lower than a priority of `10`.
89+
If a node can be matched with multiple profiles according to rules defined in the `match` field, the profile with the higher priority is applied to that node.
90+
91+
|`.recommend.match`
92+
|Specify `.recommend.match` rules with `nodeLabel` or `nodeName`.
93+
94+
|`.recommend.match.nodeLabel`
95+
|Set `nodeLabel` with the `key` of `node.Labels` from the node object by using the `oc
96+
get nodes --show-labels` command.
97+
For example: `node-role.kubernetes.io/worker`.
98+
99+
|`.recommend.match.nodeName`
100+
|Set `nodeName` with value of `node.Name` from the node object by using the `oc get nodes` command.
101+
For example: `compute-1.example.com`.
102+
|====

‎modules/nw-ptp-introduction.adoc

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,14 @@
88

99
Precision Time Protocol (PTP) is used to synchronize clocks in a network. When used in conjunction with hardware support, PTP is capable of sub-microsecond accuracy, and is more accurate than Network Time Protocol (NTP).
1010

11-
The `linuxptp` package includes the `ptp4l` and `phc2sys` programs for clock synchronization. `ptp4l` implements the PTP boundary clock and ordinary clock. `ptp4l` synchronizes the PTP hardware clock to the source clock with hardware time stamping and synchronizes the system clock to the source clock with software time stamping. `phc2sys` is used for hardware time stamping to synchronize the system clock to the PTP hardware clock on the network interface controller (NIC).
12-
1311
[id="ptp-elements_{context}"]
1412
== Elements of a PTP domain
1513

16-
PTP is used to synchronize multiple nodes connected in a network, with clocks for each node. The clocks synchronized by PTP are organized in a source-destination hierarchy. The hierarchy is created and updated automatically by the best master clock (BMC) algorithm, which runs on every clock. Destination clocks are synchronized to source clocks, and destination clocks can themselves be the source for other downstream clocks. The following types of clocks can be included in configurations:
14+
PTP is used to synchronize multiple nodes connected in a network, with clocks for each node. The clocks synchronized by PTP are organized in a source-destination hierarchy.
15+
The hierarchy is created and updated automatically by the best master clock (BMC) algorithm, which runs on every clock. Destination clocks are synchronized to source clocks, and destination clocks can themselves be the source for other downstream clocks.
16+
The three primary types of PTP clocks are described below.
1717

18-
Grandmaster clock:: The grandmaster clock provides standard time information to other clocks across the network and ensures accurate and stable synchronisation. It writes time stamps and responds to time requests from other clocks. Grandmaster clocks can be synchronized to a Global Positioning System (GPS) time source.
18+
Grandmaster clock:: The grandmaster clock provides standard time information to other clocks across the network and ensures accurate and stable synchronisation. It writes time stamps and responds to time requests from other clocks. Grandmaster clocks synchronize to a Global Navigation Satellite System (GNSS) time source. The Grandmaster clock is the authoritative source of time in the network and is responsible for providing time synchronization to all other devices.
1919

2020
Ordinary clock:: The ordinary clock has a single port connection that can play the role of source or destination clock, depending on its position in the network. The ordinary clock can read and write time stamps.
2121

‎modules/ptp-linuxptp-introduction.adoc

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * networking/using-ptp.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="ptp-linuxptp-introduction_{context}"]
7+
= Overview of linuxptp in {product-title} nodes
8+
9+
{product-title} uses PTP and `linuxptp` for high precision system timing in bare-metal infrastructure.
10+
The `linuxptp` package includes the `ts2phc`, `pmc`, `ptp4l`, and `phc2sys` programs for system clock synchronization.
11+
12+
ts2phc:: `ts2phc` synchronizes the PTP hardware clock (PHC) across PTP devices with a high degree of precision.
13+
`ts2phc` is used in grandmaster clock configurations.
14+
It receives the precision timing signal a high precision clock source such as Global Navigation Satellite System (GNSS).
15+
GNSS provides an accurate and reliable source of synchronized time for use in large distributed networks.
16+
GNSS clocks typically provide time information with a precision of a few nanoseconds.
17+
+
18+
The `ts2phc` system daemon sends timing information from the grandmaster clock to other PTP devices in the network by reading time information from the grandmaster clock and converting it to PHC format.
19+
PHC time is used by other devices in the network to synchronize their clocks with the grandmaster clock.
20+
21+
pmc:: `pmc` implements a PTP management client (`pmc`) according to IEEE standard 1588.1588.
22+
`pmc` provides basic management access for the `ptp4l` system daemon.
23+
`pmc` reads from standard input and sends the output over the selected transport, printing any replies it receives.
24+
25+
ptp4l:: `ptp4l` implements the PTP boundary clock and ordinary clock and runs as a system daemon.
26+
`ptp4l` does the following:
27+
28+
* Synchronizes the PHC to the source clock with hardware time stamping
29+
* Synchronizes the system clock to the source clock with software time stamping
30+
31+
phc2sys:: `phc2sys` synchronizes the system clock to the PHC on the network interface controller (NIC).
32+
The `phc2sys` system daemon continuously monitors the PHC for timing information.
33+
When it detects a timing error, the PHC corrects the system clock.

‎networking/using-ptp.adoc

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,8 @@ Before enabling PTP, ensure that NTP is disabled for the required nodes. You can
3333

3434
include::modules/ptp-dual-nics.adoc[leveloffset=+2]
3535

36+
include::modules/ptp-linuxptp-introduction.adoc[leveloffset=+1]
37+
3638
include::modules/nw-ptp-installing-operator-cli.adoc[leveloffset=+1]
3739

3840
include::modules/nw-ptp-installing-operator-web-console.adoc[leveloffset=+1]
@@ -45,6 +47,15 @@ When installed, the PTP Operator searches your cluster for PTP-capable network d
4547

4648
include::modules/nw-ptp-device-discovery.adoc[leveloffset=+2]
4749

50+
include::modules/nw-ptp-configuring-linuxptp-services-as-grandmaster-clock.adoc[leveloffset=+2]
51+
52+
[role="_additional-resources"]
53+
.Additional resources
54+
55+
* xref:../networking/using-ptp.adoc#cnf-configuring-the-ptp-fast-event-publisher_using-ptp[Configuring the PTP fast event notifications publisher]
56+
57+
include::modules/nw-ptp-grandmaster-clock-configuration-reference.adoc[leveloffset=+3]
58+
4859
include::modules/nw-ptp-configuring-linuxptp-services-as-ordinary-clock.adoc[leveloffset=+2]
4960

5061
[role="_additional-resources"]

0 commit comments

Comments
 (0)