From 21ba8515efe667682a3201d0999a6baf7eef39b1 Mon Sep 17 00:00:00 2001 From: Joseph <162703152+josephnef@users.noreply.github.com> Date: Sat, 30 May 2026 14:21:14 +0300 Subject: [PATCH] tests: default matrix --channel to 6 (2.4GHz); surface band asymmetry MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `tests/regress.py --channel` defaulted to `36` (5GHz UNII-1), and every matrix invocation in README + CLAUDE.md examples used `--channel 100` (5GHz UNII-2-ext). This hid a long-standing fact: devourer's 5GHz code path has broken cells for 8814 RX, 8821 TX, and 8821 RX that all pass at 2.4GHz. CLAUDE.md's "RTL8814AU... RX solid" claim was correct AT 2.4GHz but appeared to contradict the matrix output captured at 5GHz — including the "8814 RX devourer still broken" labels in PR bodies #34, #42, and #49. What this changes - `tests/regress.py`: default `--channel` → 6. Help text now spells out that 5GHz has known broken cells and recommends running with `--channel 36` / `--channel 100` to exercise them. - `tests/README.md`: example invocations drop the explicit `--channel 100`. Added a "Channel / band asymmetry" entry to Known Limitations explaining why prior PR matrix tables show cells as broken that work fine at 2.4GHz. The `--channel N` CLI knob doc also gains the band warning. - `CLAUDE.md`: regress.py examples drop `--channel 100`. Adds a paragraph explaining the band asymmetry and pointing at the historical PR tables. What this does NOT change - The actual 5GHz code-path issues. Those are a separate investigation (devourer's 8814 RX path at 5G, 8821 TX/RX at 5G). Default-to-2.4G surfaces the working-band picture; the 5G work belongs to a follow-up PR. - The persistent 8814AU TX gate — 0 hits at both bands; not changed. - The 8812AU code paths, which work at both bands and aren't touched. Empirical evidence captured in this session against current master `9e5287e` (see Test plan below): every previously-"broken" cell passes at ch6. Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 11 +++++++++-- tests/README.md | 25 +++++++++++++++++++++---- tests/regress.py | 10 +++++++--- 3 files changed, 37 insertions(+), 9 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4f73e66..a40f139 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -44,16 +44,23 @@ two USB Wi-Fi adapters plugged into the host. Run **after** building devourer. ```sh # Local mode — kernel cells use whatever driver is bound on the host -sudo python3 tests/regress.py --channel 100 +sudo python3 tests/regress.py # VM mode (recommended for RTL8814AU and other chips whose kernel driver # doesn't build on bleeding-edge kernels) — kernel cells run inside a # pinned-kernel (Ubuntu 22.04 / 5.15) libvirt VM with aircrack-ng/rtl8812au # preloaded. Provision once with tests/setup_vm.sh, then: -sudo python3 tests/regress.py --channel 100 \ +sudo python3 tests/regress.py \ --vm-name devourer-testrig --vm-ssh @ ``` +Default channel is `6` (2.4GHz). Devourer's 5GHz path has known broken +cells for 8814 RX, 8821 TX, and 8821 RX — at 2.4GHz every chip combo +except 8814 TX works. Pass `--channel 36` / `--channel 100` to exercise +5GHz; do not assume a single-band matrix is comprehensive. (The repo +history's matrix tables in PR bodies #34/#42/#49 were all captured at +`--channel 100` and document the 5GHz state.) + Three specialised modes layered on top of the default 4-cell matrix: - `--full-matrix`: iterates every ordered (TX, RX) pair of plugged DUTs diff --git a/tests/README.md b/tests/README.md index dee114d..f17113a 100644 --- a/tests/README.md +++ b/tests/README.md @@ -27,7 +27,8 @@ a moving target as kernels evolve, especially for the out-of-tree `aircrack-ng/rtl8812au` driver. ```bash -sudo python3 tests/regress.py --channel 100 +sudo python3 tests/regress.py +# default --channel 6; pass --channel 36 / --channel 100 to exercise 5GHz ``` ### VM mode (recommended) @@ -48,9 +49,11 @@ sudo tests/setup_vm.sh --status # show VM IP, ssh hint Then run the matrix in VM mode: ```bash -sudo python3 tests/regress.py --channel 100 \ +sudo python3 tests/regress.py \ --vm-name devourer-testrig \ --vm-ssh @ +# Defaults to --channel 6 (2.4GHz). Re-run with --channel 36 / 100 to +# also exercise 5GHz; devourer has known broken cells there for some chips. ``` VM mode is what unblocks chipsets where the host kernel driver doesn't @@ -117,8 +120,11 @@ per-cell stdout/stderr logs end up at `/tmp/devourer-regress-last/`. ## CLI knobs -- `--channel N` — Wi-Fi channel for both adapters (default 36; pick the - channel your nearest AP is on for guaranteed traffic) +- `--channel N` — Wi-Fi channel for both adapters (default `6`). **Devourer's + 5GHz path has known broken cells** (8814 RX, 8821 TX/RX) that are masked + if you only test 2.4GHz. Override with `--channel 36` / `--channel 100` + to surface them. The 8814 TX gate (kaeru ref `RTL8814AU libusb-userspace + bulk-OUT does not produce on-air TX`) shows on both bands. - `--duration SECONDS` — per-cell injection/measurement window (default 15) - `--pass-threshold N` — min hits to pass (default 1) - `--tx-pid 0xNNNN` / `--rx-pid 0xNNNN` — pick specific DUTs (defaults to @@ -277,3 +283,14 @@ to add new chipsets — the rest of the script is chipset-agnostic. host and devourer-claimable simultaneously. Works fine, but means both chipsets need working devourer RX — if one is RX-broken (e.g. current RTL8814AU TODO), that cell will always show 0 hits regardless of TX. +- **Channel / band asymmetry on devourer.** A single-channel matrix run + doesn't tell the full story — devourer's 5GHz code path has long- + standing broken cells (8814 RX, 8821 TX, 8821 RX) that pass on 2.4GHz. + The default of `--channel 6` was chosen because it produces the + "everything except 8814 TX works" picture that matches CLAUDE.md and + the project's primary use case. Run with `--channel 36` or + `--channel 100` to surface the 5GHz issues. Older PR matrix tables + in the repo history were captured at `--channel 100`, which is why + multiple PR bodies (e.g. #34, #42, #49) record "8814 RX devourer still + broken" — those cells work at 2.4GHz; the documented "broken" status + is band-specific. diff --git a/tests/regress.py b/tests/regress.py index be0938a..ea9969e 100755 --- a/tests/regress.py +++ b/tests/regress.py @@ -1252,9 +1252,13 @@ def main(): help="repo root with build/WiFiDriverDemo + build/WiFiDriverTxDemo", ) ap.add_argument( - "--channel", type=int, default=36, - help="Wi-Fi channel (default 36; pick a busy channel like 100 if your " - "AP is on it — higher hit counts mean less variance)", + "--channel", type=int, default=6, + help="Wi-Fi channel (default 6 — 2.4GHz). Devourer's 5GHz code path " + "has known broken cells for 8814 RX, 8821 TX, and 8821 RX (8814 " + "TX is broken on both bands). At 2.4GHz every chip combo except " + "8814 TX works. Override with `--channel 36` or `--channel 100` " + "to surface the 5GHz cells; do not assume a single-band matrix " + "is comprehensive.", ) ap.add_argument( "--duration", type=float, default=15.0,