gPTP driver

jumpstarter-driver-gptp provides IEEE 802.1AS-2020 (gPTP) and IEEE 1588-2019 (PTPv2.1) time synchronization for Jumpstarter. It manages the linuxptp stack (ptp4l and phc2sys) as supervised subprocesses, enabling precise clock synchronization between an exporter host and a target device over automotive Ethernet or standard IP networks. Parameter ranges and defaults follow the respective standards.

gPTP is the foundation of Time-Sensitive Networking (TSN), required for applications like sensor fusion, ADAS, and synchronized diagnostics in automotive ECU testing.

Installation

$ pip3 install --extra-index-url https://pkg.jumpstarter.dev/simple jumpstarter-driver-gptp

System requirements (on the exporter host):

# Debian/Ubuntu
$ sudo apt install linuxptp ethtool

# Fedora/RHEL
$ sudo dnf install linuxptp ethtool

Configuration

gPTP Slave (802.1AS, automotive Ethernet)

The most common automotive scenario — synchronize to an external grandmaster:

export:
  gptp:
    type: jumpstarter_driver_gptp.driver.Gptp
    config:
      interface: eth0
      domain: 0
      profile: gptp
      transport: L2
      role: slave
      sync_system_clock: true

IEEE 1588 UDP mode

For networks that use standard PTPv2 over UDP:

export:
  ptp:
    type: jumpstarter_driver_gptp.driver.Gptp
    config:
      interface: eth0
      domain: 0
      profile: default
      transport: UDPv4
      role: auto

gPTP Grandmaster

Prefer this host as the PTP grandmaster. role: master sets masterOnly in the generated ptp4l config so BMCA will not select a peer as master:

export:
  gptp:
    type: jumpstarter_driver_gptp.driver.Gptp
    config:
      interface: eth0
      profile: gptp
      role: master
      sync_system_clock: false

Combined with SOME/IP

gPTP provides the time base for other automotive Ethernet protocols:

export:
  gptp:
    type: jumpstarter_driver_gptp.driver.Gptp
    config:
      interface: eth0
      profile: gptp
      role: auto
  someip:
    type: jumpstarter_driver_someip.driver.SomeIp
    config:
      host: 192.168.1.100

Config parameters

Parameter

Description

Type

Required

Default

Standard ref

interface

Network interface for PTP (e.g. eth0, enp3s0)

str

yes

domain

PTP domain number (0-127)

int

no

0

IEEE 1588-2019 §7.1

profile

"gptp" (802.1AS-2020) or "default" (1588-2019)

str

no

"gptp"

transport

"L2", "UDPv4", or "UDPv6"

str

no

"L2"

role

"master", "slave", or "auto" (BMCA election)

str

no

"auto"

sync_system_clock

Run phc2sys to sync CLOCK_REALTIME to PHC

bool

no

true

ptp4l_extra_args

Additional ptp4l command-line arguments

list[str]

no

[]

PTP Standards Reference

This driver targets IEEE 802.1AS-2020 (gPTP) and IEEE 1588-2019 (PTPv2.1) via the linuxptp reference implementation. All parameter ranges and defaults are validated according to these editions.

IEEE 802.1AS-2020 (gPTP) vs IEEE 1588-2019 (PTPv2.1)

Feature

802.1AS-2020 (gPTP)

IEEE 1588-2019 (PTPv2.1)

Transport

Layer 2 only

L2, UDPv4, UDPv6

Domain

Always 0

0-127 (§7.1)

Timestamping

Hardware required

HW or software

Priority1 range

0-255 (§7.6.2.2)

0-255 (§7.6.2.2)

Accuracy

Sub-microsecond

Sub-microsecond to ms

Use case

Automotive, industrial TSN

General purpose

Profile setting

profile: gptp

profile: default

Port State Machine

PTP ports transition through these states:

INITIALIZING → LISTENING → SLAVE (synchronized to master)
                         → MASTER (elected as grandmaster)
                         → PASSIVE (backup, not active)
                         → FAULTY (error detected)

Servo States

The clock servo tracks synchronization quality:

  • s0 (unlocked): Initial state, no sync

  • s1 (calibrating): Frequency adjustment in progress

  • s2 (locked): Fully synchronized, offset stable

API Reference

GptpClient

class jumpstarter_driver_gptp.client.GptpClient

Client interface for gPTP/PTP time synchronization.

Provides methods to manage PTP synchronization lifecycle, query status, monitor sync events, and configure clock priority for BMCA master election.

Exceptions raised by the exporter-side driver are transported over gRPC and surface on the client as DriverError (and related client exceptions), not as the original RuntimeError / NotImplementedError.

get_offset() → GptpOffset

Get the current clock offset from master.

Returns:

Offset measurement including path delay and frequency.

Raises:

DriverError: If ptp4l is not started (or another driver error).

get_port_stats() → GptpPortStats

