Skip to content

cell M6: handover execution — two-phase command, TSF continuity, conditional fallback - #530

Merged
josephnef merged 2 commits into
masterfrom
feat/m6-ho-exec
Nov 5, 2026
Merged

josephnef merged 2 commits into
masterfrom
feat/m6-ho-exec

Conversation

@josephnef

Copy link
Copy Markdown
Collaborator

Part of M6 (#260), epic #254. Step 2b: handover execution on top of #528 (observe-only A3) and #529 (command and IE). Full write-up in docs/cell-m6.md.

  • CU (RAN_HO_EXECUTE=1):
    • an A3 candidate becomes a HoCommand: the target's free id and position, the switch instant and the TSF delta;
    • two-phase: sent to the target first, to the source on the target's ack, and a cancel goes to the target if the source refuses;
    • ran.ho_done when the target reports the UE.
  • Target DU: pre-admits the UE under the commanded id and publishes its grant for the switch instant.
  • Source DU: airs the tagged IE until the switch, then releases the UE only if it stopped uplinking there; otherwise it keeps it.
  • UE: at the instant it shifts its clock (TsfSync::ShiftRemote, new, selftested), takes its target identity and runs the target's buffered map. Conditional: with no target grant within 10 superframes it returns to the source.
  • Fix: a DU with no UE now paces its main loop. Its superframe count, and so its reported network superframe, used to run away.

Rig (two PTP cells; the crossing is forced with RAN_A3_OFFSET_DB=-2, as the UEs are stationary):

normal target DU killed right after staging
switch source sf 143 → target sf 137 (= the target's effective sf) source sf 172
target hears the UE in slot from the first superframe after: 1115/1117 —
outcome committed; source released at +21; ran.ho_done +5 UE fell back at +10; source kept it, 1092/1092 in slot

ctest 92/92. Not yet: DAPS (duplicated uplink plus SeqDedup), an emulated moving crossing, and different-channel handover.

🤖 Generated with Claude Code

… source relay, UE switch with TSF continuity and fallback

tools/ran-controller (RAN_HO_EXECUTE=1):
- an A3 candidate becomes a HoCommand: the target's lowest free id and
  first free position, a RAN_HO_LEAD_SF lead, and the TSF delta from the
  DUs' reports;
- two-phase: the target first, the source on the target's ack, and a cancel
  to the target if the source refuses;
- ran.ho_done when the target reports the UE; the old key is retired and
  the moved UE gets its dwell.

examples/cell:
- target DU: pre-admits the UE under the commanded id and publishes its
  grant for the switch instant; handles a cancel.
- source DU: airs the tagged HoIe until the switch, then releases the UE
  only if it stopped uplinking there; otherwise kept (make-before-break).
- UE: accepts the newest fresh IE (HoReceiver) and buffers the target's
  grant maps. At the instant it shifts its clock (TsfSync::ShiftRemote,
  new), takes the target identity and runs the target's map. With no
  target grant within CELL_HO_FALLBACK_SF it returns to the source.
- fix: a DU with no UE now paces its main loop to its superframe (its sf,
  and so its reported network superframe, ran away).
- build_du_beacon takes extra IEs.

Rig (testrig m5_ran_coord.sh, forced with RAN_A3_OFFSET_DB=-2):
- normal: switch at source sf 143 = target sf 137, the target's effective
  sf for the grant. The target heard the UE in slot from the first
  superframe (1115/1117). Released at +21; ran.ho_done at +5.
- target killed after staging: the UE fell back at +10, the source kept it
  and its uplink stayed in slot (1092/1092).
ctest 92/92 (TsfSync ShiftRemote selftest added). docs/cell-m6.md.

Refs #260

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@qodo-free-for-open-source-projects

Copy link
Copy Markdown

PR Summary by Qodo

Execute two-phase cell handovers with TSF continuity and fallback

✨ Enhancement 🐞 Bug fix 🧪 Tests 📝 Documentation 🕐 40+ Minutes

Grey Divider

AI Description

• Execute A3 handovers by staging the target before commanding the source and UE.
• Preserve UE clock continuity and return to the source if the target grant never arrives.
• Pace empty DUs to prevent their reported network superframe from running ahead.
Diagram

sequenceDiagram
    participant CU as RAN controller
    participant T as Target DU
    participant S as Source DU
    actor UE
    CU->>T: Stage HoCommand
    T-->>CU: Stage ack
    CU->>S: Send HoCommand
    alt Source stages
        S-->>UE: Tagged handover IE
        T-->>UE: Target grant map
        UE->>UE: Shift TSF and identity
        alt Target grant arrives
            UE->>T: Uplink
            T-->>CU: UE report
            S->>S: Release after silence
        else No target grant
            UE->>UE: Shift back at deadline
            UE->>S: Resume uplink
            S->>S: Keep grant
        end
    else Source refuses
        CU->>T: Cancel staging
    end
Loading
High-Level Assessment

The target-first command is appropriate: simultaneous commands could put an IE on air before the target accepts the UE. Retaining the source grant until uplink evidence confirms departure supports the stated fallback; requiring a target grant before switching would change the scheduled, clock-continuous handover model.

Files changed (7) +745 / -16

Enhancement (5) +583 / -16
cell.hAllow handover IEs in DU beacons +4/-1

Allow handover IEs in DU beacons

• Extends beacon construction to append complete extra IEs alongside the grant map and optional RACH responses.

examples/cell/cell.h

main.cppImplement DU staging, UE switching, and fallback +389/-11

Implement DU staging, UE switching, and fallback

• DUs handle handover commands and cancellation, publish target grants, advertise source IEs, and conditionally release departing UEs. UEs buffer target maps, shift TSF and identity at the switch, and return to the source if no target grant arrives. Also paces a DU with no served UEs to keep its superframe count aligned with TSF.

examples/cell/main.cpp

TsfSync.hShift the fitted remote clock without reacquisition +11/-0

Shift the fitted remote clock without reacquisition

• Adds ShiftRemote to translate the remote TSF axis while preserving the fit, sample history, and readiness across a PTP-synced cell handover.

src/TsfSync.h

HoCommand.hDefine the target cancellation marker +3/-1

Define the target cancellation marker

• Documents target_pos zero as a cancellation command for a target UE pre-admitted under the handover ID.

src/cell/HoCommand.h

main.cppCoordinate target-first A3 handover execution +176/-3

Coordinate target-first A3 handover execution

• Adds opt-in command generation, target acknowledgment before source delivery, cancellation on source refusal, retries, and completion or timeout tracking. Retires moved UEs' old measurement keys and applies dwell to their new identities.

tools/ran-controller/main.cpp

Tests (1) +32 / -0
tsf_sync_selftest.cppVerify TSF continuity across a remote-clock shift +32/-0

Verify TSF continuity across a remote-clock shift

• Tests that shifting from the source to target clock preserves readiness and timing accuracy, and that subsequent target beacons extend the existing fit.

tests/tsf_sync_selftest.cpp

Documentation (1) +130 / -0
cell-m6.mdDocument the M6 handover sequence and rig outcomes +130/-0

Document the M6 handover sequence and rig outcomes

• Explains TSF continuity, target-first staging, conditional source release, and UE fallback. Records normal and target-failure rig outcomes and identifies work not yet covered.

docs/cell-m6.md

@qodo-free-for-open-source-projects

qodo-free-for-open-source-projects Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

Code Review by Qodo

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

Grey Divider


Action required

1. Failed handovers leave target slots reserved ✓ Resolved
Description
The controller's timeout branch erases a flight without cancelling a target reservation, and
retransmission stops at the switch instant. If the target stages the UE but its acknowledgement is
lost, the source never receives the command while the target can retain the admitted UE and its
grant.

2. Reordered replies abort staged handovers ✓ Resolved
Description
The controller treats every non-Staged handover acknowledgement as a failure, although the DU
replies Stale to an older sequence arriving after a newer retry. If those UDP commands are
reordered, that stale reply can erase the flight and cancel a target that already acknowledged
staging.

3. A missed arrival window freezes the target cell's schedule ✓ Resolved
Description
Once a pending arrival's switch instant is less than 2 superframes away, nothing re-checks it: the
arrival block in the admitted-UE loop (sf + publish_lead_sf < eff_sf is false from then on) adds
the arrival back to next and sets ho_eff on every pass, and the abandon check at the publish
step then resets next = map; changed = false. Neither the ho_in entry nor the pre-admitted
registry id is ever removed, so from that point on the target DU throws away every other change it
computes each pass (RACH joiners, silence releases, cancels, source-side releases), and its map
never changes again.


Remediation recommended

4. Handover keeps running after sync loss ✓ Resolved
Description
The source DU airs its handover IE through the switch instant and the target DU publishes
pre-admitted arrivals, and neither path checks the DU's sync state. The F1 report already drops
net_sf to -1 when health.state() is Lost, but the ho_out loop and the ho_eff publish gate
only test superframe arithmetic and f1_eff. A DU that loses PTP sync therefore keeps airing and
publishing a coordinated handover schedule on its free-running count. The CU's in-flight resend loop
has the same gap: a target reporting net_sf 0 still passes tnet < effective_net_sf, so commands
keep going out.

5. Rig results report single runs only ✓ Resolved
Description
The rig table gives one value per case, such as the switch at source sf 143, the UE's 1115/1117
in-slot uplinks, and the release at +21. Handover interruption, the clock-holdover error, and
control-plane update latency are not reported as distributions across runs. The doc does not say how
many runs were made, so a single outcome cannot show the spread of the interruption.

6. Uplink duplication across cells is absent 📎 Requirement gap ≡ Correctness
Description
No DAPS duplication is wired: the doc lists DAPS and SeqDedup as not yet done, so the crossing
uses a single uplink path with no same-channel duplicate and no sequence deduplication. The UE
uplink stays on one cell until the switch, so an uplink lost during the crossing is not recovered
through the second cell. This is a known gap, and the doc names it explicitly.
Code

docs/cell-m6.md[R121-122]

+- **DAPS:** the duplicated uplink through both cells with `SeqDedup`
+  (same-channel first), and the "kill one path mid-crossing" test.
Evidence
The doc states that same-channel DAPS with SeqDedup is not covered, which matches the rule's
failure criterion that same-channel duplication is absent.

Same-channel DAPS and single-radio channel constraints
docs/cell-m6.md[121-122]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Same-channel DAPS is not implemented, so the uplink has no duplicated path during the crossing and duplicates are not suppressed.
## Fix Focus Areas
- docs/cell-m6.md[121-122]
## Recommended Fix
Duplicate the UE uplink through both cells while the handover is in flight, and wire `SeqDedup` into the receive path so each sequence is delivered once. Verify with the kill-one-path test.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


View review recommended (5)
7. Handover skips security pre-staging 📎 Requirement gap ⛨ Security
Description
The doc says the cells share one key on the rig, and that per-cell context pre-staging is open. The
handover therefore has no security context prepared at the target before the switch, and the
different-channel case (which needs FastRetune and a deaf-time budget) is also out. The
make-before-break migration is complete on the same channel only.
Code

docs/cell-m6.md[R126-129]

+- **Different-channel handover:** this needs `FastRetune` and the
+  deaf-time budget.
+- **Security context:** the cells share one key on the rig (`CELL_PSK`).
+  Pre-staging a per-cell context (802.11r-style) is open.
Evidence
The rule requires channel and security preparation for migration. The doc marks pre-staged security
context and different-channel handover as open, so the path is incomplete.

Make-before-break grant migration
docs/cell-m6.md[126-129]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The handover does not pre-stage a per-cell security context or prepare a different channel, so the migration lacks the preparation the rule requires.
## Fix Focus Areas
- docs/cell-m6.md[126-129]
## Recommended Fix
Pre-stage a per-cell security context at the target during the staging ack, and add the FastRetune path with its deaf-time budget for different-channel handover.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


8. Handover rig run is not committed ✓ Resolved
Description
The rig result depends on scripts/m5_ran_coord.sh with --cu-env and forced A3 values, and no
script in the diff verifies time-to-trigger, TSF continuity, grant migration, or delivery after a
path kill. The fault row in the doc is a manual measurement, so a regression in the fallback or the
kill case would go unnoticed by CI.

9. A reused UE identity stays ineligible ✓ Resolved
Description
The controller's retired check identifies the former source UE solely by cell and numeric UE ID,
and preserves retirement whenever that key appears in a report. If the source releases that ID and
admits another UE before a planning round sees the key absent, the replacement's measurements keep
it retired and its handover condition is never evaluated.

10. Failed identity changes leave downlinks unacknowledged ✓ Resolved
Description
run_ue clears rearm_ack and ignores the result of arm_ack() after changing its serving
identity. If hardware responder setup fails during a switch or fallback, the UE continues with the
new grant and address even though the radio has not confirmed it can acknowledge downlinks for that
identity.

11. Pre-admitted handover UE can be granted as an ordinary joiner ✓ Resolved
Description
The F1 thread calls reg.admit(um) under mu and only afterwards inserts ho_in[cmd.target_ue]
under f1_mu, while the main loop snapshots ho_in before it walks reg.admitted(). If the admit
lands between the snapshot and the walk, the UE gets the RACH-joiner grant at once: a default or
first-free position, effective sf+3, and a silence clock from now. It does not get the commanded
position at the switch instant, its ho_in entry is never erased, and it can be silence-released
before the UE ever arrives.


Informational

12. A cancel can be lost when the map does not publish ✓ Resolved
Description
run_du swaps ho_cancel into ho_cancel_snap, consuming cancellations before their grant
removals in next are published. If a pending-map barrier, F1 or arrival deadline reset, or failed
beacon update discards that tentative map, the cancellation is not retried and the already-published
arrival grant can remain until the silence release at switch instant plus release_sf.

13. Target cancel logic reads the flag it just overwrote ✓ Resolved
Description
In the CU's handover-ack handler, (a->du == source ? src_ok : tgt_ok) = ok runs before the cancel
decision if (fl.tgt_ok || a->du == fl.cmd.source), so a refusal from the target always resets
tgt_ok to false first, and the 'target already staged it' branch can never fire. If the target's
Staged ack is lost and a resend is refused after it published the arrival (it now reports the UE as
known), the flight is dropped and no cancel is sent, so the target keeps a grant for a UE that is
never coming.

Grey Divider

Tip of the day
💡 Did you know, you can turn these tips off under Display > Comment parts

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

CU:
- a failed or timed-out handover cancels the target's reservation,
  retried until acknowledged; a Stale reply (a reordered copy) is no
  verdict; nothing is sent to a DU without a network superframe;
- a retired key expires by time, so a later UE can reuse the id;
- the cancel decision reads the target flag before it is overwritten.

DU:
- a cancel acts only on the id that DU staged or published, and is kept
  until the live map no longer has the UE;
- the arrival is recorded before the registry admit (no joiner race);
- an arrival past its window expires (cell.ho.target_expired), and a
  deferred arrival removes only its own grant from the pass's map;
- no handover IE aired and no arrival published while Lost.

UE: the ACK-responder re-arm is retried until the radio takes it.

Rig (testrig scripts/m6_handover.sh, 5 normal + 3 target-crash, 90 s each):
all pass. Interruption 1/1/1 sf (min/median/max), CU done latency 5/6/16
sf, fallback 10/10/10 sf. docs/cell-m6.md updated.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@josephnef

Copy link
Copy Markdown
Collaborator Author

Qodo review addressed in 31e9ff1:

  1. Lost ack or timeout: a timed-out or failed handover sends the target a cancel, retried until acknowledged. A DU cancels only the id it staged or published, so the cancel is safe on any failure and never removes a UE confirmed to have moved under another id.
  2. Stale replies: a Stale ack (a reordered older copy) is ignored, not treated as a refusal.
  3. Missed arrival window: a target arrival past its window expires (cell.ho.target_expired) and frees its registry id. A deferred arrival removes only its own grant from the pass's map; the map is no longer reset.
  4. Sync loss: a DU that is Lost neither airs handover IEs nor publishes arrivals, and the CU sends nothing to a DU without a network superframe.
  5. Distributions: a repeated run of 5 normal and 3 target-crash cases (testrig scripts/m6_handover.sh), all passing. Interruption 1/1/1 sf, CU done latency 5/6/16 sf, fallback 10/10/10 sf (min/median/max). In docs/cell-m6.md.
  6. DAPS: the next PR (the uplink duplication with SeqDedup and the kill-one-path test), already in progress.
  7. Security pre-staging and different-channel handover: remain open, as documented. The rig cells share one key, and no USB or other-channel DU is in scope here.
  8. Committed test: testrig scripts/m6_handover.sh runs and asserts both cases and exits non-zero on regression. Rig orchestration lives in testrig, as for M1–M5.
  9. Retired keys: retirement expires by time (6 s), so a later UE can reuse the id.
  10. ACK responder: the re-arm result is checked and retried every pass until the radio takes it (cell.ue.ack_rearm_fail logged).
  11. Pre-admit race: the arrival is recorded before the registry admit and undone if the admit fails, so there is no joiner race.
  12. Lost cancel: a cancel is kept until the live map no longer has the UE.
  13. Overwritten flag: fixed by the always-cancel path above, so the overwritten-flag decision is gone.

ctest 92/92.

@josephnef

Copy link
Copy Markdown
Collaborator Author

All 11 code findings resolved. The two open items are requirement gaps, deliberately out of this PR's scope:

Merging under skip-qodo-gate.

@josephnef josephnef added the skip-qodo-gate Bypass the Qodo review gate (outage / maintainer decision) label Nov 5, 2026
@josephnef
josephnef merged commit 6f1998e into master Nov 5, 2026
27 of 28 checks passed
@josephnef
josephnef deleted the feat/m6-ho-exec branch November 5, 2026 15:38
josephnef added a commit that referenced this pull request Nov 5, 2026
Part of M6 (#260), epic #254. On top of #530 (handover execution).

- **Common sequence:** a UE's uplink is its hardware beacon, stamped
with its egress TSF, so `seq = round(egress / P)` is identical in every
DU's copy. The UE needs no change.
- **DU:** forwards its own UEs' uplinks to the CU (F1 v5 `Uplink`). With
`CELL_DAPS=1` (the default), during a handover it also forwards the UE's
other identity: the target forwards the source identity before the
switch, and the source forwards the target identity after.
- **CU:** `UlStreams` delivers each uplink once per UE stream over
`SeqDedup`. The handover command aliases the target identity onto the
source's stream, so the stream runs on across the switch. It logs
`ran.ul_gap` for every delivery gap and `ran.ul` summaries.
- **`cell_m6` ctest:** a simulated crossing (two lossy paths, the
identity flip, the source dying), the alias, the common seq, and the F1
round trip.

Rig (testrig `scripts/m6_daps.sh`, 3 runs per mode; the source DU is
killed the moment its UE accepts the handover, about 2 s before the
switch):

| uplinks missing from the crossing UE's stream | min | median | max |
|---|---|---|---|
| DAPS | 0 | 0 | 1 |
| no DAPS | 13 | 14 | 14 |

ctest 92/92. Still open: downlink duplication, the different-channel
(sequential) DAPS variant, and security pre-staging.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
josephnef added a commit that referenced this pull request Nov 5, 2026
Part of M6 (#260), epic #254: **different-channel handover**, on top of
#530 and #531.

- **Command and IE:** `HoCommand.target_channel` comes from the target
DU's report, and `HoIe.channel` travels with it (IE v2, F1 v6).
- **UE:** at the switch it shifts its clock by the TSF delta (no target
beacon needed first), takes the target identity, and **stops its uplink
beacon → retunes (`FastRetune`) → restarts it on the new channel**. It
logs the retune time and the first serving beacon after it.
- **Deadline to return:** with no target grant within
`CELL_HO_FALLBACK_SF`, the UE retunes back to the source, which still
holds it. This bounds the deaf time.
- **Trigger:** with one radio per DU, no DU hears a UE across channels,
so the A3 has no neighbour value to compare. **UE measurement gaps are
the next step.** Until then, `RAN_HO_FORCE=SRC:UE:TGT@SECONDS` forces
one handover through the normal execution path.

Rig (testrig `scripts/m6_handover.sh --channel2 157`: ch149 → ch157, 5
normal + 3 runs with the target killed after staging; all pass):

| KPI | min | median | max |
|---|---|---|---|
| `FastRetune` (8852CE, 11 retunes) | 23.5 ms | 23.6 ms | 23.7 ms |
| first target beacon after the retune | 37 ms | 52 ms | 101 ms |
| interruption (sf, first in-slot uplink at the target) | 2 | 2 | 3 |
| target crash: fallback / source uplink missed (sf) | 10 / 10 | 10 / 10
| 10 / 10 |

The switch lands on the target's effective superframe in every run:
clock continuity holds across the channel change. ctest 92/92. Details
in `docs/cell-m6.md`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

skip-qodo-gate Bypass the Qodo review gate (outage / maintainer decision)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant