PTP Notifications Overview

StarlingX supports applications that rely on PTP for synchronization. These applications are able to receive PTP status notifications from StarlingX hosting the application.

StarlingX provides a Sidecar, which runs with the hosted application in the same pod and communicates with the application via a REST API.

StarlingX supports the following features:

  • Provides the capability to enable application(s) subscribe to PTP status notifications and pull for the PTP state on demand.

  • Uses a REST API to communicate PTP notifications to the application.

  • Enables operators to install the ptp-notification-armada-app, Sidecar container, and the application supporting the REST API. For more information, see, https://docs.starlingx.io/api-ref/ptp-notification-armada-app/index.html.

  • Supports the ptp4l module and PTP port that is configured in Subordinate mode (Secondary mode).

  • The PTP notification Sidecar container can be configured with a Liveness Probe, if required. See, Liveness Probe for more information.

  • The PTP status notifications are derived based on the following conditions:

Clock Status

Status

Description

Freerun

Clock is out of sync state

  • If portState is not “SECONDARY” or ClockClass value is NOT “6, 7 or 135” or timeTraceable flag is FALSE.

  • If holdover time exceeds its provided value.

  • If PMC, ptp4l.conf, ptp4l or phc2sys are not accessible.

Locked

Clock is in sync state

If portState is “SECONDARY” and ClockClass value is “6, 7 or 135” and timeTraceable flag is TRUE and PMC, ptp4l.conf, ptp4l or phc2sys are accessible.

Holdover

Clock is in holdover state

  • For NICs using the Intel ice driver: If the state is transitioned from Locked to Holdover AND phc2sys is accessible, and holdover time does not expire.

  • For other NIC types: If the state is transitioned from Locked to Freerun AND phc2sys is accessible, and holdover time does not expire.

Integrated Containerized Applications

  • Applications that rely on PTP for synchronization have the ability to retrieve the relevant data that indicates the status of the PHC clock related to the worker node that the application is running on.

  • Once an application subscribes to PTP notifications it receives the initial data that shows the PHC synchronization state, and receives notifications when there is a state change to the sync status and/or per request for notification (pull).

The figure below describes the subscription framework for PTP notifications.

../../_images/gvf1614702096862.png

Liveness Probe

The PTP notification Sidecar container can be configured with a Liveness probe, if required. You can edit the Sidecar values in the deployment manifest to include these parameters.

Note

Port and timeout values can be configured to meet user preferences. The periodSeconds and timeoutSeconds values can be adjusted based on system performance. A shorter value places more resource demand on the Sidecar pod, so longer values can improve pod stability.

cat <<EOF >
items:
spec:
  template:
    spec:
      containers:
        livenessProbe:
          exec:
            command:
            - curl
            - http://127.0.0.1:8080/health
          failureThreshold: 3
          initialDelaySeconds: 30
          periodSeconds: 5
          successThreshold: 1
          timeoutSeconds: 5
EOF

Container images and API compatibility

The ptp-notification provides a v1 API for backwards compatibility with client applications deployed on StarlingX 6.0, as well as a v2 API for O-RAN Spec Compliant Timing notifications. By default, ptp-notification deploys two notificationservice-base containers to support these APIs. Users must decide which API they will use by deploying the appropriate notificationclient-base image as a sidecar with their consumer application.

  • The v1 API uses starlingx/notificationservice-base:stx.9.0-v2.1.1

    • Compatible with the image: starlingx/notificationclient-base:stx.5.0-v1.0.4

  • The v2 API uses starlingx/notificationservice-base-v2:stx.9.0-v2.1.1

    • Compatible with the image: starlingx/notificationclient-base:stx.9.0-v2.1.1

Upgrades of StarlingX 6.0 to the next patch will automatically upgrade the ptp-notification application and deploy both the v1 and v2 API containers. Consumer applications determine which API they interact with based on the version of notificationclient-base that is deployed along side their application.