Clock Manager Codeflow

Clock Manager (clkmgr) is a software for monitoring network time synchronization on the local platform and reporting the time synchronization status to any application executing on the local system and subscribe to it. The clkmgr communicates with the time synchronization daemons, like ptp4l from Linux PTP Project and chronyd from Chrony Project to get real-time synchronization status. Any changes to the subscribed event state will generate event notifications to the application.

The Clock Manager is a 2-part implementation. It provides a client-runtime library and a proxy daemon. We assume the Clock Manager is always installed in the same local machine as the ptp4l and chronyd.

Figure 1 - High-Level Design of Clock Manager Library

• C/C++ sample applications - User space applications are provided to showcase how to use the API from the client-runtime library. Please note that the sample applications provided are only for user reference and are not for production usage.

• Client-runtime library (libclkmgr) - A dynamic library that provides a set of APIs for C/C++ user space applications to connect, disconnect, subscribe, and obtain real-time ptp4l and chronyd synchronization status from the proxy daemon. This library is written in C++ with a BSD-3-Clause license. It communicates with a proxy daemon via message queues.

• Proxy daemon (clkmgr_proxy) - A daemon that is connecting to multiple clock sync daemons via UDS communication to obtain their latest synchronization status. A local platform should only have single proxy daemon. The proxy daemon communicates with ptp4l via libptpmgmt library and communicates with chronyd via libchrony library. If any changes are detected on the synchronization status, the proxy daemon will immediately notify all the clients that subscribed to it.

Compilation and Test Step

• Build project documentation

Supported Event

In the current state, a total of four ptp4l events are supported. The supported telemetry events are:

1. Offset in Range – A binary event indicates whether the offset between the primary and secondary clocks is within the predefined upper and lower limits.

2. Synced with GM – A binary event indicates whether the port state is a time receiver.

3. AS Capable – A binary event indicates a change in 802.1AS Capable.

4. GM Changed – A binary event indicates whether the primary clock is changed and a string event providing the primary clock’s UUID.

5. Composite event – A binary event that combines multiple events into one event. An example is combining AS Capable, GM Offset, and Synced with GM to compose a “clock is ready to use” event. In this example, if these three parameters are all within the acceptable range, the composite event will become TRUE. If any of the three events is not in the acceptable range, the composite event will become FALSE, indicating the clock is not yet ready to be consumed.

In the current state, only one Chrony events is supported. The supported telemetry events is:

1. Offset in Range – A binary event indicates whether the offset between the primary and secondary clocks is within the predefined upper and lower limits.

Additional PTP and Chrony data:

1. Clock Offset - The offset refers to the time difference (in nanoseconds) between the primary clock and secondary clock.

2. GM UUID – The UUID is a unique identifier for the Grandmaster Clock in a PTP network. The Grandmaster Clock is the primary reference clock in the network, responsible for providing the time to all other clocks.

3. Sync Interval - The synchronization interval (in microsecond) indicates the time between clock update messages send to the local service that synchronizing clock.

4. Notification Timestamp - The timestamp is a nanosecond-precision timestamp that records the time of the last notification event to ensure precise tracking of notification events.

API, classes, enums, and structures

Comprehensive documentation for all Clock Manager library APIs, classes, enums, and structures can be found on the GitHub page.