EPIC: 5G-NR-style scheduled RAN on devourer (multi-user + multi-cell)

Aberta
#254 2 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
5/5
Tempo estimado
Mais de uma semana
Facilidade para iniciantes
15/100
Tipo de issue
Funcionalidade
Clareza
Razoavelmente clara
Status de atividade
Ativa
Stack de tecnologia
c
Domínio
networking

Direção de pesquisa

Start with docs/multi-ap-cellular.md and the listed milestone issues, especially M0 (#261), which is a prerequisite for M1 (#255). This epic defines a broad, multi-phase architecture rather than a bounded implementation task; follow the milestone dependency chain to find a concrete starting point. Done means completing the planned milestones and cross-cutting validation, not a single change described here.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

enhancement

Umbrella / tracking issue for building a 5G-NR-style scheduled Radio Access Network on devourer: time-synced AP cells serving multiple scheduled UEs (robots/drones), with per-UE timing advance, coordinated scheduling, and make-before-break handover — riding the bench-proven per-link primitives and modelled on 5G NR design decisions (not LTE).

docs/multi-ap-cellular.md promotes the architecture; this EPIC turns it into a step-by-step build. The per-milestone write-ups are docs/scheduled-mac.md (M0) and docs/cell-m1.md … docs/cell-m6.md. Rig orchestration and results are in the testrig repo (scripts/m*_*.sh, results/).

Status (2026-11-12)

Built and run on the testrig: three Topton J6412 boxes, each with two RTL8852CE (Kestrel) over PCIe/vfio, plus an N300 hub that is PTP grandmaster and CU host (a star of direct i226 links, no switch in the timing path). On the rig:

  • three PTP-locked cells, on three channels, with UEs scheduled in fixed slots;
  • HARQ and link adaptation;
  • RACH join and departure;
  • CU-coordinated schedules and phase planning;
  • measurement gaps;
  • conditional handover, and DAPS on one channel and across channels;
  • per-cell keys;
  • UL and DL sequence handling across handovers.

What remains:

  • the QoS scheduler (M1);
  • runtime channel moves (M5);
  • the coarse/USB tier (#565);
  • M6 follow-ups (#566);
  • a moving-UE bench (#563).

The primitives (this is the multi-user/multi-cell layer)

Bench-proven and library-stable:

  • StartBeacon and UpdateBeaconPayload, a beacon body update measured frame-atomic on air (docs/scheduled-mac.md);
  • PinBeaconTbtt, the absolute TSF-preserving TBTT actuator that closed an AP↔PTP loop to ~0.67 µs on the 8821CE;
  • on TSF-locked-TBTT parts (Kestrel/AX), TSF steps against the free-running counter (#513; TBTT p95 3–4 µs);
  • a deterministic beacon departure, SetBeaconBackoff (#514);
  • TsfSync, WriteTsf/ReadTsfAndFreeRun, Packet::TxEgressTsf;
  • hardware ACK (SetAckResponder, the 8852C responder included), A-MPDU (SetAmpduMode), per-frame TX status (TxReport, where the chip has it; Kestrel does not), per-packet rate/power, GetRxQuality;
  • FastRetune/FastSetBandwidth/SetCcaMode.

5G-NR mapping

5G NR Our realization
gNB (cell) a devourer AP node
CU / DU split DU = AP node (src/cell/ MAC + examples/cell/): per-cell scheduling, HARQ, TA. CU = tools/ran-controller/: multi-cell coordination, mobility, admission
SSB the hardware beacon (StartBeacon)
DCI / grant (PDCCH) beacon-carried grant map {ue, dl_slot, ul_slot, rate, pwr, ta}, with an epoch and its effective superframe (src/cell/GrantMap.h, updated with UpdateBeaconPayload)
Timing advance a per-UE TA loop (TaLoop). The UE's uplink is its hardware beacon, steered through its TSF on Kestrel; PinBeaconTbtt can't hold an offset on TSF-locked parts
Numerology / mini-slots flexible slot lengths + low-latency mini-slots
Bandwidth Part (BWP) narrowband 5/10 MHz via FastSetBandwidth
Dynamic TDD per-cell flexible DL/UL split
QoS flows / 5QI per-UE 5QI class → HARQ budget, DL discard timer, link adaptation, admission priority (src/cell/CellScheduler.h; the fixed grid gives each UE one slot pair, so not slot allocation)
2-step RACH fast contention join (src/cell/Rach.h)
F1 interface DU↔CU UDP control link (src/cell/F1.h, keyed)
Xn interface direct DU↔DU coordination (inter-cell, M5/M6)
TSN / 802.1AS PTP backhaul: each DU holds its beacon grid to its PHC (src/cell/TsfDiscipline.h service mode)
Measurement gaps idle and suspend gaps for inter-frequency measurement (src/cell/MeasGap.h), with phase planning by the CU (src/cell/PhasePlan.h)
CHO an A3 condition at the CU on filtered measurements (offset, hysteresis, time-to-trigger), two-phase command, TSF continuity, conditional fallback (src/cell/Handover.h, HoCommand.h)
DAPS handover UL duplication with CU dedup, DL duplication to the target. Across channels: sequential UE visits to the target's channel, which answers with DL
PDCP SN / status report UL SeqDedup; DL DlStreamRx; the UE's DL status report in its beacon (UeDlStatus), so a target sends only what the UE lacks
Security context (802.11r / NR key derivation) per-cell, area and UE keys from one master; the CU wraps the target cell's key per handover (src/cell/Keys.h)

Architecture boundary (enforced in every milestone)

  • src/cell/ — the per-cell (DU) scheduled-MAC library (reusable):

    • SlotGrid, GrantMap, UeRegistry, UeRxAttribution, Harq, LinkAdapt, Rach (M1–M3);
    • TsfDiscipline, SyncHealth (M4);
    • F1, Coord, PhasePlan (M5);
    • Handover, HoCommand, MeasGap, Keys (M6).

    It adds nothing to the radio core unless a bench test proves userspace can't. (CellScheduler: 5QI classes; TimingAdvance: the per-UE TA loop, held per UE in UeRegistry's UeContext.)

  • examples/cell/ — a reference gNB-DU + UE node.

  • tools/ran-controller/ — the CU / backhaul app (multi-cell scheduler, coordination, CHO/DAPS). Distributed software over the F1 control link (with direct Xn DU↔DU coordination where lower latency helps); never touches the radio. (Note: this is an NR-inspired centralized facility scheduler, not a faithful 3GPP CU — it owns scheduling, not PDCP/RRC.)

Rule: logic that would still make sense with a different radio underneath is NOT in the radio core.

Milestones (coarse; each demoable, implemented step by step)

Phase 0 — feasibility contracts (measure, don't assume):

  • M0 #261 — Feasibility contracts (DL departure jitter, dynamic grant delivery, unicast-ACK/TxReport matrix, per-UE RX attribution) — blocks M1

Phase A — single gNB-DU (one cell, N UEs):

  • M1 #255 — Single-cell scheduled MAC (src/cell/ library + demo)
  • M2 #256 — Reliability & link adaptation (per-UE ACK, HARQ, rate/power)
  • M3 #257 — Admission: 2-step RACH and departure (association descoped)

Phase B — multi-cell RAN (CU + mobility):

  • M4 #258 — Network-wide time sync across cells (TSN/802.1AS-style) — closed on the PCIe tier
  • M5 #259 — CU + coordinated scheduling — closed on the PCIe tier; runtime channel moves in #567
  • M6 #260 — Mobility: CHO + DAPS handover
  • M6 test realism #563 — Moving-UE handover bench: a conducted path-loss matrix (UL and DL follow a trajectory, fading, several UEs), then an over-the-air walk
  • #565 — Coarse-tier (USB) DU on a PTP node (split out of M4/M5)
  • #566 — Follow-ups left open by M6 (EVM, roam baseline, the named test, residuals)

Dependency chain: M0 → M1; M1 → M2, M3, M4; M4 → M5 → M6 → #563 (test realism).

Cross-cutting deliverables (from the architecture review)

  • Slot-budget accounting — a valid slot = PSDU airtime + PHY preamble + SIFS/ACK + retry allowance + A-MPDU duration + radio turnaround + retune/settling + timing guard. Payload size alone is not a budget. Done in src/cell/SlotGrid.h (A-MPDU airtime not modelled); a DL frame that would start past its slot's guard is not aired.
  • A versioned on-air protocol envelope — protocol version, cell+UE identity, superframe/slot number, schedule epoch, packet/HARQ sequence, integrity + replay protection. Done: kCellProtoVersion (v5), cell-key tags on every cell frame, area tags for neighbours, replay floors. Integrity is on only with a key configured.
  • Fault detection — watchdogs for lost PTP sync, stalled beacon engine, missed schedule epochs, CU/backhaul outage, excessive TX-queue delay, over-budget retunes. Partly done:
    • loss of PTP sync (SyncHealth, auto-suspend), CU outage (DUs go autonomous), stale or late schedules (acks), and late DL frames are handled;
    • a stalled beacon engine is detected only indirectly, through the UEs' uplinks, and there is no general over-budget-retune alarm.
  • KPI-based validation — report distributions not averages: deadline-miss ratio, slot-arrival phase, collision rate, handover interruption, DAPS duplicate gain, per-UE fairness, clock holdover, control-plane update latency. Mostly done in the docs/cell-m*.md tables; still missing: per-UE fairness, a stated DAPS duplicate gain and clock holdover.

Out of scope / relationships

  • OFDMA / UL-MU / MU-MIMO (5G air interface) = Kestrel 11ax, #236. OUT. UL is TDMA-only throughout; numerology/BWP are time/bandwidth analogs, not real SCS.
  • #214 (J3 PCIe) = optional tighter TBTT actuator for a production cell.
  • #235 (SDIO) = the FPV-transport path.
  • #381 (ARM cell-node spike) — its USB-tier gate is the same question as #565.
  • #457 (multi-receiver ground station: N radios / N channels / one timebase) — the many-transmitters-into-one-site side of the same problem.
    • It shares M4's single PTP timebase (its "N nodes over Ethernet" shape is the testrig fleet) and M5's per-channel planning.
    • It extends M0's per-UE RX attribution from 2 transmitters to 10–25.
    • #563's attenuator matrix would serve it too.

Standing risk register (status 2026-11-12)

  • Deterministic downlink (M0/M1, headline): retired. Kestrel's DL departure was measured in M0, and in M1 the DL air start was p50/p99 31/41 µs after its slot start. A rare multi-ms send_packet tail remains, so a RACH slot is kept away from the next beacon.
  • No atomic beacon update (M0/M1): retired. UpdateBeaconPayload exists on every family and is frame-atomic on air (not atomic against the TBTT; it airs on the next or next-but-one TBTT). The grant map rides the beacon with an epoch and its effective superframe.
  • Unicast ACK per node, not multi-MACID (M0/M2): retired. One responder per node; the 8852CE responder measured 1036/1036. Kestrel has no per-frame TxReport, so HARQ runs on explicit UE feedback.
  • GetRxQuality is device-wide: addressed differently. UeRxAttribution exists, but link adaptation uses the SNR the UE reports for the downlink.
  • send_packet UL has no sub-slot air-departure control: followed. The UL is the UE's hardware beacon, steered through its TSF: 1.4–1.8 µs rms.
  • ~ms FastRetune: measured, 23.6 ms on the 8852CE. Different-channel DAPS is sequential (visits), with measurement gaps budgeted at 26 + 2 ms.
  • Timing advance corrects clock/actuation phase, not propagation: as designed.
  • PCIe vs USB sync tiers: the tight tier is done, with loss-of-sync auto-suspend; the coarse tier is unmeasured (#565).
  • A3/CHO tuning: hysteresis and time-to-trigger on filtered quality. In the selftest the filtered A3 made one handover per crossing (raw RSSI: 30.6); on the rig, 0 in the hover case. Fading is still untested (#563).
  • Half-duplex UE turnaround: budgeted in the grid (turnaround_us).

Architecture review folded in: this epic and its milestones were revised per an external review — M0 added, terminology corrected (F1/Xn), the multi-MACID framing corrected, M1 numerology restricted to fixed, and cross-cutting deliverables added. Refreshed 2026-11-12 against what was built.

Linguagem predominante
C
Estrelas
56
Forks
29
Merge médio
3h 43min
PRs com merge (30d)
75

Preparar o ambiente

Este projeto não oferece contêiner de desenvolvimento, Dockerfile nem guia de contribuição, então a configuração fica por sua conta: comece pelo README e veja nosso guia da primeira contribuição para os passos gerais.

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de OpenIPC/devourer

Todas as issues de OpenIPC/devourer

Issues semelhantes

Mais issues de C

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.