M4 — Network-wide time sync across cells (TSN/802.1AS-style)

[josephnef]

Part of the 5G-NR RAN EPIC #254. Phase B, first multi-cell capability.

Goal: every DU holds its beacon grid to one wired PTP grandmaster, so a slot boundary is the same instant network-wide — the prerequisite for coordinated scheduling (M5) and clock-continuous handover (M6).

5G mapping

TSN / 802.1AS fronthaul time sync. The PinBeaconTbtt discipline loop that already closed to ~0.67 µs on the 8821CE, generalized to a DU service mode.

Deliverables (into examples/cell)

• promote tests/pcie_ptp_beacon.cpp (PinBeaconTbtt + anti-windup PI, reads the I226 PHC via FD_TO_CLOCKID, running ref=a*tsf+b fit) into an examples/cell DU service mode.
• a steering-ledger variant for the USB TBTT actuator (looser than PCIe) — see docs/time-distribution.md.
• two formal sync tiers (from the architecture review), surfaced via AdapterCaps: tight-sync DU (PCIe/MMIO, ~µs hold — eligible for same-channel coordinated slots in M5) vs coarse-sync DU (USB, ~0.5–1.5 ms disturbance — requires ms guards or frequency separation). M5's coordinator reads the tier.
• loss-of-sync detection — each DU detects PTP loss / stalled beacon engine and auto-suspends its coordinated schedule (falls back to autonomous), so a desynced cell can't collide network-wide.

Reuses

The discipline loop (tests/pcie_ptp_beacon.cpp), PinBeaconTbtt, ReadTsf, AdapterCaps.hw_beacon_txtsf, SetCcaMode.

Dependencies

M1 (#254 tracks). Independent of M2/M3.

Test — tests/cell_ptp_multi.sh

Two DUs on one PTP domain: the Radxa 8821CE (PCIe, ~µs hold) + this host's USB DU (enp12s0 also carries a PHC; same LAN). Both beacons' TBTT track the same PHC — PCIe ~µs, USB looser (~0.5–1 ms actuator). Report per-DU RMS hold.

Note

A J3 PCIe part (#214) would tighten a production cell's actuator further; not required for this milestone.