first

3rd/devourer/CLAUDE.md

@@ -0,0 +1,655 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with
+code in this repository. It holds **cross-cutting** facts only. Deep subtree
+facts live in nested `CLAUDE.md` files, auto-loaded when working there:
+`src/{jaguar1,jaguar2,jaguar3,kestrel,rtl8733b}/` for per-generation registers,
+descriptors and per-chip mechanisms; `src/hopset/` for keyed FHSS and the
+adaptive hopset; `src/chanmig/` for channel migration. Add new facts to the
+narrowest file that covers them.
+
+Two standing rules for this file: never duplicate what a header already
+doc-comments (point at `src/DeviceConfig.h`, `src/TxPower.h`,
+`src/AdapterCaps.h` instead), and never quote a favourable measurement without
+its adversarial counterpart in the same breath.
+
+## What this is
+
+Userspace re-implementation of Realtek's USB Wi-Fi drivers (11n RTL873x, 11ac
+RTL88xx and 11ax RTL8852 families) — speaks to the chip directly via libusb
+instead of a kernel module. Static library `devourer` (CMake target) + example
+executables under `examples/` (`rxdemo` and `txdemo` are the canonical RX/TX
+demos). Used by the OpenIPC project for long-range video links.
+
+Five hardware backends, each behind its own self-contained HAL, dispatched at
+construction from the `SYS_CFG2` chip-id (Kestrel: PID-first):
+
+- **Jaguar1** (`src/jaguar1/`): RTL8812AU (2T2R reference), RTL8811AU (1T1R
+  cut, rides the 8812 path), RTL8814AU (4T4R RF / 3-SS baseband — a failed
+  FW-boot poll of its 3081 MCU means dead TX while RX still works), RTL8821AU
+  (1T1R + BT). 5/10 MHz narrowband on the 8812AU/8811AU/8814AU
+  (bench-characterized TX+RX); the 8821A is excluded and falls back to
+  20 MHz. See `docs/narrowband.md`.
+- **Jaguar2** (`src/jaguar2/`): RTL8822BU / RTL8812BU (chip-id `0x0a`) and
+  RTL8811CU / RTL8821CU (chip 8821C, chip-id `0x09`). A HalMAC + phydm
+  hybrid. RX + TX on 2.4/5 GHz at 20/40/80 MHz plus 5/10 MHz narrowband on
+  both variants; 5 MHz at 5 GHz is CFO-limited.
+- **Jaguar3** (`src/jaguar3/`): rtl8822c (RTL8812CU/8822CU, chip-id `0x13`)
+  and rtl8822e (RTL8812EU/8822EU, chip-id `0x17`). 5/10 MHz narrowband,
+  80 MHz (incl. a 40-in-80 frame), halrf calibration. Sustained 5 GHz TX
+  needs the coex runtime thread (started in `InitWrite`) — without it the
+  combo chip's coex firmware silences the antenna. 8822e constraints:
+  `docs/8822e-quirks.md`.
+- **Kestrel** (`src/kestrel/`): the Wi-Fi 6 / 802.11ax generation —
+  RTL8852BU/8832BU (variant C8852B) and RTL8852CU/8832CU (C8852C), one HAL
+  serving both dies on all platforms (MSVC included). Two planes: hand-ported
+  mac_ax C++ + Realtek's halbb/halrf C compiled verbatim
+  (`hal/hal{bb,rf}/g6/`). Dispatched PID-first (`kestrel/KestrelUsbIds.h`) —
+  the 0x00FC byte is not a chip-id on AX silicon. Blacklist rtw89 when
+  testing: a kernel driver pre-initializing the chip masks the cold-boot
+  path. On-air-validated: monitor RX (both dies, 2.4/5 GHz), TX injection
+  (legacy/HT/VHT/HE + HE ER SU/DCM — `docs/he-extended-range.md`),
+  5/10/20/40/80 MHz on both dies + 160 MHz on the 8852C only; 6 GHz TX tops
+  out at 80 MHz (the 6G+160 TX-enable path is un-ported). TX power is a fixed
+  BB dBm (`DEVOURER_TX_PWR`, whole dBm here). The 8852A-family (RTL8832AU) is
+  deliberately excluded. Quirks: `docs/8852c-quirks.md`.
+- **RTL8733B** (`src/rtl8733b/`): the 802.11n generation — RTL8731BU/RTL8733BU
+  (chip-id `0x16`), a HALMAC 87xx part, not a Jaguar variant: its own power,
+  firmware, MAC, descriptor and PHY paths. 1T1R, and the advertised surface is
+  only what an independent witness decoded — legacy OFDM + HT MCS0-7, BCC,
+  20/40 MHz on 2.4/5 GHz, plus long-preamble CCK on 2.4 GHz at 20 MHz, plus
+  10 MHz narrowband (5 MHz refused — `src/rtl8733b/CLAUDE.md`).
+  Everything the backend has not ported (TSF/beacons, A-MPDU, CCX/`tx.report`,
+  the flat-index and per-rate TX-power knobs) falls through to `IRadio`/`IRtlRadio`'s
+  not-ported defaults rather than being faked, so read the base class before
+  assuming a cross-generation feature below applies here. `FastRetune` IS
+  ported (intra-band, TSSI kept live — `src/rtl8733b/CLAUDE.md`). SGI, LDPC, STBC, VHT
+  and HE are refused outright. Scope, one-unit validation record and the
+  deferred matrix: `docs/rtl8733b.md`.
+
+Naming traps: **RTL8821AU is Jaguar1** (not Jaguar2, despite the Jaguar2
+RTL8821C's similar name); RTL8822**B**U (Jaguar2) ≠ RTL8822**C**U (Jaguar3);
+the TP-Link TX50UH is RTL8832**C**U (8852C-family) despite lab lore calling it
+8832AU, while the TX20U **Nano** is RTL8852BU; RTL8733B**U** is USB and
+supported, RTL8733B**S** is the SDIO sibling and has no transport here. Full
+chip / bench-throughput table: README **Supported hardware**.
+
+**PCIe** (`DEVOURER_PCIE=ON`, Linux-only, default OFF): the RTL8821CE — the
+PCIe sibling of the 8821CU — rides the same Jaguar2 HAL through a vfio-pci
+transport (`src/PcieTransport.{h,cpp}`: BAR2 MMIO registers over the same
+0x0000..0xFFFF space the USB vendor-control path addresses, 88xx
+buffer-descriptor DMA rings for TX/RX). USB and PCIe are independent
+transports behind `devourer::ITransport` (`src/Transport.h`); the
+bus-neutral `RtlAdapter` the HALs hold forwards to whichever it was built
+with. The few genuinely bus-specific bring-up steps gate on `is_usb()` (PCIe
+power-seq rows, PQ map, no USB RX-agg, no DLFW 512-pad) or ride `hci_setup()`
+(pre-power TRX ring programming, no-op on USB). Factory:
+`WiFiDriver::CreateRadioPcie(PcieTransport::Open(bdf, logger))` — the
+caller owns vfio like it owns libusb. Demos: `DEVOURER_PCIE_BDF=0000:01:00.0`
+on rxdemo and txdemo; `pcieprobe <bdf>` validates the layers bottom-up.
+Bind/restore: `tests/pcie_vfio_bind.sh` — driver_override, **not** new_id,
+because of the in-tree rtw88 auto-probe race. Validation: `sudo python3
+tests/pcie_rx_smoke.py` against a vfio-bound 8821CE.
+
+## Build
+
+```sh
+cmake -S . -B build
+cmake --build build -j
+```
+
+libusb-1.0 via `pkg-config` (Linux/macOS) or vcpkg (`VCPKG_ROOT`, Windows).
+
+The vendor kernel drivers under `reference/` are git submodules (fork rationale
++ layout in `reference/README.md`); `git submodule update --init --recursive`
+before running `tools/extract_*.py` or the hardware-testing kernel cells.
+
+Per-chip options, all default ON: `DEVOURER_JAGUAR1`, `DEVOURER_8814` (requires
+JAGUAR1), `DEVOURER_JAGUAR2_8822B`, `DEVOURER_JAGUAR2_8821C`,
+`DEVOURER_JAGUAR3_8822C`, `DEVOURER_JAGUAR3_8822E`, `DEVOURER_8733B`,
+`DEVOURER_KESTREL_8852B`, `DEVOURER_KESTREL_8852C`.
+`DEVOURER_PCIE` (default OFF, Linux-only, requires
+JAGUAR2_8821C) adds the vfio-pci transport + `pcieprobe`; OFF builds are
+byte-identical to before it existed. Turning groups off drops their firmware
+blobs + PHY tables (an 8812AU-only `rxdemo` is ~1.6 MB vs ~6.3 MB all-on — the
+verbatim-vendored Kestrel halbb/halrf plane dominates the difference).
+Configure fails on no-chip-selected or 8814-without-JAGUAR1. Each group
+exports a PUBLIC `DEVOURER_HAVE_*` define; sites referencing a dropped group
+sit behind `#if defined(DEVOURER_HAVE_*)`, and the factory returns `nullptr`
+(logs) for a chip whose support isn't built.
+
+`DEVOURER_SANITIZE=address|address+undefined|thread` (default off) builds the
+library, demos and selftests instrumented; the vendored halbb/halrf C is
+exempted from UBSan (Realtek's sources are full of unaligned loads and signed
+shifts — noise we would never act on). MSVC has AddressSanitizer only and
+rejects the other values rather than silently degrading. The demos are worth
+running under it on hardware, not just `ctest`: the lifetime bugs it finds
+(teardown, in-flight URBs) need a real device —
+`tests/tx_teardown_asan.sh` (max-duty TX killed mid-flight, incl. a real
+VBUS-cut wedge) and `tests/teardown_gen_sanity.sh` (every plugged generation
+init + teardown).
+
+CI (`.github/workflows/cmake-multi-platform.yml`): GCC/Clang/MSVC ×
+Ubuntu/macOS/Windows matrix, a `build-mingw` job, a `build-configs` matrix over
+each per-chip subset, `build-sanitizers` (ASan+UBSan `ctest`), and
+`reject-bad-configs` for the invalid option combos.
+`ctest` runs in every job (headless selftests — math guards + the
+`stream_stdin_binary` framing round-trip). Hardware testing is out-of-band.
+
+## Hardware testing
+
+`tests/regress.py` — 2×2 TX/RX matrix (devourer vs. kernel driver) over two
+plugged adapters. Run after building.
+
+```sh
+sudo python3 tests/regress.py                 # local kernel cells
+sudo python3 tests/regress.py \
+    --vm-name devourer-testrig --vm-ssh <user>@<VM-IP>   # pinned-kernel VM
+```
+
+VM mode (provision once with `tests/setup_vm.sh`) is required for chips whose
+vendor driver doesn't build on bleeding-edge kernels — notably the RTL8814AU.
+Default channel 6; pass `--channel 36` / `--channel 100` for 5 GHz — a
+single-band matrix is not comprehensive. Caveat: with the 8814 as TX, kernel-TX
+cells read 0 on every channel (`aircrack-ng/88XXau` doesn't emit host-pushed
+*beacon* injection) — judge 8814 TX by the devourer-TX cells.
+
+Layered modes: `--full-matrix` (every ordered DUT pair × 4 driver combos),
+`--encoding-matrix --tx-pid --rx-pid` (radiotap encoding combos; the kernel-TX
+rows are not authoritative for LDPC/STBC — that driver strips those bits —
+so truth-table runs add `--modes devourer:devourer`; per-cell `rx.txhit`
+events carry the decoded `rate`/`ldpc`/`stbc` as proof of what flew),
+`--sniffer-iface IFACE` (3rd-adapter capture, intended for AR9271).
+`--keep-logs` puts per-cell logs at `/tmp/devourer-regress-last/`. Full
+semantics: `tests/README.md`.
+
+Startup-time benchmarking: `tests/bench_init.py` (per-stage `init.timing`
+events from `src/InitTimer.h`; methodology + numbers in `docs/performance-tuning.md`).
+On-air TX throughput: measure **Mbps via SDR duty × PHY rate**
+(`tests/bench_onair.py`), never monitor-sniffer frame counts — a sensitive
+receiver decodes weak frames and masks a real drop. Keep a known-good control
+adapter, re-check it each session, and take one clean SDR read per session (a
+second back-to-back `sdr_duty` read can fail to reacquire and report ~0).
+
+Suspect a DUT itself (deaf with a green init, chronic FW-boot fails):
+`build/doctor` grades adapter health — EFUSE read-stability ×N, fw-boot,
+RX smoke → HEALTHY/SUSPECT/FAILING in the exit code (EFUSE stability is
+`IRtlRadio`-only; the other legs are `IRadio`);
+`tests/adapter_doctor_cold.sh` wraps it in per-rep VBUS cold + a vouched
+flood for a definitive verdict (`docs/adapter-doctor.md`). Two cold-init
+traps it encodes: the in-tree rtw88 modules auto-probe (and fw-download
+into) every Realtek dongle at each enumeration — `modprobe -r` does NOT
+survive re-enumeration, temp-blacklist instead; and `authorized`-toggle
+"cold" leaves chip state (real VBUS cold via `REGRESS_VBUS_MAP` /
+uhubctl — hub ports with per-port power switching only, not xhci root
+ports).
+
+## Logging
+
+Two planes (`docs/logging.md` is the schema source of truth): **machine events**
+= JSON Lines on stdout, one object per line, first field always
+`{"ev":"<name>",...}` — so `grep -F '"ev":"rx.txhit"'` works without a JSON
+parser, and `tests/devourer_events.py` (`iter_events`/`parse_event`) is the
+python helper every test script uses. **Human diagnostics** = stderr,
+`devourer [I] msg` (level letter T/D/I/W/E). Every line is written with one
+fwrite + flush, so piped consumers never stall on buffering and threads never
+interleave mid-line. `2>/dev/null` gives a pure event stream.
+
+Demo knobs: `DEVOURER_LOG_LEVEL=trace..silent` (stderr verbosity, default
+debug), `DEVOURER_EVENTS=stdout|stderr|off`, `DEVOURER_EVENT_FLUSH=0`
+(max-rate benches). Compile-time floor: `-DDEVOURER_LOG_MAX_LEVEL=WARN`
+compiles trace/debug out entirely (args included at `DVR_TRACE`/`DVR_DEBUG`
+sites) for production builds; unset = NDEBUG-derived. Exceptions kept as
+diffable text on the diagnostic plane: canary / bb / efuse / txpwr register
+dumps (kernel cross-validation format).
+
+## Configuration
+
+**The library reads no environment.** Construction-time knobs live in
+`devourer::DeviceConfig` (`src/DeviceConfig.h` — rx / tx / bf / tuning / debug /
+usb sections, every field doc-tagged with its env-var spelling and value
+grammar), passed as `CreateRadio`'s defaulted fourth argument. Mid-session
+knobs are runtime setters on `IRadio` (`SetTxMode`, `SetTxPowerOffsetQdb`,
+`SetTxPowerIndexOverride`, `SetRxPathMask`, `SetCcaMode`, `FastRetune`, ...).
+
+**Adapter capabilities**: `IRadio::GetAdapterCaps()` (`src/AdapterCaps.h`)
+aggregates chip identity, chain counts, the composed `GetTxCaps` +
+`GetTxPowerCaps`, channel widths, per-band tunable + characterized frequency
+spans, and feature flags — resolved at construction, thread-safe, callable
+pre-`Init`; the demos emit it as the `adapter.caps` JSONL event. Every flag is
+doc-commented at its declaration, including the bench-derived (not
+vendor-advertised) `ldpc_rx_*` and `vht_2g4_ok` truth tables and the three
+per-packet-TX-power hardware shapes — read the header, not a copy of it.
+
+Two facts that live only here: LDPC TX is per-packet radiotap-driven on all
+generations (`TxCaps.ldpc_ok`) with bench-measured coding gain ≈ +3 dB at the
+10%-delivery crossing, MCS7/20 MHz (`tests/ldpc_waterfall.sh`) — prefer
+`/LDPC` on any link whose RX side can decode it. And `GetActiveRxPaths()` is
+the live companion to the static caps: a best-effort per-chain-RSSI estimate
+of which antennas actually carry signal (needs an RX loop + traffic).
+
+The 5 GHz synthesizer tunes past the UNII channels (extended range
+~5080–6165 MHz, chan up to 253, `freq = 5000 + 5*chan`); out-of-band channels
+tune but their TX power / per-channel constants are extrapolated from the
+nearest characterized channel (one-shot `W` diagnostic). No regulatory
+enforcement — the caller owns compliance.
+
+**Env vars are the demos' interface**: `examples/common/env_config.{h,cpp}` is
+the authoritative mapping of every library-level `DEVOURER_*` var onto
+`DeviceConfig`, so the test scripts drive everything through env. For the
+per-var reference read the `env:` tags in `DeviceConfig.h` — do not look for a
+second copy here. Demo-local vars (device selection, timing, telemetry
+cadence) have no `DeviceConfig` field and are parsed in each demo's own code;
+those are the ones listed below.
+
+- `DEVOURER_PID=0xNNNN` / `DEVOURER_VID=0xNNNN` — restrict the device-open
+  loop (default VID `0x0bda`, all Realtek PIDs). `DEVOURER_USB_BUS=N` +
+  `DEVOURER_USB_PORT=a.b.c` select by USB topology when two adapters share
+  VID:PID **and** serial.
+- `DEVOURER_CHANNEL=N` — monitor channel.
+- `DEVOURER_TX_RATE=<rate>[/<bw>][/SGI][/LDPC][/STBC][/ER|/ER106][/DCM]` — TX
+  mode for rate-less frames (`MCS7/40/SGI`, `VHT2SS_MCS3/80/LDPC`, `1M`...).
+  Unset = 6M legacy. CCK rates are 2.4 GHz-only; `1M` buys ~9 dB link budget
+  over `6M`. Rate resolution never reads the band, so `VHT*` rates air on
+  2.4 GHz too — the non-standard NitroQAM/TurboQAM extension, confirmed on the
+  dies whose `AdapterCaps.vht_2g4_ok` is set, peer-decode required and the
+  256-QAM MCS8/9 points still unmeasured (`docs/vht-on-2g4.md`). `/ER`, `/ER106`, `/DCM` are HE-only (Kestrel): the HE ER SU
+  extended-range PPDU + dual-carrier modulation (`docs/he-extended-range.md`).
+  The library itself is radiotap-driven — a frame carrying its own rate
+  radiotap overrides the mode per-packet (ER SU = radiotap-HE FORMAT=EXT_SU).
+  Programmatic: `SetTxMode` / `ClearTxMode`.
+- `DEVOURER_SKIP_RESET=1` — skip `libusb_reset_device` before claim (only
+  helps when firmware state is intact). Kestrel adapters skip the reset
+  unconditionally — a USB reset on running firmware can land the chip in the
+  dead ZeroCD DISK id (`src/kestrel/CLAUDE.md`).
+- `DEVOURER_TX_GAP_US=N` — txdemo inter-frame gap (default 2000, ~500 fps;
+  `0` = max duty for heating experiments).
+- `DEVOURER_TX_FRAMES=N` — txdemo finite frame bound (default `0` =
+  unbounded). Exits through the ordinary `Stop()` path once N frames have been
+  submitted, so first-light and regression captures get a clean teardown
+  instead of a killed timed flood.
+- `DEVOURER_USB_DEBUG=1` — libusb DEBUG log level (~7 MB / 15 s, has filled
+  `/tmp` mid-capture; adds 0.5–0.8 s to init).
+- `DEVOURER_THERMAL_POLL_MS=N` — emit `thermal` events from the RF 0x42 meter,
+  on every generation (the poller rides `IRadio::GetThermalStatus`).
+  `raw` is 0..63 thermal units (~1.5–2 °C each, **not** absolute °C); `delta`
+  = raw − EFUSE baseline. **Telemetry only**: the poller emits and warns
+  (`DEVOURER_THERMAL_WARN_DELTA`, default 15) and never stops RX; no HAL gates
+  its send path on the meter. A rising delta is *suggestive*, not a validated
+  degradation predictor — `docs/warm-tx-degradation.md` has delivery scattered
+  63–83% with no relation to the meter, and inside one uninterrupted session
+  the meter stays pinned while delivery drifts.
+- `DEVOURER_LINKHEALTH=1` (rxdemo, needs `DEVOURER_RX_ENERGY_MS=N`) — classify
+  the RX sensor tuple via `src/LinkHealth.h`. **EVM, not SNR, is the
+  saturation tell**: strong RSSI + poor EVM means back power OFF, which is the
+  opposite of the weak-link response (`docs/bench-testing-near-field.md`).
+- `DEVOURER_LA_CAPTURE=<trig>/<rate>M/dma0/port:0x880` (rxdemo) — one-shot
+  LA-mode IQ capture to a `DVLA` file, offline per-tone H(k) via
+  `tools/la_csi.py`. Not on the 8812A/8821A (no LA block). Packing, per-chip
+  windows, trigger semantics and wedge risks: `docs/la-capture.md`.
+
+Behavioural traps the per-field docs can't carry:
+
+- `DEVOURER_TX_WITH_RX=thread` (concurrent TX+RX on one claimed handle:
+  `InitWrite` once, then `StartRxLoop` on a thread) must be set **before**
+  `InitWrite` on Jaguar3. This is the single-radio beamforming self-sounding
+  station: pair with `DEVOURER_BF_ARM_SOUNDER` / `DEVOURER_TX_NDPA` /
+  `DEVOURER_BF_DETECT_REPORT` (`docs/beamforming-self-sounding.md`).
+  Non-`thread` values select a `fork()` RX child that only works on Termux;
+  on regular Linux the forked bring-ups race and die.
+- `DEVOURER_RX_PATHS` (Jaguar1 RX-chain mask) routes through `SetRxPathMask`
+  and is **sticky** across `SetMonitorChannel`. Toggle spec
+  `0xAA:0xBB[:0xCC]@<ms>` cycles masks on a timer for mobility/MRC
+  measurements (`docs/measuring-spatial-diversity.md`,
+  `tests/mrc_mobility.py`). `DEVOURER_RX_ALLPATHS=1` emits per-chain
+  RSSI/SNR/EVM as a separate `rx.path` event on the four Jaguar/Kestrel
+  generations (Kestrel parses its halbb physts path pages; C/D nonzero only on
+  the 8814AU — the other dies are ≤2 RX chains; the 1T1R RTL8733B does not
+  emit it). Windowed per-antenna means ride `GetActiveRxPaths()` / the
+  `adapter.rxpaths` event (rssi/snr/evm per chain).
+- `DEVOURER_RX_KEEP_CORRUPTED=1` is the entry point for the fused-FEC salvage
+  layer (`docs/fused-fec.md`), and stays opt-in for a reason: a body with a
+  corrupt tail is the worst-case input for an IP-stack consumer that didn't
+  ask for it.
+- `DEVOURER_RX_CSI_MASK` / `DEVOURER_RX_NBI` apply at RX-loop start and
+  **revert on a channel switch**. Measured inert against a *jammed* slice —
+  that loss is pre-FCS sync/AGC, upstream of the equalizer. They target
+  in-band spurs on otherwise decodable frames
+  (`docs/pseudo-preamble-puncturing.md`).
+- `DEVOURER_DIS_CCA=1` (runtime `SetCcaMode` — the interface method is pure
+  virtual so no backend can silently no-op it)
+  disables the MAC carrier-sense gate — **both** primary CCA (`0x520[14]`)
+  and EDCCA (`[15]`). The default is carrier-sense + EDCCA **enabled** on
+  Jaguar1/2/3; on Jaguar1 the enable is real work — its BB table parks the
+  EDCCA thresholds (`0x8a4`) at never-trigger, so bring-up programs the
+  vendor adaptivity operating point (IGI-coupled; the phydm watchdog
+  re-tracks it when running). The primary-CCA bit is the one that matters:
+  monitor injection is not CCA-free, it defers ~40–60% to a co-channel
+  802.11 transmitter, and clearing `[14]` recovers ~1.5–2.2× (on-air
+  8822EU/8812CU, `tests/dis_cca_tx_onair.sh`); the energy bit `[15]` alone
+  is null against a decodable preamble. **On by default on the streamtx FPV
+  downlink** (the link owns the channel — CSMA backoff only stutters it);
+  `DEVOURER_DIS_CCA=0` forces standard carrier-sense back. On Kestrel the
+  8852C runs the same enabled default (measured: full-rate TX, 2.4x flood
+  deferral); the 8852B TX bring-up still clears the gates and WARNS pending
+  its measurement arm (`tests/kestrel_cca_default_check.sh`). On the RTL8733B
+  the disable is **not ported** — the HALMAC 87xx carrier-sense gate has not
+  been located and measured there, so `SetCcaMode(true)` throws (loudly, but
+  without tearing the session down) while `SetCcaMode(false)`, the state its
+  MAC bring-up already leaves programmed, succeeds as a no-op; setting the
+  config knob warns once at bring-up (RX-only sessions included) and airs
+  with carrier-sense. Does NOT apply
+  the vendor BB CCA-off writes (they deafen the RX). RX-decode side is a
+  separate null (`tests/dis_cca_onair.sh`).
+
+**Runtime TX power** — the adaptive-link power lever, three knobs on the four
+Jaguar/Kestrel generations: `SetTxPowerOffsetQdb` (relative,
+shape-preserving), `SetTxPowerIndexOverride` (flat absolute),
+`SetTxPowerRateDiffs` (replace the
+calibrated per-rate shape). The RTL8733B ports **only the first**, and on a
+different mechanism: its closed-loop TSSI target table, not a TXAGC index, so
+its caps report the dBm model (`index_max = 0`) over the int8 delta field's
+`[-128, +127] qdB`, centred on a safe 16 dBm first-light target. Neither end is
+re-clamped at something softer; where the chip stops responding — about
+-96 qdB down, about +32 up, where the PA compresses and only EVM shows it — is
+measured and documented rather than enforced. The flat index is refused there
+because it was measured unable to carry HT at all. The contract — how they
+compose, the MCS7-anchor
+semantics, family step sizes, the write-only-family `hw_readback=false`
+shadow, and Kestrel's software send-time fold — is documented at the
+declarations in `src/TxPower.h`; the per-chip mechanics are in each
+`src/<gen>/CLAUDE.md`. All three apply live and stick across
+`SetMonitorChannel` and `FastRetune`. None is regulatory-clamped: the
+operator owns compliance.
+
+`txpower` (`examples/txpower/`) is the reference consumer —
+`--rate-diffs cck,legacy,m0..m7|clear`, `--offset-start`/`--offset-stop`,
+`--flat`; `txdemo` maps the third knob as `DEVOURER_TX_RATE_DIFFS`. What each
+validation script actually proves matters on a write-only family:
+`tests/txpwr_offset_regcheck.sh` and `tests/txpwr_rate_diffs_regcheck.sh`
+check **register/shadow state management**, not radiated power —
+`tests/txpwr_rate_diffs_onair.sh` is the one that measures the antenna, per
+rate.
+
+**Per-packet TX power** — a radiotap `DBM_TX_POWER` dB-delta per frame, zero
+USB cost once armed. The three hardware shapes (Jaguar2 + 8814A descriptor
+LUT, Jaguar3 programmable BB banks, Kestrel fixed-dBm BB rewrite) are
+documented with the `per_pkt_txpwr_*` caps in `src/AdapterCaps.h`, and in
+full in each `src/<gen>/CLAUDE.md`. The 8812AU/8821AU have no descriptor field
+at all — their compensating fast lever is `FastSetTxPowerOffsetQdb`
+(BB-swing). Sweep harnesses: `tests/txpkt_pwr_ofset_onair.sh` (TX_PID/TX_VID
+select the DUT; Kestrel DUTs need `TX_PWR=14`-style dBm bases),
+`tests/txpkt_fastswing_onair.sh`, `tests/txpkt_hop_persist.sh`.
+
+Per-packet unequal error protection: `svctx` classifies stdin HEVC NALs by
+temporal layer and injects each at its ladder's rate
+(`DEVOURER_SVC_LADDER="CRIT=<spec>;T0=<spec>;..."`); the application-FEC half
+(RS outer code + corrupt-frame salvage) lives in `tools/precoder/`
+(`docs/fused-fec.md`).
+
+## Frequency hopping
+
+`IRadio::FastRetune(channel)` — lean intra-band, same-bandwidth retune on
+all five generations (RF channel switch only, write-only from a
+compose cache); falls back to full `SetMonitorChannel` on a band change.
+FHSS-grade on the Jaguar/Kestrel dies: ~0.5–2.5 ms per hop depending on chip.
+On the RTL8733B the hop keeps TSSI tracking live (per-channel rate-offset
+dwords rewritten in place) and costs ~55 ms call / ~10 ms p50 radio-live on
+the USB-HS validation unit — vs its ~330-440 ms full path — with a measured
+1-in-20 40 ms radio-live tail; one unit, no SDR (`src/rtl8733b/CLAUDE.md`). On the Jaguar2 dies (8822B, 8821C) and Jaguar3
+(8822C, 8822E), `DEVOURER_FASTRETUNE_FW=1` hands the hop to the chip firmware
+instead (H2C 0x1D, fire-and-confirm-later): ~1.4 ms dead air on the 8822B (a
+tie on-air on the 8822C/8822E, but ~3× cheaper host-side), and `=2` extends it
+to **cross-band** hops (~2–2.6 ms vs the ~90 ms full path) — protocol + bench:
+`docs/experiments/kernel-channel-switch-offload.md`. `send_packet` honours a radiotap `CHANNEL` field, so
+hopping is per-packet and radiotap-driven like rate. Demos hop via
+`DEVOURER_HOP_CHANNELS` (SweepSpec grammar: `1,6,11`, `36-48/4`, `5170-5250/5`
+MHz) + `DEVOURER_HOP_DWELL_FRAMES` / `_ROUNDS` / `_FAST` / `_RADIOTAP` /
+`_BW` / `_OFFSET`; `DEVOURER_HOP_PROF=1` emits per-stage `debug.hop_prof`
+timing. Validation:
+`tests/run_hop_validation.sh`, `tests/hop_parity_check.sh` (register parity
+full-vs-fast). Implementation + per-generation ports:
+`docs/frequency-hopping.md`.
+
+Above that primitive sits the **keyed FHSS / adaptive hopset** subsystem
+(`src/hopset/`, header-only and pure): keyed slot schedules and lockstep RX
+(`DEVOURER_HOP_SLOT_MS` + `DEVOURER_HOP_SEED`), a receiver-driven channel
+exclusion policy, and TX-side quiet-window sensing with endpoint fusion. Knob
+reference, policy thresholds, measured sensing constants and the on-air
+harnesses: `src/hopset/CLAUDE.md`. Article + results: `docs/fhss.md`,
+`docs/jammer-resilience.md`.
+
+`IRadio::FastSetBandwidth(bw)` is the bandwidth analogue — a lean
+same-channel toggle between 20 MHz and 5/10 MHz narrowband (baseband re-clock
+only; ~0.18 ms on the 8812AU vs ~90 ms for the full `SetMonitorChannel`);
+falls back to the full path for a 40/80 MHz endpoint. Validation:
+`tests/fast_bw_parity.sh`. See `docs/narrowband.md`.
+
+RX counterpart: `DEVOURER_RX_SWEEP` dwells FastRetune-cheap bins emitting
+per-bin energy + frame stats; `tests/sounding_sweep.sh` + `tests/sounding_map.py`
+recover a coarse per-bin H(f) — down to 5 MHz bins on Jaguar3
+(`docs/rx-spectrum-sensing.md`).
+
+## Adaptive channel migration
+
+Slow, evidence-driven whole-link channel moves — the deliberate complement to
+per-slot FHSS. Pure caller-side logic under `src/chanmig/`: a passive scout on
+a second adapter (`chanscout`), a two-leg scoring engine, an authenticated
+ground-proposes / drone-commits protocol (`examples/chanmig --role
+ground|drone`), and a deterministic automation gate
+(`DEVOURER_MIG_MODE=off|advisory|manual|automatic`, default `advisory`).
+Control frames are their own 802.11 frames — video PSDUs are never touched,
+and there is no regulatory DB: the caller owns compliance. Layer detail,
+validation matrix and the near-field bench note: `src/chanmig/CLAUDE.md`.
+
+## Hardware time, beacons, AP mode
+
+`ReadTsf()` reads the 64-bit MAC TSF and every received frame carries the
+MAC-latched `tsfl` RX timestamp — on the four Jaguar/Kestrel generations,
+µs-grade (`docs/time-distribution.md`, measured vs NTP/PTP:
+`docs/timing-accuracy.md`).
+`StartBeacon` loads a beacon into the MAC's reserved page and the chip
+auto-transmits at each TBTT with the live TSF stamped at the TX instant — the
+sub-µs downlink. The chip beacons **autonomously**, so `StopBeacon()` is what
+stops it mid-session; a session that ends via `Stop()` or destruction powers the
+chip down and takes the beacon with it (Jaguar1/Jaguar3 — Jaguar2 has no
+teardown power-down yet, so there it keeps airing until the adapter is
+re-enumerated).
+`UpdateBeaconPayload` swaps the airing content in place (frame-atomic on air,
+TBTT-quantized latency); `PinBeaconTbtt` steers the TBTT to an absolute TSF
+instant without corrupting the clock (Jaguar1: offset 0 only — its TBTT is
+hardware-locked to the TSF grid); `AdjustBeaconTimingFine` is the µs-fine
+manual lever. Demos: `timesync` (`DEVOURER_TSYNC_ROLE=master|slave|ue` +
+`DEVOURER_TSYNC_*` knobs, incl. the PCIe master + I226-PTP discipline loop)
+and `tdma` (TSF-slotted narrowband↔wide bursts on one channel). The beacon is
+also the seed of AP mode — a real Linux station associates, open or WPA2-PSK
+(`docs/ap-mode.md`); the multi-cell architecture it enables is
+`docs/multi-ap-cellular.md`, and the measured scheduler contracts (submit→air
+guard time, dynamic beacon grants, ACK/TxReport, per-UE RX attribution) are
+`docs/scheduled-mac.md`. None of this section is ported on the RTL8733B —
+`ReadTsf` returns 0 and `StartBeacon` returns false there.
+
+## Aggregation, hardware ACK, TX reports
+
+`SetAmpduMode` enables 802.11 A-MPDU on injected frames: ~+30% *goodput* at
+the PHY ceiling by amortizing per-frame overhead — an occupancy metric can't
+show it, count delivered payload. That number is high-MCS broadcast; the
+unicast-ARQ shape measured **−8%** delivered at MCS3, and per-frame CCX
+accounting does not survive AGG_EN (docs/aggregation.md) — under A-MPDU the
+receipts tier is the delivery truth. `SetAckResponder(mac)` arms the hardware
+ACK/BlockAck responder; with a unicast TA on the soliciting frame this closes
+a hardware-ARQ loop (autonomous MAC retransmission until ACK). The ACK's
+horizon is chip-FIFO **admission** (bench: 8812EU responder,
+`tests/arq_e2e_delivery.sh` per-frame ledgers): receiver-side congestion
+upstream of admission declines the ACK, so the loop sees and retries it — but
+a host stage that drops on a full queue while keeping URBs armed turns the
+same loss into ACKed-but-undelivered that the TX peer logs as delivered and
+never retries. The spsc-fat ring's `DEVOURER_RX_POOL_EXHAUST` policy is that
+choice (`src/DeviceConfig.h`): `backpressure` (default) parks exhausted URBs
+so the chip declines further ACKs and the loss stays ARQ-visible
+(`pool_stalls` in `rx.ring`; bench: 0 ACKed-but-undelivered under stalls that
+lose 5.5k+ frames on the `drop` policy, which remains opt-in and counted as
+`pool_dropped`). Per-frame TX
+outcomes surface as `tx.report` events (CCX via C2H) — the TX-side link
+sensor; C2H rides the RX path, so J1/J2 TX-only sessions see none (run
+`DEVOURER_TX_WITH_RX=thread`; J3's coex thread drains C2H regardless).
+`GetRxQuality()` is the device-wide windowed RX sensor;
+`cell::UeRxAttribution` is its per-transmitter (per-UE) counterpart. Docs:
+`docs/aggregation.md`, measured per-generation matrix `docs/scheduled-mac.md`.
+
+## Architecture
+
+**The caller owns libusb.** `WiFiDriver::CreateRadio` is intentionally
+thin — `libusb_init`, device open, kernel-driver detach, and
+`libusb_claim_interface(handle, 0)` must happen **before** handing the handle
+to the factory. `examples/rx/main.cpp` is the canonical boilerplate;
+`devourer::claim_interface_then_reset` (src/UsbOpen.h) is the recommended
+open path (advisory per-adapter lock before reset).
+
+Owning libusb means owning the **teardown order**: destroy the `IRadio`
+first, then release the interface, close the handle, and only then
+`libusb_exit`. The device is what quiesces TX (`IRadio::Stop`, and the
+destructor as a backstop: Jaguar1's async bulk-OUT URBs must be cancelled and
+reaped while the context still exists), so tearing libusb down first is a
+crash, not a leak — and only under enough TX load to keep URBs outstanding at
+exit. `examples/common/DeviceSession.h` is the demos' RAII holder for exactly
+that order; the transport logs a diagnostic naming this if it is destroyed
+with TX still in flight.
+
+**Chip identity is resolved at construction** from the `SYS_CFG2` chip-id +
+USB PID. `CreateRadio` returns an `IRadio` (`Init` = bring-up + RX
+loop; `InitWrite` = TX bring-up; `StartRxLoop` = blocking RX worker on an
+already-up chip, enabling TX+RX on one handle; `send_packet`) and constructs
+`RtlJaguarDevice` / `RtlJaguar2Device` / `RtlJaguar3Device` / `RtlKestrelDevice`
+/ `Rtl8733bDevice` per backend. `Rtl8812aDevice` is a deprecated alias of
+`RtlJaguarDevice`. The five Realtek backends derive from `IRtlRadio`
+(`src/IRtlRadio.h`), the Realtek-only extension of `IRadio` — the header
+carries the member list and the downcast contract. Optional device methods
+are **virtual with not-ported defaults**, not pure virtual — a backend that
+hasn't ported a feature inherits
+`false`/`0`/a full-path fallback rather than a fake. Check the override list in
+the backend's header before believing a cross-generation claim.
+
+Generation-agnostic core in `src/` (always compiled; depends on no HAL):
+
+- `IRadio` (`src/IRadio.h`) — the vendor-neutral radio contract every backend
+  implements; `WiFiDriver::CreateRadio` returns one.
+- `WiFiDriver` — the factory (`CreateRadio`).
+- `DeviceConfig.h` — construction-time configuration struct; every component
+  copies the sub-struct it consumes at construction.
+- `RtlAdapter` — the bus-neutral register/frame accessor; a copyable value
+  type shared by every component, forwarding to the `ITransport` it was
+  built with (`UsbTransport` = libusb vendor control + bulk; `PcieTransport` =
+  BAR2 MMIO + DMA rings). `RtlUsbAdapter` is a deprecated alias.
+- `Radiotap.c` — radiotap iterator. TX buffers passed to `send_packet` **must**
+  begin with a radiotap header; rate/MCS/VHT/STBC/LDPC/SGI/bandwidth are read
+  from it.
+- `RateDefinitions.h`, `RxPacket.h`, `TxDescBits.h` — symbols all generations'
+  parsers build on, kept neutral so no generation's header pulls in another's.
+- `PhyTableLoader` — runtime walker for Realtek's phydm-format register tables
+  (`check_positive` + opcode state machine, without pulling in phydm itself).
+  Shared by Jaguar1 + Jaguar2; Jaguar3 has its own `PhyTableLoaderJaguar3`.
+- `cell/` — caller-side per-cell helpers built on the device API
+  (`UeRxAttribution`: per-transmitter windowed RX statistics keyed by 802.11
+  TA); the device RX loops are untouched.
+
+Per-backend HALs are self-contained under `src/jaguar1/`, `src/jaguar2/`,
+`src/jaguar3/`, `src/kestrel/`, `src/rtl8733b/`; each subtree's `CLAUDE.md`
+maps its files, strategy seams and chip-specific mechanisms.
+
+`hal/` holds vendor headers and tables. The per-chip PHY/limit tables and most
+firmware blobs are **generated** by `tools/extract_*.py` (check `tools/` for
+which — the set has grown) — edit the generators, never the output files. The
+newer extractors (`extract_8733b_*.py`) pin per-source and per-array SHA-256
+hashes and carry a `--check` mode that reproduces the checked-in output
+byte-for-byte; prefer that shape when adding one.
+
+## Hardware gotchas
+
+- **ZeroCD trap**: some Realtek dongles enumerate first as USB mass-storage
+  (`0bda:1a2b`) exposing a Windows installer, then re-enumerate as the NIC. If
+  `libusb_open_device_with_vid_pid` returns NULL, check `lsusb` — may need
+  `usb_modeswitch`.
+- **rmmod/sysfs-unbind actively de-inits the chip** (RF off, MAC DMA off).
+  After detaching a kernel driver, expect a cold re-init; `DEVOURER_SKIP_RESET`
+  only helps when firmware state is intact.
+- **The chip retains state across soft re-init** — cold-bisect hardware
+  problems with a VBUS power-cycle, not a re-run.
+- **Qualify the ground station before believing a delivery number.** Delivery is
+  a property of a *link*; a receiver whose modulation cliff sits at the rate
+  under test measures itself, not the transmitter, and swings between "fine" and
+  "zero" on a few dB of ambient while the robust rates stay pinned — which looks
+  exactly like a transmitter that degrades and recovers. Same TX, same channel,
+  minutes apart: a TP-Link Archer T3U (8822BU, **internal** antennas) ran
+  MCS3 97.8 / MCS4 98.3 / MCS5 79.1 / MCS6 49.0 / **MCS7 2.9**, while an
+  RTL8814AU (two **external** antennas) was flat at ~80% across the same ladder.
+  Both healthy — one just has less margin. `tests/ground_station_qualify.sh`
+  sweeps the ladder and refuses the pairing (exit 1) when the test rate is off
+  the flat part. Prefer external-antenna adapters as ground stations for
+  high-MCS work, and cross-check with a second, independent receiver.
+- **A single delivery probe is worth ±3 points, so small effects are not
+  findings.** Ten identical back-to-back MCS7/20 probes on an 8812AU (nothing
+  changed between them) gave sd 1.8 and a 5.7-point spread; the MCS1 control
+  over the same run held 98.0 ± 0.2. Anything under ~4 points needs repetition
+  before it means anything — several plausible-looking "decay curves" have
+  turned out to sit inside that band. `tests/probe_repeatability.sh` measures
+  the floor for a given pair; run it before believing a delivery difference.
+- **Do not attribute a rate ceiling to chip temperature without varying
+  temperature independently.** Delivery does correlate with the `thermal` meter
+  within a probe sequence, and that correlation is a trap: a sweep varying
+  *only* the power-off duration (identical reset every arm) found delivery
+  scattered 63–83% with no relation to off-time or temperature, and inside a
+  single uninterrupted session the meter stays pinned while delivery drifts.
+  Read the `thermal` event (`DEVOURER_THERMAL_POLL_MS`) beside a rate-ceiling
+  number by all means, but a power cycle changes chip state *and* temperature
+  together, so it can never separate them (`docs/warm-tx-degradation.md`).
+- **MediaTek Android hosts cap bulk-IN reads at 16 KB**: some MTK xhci/usbfs
+  stacks (Dimensity 810, Helio G99, MT6765) never complete a larger bulk-IN
+  transfer — `LIBUSB_ERROR_TIMEOUT` forever, zero RX with a green init
+  (OpenIPC/PixelPilot#6). The 11ac RX rings therefore post 16 KB URBs paired
+  with ≤16 KB device-side aggregation caps (`DeviceConfig::Rx::urb_bytes`,
+  `DEVOURER_RX_URB_BYTES`); raise both together or MTK hosts go silent, and
+  never let an aggregate exceed the URB size or the parse walk breaks.
+  Kestrel is exempt (8852C RXAGG LEN_TH ~20 KB needs its 32 KB ring) and
+  unvalidated on MTK hosts. The RTL8733B is the worked example of the failure:
+  its vendor-default 20 KiB aggregate was observed being split by xHCI across
+  16 KiB completions, tail and body landing separately. It now caps the device
+  at 12 KiB and floors its URB at the same constant, tied together by a
+  `static_assert` — raising one alone reintroduces the straddle.
+
+## TX path
+
+```cpp
+auto logger = std::make_shared<Logger>();
+WiFiDriver driver(logger);
+auto dev = driver.CreateRadio(handle);  // handle is already claimed
+dev->InitWrite(SelectedChannel{ .Channel = 36, .ChannelOffset = 0,
+                                .ChannelWidth = CHANNEL_WIDTH_20 });
+dev->send_packet(buffer, len);  // buffer[0..] = radiotap header, then 802.11
+```
+
+The canonical test beacon (`examples/tx/main.cpp`) uses SA
+`57:42:75:05:d6:00` — the same constant is hardcoded into
+`examples/rx/main.cpp` as the `rx.txhit` event matcher and into
+`tests/regress.py` (`CANONICAL_SA`). Change all three together if it ever
+moves.
+
+**TX transfer mode is deliberately per-generation**
+(`docs/performance-tuning.md`): Jaguar1 submits asynchronously
+(`RtlAdapter::send_packet` → `tx_async`, caller-thread completion reaping —
+its USB2 round-trip is too long for a blocking send to saturate the link);
+Jaguar2/Jaguar3 send synchronously (`bulk_send_sync_ep` → `tx_sync` — their
+USB3 round-trip saturates on one blocking thread, and sync gives the HalMAC
+bring-up a clean per-send NAK backoff); the RTL8733B is synchronous too, so
+every submission has a bounded result and no buffer outlives the `send_packet`
+call. Don't unify the modes — either direction regresses throughput or
+bring-up safety.
+
+**Nothing reads a register per frame on the send path.** Measured on one
+RTL8733B unit during bring-up: a single thermal read (3 RF writes + a 15 µs
+settle + an RF read, each several USB control transfers) cost 2.51 ms of a
+2.71 ms per-frame budget on USB high speed — 93%, for a meter that tracks PA
+bias and is not a validated degradation predictor. One bench, one part, and a
+USB3 host would divide it; the shape of the result is the transferable part.
+Sensor reads belong on the caller's own cadence via the runtime getters, never
+inside `send_packet`.