Frequency-resolved link quality (3/3): passive VHT compressed-beamforming report capture — per-tone data for free

[josephnef]

Why

802.11ac explicit beamforming sounding leaks per-subcarrier channel state onto the air: the beamformee estimates H(k) from an NDP, SVDs it, compresses the steering matrix V(k) into quantized Givens-rotation angles (phi/psi) plus per-tone SNR, and transmits the result as a VHT Compressed Beamforming Action frame (category 21/VHT, action 0). On Jaguar silicon this pipeline is hardware-terminated — our own chip's estimate is unreadable — but any monitor-mode RX we already have can capture the report a third-party beamformee transmits. That frame is genuine per-tone data: no chip feature, no debug port, no wedge risk.

What it gives the adaptive link

• Per-tone average SNR (the report carries it explicitly per subcarrier group) and per-tone V(k) angles → the frequency-selective shape of someone else's path through the same environment.
• Useful as an ambient "spectrum weather" source where BF-capable links (MU/SU-BF APs, 11ac wave-2) are active — complements issue 1 (our own coarse map) and issue 2 (our own per-tone, one-shot).
• Caveats up front: only works while a BF link is sounding nearby; the path measured is theirs, not ours; angles encode relative channel shape, not absolute gain.

Scope

Driver-side this is nearly free — monitor mode already passes management/action frames. The work is a decoder + bench recipe:

