Configure TAI Offset for T-GM PTP Deployments

About this task

In a T-GM deployment, phc2sys synchronizes the system clock (CLOCK_REALTIME) with the NIC PHC and applies the UTC offset to derive the correct UTC time from TAI. This page explains how T-GM configurations automatically manage the TAI offset and leap seconds.

Background

PTP operates on TAI. Applications that require UTC time must know the current TAI-UTC offset (currently 37 seconds) to convert between the two timescales. The Linux kernel maintains this offset through the CLOCK_TAI clock, which can be read directly by user-space applications.

In earlier releases, configuring phc2sys with a manual offset (-O 37) did not update the kernel’s TAI clock. As a result, applications reading CLOCK_TAI would see an incorrect offset of zero. In addition, maintaining leap second flags and the currentUtcOffset field in PTP Announce messages required manual operator intervention using pmc commands.

Automated Behavior

The following behaviors are handled automatically for T-GM deployments:

Note

This feature applies only to phc2sys instances configured with a manual UTC offset using the -O option or utc_offset parameter. Instances using automatic offset discovery (-a or -w), such as those running in T-BC mode, obtain the offset from ptp4l and are therefore unaffected.

Kernel TAI offset

When phc2sys is configured with a manual UTC offset and the utc_offset_valid parameter in T-GM mode, it sets the kernel CLOCK_TAI clock to the correct value. Applications that use CLOCK_TAI can therefore obtain accurate TAI time without any additional configuration.

Leap second flags

StarlingX reads the leap-seconds file and automatically updates the leap61 / leap59, currentUtcOffsetValid, and timeTraceable flags in PTP Announce messages. These flags are asserted 12 hours before a scheduled leap second at midnight UTC and cleared 6 hours after the leap second occurs.

Dynamic currentUtcOffset

The currentUtcOffset value reported in PTP Announce messages is derived from the leap-seconds file. When a leap second occurs, the offset is incremented (or decremented) automatically.

Startup Behavior

On initial startup, phc2sys delays synchronization of CLOCK_REALTIME until the UTC offset is confirmed to be valid and traceable. This prevents a transient clock adjustment, such as a 37-second jump, during initialization that could disrupt applications.

If phc2sys does not appear to synchronize the system clock after startup, verify that:

• ptp4l has reached the Master state (time properties are only reported after the port transitions to Master).

• pmc -u -b 0 'GET TIME_PROPERTIES_DATA_SET' shows currentUtcOffsetValid 1.

• The utc_offset_valid parameter is set to 1 on the phc2sys instance.

Once these conditions are met, phc2sys begins synchronizing CLOCK_REALTIME and updates the kernel CLOCK_TAI offset.

Prerequisites

• The system is configured as a T-GM with ts2phc and GNSS.

• A valid leap-seconds file is present on the system. For instructions on maintaining the leap-seconds file, see Update Leap Seconds File.

• PTP services are running and the ptp4l port is in the Master state.

• phc2sys is running and healthy (required for kernel leap second insertion).

Configure TAI Offset

To enable automated TAI offset and leap flag management, configure the following on your T-GM system:

1. Ensure that the ts2phc instance has a valid leap-seconds file configured:

   ~(keystone_admin)]$ system ptp-instance-parameter-add <ts2phc-instance> leapfile=/usr/share/zoneinfo/leap-seconds.list
   

2. Configure the phc2sys instance with a manual UTC offset and mark it as valid:

   ~(keystone_admin)]$ system ptp-instance-parameter-add <phc2sys-instance> utc_offset=37
   ~(keystone_admin)]$ system ptp-instance-parameter-add <phc2sys-instance> utc_offset_valid=1
   

3. Apply the configuration:

   ~(keystone_admin)]$ system ptp-instance-apply
   

The utc_offset_valid parameter instructs phc2sys to treat the configured UTC offset as authoritative and set the CLOCK_TAI kernel accordingly. Without this parameter, the kernel TAI offset remains at zero even when utc_offset is configured.

Note

The default leap-seconds file is located at /usr/share/zoneinfo/leap-seconds.list. This file is part of the base OS image. For instructions on updating it when new leap seconds are announced, see Update Leap Seconds File.

Note

StarlingX reads the leap-seconds file when PTP services start. If you deploy an updated leap-seconds file, restart PTP services with system ptp-instance-apply to reload the new data.

Leap Second Lifecycle

The automated leap second handling follows this timeline:

Timing	System action
12 hours before midnight UTC	StarlingX sets leap61=1 (or leap59=1), currentUtcOffsetValid=1, and timeTraceable=1 in PTP Announce messages
At midnight UTC	The kernel inserts (or removes) the leap second; phc2sys suspends clock updates during the transition
6 hours after midnight UTC	StarlingX clears leap flags and updates currentUtcOffset to the new value (e.g., 37 → 38)

Important

phc2sys must be running at midnight UTC for the kernel to apply the leap second. If phc2sys is stopped before the leap event, the kernel considers the clock unsynchronized and does not apply the leap second.

Verify TAI Offset

After configuring a T-GM deployment, verify that the automated TAI offset is working correctly.

