Quiesce TX before libusb teardown (#281); fix Kestrel CCK + wide-bandwidth RX (#343)

[josephnef]

Two bugs that a sanitizer build found in the same session. They are independent
— separate commits — but they share the reason nobody had seen them: neither is
reachable from ctest, and one of them is invisible to the measurement we
normally trust.

1. TX teardown — fixes #281

txdemo segfaults inside libusb on teardown when killed during max-duty TX on
a Jaguar1 adapter, and exits cleanly at DEVOURER_TX_GAP_US=2000. Two defects
hid behind that one signature.

The crash is a teardown-order bug. ~UsbTransport pumped
libusb_handle_events whenever transfers were in flight, but the demos
destroyed their IRtlDevice at end of main — after libusb_release_interface
/ close / exit — so the pump ran on a context libusb had already freed. Only
reachable with URBs outstanding at exit, i.e. exactly gap 0. EepromManager
appears in the backtrace only because it holds an RtlAdapter by value and is
declared first, so it drops the last transport reference; reordering members
would move the frame, not fix anything.

SEGV on unknown address 0x14 ... /usr/lib/libusb-1.0.so.0
  #3 devourer::UsbTransport::~UsbTransport()   UsbTransport.cpp:269
  #11 RtlJaguarDevice::~RtlJaguarDevice()      RtlJaguarDevice.cpp:1823
  #15 main                                     examples/tx/main.cpp:2061

The second defect: RtlJaguarDevice::send_packet/send_packets built the
URB in a local std::vector and handed .data() to a fire-and-forget
libusb_submit_transfer. libusb requires that buffer to outlive the transfer.
Linux usbfs copies the payload at submit, so it is invisible there — but it is a
real bug on the backends that keep the caller's pointer.

Fixed at the transport seam:

• IRtlTransport::quiesce_tx() — cancels every outstanding transfer, reaps
  the completions, refuses further sends; bounded by a deadline that reports
  tx.quiesce_timeout rather than hanging teardown. Called from
  IRtlDevice::Stop() and from every device destructor, i.e. while all owners
  are alive. Jaguar1 gains a Stop() override for it — TX quiesce only,
  deliberately not a card-disable power sequence, which this family has
  never run.
• tx_async copies the payload into a transport-owned buffer freed in the
  callback. Symmetric alloc/free rather than LIBUSB_TRANSFER_FREE_BUFFER,
  which would cross CRT heaps on Windows.
• examples/common/DeviceSession.h owns device → interface → handle →
  context and unwinds in that order; every demo adopts it, which also fixes the
  resources their early returns leaked.

Jaguar1-over-USB is the only asynchronous submitter in the tree, so the other
generations are unaffected — their quiesce finds nothing in flight.

Validation (RTL8821AU, ASan build): 4/6 cells crash before, 9/9 clean
after — including SIGINT, the aggregation URB, and a real VBUS cut mid-flood
(NO_DEVICE completions, prompt quiesce, adapter re-enumerates). On-air
throughput unchanged (49.9/39.2 → 49.8/39.2 Mbps at 2.4/5 GHz); regress.py
green on ch6 and ch36; all generations clean under ASan.

2. Kestrel RX — fixes #343

The Kestrel receiver was dead in two whole regimes: no CCK at all on 2.4 GHz,
and nothing above 20 MHz. 20 MHz OFDM was fine on both bands and TX was fine
at every width, which is why it survived — the 40/80 MHz validation rested on
SDR transmit duty, and a duty measurement cannot see a broken receiver.

HalKestrel::set_channel passed halbb_ctrl_bw_ch a primary sub-band index
where the vendor wants the primary channel number (phl hands it
rtw_chan_def::chan unchanged). Inside, pri_ch is used three ways, all
receive-side: it indexes the 2.4 GHz CCK SCO threshold tables at pri_ch - 1,
it is compared against central_ch to derive the 0x4978[11:8] sub-band index,
and it places the NBI spur notch. At 20 MHz the index is 0, so the CCK path
reads that table at -1 — the stack-buffer-underflow that surfaced all of this.

cell	before	after
CCK 1M @ ch6, RX 20 MHz	0	57
OFDM 6M @ ch6, RX 20 MHz	56	56 ← control
OFDM 6M @ ch36, RX 20 MHz	57	57 ← control
OFDM 6M @ ch36, RX 40 MHz	0	57
OFDM 6M @ ch36, RX 80 MHz	0	57
Kestrel TX 20/40/80 → ref RX	38	38

RTL8832CU against an RTL8821AU emitter, hits over 12 s, each figure reproduced
twice. The 8852B backend has the identical function, so that die is affected the
same way — untested here for want of a plugged one.

Tooling

DEVOURER_SANITIZE=address|address+undefined|thread builds the library, demos
and selftests instrumented (vendored halbb/halrf exempted from UBSan; MSVC
restricted to its ASan and made to error rather than silently degrade), plus a
build-sanitizers CI job running ctest under ASan+UBSan.

The bugs this class produces need a real device, so the hardware harnesses carry
the weight: tests/tx_teardown_asan.sh, tests/teardown_gen_sanity.sh,
tests/kestrel_prich_onair.sh. All three take BUILD=<dir>, which is how each
before/after table above was produced. One new headless test,
tx_quiesce_seam, guards the wiring; ctest is 47/47 under ASan+UBSan.

🤖 Generated with Claude Code