Jaguar1: runtime SetRxPathMask/GetRxPathMask — sticky RX-chain diversity lever (#189)

[josephnef]

Closes #189.

What

The RX-chain enable mask (0x808 byte 0 — path A/B/C/D CCK+OFDM enable) becomes a runtime API on RtlJaguarDevice, the adaptive-link spatial-diversity lever:

void SetRxPathMask(uint8_t mask);  // 0x11=A, 0x33=A+B, 0x77=A+B+C, 0xFF=all
int  GetRxPathMask();              // reads 0x808[7:0] back; -1 = never set

Previously the only way to move it was the DEVOURER_RX_PATHS env var — fixed at bring-up or cycled on a blind timer. A controller with a motion/fade signal (e.g. beamforming-variance from the sensing path) can now switch chains live. The env single-value path routes through SetRxPathMask (one code path, identical behaviour); the toggle-spec thread is unchanged.

Sticky (the #189 open question, resolved the useful way): once set, the mask is re-applied after every SetMonitorChannel — a channel set runs IQK, which saves/restores 0x808 and would otherwise revert the mask to the table default. Gated on the mask having been set, so the default all-paths path stays byte-identical when the knob is unused. FastRetune's lean path skips IQK, so the mask survives a hop naturally.

Scoped to Jaguar1 (concrete RtlJaguarDevice, reached by dynamic_cast like the other RX research helpers): the 8814AU is the only part with ≥2 chains to actually trade; the 2T2R Jaguar2/3 parts have no 4-chain diversity story.

Validation

tests/rx_path_mask_check.sh — 8814AU as RX (4T4R), 8812AU beacon as source, DEVOURER_RX_ALLPATHS per-chain RSSI as the sensor:

run	mask	A	B	C	D
all paths	0xFF	52	50	52	56
A+B only	0x33	52	50	28	28
A+B under RX_SWEEP_FULL (full SetMonitorChannel/dwell)	0x33	52	50	28	28

• Functional: 0x33 collapses chains C,D to 28 (the noise floor) while A,B hold — the write reaches the right chains.
• Sticky: C,D stay collapsed across the full SetMonitorChannel dwells — proving the re-apply. Without it the first channel set reverts 0x808 to all-paths and C,D pop back up.

ctest green. No new env vars; the DEVOURER_RX_PATHS env knob is unchanged apart from now being sticky across channel sets (a capability improvement — the mrc/decorrelation harnesses do single-channel captures, so nothing regresses).

Not in scope (per the research behind #189/#190)

IGI/DIG and NBI/CSI-mask do not get runtime setters: RX gain is chip-closed (per-frame AGC + the slow DIG loop + LNA-saturation AGC-table switching), and the adaptive response to a spur is a channel hop (already runtime). This is the one RX knob that earns a runtime API. The Jaguar3 DIG parity gap is tracked separately (#190).

🤖 Generated with Claude Code