// 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

[role="_abstract"]
Holdover allows the grandmaster (T-GM) clock to maintain synchronization performance when the global navigation satellite system (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, and the resulting slope is expressed in nanoseconds per second.
====

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::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 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.

image:darkcircle-3.png[20,20] The GNSS signal is lost again, and the T-GM clock re-enters the `HOLDOVER` mode. The time error begins to increase.

image:darkcircle-4.png[20,20] The time error exceeds the `MaxInSpecOffset` threshold due to prolonged loss of traceability.

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.
