[josephnef]

M6 (#260, EPIC #254): a UE re-attaches to its DU after the DU restarts. This closes the open item from #535.

Why

#535 made the UE's clock follow a restarted DU. But the restarted DU's grant maps begin again at a low epoch on a new superframe count, and the UE's GrantMapReceiver refused them as old. The UE kept its old map and was never heard in the new grid (0 uplinks on the rig).

What

• GrantMapReceiver::offer_after_restart(m, beacon_sf, window = 16): a map at a strictly lower epoch than the newest accepted, but due within 16 superframes of the beacon carrying it, starts the receiver over.
  • A stale map from before the restart is due far from the new count and is still refused.
  • The same epoch again is the live map repeated, which is not a restart. A first rig run found this case.
  • Also adds a newest_epoch() getter.
• UE:
  • the restart path is asked only for CELL_UE_REATTACH_SF (200) superframes after the UE's clock fit confirms a step of the DU's TSF (cell M6: the UE's clock fit survives a jump of its DU's TSF (TsfSync step detection) #535);
  • on a re-attach it resets what belonged to the old DU instance, as a handover switch does: DL HARQ space, MR generation (the DU checks it against its new count), neighbour list, gap parking, and pending handover IEs;
  • it logs cell.ue.reattach.
• Logging fix: the UE's cell.dl.rx in_slot now judges against the DL slot of its grant in force, not the position matching its id. Any CU move showed as DL out of slot (0.05), although the frames were right.
• Docs: docs/cell-m6.md gains a "Re-attachment after a DU restart" section and a fix for the doubled DAPS heading left by cell M6: the UE's clock fit survives a jump of its DU's TSF (TsfSync step detection) #535. RACH-joined UEs across a DU restart are listed as open.
• Selftest (cell_m6): refused when not near the beacon's count, a pre-restart stale map, another cell's map, accepted and then running on, never back to a higher epoch, and the live map repeated.

Rig (testrig scripts/m6_fitstep.sh: DU1 killed and restarted under its UE, 3/3 pass)

KPI	value
re-attachments per run	1 (old epoch 7–11 → epoch 1)
uplink heard by the restarted DU, from 10 sf after its service start	99.8–100 % of superframes
of them in slot	99.8 %
first in-slot uplink after service start	superframe 0
UE DL in its granted slot after the re-attach	100 %

• Detection off (counterfactual): no re-attach, and the restarted DU never hears the UE.
• Regression: same-channel handover 2/2 plus fallback 1/1, measurement-gap handover 1/1, phase planning 1/1, transient TSF jump 3/3. No spurious re-attach in any of them.

Residual: grant maps carry no tag (they never did), so the epoch rule orders maps; it doesn't authenticate them.

🤖 Generated with Claude Code

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Re-attach static UEs after a DU restart

🐞 Bug fix 🧪 Tests 📝 Documentation 🕐 20-40 Minutes

AI Description

• Re-attach static UEs to restarted DUs whose grant-map epochs begin again.
• Clear state tied to the old DU instance and correct DL slot logging after grant moves.
• Test restart-map acceptance and document rig results and remaining RACH limitations.

Diagram

graph TD
  DU["DU beacon"] --> FIT["Clock fit"] --> RX["Grant receiver"] --> GATE{"Restart eligible?"}
  GATE -->|yes| RESET["Reset grant state"] --> CLEAN["Clear UE state"]
  GATE -->|no| KEEP["Keep existing state"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Add a DU instance identifier to grant maps

• ➕ Distinguishes a new DU instance from old maps without relying on epoch and timing proximity.
• ➖ Requires a grant-map protocol change and coordinated DU and UE deployment.
• ➖ An instance identifier alone would not authenticate a map.

Recommendation: Use the proposed clock-step-gated epoch rule for the current static-UE scope: it restores service without changing the wire format and limits when old epochs can be accepted. Consider an explicit DU instance identifier if restart recovery must extend beyond this timing assumption; RACH-joined UEs still need a separate re-join path.

Files changed (4) +163 / -10

Bug fix (2) +73 / -3

main.cppGate UE re-attachment on confirmed DU clock steps +55/-3

Gate UE re-attachment on confirmed DU clock steps

• Adds a configurable 200-superframe re-attachment period after a confirmed clock step. On an accepted restart map, clears state belonging to the old DU instance and emits a re-attachment event. DL receive logging now judges slot placement against the grant in force rather than the UE-id position.

examples/cell/main.cpp

GrantMap.hAllow eligible lower-epoch maps after a restart +18/-0

Allow eligible lower-epoch maps after a restart

• Adds a newest-epoch getter and a restart-specific offer method. It rebinds the receiver only for a same-cell map with a strictly lower epoch whose effective superframe is within the beacon-relative window.

src/cell/GrantMap.h

Tests (1) +34 / -0

cell_m6_selftest.cppExercise restart-map acceptance and rejection +34/-0

Exercise restart-map acceptance and rejection

• Tests rejection of distant, stale, other-cell, equal-epoch, and higher-epoch maps through the restart path. Verifies that a nearby lower-epoch map starts a new receiver epoch and subsequent normal maps advance.

tests/cell_m6_selftest.cpp

Documentation (1) +56 / -7

cell-m6.mdDocument restart re-attachment and rig results +56/-7

Document restart re-attachment and rig results

• Explains the lower-epoch acceptance rule, its clock-step gate, reset behavior, and lack of map authentication. Records rig outcomes, identifies RACH-joined UE recovery as open, and fixes a duplicated DAPS heading.

docs/cell-m6.md

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Forged maps can reset a UE's grant state ✓ Resolved

Description

GrantMapReceiver::offer_after_restart accepts any map whose epoch is strictly lower than the
newest accepted, provided its effective_sf falls within 16 superframes of the beacon's superframe,
and then calls rebind and offer, which discards the current grant state. Grant maps carry no tag
or other integrity field, so nothing authenticates the map or binds it to the DU that sent it, and a
replayed or crafted map can pass this check during the 200-superframe re-attach window after a clock
step. The PR description acknowledges this as a residual, but the new path widens what an
unauthenticated map can do by letting it overwrite the UE's existing grant state.

---

2. Gaps and clock fixes stall after restart ✓ Resolved

Description

The reattachment reset clears gap_parked but leaves next_gap_sf and no_step_until_sf expressed
in the old DU's local superframe count. When the restarted DU's count drops, measurement gaps wait
for the old deadline, and a recent gap can suppress needed TSF corrections until the new count
catches up.

---

3. Restart can delay handover fallback ✓ Resolved

Description

The reattachment reset leaves ho_back and its old target-superframe deadline intact even though it
replaces the target's grant-map state. If a handover is still awaiting a target grant when that
target restarts without the staged UE, the fallback check waits for the restarted DU to reach the
old deadline before returning to the source.

---

View review recommended (1)

4. Some received downlinks lose their log ✓ Resolved

Description

The new cell.dl.rx slot lookup leaves want unset when no grant map is current or that map lacks
the UE, so the existing if (!want) return skips the event after HARQ processing. A valid downlink
received before its first grant map, or while absent from the map in force, is therefore omitted
from reception logs rather than recorded as out of slot.

---

Tip of the day

💡 Did you know, you can switch off images and animations for a plain-text comment

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[josephnef]

Qodo review addressed in d40aed3:

1. Forged maps can reset grant state (requirement gap): grant maps have never carried a tag, so a forged map could already redirect a UE's slots. The restart path is additionally gated by a confirmed step of the DU's clock (6 agreeing beacons, cell M6: the UE's clock fit survives a jump of its DU's TSF (TsfSync step detection) #535) and limited to the re-attach window. Authenticating the grant map IE (a per-cell tag, as the NL/MR/HO IEs have) is a wire change for DU, UE and witness. It is out of scope here: the exposure is now stated in docs/cell-m6.md next to the rule, and grant-map authentication is listed as an open item.
2. Gap and step deadlines on the old count: next_gap_sf and no_step_until_sf return to their sentinels on a re-attach.
3. Handover fallback delayed by a target restart: with ho_back active, the way back is kept and its deadline is re-based on the restarted target's count.
4. Ungranted DL not logged: cell.dl.rx is emitted without a grant in force too (in_slot 0, new field granted 0).

ctest 95/95. Rig re-run (m6_fitstep.sh, restart + transient + detection-off): passes; one re-attach, uplink 99.8 % heard and in slot from service start, DL 100 % in its granted slot.

[josephnef]

CI green; all four Qodo findings resolved. The remaining item is the high-level alternative (a DU instance identifier in grant maps), for which Qodo's own recommendation is the clock-step-gated epoch rule used here for the static-UE scope, without a wire change. Map authentication and RACH re-join are listed as open in docs/cell-m6.md. Merging with skip-qodo-gate.