M1 — Single-cell scheduled MAC (src/cell/ DU library + examples/cell node)

[josephnef]

Part of the 5G-NR RAN EPIC #254. Phase A, first demoable capability.

Goal: one gNB-DU serves N UEs on a shared, TSF-locked fixed-grid slot grid — per-UE registry, a QoS scheduler that emits a grant map (DCI-style), collision-free scheduled DL (within the M0-measured guard), and scheduled UL with per-UE timing advance.

Restricted numerology (from the architecture review)

M1 deliberately uses a fixed grid — variable-length slots and mini-slots follow once M0 has measured real airtime/scheduling distributions:

• fixed superframe; fixed beacon/TBTT period in integer TU;
• one periodic uplink opportunity per UE;
• an explicit DL→UL turnaround guard;
• no channel or bandwidth switching inside M1.

5G mapping

• gNB-DU = the AP node; SSB = the hardware beacon; DCI/PDCCH = the grant map {ue, dl_slot, ul_slot, rate, pwr, ta} (delivery mechanism decided in M0 — likely a slow static beacon grant + scheduled unicast deltas, since there is no atomic beacon-update API); timing advance = the per-UE UL phase loop (corrects clock/actuation phase, not propagation — indoor propagation is ns).

Deliverables (the reusable DU MAC library src/cell/)

• UeRegistry — per-MACID state: assoc, timing advance, and a per-UE RX-quality window built from M0's per-frame attribution (NOT device-wide GetRxQuality, which is a draining accumulator).
• GrantMap — DCI-style IE build/decode (headless round-trip selftest); delivery per the M0 decision.
• SlotGrid — fixed-grid slot phase math on the disciplined TSF (generalize examples/tdma/tdma.h Schedule/at() + the TD tag). Full slot-budget accounting (PSDU + preamble + SIFS/ACK + retry + turnaround + guard), not payload size alone.
• scheduled DL loop — per-UE slot, per-packet rate/power via RadiotapBuilder.h, respecting the M0-measured DL departure guard.
• scheduled UL + per-UE TA — generalize the single-UE loop in examples/timesync/main.cpp (master_ta_cb) to per-MACID; UE uplink = HW-beacon steered by PinBeaconTbtt.
• CellScheduler — 5QI-style QoS classes producing the grant map.
• examples/cell/ — reference gNB-DU + UE node (generalizes examples/timesync/ + examples/tdma/).

Reuses

PinBeaconTbtt, StartBeacon, ReadTsf, examples/tdma/tdma.h, examples/timesync/, RadiotapBuilder.h.

Risks (from EPIC)

• send_packet UL has no sub-slot air-departure control → UL must ride the HW-beacon-steered path, not naive send_packet.
• Half-duplex UE turnaround bounds adjacent DL-RX / UL-TX mini-slot sizing.
• ~ms FastRetune ⇒ slots ≫ retune time if a slot ever changes channel.

Dependencies

M0 (#261) — the four feasibility contracts (DL guard, grant delivery, unicast-ACK matrix, per-UE attribution) gate this milestone's design.

Test — tests/cell_2ue.sh

2 USB stations under the Radxa 8821CE DU; each gets its DL+UL slot; each station's arrival-TSF-mod-period lands in-slot, zero collisions. Reuse timesync_ta_analyze.py for arrival-phase RMS. Plus a headless selftest: GrantMap round-trip + SlotGrid phase math, in the CMake selftests aggregate.