Merge pull request #85104 from sr1kar99/2019-holdover-implementation

TELCODOCS#2019: Holdover mechanism implementation in a grandmaster clock

Author: mburke5678

modules/nw-ptp-holdover-in-a-grandmaster-clock.adoc

@@ -0,0 +1,41 @@
+// Module included in the following assemblies:
+//
+// * networking/ptp/configuring-ptp.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="holdover-in-a-grandmaster-clock_{context}"]
+= Holdover in a grandmaster clock with GNSS as the source
+
+Holdover allows the grandmaster (T-GM) clock to maintain synchronization performance when the GNSS source is unavailable. During this period, the T-GM clock relies on its internal oscillator and holdover parameters to reduce timing disruptions.
+
+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`). 
+`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.
+
+If the `MaxInSpecOffset` value is less than the `LocalMaxHoldoverOffset` value, and the T-GM clock exceeds the maximum offset value, the T-GM clock transitions from the holdover state to the `FREERUN` state.
+
+[IMPORTANT]
+====
+If the `LocalMaxHoldoverOffSet` value is less than the `MaxInSpecOffset` value, the holdover timeout occurs before the clock reaches the maximum offset. To resolve this issue, set the `MaxInSpecOffset` field and the `LocalMaxHoldoverOffset` field to the same 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 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:
+
+* Slope = `localMaxHoldoverOffSet` / `localHoldoverTimeout`
++
+For example, if the `LocalHoldOverTimeout` parameter is set to 60 seconds, and the `LocalMaxHoldoverOffset` parameter is set to 3000 nanoseconds, the slope is calculated as follows:
++
+Slope = 3000 nanoseconds / 60 seconds = 50 nanoseconds per second
++
+The T-GM clock reaches the maximum offset in 60 seconds.
+
+[NOTE]
+====
+The phase offset is converted from picoseconds to nanoseconds. As a result, the calculated phase offset during holdover is expressed in nanoseconds per second, and the resulting slope is measured in nanoseconds per second.
+====

networking/ptp/configuring-ptp.adoc

@@ -40,6 +40,13 @@ include::modules/nw-ptp-e810-hardware-configuration-reference.adoc[leveloffset=+
 
 include::modules/nw-ptp-dual-wpc-hardware-config-reference.adoc[leveloffset=+2]
 
+include::modules/nw-ptp-holdover-in-a-grandmaster-clock.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../networking/ptp/configuring-ptp.adoc#nw-ptp-grandmaster-clock-class-reference_configuring-ptp[Grandmaster clock class sync state reference]
+
 include::modules/ptp-configuring-dynamic-leap-seconds-handling-for-tgm.adoc[leveloffset=+1]
 
 include::modules/nw-ptp-configuring-linuxptp-services-as-boundary-clock.adoc[leveloffset=+1]