MT7612U integration: wire src/mt7612u in behind IRadio

[josephnef]

Tracks the integration of the MediaTek MT7612U subtree (src/mt7612u/, landed unwired in #412 and hardened in #414) behind the vendor-neutral radio contract from #415. Until this lands the subtree builds only through its own Makefile and no devourer binary can open an MT7612U.

Scope

• CMake: DEVOURER_MT7612U option (default OFF), following the DEVOURER_HAVE_* pattern; the subtree's pthread/nanosleep/clock_gettime swap to <thread>/<chrono> so MSVC and mingw build it (Windows is first-class here).
• Factory: a vendor-neutral VID:PID gate in WiFiDriver::CreateRadio ahead of the Realtek SYS_CFG2 read, the way Kestrel gates PID-first — on MediaTek silicon that read is the wrong protocol, not merely ambiguous. An unrecognised non-Realtek VID must refuse rather than fall through to Jaguar1. ChipGeneration entry for MediaTek.
• Transport: MediaTek gets its own transport behind the same factory, not a shim over ITransport (32-bit registers plus in-band MCU over EP8/EP5 do not fit the Realtek shape). The C library is the transport; adopt the handle WiFiDriver already opened, reset and claimed via mt7612u_open_handle().
• IRadio implementation over the C library: Init/InitWrite/StartRxLoop/SetMonitorChannel/send_packet(+send_packets)/GetSelectedChannel/SetCcaMode (implement or refuse loudly), caps, ACK responder, TSF, link quality. Unsupported optional members keep the not-ported defaults; unavailable measurements report invalid, never fabricated IGI/NHM values.
• The 1 Hz PHY tick lives inside the backend, on a backend-owned worker thread (the Jaguar3 phydm-thread shape), not as an IRadio method. Stop/join it before teardown; serialize whole channel-change / power operations against it (the recursive io_lock protects nested transactions, not a full channel change); never run calibration from an RX completion callback.
• RX-loop stop semantics: StopRxLoop() must not map onto mt7612u_rx_stop() — that cancels both rings without disabling MAC RX first. Preserve disable-RX-before-removing-the-drain and shared ring ownership so RX is restartable.
• FCS contract: Packet::Data promises a trailing FCS; the MT7612U MAC strips it and the 4–7 trailing bytes are the FCE info trailer, not a CRC. Add explicit FCS-presence metadata to the RX type and make it reach every consumer that trims four bytes before the factory dispatches to MediaTek.
• RSSI units: devourer carries RSSI as an unsigned byte biased by 110; the C library reports signed dBm. Convert at the boundary (a raw cast reported −63 dBm as +83).
• Firmware: the library loads mt7662.bin / mt7662_rom_patch.bin from a directory at runtime; every Realtek backend embeds its blob. Decide embed-vs-runtime-path and plumb the choice through DeviceConfig (no environment reads in the library). MT7612U_DEV selection likewise moves to a config field / open-with-selector.
• Logging: route the subtree's stderr diagnostics through devourer's Logger (a sink hook on the C library); JSONL events for adapter.caps and the RX/TX planes as the demos expect.
• Validation: regress.py cell against the MediaTek vendor driver under reference/; ctest cells; mt7612uprobe beside kestrelprobe/rtl8733bprobe; on-air TX and RX figures on the same bench as the Realtek table in the README, with the adversarial counterpart stated in the same breath.

Follow-ups that fall out of it (separate issues if they grow)

• A neutral frame-free energy type, so hopset TX-side sensing, chanmig probing and chanscout dwells stop being Realtek-only (GetRxEnergy sits on IRtlRadio since Rename the radio contract to vendor-neutral names (IRadio, ITransport, CreateRadio) and split the Realtek-only members onto IRtlRadio #415).
• RxQuality.h / AdapterHealth.h still expose Realtek types transitively through IRadio.h.
• The hard TX_BUSY-stuck USB wedge tier has no proven recovery (bringup swreset is implemented, unverified for want of a reproduction).

Known limits of the part, so nobody expects them

No fast retune (≈50 ms fast / ≈530 ms full — FHSS and per-packet hopping are out of reach), no 5/10 MHz narrowband (no encoding in MT_RATE_BW), no HE, no 160 MHz, no beacons/TBTT, unicast injection is a 40× cliff (address one-way links to broadcast/multicast). Measured record: docs/mt7612u.md.

Refs: #412, #414, #415.

[snokvist]

Picking this up. #420 is the first item — the FCS contract — as its own PR, because the metadata has to reach consumers before the factory can dispatch to a backend that has no FCS, so it gates the rest.

It turned out much smaller than the checklist line suggests: a full sweep found exactly two C++ sites that trim four bytes (BfReportDecode.h, BfReportDetect.h) plus one offline tool, zero sites that read those bytes as a CRC, and no pcap writer or RX radiotap emission — so there are no capture-file semantics to change. Defaulted true, no Realtek parser touched, no-op by construction.

Two decisions I've taken rather than asked about, both from the repo's own precedent — flagging them here so they're cheap to overrule now rather than at review:

• Threading: compile the subtree as C++ and use std::recursive_mutex / std::thread / <chrono>, as the issue asks. Measured cost: 0 C++ keyword collisions (all 118 grep hits were comment prose), 5 malloc/calloc casts, 4 timing sites. src/jaguar1/PhydmWatchdog.cpp is the worker-thread precedent I'll follow for the 1 Hz tick.
• Firmware: embed the blobs, with a DeviceConfig path override. Every Realtek backend embeds, and the rootless-Android case has nowhere natural for a runtime path. One thing that is yours rather than mine: whether MediaTek's linux-firmware blob may be redistributed in this repo. Say the word and I'll switch to runtime-path-only.

Planned order after #420: CMake option + subtree portability + the VID gate (no radio yet — testable by whether an unrecognised non-Realtek VID refuses instead of falling through to Jaguar1), then the IRadio backend, then validation.

Two notes from building against the contract, in case they shift your view of the scope:

• IRadio has only 6 pure virtuals after Rename the radio contract to vendor-neutral names (IRadio, ITransport, CreateRadio) and split the Realtek-only members onto IRtlRadio #415 (InitWrite, StartRxLoop, SetMonitorChannel, send_packet, GetSelectedChannel, SetCcaMode) — the Realtek-only members moving to IRtlRadio took most of the surface off the table, so the backend is a lot less than the checklist implies.
• StopRxLoop's "disable RX before removing the drain" is already in the subtree as mt_mac_rx_disable() — it went in as the teardown-ordering fix in mt7612u: fix the receive collapse (1 Hz PHY tick) and recover the USB wedge #414, so that bullet is mostly wiring rather than new work.

[snokvist]

@josephnef — all four blocks are on the remote and every scope box is covered. Nothing here is waiting on me; three decisions are waiting on you.

The stack

Each branch is cut from the previous, so each PR's diff shows its parents. Merging them in order rebases each to just its own commits.

PR	block	head	CI	review threads
#420	FCS contract	31cb738	all green	0 open
#421	CMake, C++ portability, factory gate	58f508b	all green	0 open, CLEAN
#422	the IRadio backend	f38b8d5	22/22	1 open (below)
#423	validation	6b73e9f	22/22	4 open (below)

Happy to retarget any of them at master individually, or to squash the stack, whichever suits you.

One thing that looks worse than it is: #420 shows BLOCKED with zero unresolved threads and every check green. qodo-gate posted 13 check runs on that commit — three failures, then ten successes — and the early failures still count against the rollup. I have not re-pushed to clear it, because three branches are stacked on that commit and it would force a rebase of the other three PRs to fix a cosmetic gate state. Say the word if you would rather I did.

Decisions I need from you

1. Should rx.pool_exhaust=Backpressure be fatal on this part? (#422, #423)

DeviceConfig promises the non-SpscFat modes "never drop host-side". This part cannot keep that: backpressure here means an undrained EP4, and an undrained receiver wedges the chip below the USB level — libusb_reset_device, the sysfs authorized toggle and rebinding the kernel driver all fail, only a physical replug recovers it. Honouring the default literally is the exact failure the RX hand-off queue exists to prevent.

Today it warns once at bring-up, then drops the newest frame and counts every drop. The alternative is to refuse at bring-up so a caller opts into the drop policy explicitly. One-line change either way — I did not want a default configuration to start refusing adapters without you choosing it.

Datapoint: across every measured cell of the regression matrix, including one carrying 21842 frames at ~1360 fps, the drop path never fired.

2. Does the reference/mt76 gap block #423?

The Validation bullet asks for the matrix against the vendor driver under reference/. I ran it against the host's in-tree mt76x2u (6.14.0-37) — the same codebase, a different revision — and said so in docs/mt7612u.md. Loading reference/mt76 @ be5ce79 on this host means replacing the mt76 core module, refcount 9, with mt7921e among its users, i.e. the machine's own Wi-Fi.

regress.py's VM mode is the designed way round exactly that, and has never been provisioned for MediaTek. So this is not done, not not possible. It is a VM provisioning job rather than a code change. Your call whether it blocks the block or becomes a follow-up issue.

Worth weighing: the transcription from the pinned revision is checked byte-for-byte by two new cells that pin the vendor file's SHA-256. What the in-tree run cannot tell you is whether interop holds specifically at be5ce79.

3. May MediaTek's linux-firmware blob be redistributed in-tree?

Flagged in #422 and still open. Every Realtek backend embeds its firmware; mt7662.bin / mt7662_rom_patch.bin ship under their own licence and zstd-compressed, so today they are a searched path (DeviceConfig.mt7612u.firmware_dir). If the answer is yes, embedding them is a small change and I will make it.

The other open threads, and why they are open

• The retune race (mt7612u: block D — regress.py against the vendor driver, and the cells the backend was missing #423). mt_read_rx_gain() rewrites lna_gain/rssi_offset[] while mt_rx_parse() reads them per frame, so a frame parsed mid-retune gets a mixed RSSI correction. Real, found with ThreadSanitizer on hardware, and on docs/mt7612u.md's Open list with the fix it wants. It is in the C library, not in Mt7612uRadio — TSan reported nothing inside that class. For scale, the same stress on the shipping RTL8812AU path gives 8 reports, all in RtlJaguarDevice.cpp/RtlAdapter.h. Retune-during-RX is not race-free anywhere in this project today, which is why I left it recorded rather than fixed here.
• "StartRxLoop after InitWrite cannot receive" (mt7612u: block D — regress.py against the vendor driver, and the cells the backend was missing #423). Declined with the check: InitWrite() never creates an async ring — mt_async_start() is reached only through mt7612u_rx_start(), and tx.cpp:229 falls back to a synchronous bulk transfer when d->a is NULL — so the early-out that finding describes is unreachable from that sequence. Left open in case you read the ownership differently.

Two more library-side gaps are recorded in docs/mt7612u.md Counterparts rather than left as review threads: TxStats::failed counts refusals rather than wire deaths (needs a monotonic wire-failure counter in the C library), and the log sink is process-global (needs mt7612u_set_log_sink(dev, ...)). Both are small public-header changes I am happy to make if you want them in this stack rather than after it.

What block D actually measured

tests/regress.py now runs its four-cell matrix on this part — two MT7612U units, mt76x2u on whichever side each cell calls "kernel". Twenty cells over five runs, both bands, every one green on its first attempt. The kernel driver decodes our frames as 6.0 Mb/s 5180 MHz 11a and 2437 MHz 11g with a per-antenna breakdown, so the TX evidence is an independent decoder rather than our own reading of our own transmit.

Three new ctest cells, five MediaTek total. mt7612u_rx_queue is the first to cover backend behaviour rather than a lookup, mutation-tested ten ways and clean under TSan and ASan+UBSan.

Running it found three bugs in the harness itself, two of them latent for any same-model pair: _wlan_iface_for_dut matched by VID:PID and took the first hit, so a kernel cell could tcpdump the very adapter devourer had claimed; --keep-logs called os._exit after print() on a block-buffered pipe and discarded the table it exists to preserve; and _count_tcpdump_hits counted a trailing blank line, so every kernel-RX figure this harness has ever published was one high — which is how a baseline cell came to report a suspiciously perfect 459 / 459 when 458 of 459 arrived. The published tables are re-measured with that fixed, not corrected by hand.

Two honest limits on those numbers, both in the doc at the same length as the numbers: a ✓ is one frame at the default threshold, and the counts are not a stable measurement — the same devourer-TX → kernel-RX cell read 9077, 8921 and 6758 across three ch36 runs against a near-constant ~9400 offered. The verdict repeats; the counts do not. That is why the README's bandwidth cells for this part carry a marker rather than a number.