• M1 — decoder tool (tools/bfr_decode.py): parse VHT Compressed Beamforming Action frames from a pcap or from the <devourer-body> stream. Handle the MIMO control field (Nc, Nr, BW, grouping Ng, codebook size), unpack the angle stream, reconstruct V(k), extract per-tone SNR. Output a per-tone heatmap / CSV.
• M2 — capture check on devourer RX: confirm the frames traverse our RCR filter and arrive intact on 8812AU/8822CU monitor RX (they're plain action frames, but verify no length/subtype filtering bites).
• M3 — bench generator: a repeatable local source of reports — a BF-capable AP + STA pair (e.g. an 11ac wave-2 AP with SU-BF enabled + any beamformee-capable kernel STA), so validation doesn't depend on neighbourhood traffic.
• M4 — validation: sanity-check the decoded per-tone SNR shape against a B210 capture of the same environment (coarse correlation, not exact — different path).

References

• IEEE 802.11-2016 §9.4.1.48 (VHT MIMO Control), §9.4.1.49 (compressed beamforming report field), §19.3.12.3 (Givens decomposition).
• Prior art: "BFI sensing" literature uses exactly this side channel for passive sensing.

Part 3 of a 3-issue series; part 1 is the narrowband sweep, part 2 is LA-mode IQ capture.

[josephnef]

Upgrade path discussed for the adaptive link: since we control both adapters, we don't have to wait for ambient BF traffic — one adapter plays beamformer, the other beamformee, and we capture our own report off the air (self-sounding). The hardware-terminated CSI pipeline on the beamformee stops mattering because its output is transmitted to the beamformer, which is ours and in monitor mode.

Ingredients already in-tree:

• NDPA TX-descriptor field on Jaguar1 (SET_TX_DESC_NDPA_8812, reference/rtl8812au/include/rtl8812a_xmit.h); on Jaguar3 devourer's bf_init already programs the NDPA sounding engine (REG_NDPA_OPT_CTRL/TXBF_CTRL, src/jaguar3/HalJaguar3.cpp).
• Vendor beamformee-entry configuration to crib from: reference/rtl88x2cu/hal/phydm/phydm_beamforming.c + txbf/.

Proposed additional milestone (after M1 decoder, before/parallel to M3 bench generator — this replaces the external-AP generator if it works):

• M5 — self-sounding: (a) arm the beamformee HW responder in monitor mode by programming the BF entry / REG_SND_PTCL_CTRL with the peer adapter's MAC — go/no-go gate: does the chip auto-respond to NDPA/NDP without an association? (b) emit NDPA (+HW NDP follow-up) from the beamformer side via the descriptor NDPA bits; check whether the FW-NDPA path (CONFIG_BEAMFORMER_FW_NDPA) is needed instead. (c) capture + decode the returned report with the M1 tool.

Content caveat to encode in the decoder: the SU report = per-tone V(k) angles + per-stream average SNR (wideband); per-tone delta-SNR exists only in the MU-exclusive segment (8822C can MU-beamformee; 8812AU is SU-only). So self-sounding yields the per-tone spatial/multipath shape of our own link on demand; per-tone magnitude comes from combining with the narrowband sweep bins or an MU-type report.

[josephnef]

Hardware-validated on real silicon ✅ — both go/no-go gates PASS

Ran the self-sounding experiment (M5) end-to-end with three adapters on ch100. Both hardware unknowns are answered YES, and we captured real per-subcarrier CSI of our own link.

Gate 1 — NDP emission (sounder side): setting the TX-descriptor NDPA bit (SET_TX_DESC_NDPA_8812(desc,1)) on the injected NDPA control frame plus arming the MAC sounding engine (0x718=0xCB, 0x71B=0x50, 0x42C P_AID=0, 0x42F |= BIT4|6|7, 0x714 BFMEE_SEL) makes the chip auto-append a hardware NDP. B210 burst-pair probe: pair_frac 0.002 → 1.000, inter-burst gap ~18 µs (SIFS). The descriptor bit alone is not enough — the engine arm is required.

Gate 2 — unassociated beamformee response (responder side): an 8821AU armed as beamformee with no association (0x718=0xCB, 0x71B=0x50, 0x6E4..9=beamformer MAC, 0x6F4/F8/FC=CSI params, 0x9B4=CSI content) hardware-replies a VHT Compressed Beamforming report. Passive 8814AU sniffer: 3841 reports armed / 0 unarmed, SA = the 8821AU MAC, Nc=1 Nr=2 BW=20MHz Ng=1, 99-byte frame. Address-match + register-arm is sufficient; no CAM/macid entry needed.

Payload is genuine per-tone CSI: 66-byte body = 1 avg-SNR byte + 65 compressed Givens-angle bytes that vary across subcarriers (real frequency structure) and stay consistent across consecutive reports (quasi-static bench geometry).

Implications for this issue

Self-sounding retires the "needs ambient BF traffic" caveat — we can sound our own link on demand at whatever cadence we want. So M5 becomes the primary acquisition path and M3 (external-AP bench generator) is downgraded to optional. The M1 decoder is still exactly what's needed — it just consumes our own reports now.

Gotcha worth recording for the decoder (M1)

CSI reports are transmitted as Action No-Ack (FC subtype 0xE0), not Action (0xD0). A parser matching only 0xD0 will see zero frames. Category 0x15 / action 0x00 for VHT.

Experiment lives on branch bf-selfsounding-probe (not for merge as-is): env hooks DEVOURER_TX_NDPA, DEVOURER_BF_ARM_SOUNDER, DEVOURER_BF_ARM_BFEE=<mac>, DEVOURER_TX_NDPA_RA=<mac>, DEVOURER_BF_DETECT_REPORT, plus tests/bf_* scripts.

[josephnef]

Jaguar-2 (8822BU) self-sounding — implementation plan (deferred until the Jaguar-2 port lands)

Recording how to mirror the working Jaguar-1 + Jaguar-3 self-sounding onto Jaguar-2, so it can be picked up once src/jaguar2/ bring-up is complete. This issue stays open while the Jaguar-1/Jaguar-3 changes land — Jaguar-2 remains pending.

The good news: the register recipe already exists

kBfeeJaguar23 in the shared src/BeamformingSounder.h was transcribed from the vendor hal_txbf_8822b_enter() — i.e. it is literally the 8822B function. I diffed reference/rtl88x2bu/hal/phydm/txbf/haltxbf8822b.c against the rtl88x2cu copy: byte-identical. So Jaguar-2 reuses kBfeeJaguar23 verbatim; the MAC sounding registers (0x718 / 0x6E4 / 0x6F4 / 0x714 / 0x42C) are the same across the whole AC family. No new recipe to write.

Recipe (all in kBfeeJaguar23, vendor-confirmed for 8822B): SND_PTCL_CTRL(0x718)=0xDB; 0x6E4..9 = beamformer MAC; 0x71B=0x50; RX-filter gates 0x6A1 |= 0x40 (accept action-no-ack) and 0x6A2 |= 0x30 (accept NDPA/BF-poll); own-AID 0x1680=0; CSI_RPT_PARAM 0x6F4 16-bit; and no 0x9B4 write (that address is unused/other on 8822B — only Jaguar-1 uses it for BB CSI-content).

Prerequisite / gating

Needs the Jaguar-2 port to reach initialized bring-up with the channel set (power-on → DLFW → MAC/BB/RF init → channel). Currently blocked on the DLFW SS-segment boundary. Note: the beamformee responder is a hardware MAC function — the chip replies to NDPA autonomously, so this does not require devourer's host bulk-IN RX datapath to be fully working. That makes the beamformee test a useful early canary for the Jaguar-2 port: it validates PHY/MAC RX + the sounding engine independent of the host RX plumbing.

Work items

1. Beamformee arming (primary). In RtlJaguar2Device::Init, gate on DEVOURER_BF_ARM_BFEE=<mac>: program a known self-MAC into 0x0610 (Jaguar-2 bring-up doesn't program it, same as Jaguar-3), then devourer::bf::arm_beamformee(_device, mac, devourer::bf::kBfeeJaguar23). Mirror the ~15-line block already in RtlJaguar3Device::Init. Order it after HalmacJaguar2MacInit writes REG_RXFLTMAP0/2 (WLAN_RX_FILTER*), since the recipe read-modify-writes those to add the NDPA-accept bits.
2. Sounder arming (secondary, only for 8822BU-as-beamformer). InitWrite gate on DEVOURER_BF_ARM_SOUNDER → devourer::bf::arm_sounder(_device) (fully shared). And add SET_TX_DESC_NDPA_8822B(d,v) = SET_BITS_TO_LE_4BYTE((d)+0x0C, 22, 2, v) to FrameParserJaguar2.h (the family-standard position; not yet defined for Jaguar-2) + mark it in send_packet under DEVOURER_TX_NDPA. Not needed for the first bring-up test.
3. Report detector — no Jaguar-2 work. The demo detector (DEVOURER_BF_DETECT_REPORT) is generation-neutral; any monitor RX captures the reports.
4. Test. Add tests/bf_selfsound_jaguar2.sh mirroring bf_selfsound_jaguar3.sh: 8812AU sounder → 8822BU beamformee (armed) → 8814AU sniffer at ch100; expect <devourer-bf-report> with SA = the programmed 8822BU MAC, Nc=2 Nr=2 (2T2R, like the 8822C/E), and 0 when unarmed. Decode with the existing chip-agnostic tools/bf_report_decode.py.

Expected result

Given the identical vendor recipe and the 2×2 reports already seen on 8822CU/8822EU, the 8822BU should behave the same. If the beamformee doesn't respond, the first suspects are (a) RXFLTMAP ordering vs monitor setup and (b) the chip not being initialized enough to process the NDPA — not the recipe.