Adding docs for 3 card T-GM

Author: aireilly

_topic_maps/_topic_map.yml

@@ -1515,10 +1515,10 @@ Topics:
 - Name: Using Stream Control Transmission Protocol
   File: using-sctp
   Distros: openshift-enterprise,openshift-origin
-- Name: Using Precision Time Protocol hardware
+- Name: Using PTP hardware
   Dir: ptp
   Topics:
-  - Name: About Precision Time Protocol in OpenShift cluster nodes
+  - Name: About PTP in OpenShift cluster nodes
     File: about-ptp
   - Name: Configuring PTP devices
     File: configuring-ptp

images/561_OpenShift_Using_PTP_network_0124.png

@@ -4,21 +4,22 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="configuring-linuxptp-services-as-grandmaster-clock-dual-nic_{context}"]
-= Configuring linuxptp services as a grandmaster clock for dual E810 NICs
+= Configuring linuxptp services as a grandmaster clock for 2 E810 NICs
 
-You can configure the `linuxptp` services (`ptp4l`, `phc2sys`, `ts2phc`) as a grandmaster clock (T-GM) for dual E810 NICs by creating a `PtpConfig` custom resource (CR) that configures the host NICs.
+You can configure the `linuxptp` services (`ptp4l`, `phc2sys`, `ts2phc`) as a grandmaster clock (T-GM) for 2 E810 NICs by creating a `PtpConfig` custom resource (CR) that configures the NICs.
 
-You can configure the `linuxptp` services as a T-GM for the following dual E810 NICs:
+You can configure the `linuxptp` services as a T-GM for the following E810 NICs:
 
-* Intel E810-XXVDA4T Westport Channel NICs
-* Intel E810-CQDA2T Logan Beach NICs
+* Intel E810-XXVDA4T Westport Channel NIC
+* Intel E810-CQDA2T Logan Beach NIC
 
-For distributed RAN (D-RAN) use cases, you can configure PTP for dual-NICs as follows:
+For distributed RAN (D-RAN) use cases, you can configure PTP for 2 NICs as follows:
 
-* NIC one is synced to the global navigation satellite system (GNSS) time source.
-* NIC two is synced to the 1PPS timing output provided by NIC one. This configuration is provided by the PTP hardware plugin in the `PtpConfig` CR.
+* NIC 1 is synced to the global navigation satellite system (GNSS) time source.
+* NIC 2 is synced to the 1PPS timing output provided by NIC one. This configuration is provided by the PTP hardware plugin in the `PtpConfig` CR.
 
-The dual-NIC PTP T-GM configuration uses a single instance of `ptp4l` and one `ts2phc` process reporting two `ts2phc` instances, one for each NIC.
+The 2-card PTP T-GM configuration uses one instance of `ptp4l` and one instance of `ts2phc`.
+The `ptp4l` and `ts2phc` programs are each configured to operate on two PTP hardware clocks (PHCs), one for each NIC.
 The host system clock is synchronized from the NIC that is connected to the GNSS time source.
 
 [NOTE]

images/holdover_in_t_gm.png

