tests: --encoding-matrix iterates radiotap LDPC/STBC per cell

[josephnef]

What this is

New mode for tests/regress.py. For one ordered TX→RX pair, iterates every (driver-mode × radiotap encoding combo) cell and emits a single table. 16 cells per run (4 driver modes × 4 encoding combos: BCC, LDPC, STBC=1, LDPC+STBC=1, all at MCS 1 / 20 MHz).

Designed to surface chip-specific RX-encoding asymmetries that the existing default and --full-matrix modes can't see — they only exercise the chip's default encoding, so a chip whose decoder doesn't support, say, LDPC would silently never have an LDPC frame thrown at it.

sudo python3 tests/regress.py --encoding-matrix \
    --tx-pid 0x8813 --rx-pid 0x0120 --channel 100 \
    --vm-name devourer-testrig --vm-ssh <user>@<VM-IP>

Prompted by @RomanLut's note in #22: "BTW, rtl8821au supports LDPC TX, but not LDPC RX. PixelPilot can not receive video stream from Eachine Sphere Link if LDPC is enabled. You may also want to add LDPC and STBC settings to the tests."

Implementation

• txdemo/main.cpp — reads DEVOURER_TX_MCS / _LDPC / _STBC / _BW env vars at startup and patches the radiotap MCS info bytes in beacon_frame[10..12]. WiFiDriverTxDemo writes its radiotap header directly into the chip's bulk-OUT buffer, so these knobs are ground truth for what flies on devourer TX.
• tests/inject_beacon.py — --mcs / --ldpc / --stbc / --bandwidth flags. Scapy's RadioTap layer doesn't expose first-class LDPC/STBC, and its MCS plumbing has churned across versions, so the helper hand-builds the 13-byte radiotap header via struct.pack and prepends it as Raw — matches txdemo's exact layout.
• tests/regress.py — ENCODING_COMBOS at module level, encoding= parameter threaded through run_cell / _spawn_devourer_tx / _spawn_kernel_tx / _devourer_env. New run_encoding_matrix + emit_encoding_markdown. New --encoding-matrix flag in main(). All existing call sites remain encoding=None, current behaviour preserved.
• tests/README.md — new "Specialized modes" section covering both --full-matrix (which was undocumented since tests: --full-matrix runs N-adapter cross-driver interop tables #34) and --encoding-matrix, plus the kernel-TX caveat below.

Validation on the lab rig (8814 TX → 8821 RX, channel 100, VM mode)

Mode (TX/RX driver)	BCC	LDPC	STBC=1	LDPC+STBC=1
k/k	447 ✓	449 ✓	438 ✓	433 ✓
d/k	0 ✗ (4500 fail)	0 ✗	0 ✗	0 ✗
k/d	400 ✓	400 ✓	400 ✓	400 ✓
d/d	0 ✗	0 ✗	0 ✗	0 ✗

16/16 cells ran, table emitted cleanly. Plumbing works end-to-end.

Honest note: the LDPC asymmetry didn't surface

The k/d row is flat across encodings. Two plausible reasons (documented in tests/README.md):

1. aircrack-ng/88XXau may not honour radiotap MCS TX flags. mac80211 + the OOT driver's rate-selection can override what the helper requests, so the kernel-TX-side columns may all carry the chip's default encoding on-air regardless of what inject_beacon.py asked for. Verifying this requires a third adapter as sniffer (AR9271) decoding the captured MCS flags.
2. 8821AU is 802.11ac silicon. Roman's failing case is likely VHT-LDPC, which sits in radiotap bit 21 (VHT info, 12 bytes), not the HT-LDPC bit (bit 19, MCS flags, 3 bytes) this PR adds. Extending ENCODING_COMBOS with VHT entries is straightforward future work; left for a follow-up so this PR stays small.

The d/k and d/d rows are unaffected by either caveat — txdemo writes the radiotap header directly into the chip's bulk-OUT buffer, no kernel filtering involved. They're the ground truth direction for testing devourer-side encoding parity. They show 0 here because 8814 TX is currently broken on master (separate known issue), not because the encoding plumbing failed.

What this PR doesn't touch

• The default 4-cell mode and --full-matrix behaviour — both pure-additive.
• VHT (802.11ac) encoding fields — HT only for now.
• Sniffer-side validation of on-air encoding — would need a third adapter wired in.
• Any TX/RX/HAL code outside txdemo — WiFiDriver.a itself is unchanged.

Test plan

• --encoding-matrix --tx-pid 0x8813 --rx-pid 0x0120 --channel 100 --vm-name devourer-testrig --vm-ssh ... runs all 16 cells and emits the table
• --help lists the new flag
• inject_beacon.py _build_radiotap_mcs produces correct bytes for each (ldpc, stbc) combo (manually verified)
• WiFiDriverTxDemo reads env vars and logs each one (visible in <devourer-tx> log lines)
• Default mode (tests/regress.py --channel 100) still works — no encoding params passed, encoding=None default preserved
• --full-matrix still works (not re-validated in this session, but the only run_cell call-site changes are new optional encoding=None parameters)
• Add VHT encoding combos as a follow-up
• Add AR9271 sniffer validation step to confirm on-air MCS flags match what the helper requested

🤖 Generated with Claude Code