linuxptp4avb

A Debian package that wraps the upstream linuxptp package with a ready-to-run IEEE 802.1AS gPTP profile: a gptp.service systemd unit running ptp4l, the gPTP-AVB.cfg ptp4l configuration, and an /etc/default/gptp EnvironmentFile so the interface and step threshold are configurable per host.

Decoupled clock design (important). ptp4l disciplines only the NIC PHC (/dev/ptp0) to the local gPTP grandmaster — the AVB network switch — which is the AVTP media timebase. It does not touch CLOCK_REALTIME, and this package ships no phc2sys. CLOCK_REALTIME is owned solely by chrony (a package dependency), locked to the site GPS (e.g. a TimeMachines TM2000B) via the local NTP server. The PHC (gPTP, switch epoch) and CLOCK_REALTIME (GPS/UTC epoch) are intentionally kept independent — the correct behaviour when locking to a local gPTP grandmaster whose epoch is not UTC. See the umbrella docs/MEDIA_CLOCK_TIMING.md and avb/docs/GPS_MEDIA_CLOCK.md.

Portions of this repository were developed with assistance from Claude, an AI model by Anthropic. The underlying ptp4l binary is upstream linuxptp under its own license; this repository contains my own Debian packaging and IEEE 802.1AS gPTP profile around it, with Claude assisting in refactoring and in validating the profile against 802.1AS. All architectural decisions, final implementations, and engineering judgments are my own, and any errors are mine alone.

What it ships

Path	Type	Notes
/usr/lib/systemd/system/gptp.service	systemd unit	Runs ptp4l -f /etc/linuxptp/gPTP-AVB.cfg -i $PTP_INTERFACE. Type=simple, restarts on failure. Enabled+started on install.
/etc/linuxptp/gPTP-AVB.cfg	conffile	802.1AS ptp4l profile. Disciplines only the PHC, never CLOCK_REALTIME. Named to avoid confusion with linuxptp's own example gPTP.cfg under /usr/share/doc.
/etc/default/gptp	conffile	PTP_INTERFACE, STEP_THRESHOLD

There is no phc2sys-gptp.service — it was removed in 0.3.0. The package's postinst actively stops/disables any leftover phc2sys-gptp.service from versions ≤ 0.2.0 so it can't fight chrony for CLOCK_REALTIME.

Depends: linuxptp (the ptp4l binary) and chrony (disciplines CLOCK_REALTIME from GPS).

Install

On a Debian Trixie (or compatible) host:

sudo apt install ./deb-output/linuxptp4avb_0.4.0_all.deb

This automatically:

• pulls in linuxptp and chrony as dependencies,
• enables and starts gptp.service.

The result: ptp4l locks the PHC to the gPTP grandmaster on the network (the AVB switch); chrony — configured separately — locks CLOCK_REALTIME to GPS. The two clocks stay decoupled; the AVB audio entity reconciles them (gPTP timestamps, GPS-derived media frequency). See docs/MEDIA_CLOCK_TIMING.md for the chrony and entity side.

Migration

• From a hand-installed /etc/systemd/system/ptp4l.service: remove it first so two units don't race to drive ptp4l on the same interface:

  sudo systemctl disable --now ptp4l
  sudo rm /etc/systemd/system/ptp4l.service
  

• From ≤ 0.2.0 (which shipped phc2sys-gptp.service): nothing to do — the postinst stops and disables it for you.

• Config file rename (0.3.x → 0.4.0): the profile moved from /etc/linuxptp/gPTP.cfg to /etc/linuxptp/gPTP-AVB.cfg. The old conffile is removed on upgrade (dpkg-maintscript-helper rm_conffile); if you had local edits, dpkg preserves the old file as *.dpkg-bak — re-apply them to the new file.

Configure

Edit /etc/default/gptp to change the interface (default eth0) or step threshold (default 1.0 second):

PTP_INTERFACE=end0
STEP_THRESHOLD=1.0

Then restart the service:

sudo systemctl restart gptp

/etc/default/gptp and /etc/linuxptp/gPTP-AVB.cfg are both dpkg conffiles, so your edits survive upgrades (you'll be prompted on conflict).

Do not add phc2sys to discipline CLOCK_REALTIME from this PHC — that re-couples the clocks and silently defeats the GPS-frequency media clock. Let chrony own CLOCK_REALTIME.

Build

On Debian/Ubuntu with build-essential debhelper devscripts lintian installed:

./build.sh

The .deb lands in deb-output/.

If you're not on a Debian host, do the build inside a throwaway Trixie container:

podman run --rm -it -v "$PWD:/work" -w /work debian:trixie bash -c '
    apt-get update -qq &&
    apt-get install -y -qq build-essential debhelper devscripts lintian &&
    ./build.sh'

License

GPL-2.0-or-later (matches linuxptp upstream). See LICENSE.