@@ -0,0 +1,106 @@
+// Module included in the following assemblies:
+//
+// * networking/ptp/configuring-ptp.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="configuring-linuxptp-services-as-grandmaster-clock-three-nic_{context}"]
+= Configuring linuxptp services as a grandmaster clock for 3 E810 NICs
+
+You can configure the `linuxptp` services (`ptp4l`, `phc2sys`, `ts2phc`) as a grandmaster clock (T-GM) for 3 E810 NICs by creating a `PtpConfig` custom resource (CR) that configures the NICs.
+
+You can configure the `linuxptp` services as a T-GM with 3 NICs for the following E810 NICs:
+
+* Intel E810-XXVDA4T Westport Channel NIC
+* Intel E810-CQDA2T Logan Beach NIC
+
+For distributed RAN (D-RAN) use cases, you can configure PTP for 3 NICs as follows:
+
+* NIC 1 is synced to the Global Navigation Satellite System (GNSS)
+* NICs 2 and 3 are synced to NIC 1 with 1PPS faceplate connections
+
+Use the following example `PtpConfig` CRs as the basis to configure `linuxptp` services as a 3-card Intel E810 T-GM.
+
+.Prerequisites
+
+* For T-GM clocks in production environments, install 3 Intel E810 NICs in the bare-metal cluster host.
+
+* Install the OpenShift CLI (`oc`).
+
+* Log in as a user with `cluster-admin` privileges.
+
+* Install the PTP Operator.
+
+.Procedure
+
+. Create the `PtpConfig` CR. For example:
+
+.. Save the following YAML in the `three-nic-grandmaster-clock-ptp-config.yaml` file:
++
+.PTP grandmaster clock configuration for 3 E810 NICs
+[%collapsible]
+====
+[source,yaml]
+----
+include::snippets/ptp_PtpConfigThreeCardGmWpc.yaml[]
+----
+====
++
+[NOTE]
+====
+Set the value for `ts2phc.nmea_serialport` to `/dev/gnss0`.
+====
+
+.. Create the CR by running the following command:
++
+[source,terminal]
+----
+$ oc create -f three-nic-grandmaster-clock-ptp-config.yaml
+----
+
+.Verification
+
+. Check that the `PtpConfig` profile is applied to the node.
+
+.. Get the list of pods in the `openshift-ptp` namespace by running the following command:
++
+[source,terminal]
+----
+$ oc get pods -n openshift-ptp -o wide
+----
++
+.Example output
+[source,terminal]
+----
+NAME                          READY   STATUS    RESTARTS   AGE     IP             NODE
+linuxptp-daemon-74m3q         3/3     Running   3          4d15h   10.16.230.7    compute-1.example.com
+ptp-operator-5f4f48d7c-x6zkn  1/1     Running   1          4d15h   10.128.1.145   compute-1.example.com
+----
+
+.. Check that the profile is correct. Run the following command, and examine the logs of the `linuxptp` daemon that corresponds to the node you specified in the `PtpConfig` profile:
++
+[source,terminal]
+----
+$ oc logs linuxptp-daemon-74m3q -n openshift-ptp -c linuxptp-daemon-container
+----
++
+.Example output
+[source,terminal]
+----
+ts2phc[2527.586]: [ts2phc.0.config:7] adding tstamp 1742826342.000000000 to clock /dev/ptp11 <1>
+ts2phc[2527.586]: [ts2phc.0.config:7] adding tstamp 1742826342.000000000 to clock /dev/ptp7 <1>
+ts2phc[2527.586]: [ts2phc.0.config:7] adding tstamp 1742826342.000000000 to clock /dev/ptp14 <1>
+ts2phc[2527.586]: [ts2phc.0.config:7] nmea delay: 56308811 ns
+ts2phc[2527.586]: [ts2phc.0.config:6] /dev/ptp14 offset          0 s2 freq      +0 <2>
+ts2phc[2527.587]: [ts2phc.0.config:6] /dev/ptp7 offset          0 s2 freq      +0 <2>
+ts2phc[2527.587]: [ts2phc.0.config:6] /dev/ptp11 offset          0 s2 freq      -0 <2>
+I0324 14:25:05.000439  106907 stats.go:61] state updated for ts2phc =s2
+I0324 14:25:05.000504  106907 event.go:419] dpll State s2, gnss State s2, tsphc state s2, gm state s2,
+I0324 14:25:05.000906  106907 stats.go:61] state updated for ts2phc =s2
+I0324 14:25:05.001059  106907 stats.go:61] state updated for ts2phc =s2
+ts2phc[1742826305]:[ts2phc.0.config] ens4f0 nmea_status 1 offset 0 s2
+GM[1742826305]:[ts2phc.0.config] ens4f0 T-GM-STATUS s2 <3>
+----
+<1> `ts2phc` is updating the PTP hardware clock.
+<2> Estimated PTP device offset between PTP device and the reference clock is 0 nanoseconds.
+The PTP device is in sync with the leader clock.
+<3> T-GM is in a locked state (s2).

images/openshift-ptp-3-card-grandmaster.png

@@ -25,9 +25,6 @@ For example, the PRTC is traceable to a GNSS time source.
 |T-GM clock is in `HOLDOVER` mode, and within holdover specification.
 The clock source might not be traceable to a category 1 frequency source.
 