1. Confirm that the kernel TAI offset is set:

   ~(keystone_admin)] $ python3 -c "import os, time; \
     tai=os.clock_gettime(os.CLOCK_TAI); utc=time.time(); \
     print(f'TAI - UTC = {int(tai - utc)} seconds')"
   TAI - UTC = 37 seconds
   

2. Verify that currentUtcOffsetValid and timeTraceable are set in PTP:

   ~(keystone_admin)]$ sudo pmc -u -b 0 'GET TIME_PROPERTIES_DATA_SET'
   currentUtcOffset      37
   leap61                0
   leap59                0
   currentUtcOffsetValid 1
   ptpTimescale          1
   timeTraceable         1
   frequencyTraceable    1
   

3. Confirm that the TAI offset appears in phc2sys logs:

   ~(keystone_admin)]$ sudo grep -i "tai offset" /var/log/user.log
   

Verify Leap Second Handling

To confirm that StarlingX correctly handles a leap second event, check the following at each stage of the lifecycle.

Before the leap second (12+ hours prior):

1. Verify that leap flags have been asserted in PTP Announce messages:

   ~(keystone_admin)]$ sudo pmc -u -b 0 'GET TIME_PROPERTIES_DATA_SET'
   currentUtcOffset      37
   leap61                1
   currentUtcOffsetValid 1
   timeTraceable         1
   

2. Confirm that phc2sys has detected the pending leap and configured the kernel to apply it:

   ~(keystone_admin)]$ sudo grep -i "leap" /var/log/user.log
   phc2sys[...]: clock set to insert leap second at midnight (UTC)
   

After the leap second (within 6 hours):

1. Verify that the kernel TAI offset has incremented:

   ~(keystone_admin)]$ python3 -c "import os, time; \
     tai=os.clock_gettime(os.CLOCK_TAI); utc=time.time(); \
     print(f'TAI - UTC = {int(tai - utc)} seconds')"
   TAI - UTC = 38 seconds
   

2. Confirm that phc2sys suspended and resumed clock updates:

   ~(keystone_admin)]$ sudo grep -i "suspend\|leap" /var/log/user.log
   phc2sys[...]: clock set to insert leap second at midnight (UTC)
   phc2sys[...]: clock update suspended due to leap second
   

After flag clearing (6+ hours post-leap):

Verify that flags have been cleared and offset updated:

~(keystone_admin)]$ sudo pmc -u -b 0 'GET TIME_PROPERTIES_DATA_SET'
currentUtcOffset      38
leap61                0
leap59                0
currentUtcOffsetValid 1
timeTraceable         1

currentUtcOffset should reflect the new value (incremented by 1 for a positive leap second, decremented by 1 for a negative leap second).

Note

If the leap second was not applied (TAI offset remains unchanged, no “suspended” log message is present), verify that phc2sys was running continuously through midnight UTC. If phc2sys was stopped or terminated, the kernel does not apply the scheduled leap second.

Manual Override

The automated behavior does not prevent manual intervention. Operators can still use the pmc command to set flags directly if needed:

~(keystone_admin)]$ sudo pmc -u -b 0 -f /etc/linuxptp/ptpinstance/ptp4l-<instance>.conf \
-s /var/run/ptp4l-<instance> \
'SET GRANDMASTER_SETTINGS_NP clockClass 6 clockAccuracy 0x21 offsetScaledLogVariance 0x4e5d \
currentUtcOffset 37 leap61 1 leap59 0 currentUtcOffsetValid 1 ptpTimescale 1 \
timeTraceable 1 frequencyTraceable 1 timeSource 0x20'

Manual overrides are temporary and will be restored to the automated values shortly after the next PTP service polling interval.

Upgrade Considerations

When upgrading from an earlier release:

• Existing T-GM configurations using -O 37 or utc_offset=37 continue to work without changes. To enable the new kernel CLOCK_TAI offset feature, add utc_offset_valid=1 to the phc2sys instance:

  ~(keystone_admin)]$ system ptp-instance-parameter-add <phc2sys-instance> utc_offset_valid=1
  ~(keystone_admin)]$ system ptp-instance-apply
  

  Without this parameter, the system behavior remains unchanged: CLOCK_TAI remains at zero. Leap-second flag automation is enabled regardless of this parameter.

• If you previously used a manual pmc SET GRANDMASTER_SETTINGS_NP cron job or script for leap second handling, it can be removed after upgrade.

• The utc_offset parameter is no longer required in the ptp4l instance configuration for T-GM mode. Existing configurations that explicitly specify this parameter remain supported and are unaffected.

Operational Considerations

• Leap-seconds file maintenance: The leap-seconds file expires semi-annually (June and December). If the file has expired, StarlingX continues to use the last known UTC offset value but does not assert leap flags for future events. Check /var/log/user.log for warnings about an expired leap-seconds file. See Update Leap Seconds File for the update procedure.

• T-BC mode: In T-BC mode, leap second flags propagate automatically from the upstream Grandmaster via PTP Announce messages. No local leap-seconds file configuration is required on T-BC nodes.

• Leap second abolishment: CGPM has resolved to discontinue the use of leap seconds by 2035. Until this transition is complete, the leap-seconds file remains necessary for correct TAI-UTC conversion.