Frequency-resolved link quality (1/3): narrowband noise/sounding sweep — coarse spectrum map for the adaptive link

[josephnef]

Why

The chip only exports wideband scalars per frame (per-chain RSSI/SNR, per-stream EVM — all averaged across the whole channel). The adaptive link (hop-set selection, notch-vs-broadband diagnosis for the FEC/SVC ladder) wants to know which parts of the spectrum are clean vs faded. Per-subcarrier CSI is not host-readable on Jaguar-class silicon (the beamforming CSI report is hardware-terminated and transmitted over the air), so the cheapest frequency axis we can build is the tuner itself: sweep the radio across sub-bands and take one wideband measurement per dwell.

Two ingredients make this practical:

• FastRetune (~1.5–8.5 ms/hop on Jaguar1) keeps a multi-bin sweep in the hundreds-of-ms range instead of many seconds.
• Jaguar3 narrowband mode (5/10 MHz re-clock, 0x9b0[7:6] small-BW + 0x9b4 DAC/ADC dividers, src/jaguar3/RadioManagementJaguar3.h) shrinks the measurement bin to 5 MHz — ~16 subcarriers of a 20 MHz channel, i.e. resolution comparable to typical indoor coherence bandwidth, which is where the actionable frequency-selective structure lives.

Two measurement modes (both wanted)

1. Passive noise/interference map (RX-only): per dwell, read the idle noise floor / FA-counter rate / energy. Finds interferers; blind to fading of our own link (a faded-but-quiet bin looks clean).
2. Active link sounding (both ends devourer, the OpenIPC case): TX hops narrowband probe frames across the bins (per-packet radiotap CHANNEL already works), RX reports per-bin RSSI/EVM from the existing phy-status parse. This is a genuine coarse sounding of H(f) over our path — the mode that actually sees multipath notches.

Milestones

• M1 — FastRetune on Jaguar3. Port per docs/frequency-hopping.md (the porting guideline); today FastRetune exists only on RtlJaguarDevice. Cache RF18, skip the TX-power loop and post-set work a dwell doesn't need.
• M2 — per-dwell noise metric. Port the phydm noise-floor read (11ac path: 0xff0 idle / debug-port 0xfa0, see reference/*/hal/phydm/phydm_noisemonitor.c) and/or FA counters. NB: the FA/noise register addresses differ between Jaguar1 (0xF48/0xF4C/0xA5C) and Jaguar3 — source the jgr3 set from reference/rtl88x2cu/hal/phydm/phydm_ccx.c.
• M3 — sweep orchestrator. Env-driven (e.g. DEVOURER_SWEEP="5170-5250/5") background sweep emitting machine-parseable <devourer-sweep>freq=N bw=N noise=N fa=N lines, following the existing <devourer-thermal>/<devourer-rxpath-mask> marker pattern. Analysis/plot script under tests/.
• M4 — active two-ended sounding. Probe-TX schedule + per-bin RSSI/EVM aggregation on RX; validate the recovered coarse H(f) against a B210 wideband capture (same rig as tests/run_hop_validation.sh).

Caveats to encode in the design

• Bins are time-multiplexed — bursty interference aliases into fake frequency structure; repeat sweeps / dwell long enough for statistics.
• Sweeping is RX downtime on the operating channel; budget dwells accordingly.
• 5 MHz bins are Jaguar3-only; on Jaguar1 the sweep degrades to a 20 MHz per-channel map (still useful for hop-set selection).

Part 1 of a 3-issue series on frequency-resolved link quality; the other two cover LA-mode IQ capture (true per-tone CSI, one-shot) and passive VHT beamforming-report capture.

[josephnef]

Prerequisite for M4 (active two-ended sounding): Jaguar3 currently never parses the RX phy-status trailer, so per-bin RSSI/EVM would read zero on the only generation with 5 MHz bins. Tracked separately in #152.