Get PTP port statistics.

Returns:

Port statistics counters.

Raises:

DriverError: If ptp4l is not started (or another driver error).

is_synchronized() → bool

Check whether PTP is synchronized.

Returns True when this clock is MASTER, or SLAVE with servo locked.

Returns:

True if synchronized.

Raises:

DriverError: If ptp4l is not started (or another driver error).

monitor() → Generator[GptpSyncEvent, None, None]

Stream PTP sync status updates.

Yields GptpSyncEvent objects with current offset, delay, and state.

Yields:

Sync event updates.

start() → None

Start PTP synchronization on the exporter host.

Spawns ptp4l (and optionally phc2sys) as managed subprocesses.

Raises:

DriverError: If ptp4l is already running (or another driver error).

status() → GptpStatus

Query the current PTP synchronization status.

Returns:

Current synchronization status including port state, offset, delay, and servo state.

Raises:

DriverError: If ptp4l is not started (or another driver error).

stop() → None

Stop PTP synchronization.

Terminates ptp4l and phc2sys processes and cleans up temp files.

Raises:

DriverError: If ptp4l is not started (or another driver error).

wait_for_sync(timeout: float = 30.0, poll_interval: float = 1.0, threshold_ns: float | None = None) → bool

Block until PTP synchronization is achieved or timeout expires.

Only catches DriverError / RuntimeError (driver not-yet-ready) during polling. Transport or unexpected failures propagate immediately.

Args:

timeout: Maximum time to wait in seconds. poll_interval: Polling interval in seconds. threshold_ns: Optional offset threshold in nanoseconds.

Returns:

True if synchronized before timeout, False otherwise.

Note

get_clock_identity(), get_parent_info(), and set_priority1() are available on the MockGptp driver for testing. On the real Gptp driver they raise NotImplementedError until ptp4l UDS management socket integration is added.

Examples

Basic lifecycle

from jumpstarter.common.utils import env

with env() as client:
    gptp = client.gptp

    gptp.start()

    # Wait for synchronization (up to 30 seconds)
    if gptp.wait_for_sync(timeout=30.0):
        offset = gptp.get_offset()
        print(f"Synchronized! Offset: {offset.offset_from_master_ns:.0f} ns")
    else:
        print("Sync timeout")

    gptp.stop()

Monitoring sync events

from jumpstarter.common.utils import env

with env() as client:
    gptp = client.gptp

    gptp.start()
    for event in gptp.monitor():
        print(f"[{event.event_type}] offset={event.offset_ns:.0f}ns state={event.port_state}")
        if event.event_type == "fault":
            break
    gptp.stop()

Using MockGptp in tests

from jumpstarter_driver_gptp.driver import MockGptp
from jumpstarter.common.utils import serve

def test_my_application():
    with serve(MockGptp()) as gptp:
        gptp.start()
        assert gptp.is_synchronized()
        assert abs(gptp.get_offset().offset_from_master_ns) < 1000
        gptp.stop()

CLI Commands

When used inside jmp shell, the driver provides these commands:

j gptp start              # Start PTP synchronization
j gptp stop               # Stop PTP synchronization
j gptp status             # Show sync status
j gptp offset             # Show current clock offset
j gptp monitor -n 20      # Monitor 20 sync events
j gptp set-priority 0     # Force grandmaster role

Hardware Requirements

PTP-capable NICs

For sub-microsecond accuracy, the network interface must support hardware timestamping. Common PTP-capable NICs:

  • Intel i210, i225, i226 (automotive-grade variants available)

  • Intel X710, XL710, E810

  • Broadcom BCM5719, BCM5720

  • TI AM65x / Jacinto 7 (embedded automotive)

  • NXP S32G (automotive gateway)

Verifying hardware timestamping

$ ethtool -T eth0
# Look for:
#   hardware-transmit
#   hardware-receive
#   hardware-raw-clock

If hardware timestamping is not available, the driver automatically falls back to software timestamping (-S flag) with a warning. Software timestamping provides millisecond-level accuracy, sufficient for development but not for production TSN.

Troubleshooting

Permission denied

ptp4l requires CAP_NET_RAW (or root) for Layer 2 transport and hardware timestamping:

$ sudo setcap cap_net_raw+ep $(which ptp4l)
# or run the exporter as root

No hardware timestamping

If you see “falling back to software timestamping”:

  1. Check NIC support: ethtool -T <interface>

  2. Verify the NIC driver is loaded: lsmod | grep <driver>

  3. Some virtualized NICs (virtio, veth) only support software timestamping

ptp4l not found

Ensure linuxptp is installed:

$ which ptp4l
/usr/sbin/ptp4l

No sync achieved

  • Verify the link partner (DUT) is running a gPTP stack

  • Check physical layer: ethtool <interface> should show link up

  • Review ptp4l logs in the exporter output

  • Ensure both ends use the same domain number and transport