DOC: Differentiate the ptp-notification behavior between T-GM and T-BC

[Elisamara Aoki Gonçalves]

Brief Description
-----------------
Doc changes are required to align with the code changes introduced in https://docs.starlingx.io/admintasks/kubernetes/install-ptp-notifications.html

Severity
--------
<Minor: System/Feature is usable with minor issue>

Diff with proposed changes in https://docs.starlingx.io/admintasks/kubernetes/install-ptp-notifications.html

diff --git a/doc/source/admintasks/kubernetes/install-ptp-notifications.rst b/doc/source/admintasks/kubernetes/install-ptp-notifications.rst
index bea04ea8..8aa2b921 100644
--- a/doc/source/admintasks/kubernetes/install-ptp-notifications.rst
+++ b/doc/source/admintasks/kubernetes/install-ptp-notifications.rst
@@ -132,6 +132,7 @@ For example, follow the steps below:
           ptp4lServiceName: ptp4l-legacy
           phc2sysServiceName: phc2sys-legacy
           logging_level: INFO
+ ptp4lClockClassLockedList: "6,7,135"
           device:
             holdover_seconds: 15
             poll_freq_seconds: 2
@@ -139,6 +140,8 @@ For example, follow the steps below:
           ptp4lServiceName: True
           phc2sysServiceName: True
           ts2phcServiceName: True
+ ptp4lClockClassLockedList: "6,7,135"
+ phc2sysToleranceThreshold: 1000
           log_level: INFO
           control_timeout: 2
           device:
@@ -161,9 +164,10 @@ For example, follow the steps below:
              ptp4lServiceName: ptp4l-instancename
              phc2sysServiceName: phc2sys-instancename
              logging_level: INFO
- device:
- holdover_seconds: 15
- poll_freq_seconds: 2
+ ptp4lClockClassLockedList: "6,7,135"
+ device:
+ holdover_seconds: 15
+ poll_freq_seconds: 2

        ``ptptracking``

@@ -184,6 +188,19 @@ For example, follow the steps below:
        ``logging_level: INFO``
            Set the logging level. DEBUG can be used for additional logs.

+ ``ptp4lClockClassLockedList``
+ Set the list of clock classes that will allow ptp-notification to report "Locked". The
+ clockClass for a monitored ptp4l instance is read via the 'pmc'; if the instance
+ clockClass matches once of the 'ptp4lClockClassLockedList' values, then
+ ptp-notification will report "Locked" for that instance.
+
+ The default values are "6,7,135", which means that ptp-notification will report locked
+ when reading a clockClass of 6, 7 or 135 from the configured ptp4l instance. These
+ values are recommended for nodes operating as a Boundary Clock (BC).
+
+ For nodes operating as a GM, it is recommended to set the value to "6", so that only
+ clockClass 6 is reported as locked.
+
        ``holdover_seconds``
            ``holdover_seconds`` configures how long each service will stay in
            the HOLDOVER state before transitioning to FREERUN. The holdover value
@@ -209,6 +226,8 @@ For example, follow the steps below:
              phc2sysServiceName: True
              ts2phcServiceName: True
              log_level: INFO
+ ptp4lClockClassLockedList: "6,7,135"
+ phc2sysToleranceThreshold: 1000
              control_timeout: 2
              device:
                holdover_seconds: 15
@@ -240,6 +259,30 @@ For example, follow the steps below:
        ``log_level: INFO``
            Set the logging level. DEBUG can be used for additional logs.

+ ``ptp4lClockClassLockedList``
+ Set the list of clock classes that will allow ptp-notification to report "LOCKED". The
+ clockClass for a monitored ptp4l instance is read via the 'pmc'; if the instance
+ clockClass matches once of the 'ptp4lClockClassLockedList' values, then
+ ptp-notification will report "LOCKED" for that instance.
+
+ The default values are "6,7,135", which means that ptp-notification will report locked
+ when reading a clockClass of 6, 7 or 135 from the configured ptp4l instance. These
+ values are recommended for nodes operating as a Boundary Clock (BC).
+
+ For nodes operating as a Grand Master (GM), it is recommended to set the value to "6",
+ so that only clockClass 6 is reported as locked.
+
+ ``phc2sysToleranceThreshold``
+ Default value: 1000
+
+ Set the skew threshold in nanoseconds at which ptp-notification will report that the
+ system clock is no longer considered "LOCKED".
+
+ The ptp-notification application compares the time of the system clock to the configured
+ source PHC; if the delta between the system clock and the PHC is greater than the
+ 'phc2sysToleranceThreshold', a notification will be generated that the system clock is
+ not locked.
+
        ``control_timeout: 2``
            control_timeout sets how frequently, in seconds the services are checked.
            Value applies to all service types.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.opendev.org/c/starlingx/docs/+/898013

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.opendev.org/c/starlingx/docs/+/898013
Committed: https://opendev.org/starlingx/docs/commit/a8cbef9b823d1cda5a3725ee269c786f1572d9b3
Submitter: "Zuul (22348)"
Branch: master

commit a8cbef9b823d1cda5a3725ee269c786f1572d9b3
Author: Elisamara Aoki Goncalves <email address hidden>
Date: Wed Oct 11 20:54:44 2023 +0000

    Differentiate the ptp-notification behavior between T-GM and T-BC (dsR8)

    Fix indentation and formatting issues

    closes-bug: 2039106

    Change-Id: Ia1930d060fe7032e37212772de7013dead6ae4c5
    Signed-off-by: Elisamara Aoki Goncalves <email address hidden>