[josephnef]

M6 (#260, EPIC #254): the UE's clock fit now survives a jump of its serving DU's TSF. This closes the open item from #534.

Why

The UE fits the DU's TSF from DU beacons against its own free-running counter (src/TsfSync.h). The fit is cumulative, so a single jump in the DU's TSF is read as skew and keeps biasing every translation for a long time. In the #534 runs, one ~1.3 ms jump drove a UE's skew estimate to thousands of ppm, and its measurement gaps then missed.

What

• TsfSync::SetStepDetect(threshold_us, confirm), opt-in and off by default, so other users are unchanged:
  • a beacon more than the threshold off the fit is held out of it;
  • confirm held beacons in a row that agree on one offset (within a quarter of the threshold) are treated as a step: the remote axis is re-anchored (a TSF step changes the offset, never the crystals' rate) and the held beacons join the fit;
  • held beacons that never agree are dropped, so a stray frame can't bend the line;
  • counters: Steps(), LastStepUs(), Rejected();
  • ShiftRemote (handover) also drops beacons held from the previous transmitter.
• UE: detection is on by default with CELL_UE_FIT_STEP_US 200 and CELL_UE_FIT_CONFIRM 6, and is logged as cell.ue.fit_step. Six beacons outlast the DU's own discipline pass (500 ms), so a jump the DU undoes itself is never followed.
• DU, test only: CELL_DU_TEST_TSF_STEP=US@SF adds a TSF jump after the discipline's sample, so it stays on air for one pass.
• Selftests (tsf_sync):
  • the rig case: a +1300 µs step after 24 beacons is read as skew with detection off, and as one step with the skew kept with it on;
  • the step back is also confirmed;
  • a stray beacon is dropped;
  • a jump undone within the confirm window is dropped;
  • alternating outliers never confirm.
• Docs: docs/cell-m6.md, a section on the UE's clock fit across a jump.

Rig (testrig scripts/m6_fitstep.sh, 3 runs per case, all pass)

case	steps followed	UE skew, max |ppm|	DL frames in the DL area after	uplinks off-slot, 20 sf after
DU restart under the attached UE, detection on	the restart jump (−30.5…−31.1 s) and acquisition steps	8.0–10.1	100 %	not judged (below)
same, detection off (1 run)	—	996 125	11 %	not judged
1300 µs jump the DU undoes ~500 ms later	none (5 beacons held, then dropped)	8.4–11.9	100 %	0

With confirm 3 (an earlier iteration), the UE followed the transient out and back, 3 beacons late each way, which put 4–5 of 20 uplinks off-slot. That is why the default is 6.

Regression on the rig:

• same-channel handover 2/2, with fallback 1/1;
• measurement-gap handover 1/1;
• inter-frequency handover 3 of 4. In the failure, the UE heard no target beacon within its fallback window. No beacon was held by the detection (no fit_step event). The cause is not established; DU2's discipline was converging from a −90 ppm acquisition estimate in that run.

Not in scope, now listed as open in the docs: after a DU restart, the UE's clock follows but its grant state does not. The restarted DU's grant maps restart at a low epoch on another superframe count, so the UE is not heard in the new grid.

🤖 Generated with Claude Code

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

PR Summary by Qodo

Keep the UE clock fit stable across serving DU TSF jumps

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

AI Description

• Confirm persistent DU TSF jumps before re-anchoring the UE fit, preserving its skew estimate.
• Discard transient or inconsistent beacons so they cannot distort clock translations.
• Add a DU test jump, selftests, diagnostics, and rig findings.

Diagram

graph TD
  Beacon["DU beacons"] --> Residual["Fit residual"] --> Outlier{"Beyond threshold?"} -->|Yes| Held["Hold beacons"] --> Confirm{"Step confirmed?"} -->|Yes| Shift["Re-anchor axis"] --> Fit["Clock fit"]
  Outlier -->|No| Fit
  Confirm -->|Interrupted| Drop["Discard held"]
  Confirm -->|Pending| Held

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Reset and reacquire the fit after a confirmed step

• ➕ Simpler separation of pre- and post-jump samples.
• ➖ Loses the established crystal-rate estimate and requires new samples before the fit is ready.

Recommendation: Keep the PR's remote-axis re-anchoring: a TSF write changes the clock offset, not its crystal rate. Confirming the change before shifting also avoids following short-lived corrections; resetting the fit would unnecessarily interrupt clock translation.

Files changed (4) +224 / -12

Bug fix (2) +118 / -3

main.cppEnable UE step detection and add a DU test jump +53/-0

Enable UE step detection and add a DU test jump

• Configures UE step detection with a 200 µs threshold and six-beacon confirmation window, and emits fit-step diagnostics. Adds a test-only DU TSF jump after a discipline sample to exercise a transient discontinuity.

examples/cell/main.cpp

TsfSync.hConfirm clock steps without corrupting the fitted skew +65/-3

Confirm clock steps without corrupting the fitted skew

• Adds opt-in residual-based holding and confirmation, re-anchors the remote axis for confirmed steps, and counts rejected beacons. Handover shifts now clear beacons held from the previous transmitter.

src/TsfSync.h

Tests (1) +57 / -0

tsf_sync_selftest.cppCover persistent, transient, and inconsistent TSF jumps +57/-0

Cover persistent, transient, and inconsistent TSF jumps

• Tests skew corruption without detection, recovery across a persistent jump and step back, rejection of a stray beacon, and refusal to follow short-lived or alternating outliers.

tests/tsf_sync_selftest.cpp

Documentation (1) +49 / -9

cell-m6.mdDocument TSF-step behavior and rig results +49/-9

Document TSF-step behavior and rig results

• Explains how the UE holds, confirms, or drops divergent beacons and records restart and transient-jump rig outcomes. Replaces the resolved clock-fit open item with the remaining grant-state problem after a DU restart.

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. Failed readbacks misdate test uplinks ✓ Resolved

Description

sync_once leaves clk.valid true when the test TSF write's ReadTsfAndFreeRun readback fails,
retaining the pre-write clock offset. If the write took effect, concurrent RX processing before the
next successful refresh uses that stale offset to attribute uplinks to slots and calculate forwarded
uplink sequences.

---

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 0071ca3: failed read-back after the test TSF step — the RX clock snapshot is now invalidated under clk_mu when the read-back fails, exactly as the discipline's own write path does, and stays invalid until a fresh read publishes one. ctest 95/95.

[josephnef]

CI green; Qodo's bug is resolved (0071ca3). The remaining item is the high-level alternative 'reset and reacquire the fit after a confirmed step': that discards the crystals' rate the fit already holds and leaves the UE without a clock until 16 new beacons (~1.6 s); a TSF step changes only the offset, so re-anchoring the remote axis keeps the UE scheduled through it (rig: skew <= 10 ppm across a DU restart). Merging with skip-qodo-gate.