Crystal-cap (XTAL) trim knob — CFO lever to make 5 MHz narrowband robust at 5 GHz

[josephnef]

Problem

5 MHz narrowband at 5 GHz is CFO-limited (found during #216 validation): the quarter-clock re-clock shrinks the OFDM subcarrier spacing 4× (78.125 kHz → ~19.5 kHz), so the sync tolerance drops to a quarter of the 20 MHz budget — while the absolute TX/RX crystal offset is ~2.2× larger at 5.2 GHz than at 2.4 GHz for the same ppm mismatch.

Measured on the bench (same TX session, same code):

TX → RX pair	5 GHz ch44, 5 MHz	2.4 GHz ch6, 5 MHz
8812CU → 8812EU	10200 hits — solid	—
8812CU → 8811CU	bimodal: 9100 hits one bring-up, 0 the next three	7000–7600, stable ×3

A marginal crystal pair sits right at the 5 MHz/5 GHz sync boundary and flips per bring-up with thermal drift. 10 MHz (2× the budget) is reliable at both bands for every pair on the rig.

Proposal

Expose the Realtek crystal-cap trim as a runtime lever, so a link can pull the two crystals together by a few ppm:

• The chips have an XTAL load-capacitance trim field in the AFE control block, with an EFUSE-calibrated default (XTAL_K); the vendor drivers program it at init and some use it for dynamic CFO compensation (ATC/crystal-cap tracking in phydm).
• Library: a SetXtalCap(uint8_t) runtime setter on IRtlDevice (plus GetAdapterCaps reporting the trim range), per-generation HAL implementation reading the EFUSE default first.
• Demos: DEVOURER_XTAL_CAP=0xNN through DeviceConfig per the usual env mapping.
• Adaptive use: the RX side already measures per-frame CFO (phy-status report) — a follow-on could close the loop automatically (trim toward measured CFO ≈ 0), which fits the adaptive-link runtime-setter model.

Validation plan

• The bimodal 8812CU↔8811CU pair at ch44/5 MHz is the perfect testbed: sweep the trim on one end and show the 5 MHz cell goes from bimodal to stable (tests/narrowband_cross_rx.sh, true-count metric).
• SDR cross-check: measured carrier offset of the beacon before/after trim (B210).
• Regression: 20 MHz TX/RX smoke with a trimmed crystal (trim must not detune the synth out of lock).

Notes

• Per-chip trim range/registers differ per generation (Jaguar1/2/3) — start with the pair that exposes the problem (Jaguar2 8821C + Jaguar3).
• Documented in tests/narrowband_cross_rx.sh header + CLAUDE.md as of Jaguar2 5/10 MHz narrowband — 8821C validated, 8822B gated #216: "a 0 in the 5M cell at 5 GHz means retry / try 2.4 GHz before it means broken" — this knob is the proper fix.

🤖 Generated with Claude Code