Coarse-tier (USB) DU on a PTP node — the M4/M5 items split out of the PCIe tier

Open
#565 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
8/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
c, cpp, shell

Research direction

This needs a USB DU on a PTP-locked rig, which a newcomer is unlikely to have, so start by reading src/AdapterCaps.h (sync_tier()), src/cell/TsfDiscipline.h (the ledger mode), and the refusal in examples/cell. The selftests tests/cell_m4_selftest.cpp and tests/cell_m5_selftest.cpp show what is simulated today. Done means a measured coarse-tier hold reported as distributions from tests/cell_ptp_multi.sh on real hardware, which is not achievable without the rig.

Written by the indexing model from the issue text.

Description

enhancement

Part of the 5G-NR RAN EPIC #254. Split out of M4 #258 and M5 #259, which close on the PCIe tier. Everything here needs a USB DU on a PTP-locked node, and the rig doesn't have one.

What the rig has run

Only the tight tier: three RTL8852CE cells over PCIe, each beacon grid held to the PTP fabric by src/cell/TsfDiscipline.h in service mode (CELL_REF_PTP). They held 1.8–3.6 µs rms (testrig results/2026-11-04-m4-three-cell-beacon-sync.txt), with loss-of-sync auto-suspend verified (results/2026-11-05-m4-cell-sync.txt). The coarse tier exists in code and selftests only:

  • AdapterCaps::sync_tier() classifies a USB DU as coarse (src/AdapterCaps.h, ctest adapter_caps_derive).
  • TsfDiscipline.h has a ledger mode for the USB TBTT actuator, exercised only by a simulated selftest (tests/cell_m4_selftest.cpp).
  • examples/cell refuses service mode on a DU that isn't tight-sync, so a USB DU can't run as a disciplined cell today.
  • The coarse tier's ~0.5–1.5 ms comes from docs/time-distribution.md, not from a measurement (docs/cell-m4.md: "Not yet measured").
  • The M5 planner gives a coarse DU frequency separation only (tests/cell_m5_selftest.cpp). No coarse DU has run on the rig (docs/cell-m5.md).

Deliverables

  • A USB DU host on the PTP fabric: a host with a PTP-capable i226 link to the n300-1 hub (star, no switch in the timing path), qualified with testrig box_acceptance.sh, and a USB radio whose AdapterCaps passes the cell DU checks. Which USB radio and host is an open decision (#381 gate C asks the same question for ARM).
  • Service mode for the ledger variant in examples/cell, enabled for coarse-tier DUs (it is refused today).
  • tests/cell_ptp_multi.sh (from M4): one PCIe DU and one USB DU on one PTP timebase, with the hold reported per DU as distributions (rms, p95, p99). This measures the coarse tier.
  • The M5 coarse-tier rule on air: a coarse DU next to a tight one gets frequency separation, never a shared channel's time slots. The coordination run (m5_ran_coord.sh) with one USB DU.
  • Loss-of-sync on the coarse tier: the M4 auto-suspend test (stop ptp4l) with the USB DU.

Relationships

  • #381 (ARM cell-node spike), gate C: the same USB-tier discipline, on ARM.
  • M5 #259 keeps its PCIe item, applying channel separation to a running DU at runtime.
Dominant language
C
Stars
56
Forks
29
Avg merge
3h 43m
Merged PRs (30d)
75

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from OpenIPC/devourer

All issues in OpenIPC/devourer

Similar issues

More C issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.