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,