-|`gm.ClockClass 140`
-|T-GM clock is in `HOLDOVER` mode, is out of holdover specification, but it is still traceable to the category 1 frequency source.
-
 |`gm.ClockClass 248`
 |T-GM clock is in `FREERUN` mode.
 |====

images/openshift-ptp-holdover-tgm-clock-with-gnss.png

@@ -10,7 +10,7 @@ Holdover allows the grandmaster (T-GM) clock to maintain synchronization perform
 
 You can define the holdover behavior by configuring the following holdover parameters in the `PTPConfig` custom resource (CR):
 
-`MaxInSpecOffset`:: Specifies the maximum allowed offset in nanoseconds. If the T-GM clock exceeds the `MaxInSpecOffset` value, it transitions to the `FREERUN` state (clock class state `gm.ClockClass 248`). 
+`MaxInSpecOffset`:: Specifies the maximum allowed offset in nanoseconds. If the T-GM clock exceeds the `MaxInSpecOffset` value, it transitions to the `FREERUN` state (clock class state `gm.ClockClass 248`).
 `LocalHoldoverTimeout`:: Specifies the maximum duration, in seconds, for which the T-GM clock remains in the holdover state before transitioning to the `FREERUN` state.
 `LocalMaxHoldoverOffSet`:: Specifies the maximum offset that the T-GM clock can reach during the holdover state in nanoseconds.
 
@@ -23,7 +23,7 @@ If the `LocalMaxHoldoverOffSet` value is less than the `MaxInSpecOffset` value,
 
 For information about clock class states, see "Grandmaster clock class sync state reference" document.
 
-The T-GM clock uses the holdover parameters `LocalMaxHoldoverOffSet` and `LocalHoldoverTimeout` to calculate the slope. Slope is the rate at which the phase offset changes over time. It is measured in nanoseconds per second, where the set value indicates how much the offset increases over a given time period. 
+The T-GM clock uses the holdover parameters `LocalMaxHoldoverOffSet` and `LocalHoldoverTimeout` to calculate the slope. Slope is the rate at which the phase offset changes over time. It is measured in nanoseconds per second, where the set value indicates how much the offset increases over a given time period.
 
 The T-GM clock uses the slope value to predict and compensate for time drift, so reducing timing disruptions during holdover. The T-GM clock uses the following formula to calculate the slope:
 
@@ -43,9 +43,9 @@ The phase offset is converted from picoseconds to nanoseconds. As a result, the
 The following figure illustrates the holdover behavior in a T-GM clock with GNSS as the source:
 
 .Holdover in a T-GM clock with GNSS as the source
-image::holdover_in_t_gm.png[Holdover in a T-GM clock with GNSS as the source]
+image::openshift-ptp-holdover-tgm-clock-with-gnss.png[Holdover in a T-GM clock with GNSS as the source]
 
-image:darkcircle-1.png[20,20] The GNSS signal is lost, causing the T-GM clock to enter the `HOLDOVER` mode. The T-GM clock maintains time accuracy using its internal clock.
+image:darkcircle-1.png[20,20] The GNSS signal is lost, causing the T-GM clock to enter the `HOLDOVER` mode. The T-GM clock maintains time accuracy by using its internal clock.
 
 image:darkcircle-2.png[20,20] The GNSS signal is restored and the T-GM clock re-enters the `LOCKED` mode. When the GNSS signal is restored, the T-GM clock re-enters the `LOCKED` mode only after all dependent components in the synchronization chain, such as `ts2phc` offset, digital phase-locked loop (DPLL) phase offset, and GNSS offset, reach a stable `LOCKED` mode.
 
@@ -55,4 +55,4 @@ image:darkcircle-4.png[20,20] The time error exceeds the `MaxInSpecOffset` thres
 
 image:darkcircle-5.png[20,20] The GNSS signal is restored, and the T-GM clock resumes synchronization. The time error starts to decrease.
 
-image:darkcircle-6.png[20,20] The time error decreases and falls back within the `MaxInSpecOffset` threshold.
+image:darkcircle-6.png[20,20] The time error decreases and falls back within the `MaxInSpecOffset` threshold.