mt7612u: DEVOURER_MT7612U option, C++ portability, and a factory gate that stops the Jaguar1 misroute

[snokvist]

Stacked on #420. This branch is cut from that PR's head, so the diff shows
its four commits too (8c5dd0d, eb10389, 8dd504c, 31cb738 — the FCS
contract). The five that belong to this one are dde4766, cdbb72d,
20e0b7e, 9238f39, b839df3. Merge #420 first and this rebases to nothing;
happy to retarget it if you would rather they went in together.

Second block of #419. Takes the two scope items that do not need a radio: the
DEVOURER_MT7612U option with the portability work behind it, and the factory
gate. There is still no IRadio backend — CreateRadio recognises the MediaTek
ids only to refuse them.

The bug the gate fixes, measured

CreateRadio ends in an unconditional Jaguar1 construction, and read_chip_id()
discarded its libusb return code. So a device that does not answer the Realtek
SYS_CFG2 vendor read arrived there as chip-id 0x00 and was brought up as an
RTL8812AU. Both arms of the same control transfer, on this bench:

bmRequestType 0xC0, bRequest 5, wValue 0x00FC, 1 byte

  RTL8812AU  0bda:8812   rc=1                        chip_id=0x04
  MT7612U    0e8d:7612   rc=-7 LIBUSB_ERROR_TIMEOUT  destination byte UNTOUCHED
  MT7612U    0e8d:7612   rc=-7 LIBUSB_ERROR_TIMEOUT  (second adapter, same)

The MediaTek arm ran with a 0xAA poison byte in the destination and it
survived, so the 0 that reached the dispatch was the caller's own initialiser,
never a reading. read_chip_id's own comment already described the consequence
— "Returns 0 on a failed read, which falls through to the Jaguar1 path" — this
just makes it not happen.

Two guards, both ahead of the Realtek read:

• Mt7612uUsbIds.h — the complete 16-entry mt76x2u_device_table, taken from
  the pinned reference/mt76 @ be5ce79 so it is re-verifiable from a fresh
  checkout, gated the way Kestrel gates.
• read_chip_id returns std::optional — nullopt when the transfer
  failed. A successful read of 0x00 still returns a value and keeps its
  existing fall-through, so no cold-boot transient changes behaviour.

Why the gate is vid:pid, and not what the issue asked for literally

The scope item says "an unrecognised non-Realtek VID must refuse". I did not
implement that, because it would refuse working adapters. Six vendor ids ship
both silicon families, and they do not merely coexist — they interleave inside
one vendor's product-id range:

vendor	MediaTek ids	Realtek ids
0x0846 Netgear	9014, 9053	9051, 9052, 9054
0x056e ELECOM	400a	4007, 400b, 400d, 400e, …
0x0b05 ASUS	17eb, 180b, 1833	17d2, 1817, 1852, 1853, 1a62
0x2357 TP-Link	0137	0101, 0103, 0106, 010d, …
0x7392 Edimax	b711	6822, a811, a812, a813, …
0x2c4e Mercury	0103	0127

The pairs, by contrast, are disjoint: none of the 16 MediaTek ids matches any
of the 91 Realtek ids devourer can serve. That is the same property the
Kestrel gate already relies on. The transfer-failure guard then covers the intent
behind the scope item without the cost — it refuses every non-Realtek part,
named or not. Say the word if you want the literal vendor-id rule as well; I
think this pair is strictly better, and the table above is why.

Portability

The subtree is now C++ (.cpp), so there is one compilation mode rather than a
second path that can rot unnoticed. Cost measured by compiling each file with
g++ -std=c++20 -Wall -Wextra before changing anything: 12 sites in the
library (11 implicit void* conversions, 1 uint8_t→enum) and 40 in bringup,
32 of which cascaded from three _Atomic declarations. No C++ keyword
collisions, no VLAs, no compound literals, no tentative definitions; both
designated initialisers were already in declaration order.

pthread_mutex_t          -> std::mutex
io_lock (recursive)      -> std::recursive_mutex
pthread_cond_t           -> std::condition_variable_any
pthread_t                -> std::thread
nanosleep                -> std::this_thread::sleep_for
clock_gettime(MONOTONIC) -> std::chrono::steady_clock

condition_variable_any rather than condition_variable so it waits on the
bare mutex and every lock site keeps its original shape — a much smaller diff
through code whose teardown ordering is documented as a use-after-free hazard.
Those waits are teardown and TX back-pressure, never a hot path.

The exported surface is still C. include/mt7612u/mt7612u.h already had an
extern "C" guard and tests/api_link.c is deliberately still compiled by
$(CC), so the ABI is tested rather than asserted: it resolves 25 entry points
against the C++ objects, and nm shows the public symbols unmangled.

Two things fell out that are worth naming:

• A constructed std::recursive_mutex member retires the io_lock_ready
  flag. A zeroed pthread_mutex_t is a valid NON-recursive lock, so an open
  path that skipped the explicit init self-deadlocked the PHY tick — the adopt
  path did exactly that once. That state is now unrepresentable.
• The teardown's pthread_cond_timedwait deadline arithmetic became one
  wait_for, dropping a CLOCK_REALTIME dependence where a wall-clock step
  could stretch or skip the 2 s budget.

The two structs holding those members moved from calloc/free to new /
delete — calloc never runs a constructor. {} still zeroes every scalar.
-Wclass-memaccess then caught a real defect that introduced: a memset over a
constructed device in frame_shape. Its loop case now declares the device
inside the loop, preserving the per-iteration reset.

Not ported: the flock adapter lock is _WIN32-guarded rather than
mirrored. It works by contending for the same lock file UsbDeviceLock uses,
but on Windows that class is a named mutex — so a file lock there would exclude
nobody, and mirroring the mutex would duplicate what the devourer path already
owns. Unprotected on Windows is a bare mt7612u_open() with no devourer around
it, which is the bench tool's case, and the bench is Linux.

Capability fallout

bw_mask_for_generation ends in a catch-all returning 20/40/80 plus
kBw5|kBw10, so the new enumerator silently inherited narrowband:

old chain, ChipGeneration::Mt7612u -> 0x1f   (kBw5|kBw10 set)
new chain, ChipGeneration::Mt7612u -> 0x1c   (20/40/80 only)
every other generation             ->  unchanged

MT_RATE_BW encodes nothing narrower than 20 MHz, and this issue lists that
among the part's known limits. Nothing calls it with Mt7612u today, which is
why it was worth fixing now — the first caller is the backend, and a capability
claimed there is claimed silently. adapter_caps_selftest pins the value and
the narrowband bits.

What review changed

Two reviewers went at this, and both found things I had wrong. Recording them
because they are the substance of the branch, not footnotes.

The selftest could not see Jaguar. It cross-checked the MediaTek set against
KestrelUsbIds.h and Rtl8733bUsbIds.h — 27 ids. Jaguar1/2/3 dispatch by
chip-id and have no table in devourer, so 64 more were invisible, and every
interleaved vendor id above lives in that 64. Adding {0x0b05, 0x17d2} — an
ASUS USB-AC56, a real RTL8812AU — passed the old test while refusing a genuine
Jaguar1 adapter. The test now carries a 64-entry witness list from
reference/rtl8812au, checks all 91, and asserts the coverage count so a future
trim cannot silently restore the blindness. Both attacks now fail it:

mt7612u_usb_ids: FAIL 0b05:17d2 is Jaguar1/2/3 but the MediaTek gate claims it
mt7612u_usb_ids: FAIL 0846:9054 is Jaguar1/2/3 but the MediaTek gate claims it

My table was 11 of 16, from the wrong source — this machine's kernel tree
rather than the pinned submodule. Recomputing against the complete table also
turned "three shared vendor ids" into six, which is the table above.

The library read the environment and wrote to stderr. qodo raised both, and
both are things this PR's own DEVOURER_MT7612U created by linking the subtree
into libdevourer: a bench tool that reads MT7612U_DEV is a quirk, a library
that picks its adapter from ambient process state is a defect, and the same for
one that writes diagnostics to a stream its host does not control.
mt7612u_open_selected() takes the selector and mt7612u_set_log_sink() diverts
the diagnostics; the library now reads no environment and names stderr in exactly
one place. mt_diag() turned out to be reimplementing Logger — same format,
same fwrite+fflush atomicity, none of set_level / set_diag_stream /
DEVOURER_LOG_MAX_LEVEL — and on Android Logger::emit has an
__android_log_write branch these writes did not, so the subtree's diagnostics
landed nowhere visible on the platform devourer ships to.

Two exceptions could cross the extern "C" boundary, both proved by probe
rather than argued: catch (const std::system_error &) is narrower than what
std::thread's constructor throws (libstdc++ allocates the thread state with a
throwing new, so OOM arrives as bad_alloc), and new (std::nothrow) T{}
is not nothrow for these types, because std::condition_variable_any holds a
shared_ptr<mutex> that allocates in its constructor. Both are now
try/catch (...) returning the existing -1 / NULL.

Also folded: three comments still said mt_dev_state_init/destroy manage
io_lock after this branch made them empty; one comment quoted a read_chip_id
note the same commit deleted; and mt_usleep is no longer interruptible
(measured: a 200 ms request under 100 Hz SIGALRM returned after 10 ms with
nanosleep, 201 ms with sleep_for) and now says so.

Verification

Local:

• Both CMake configs build warning-free, 59/59 ctest (58 before; the new
  cell is mt7612u_usb_ids).
• The stripped mt7612u+jaguar1 config builds, 49/49.
• make -C src/mt7612u check passes (four binaries now, log_sink added);
  api_link resolves 27 C entry points against the C++ objects.
• Sanitized (address+undefined, RelWithDebInfo) with the option ON: 59/59.

On hardware, the gate end to end — the same adapter, the same command, across
the parent commit and this branch:

parent 31cb738:  Creating RtlJaguarDevice (PID 0x7612, chip-id 0x00)
this branch:     MediaTek MT7612U (0e8d:7612) detected; devourer has no MediaTek
                 radio backend yet — refusing rather than misdetecting it as Realtek
                 No driver for this chip in this build — exiting   (exit 1)

The parent really does construct an RtlJaguarDevice for a MediaTek adapter, so
the bug is demonstrated rather than inferred. Control, unchanged on both:
Creating RtlJaguarDevice (PID 0x8812, chip-id 0x04) for the RTL8812AU.

And the library itself, on an MT7612U at 0e8d:7612:

• bringup regs — MT_ASIC_VERSION 0x76120044, CFG- and MAC-space write /
  read-back / restore, EEPROM MAC. GATE A: PASS, and again after the RX run,
  so nothing wedged.
• bringup arx 1 10 — ROM patch + ILM/DLM load, ring up, 7918 frames in 10 s
  (790/s), rx_err=0 rx_invalid=0 rx_dropped=0. The callback count and the
  driver's ring count agree exactly, which is what exercises the new
  std::atomic and mutex paths against each other.
• The same run under ASan+UBSan with detect_leaks=1: 2623 frames (sanitizers
  cost most of the rate), no ASan report, no UBSan report, no leak — the
  part that actually tests the ring's new/delete teardown.

CI is what verifies the Windows claim, since none of it builds locally.
DEVOURER_MT7612U=ON is now set in the multi-platform matrix (gcc, clang, MSVC
cl, macOS), the mingw job, and build-sanitizers, plus one stripped
build-configs cell so the subtree cannot quietly acquire a dependency on a
Realtek chip's sources.

Blast radius

For anyone who never sets the option, the compiled delta is confined to
WiFiDriver.cpp and is exactly the two refusals above, plus an unused
ChipGeneration enumerator. No Realtek dispatch path changes: a chip that
answers SYS_CFG2 reaches precisely the branch it reached before.

Still open, deliberately

• No IRadio backend, no transport adoption, no firmware embedding — next
  block.
• MT7612U_DEV is still a getenv in open_selected(). mt7612u: a MediaTek backend, measured — is it in scope? #412 deferred it
  because there is no public way to pass a selector (mt7612u_open() allocates
  the device and the struct is opaque). I corrected two comments that claimed
  the library reads no environment, since it does.
• MT7612U deliberately does not join the "No chip support selected"
  FATAL_ERROR list: with no backend, an MT7612U-only build would produce a
  library that can open nothing. It joins when the backend lands.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01Tba83kymS5W2v1vn2yRxrj

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Add MT7612U build support, safe factory gating, and FCS metadata

🐞 Bug fix ✨ Enhancement 🧪 Tests 📝 Documentation ⚙️ Configuration changes 🕐 40+ Minutes

AI Description

• Refuses MT7612U and failed Realtek probes before Jaguar1 fallback.
• Ports the MT7612U library to portable C++ and enables optional CMake builds.
• Propagates per-frame FCS presence through beamforming consumers and tests.

Diagram

graph TD
  MTLib["MT7612U Library"] -.->|"No backend"| Factory["Radio Factory"] --> Gate{"MT USB ID?"} -->|"No"| Probe{"SYS CFG2 OK?"} -->|"Yes"| Realtek["Realtek Backends"]
  Gate -->|"Yes"| Refuse["Safe Refusal"]
  Probe -->|"No"| Refuse
  RxMeta["FCS Metadata"] --> BF["BF Consumers"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Reject non-Realtek vendor IDs

• ➕ Implements a simple vendor-level policy without maintaining a MediaTek product table.
• ➖ Rejects supported Realtek silicon sold under shared OEM vendor IDs.
• ➖ Cannot handle interleaved MediaTek and Realtek product IDs safely.

2. Keep the subtree in C with portability shims

• ➕ Minimizes source-language conversion and retains the original pthread implementation.
• ➖ Requires a custom Windows threading and timing abstraction.
• ➖ Creates a second compilation model that can diverge from the main C++ build.
• ➖ Retains manual construction hazards for mutex-containing objects.

3. Model FCS presence as an adapter capability

• ➕ Stores the property once when hardware behavior is generation-wide.
• ➕ Avoids adding metadata to every received packet.
• ➖ Free-function consumers receive only frame bytes and lengths, not adapter capabilities.
• ➖ Cannot represent future per-frame variation or mixed capture sources.
• ➖ Encourages callers to recover device context instead of honoring the packet contract.

Recommendation: Keep the PR's VID:PID gate plus transfer-failure guard: it prevents the demonstrated Jaguar1 misroute without excluding OEM Realtek devices. The C++ conversion aligns the subtree with the project's supported platforms while preserving its C ABI, and per-frame FCS metadata is the most reliable boundary because all consumers can access it directly. Review should focus particularly on synchronization equivalence, exception containment across the C ABI, and completeness of USB-ID collision coverage.

Files changed (36) +1047 / -272

Enhancement (4) +128 / -9

BfReportDetect.hEmit and honor beamforming FCS metadata +7/-2

Emit and honor beamforming FCS metadata

• Conditionally excludes a trailing FCS from CSI output and records FCS presence in beamforming events. Tightens the minimum report length before parsing.

examples/common/BfReportDetect.h

AdapterCaps.hDefine MT7612U generation capabilities +15/-1

Define MT7612U generation capabilities

• Adds the MT7612U chip generation and name. Explicitly limits it to 20/40/80 MHz so it cannot inherit unsupported narrowband capabilities.

src/AdapterCaps.h

RxPacket.hAdd per-frame FCS presence metadata +27/-6

Add per-frame FCS presence metadata

• Adds rx_pkt_attrib::fcs_present with a backward-compatible true default. Revises the Packet data contract to require consumers to consult the flag before trimming bytes.

src/RxPacket.h

Mt7612uUsbIds.hAdd the complete MT7612U USB-ID table +79/-0

Add the complete MT7612U USB-ID table

• Defines the 16 VID:PID pairs from the pinned mt76 reference and provides a header-only lookup. Documents why exact pairs, rather than vendor IDs, are required for safe pre-probe gating.

src/mt7612u/Mt7612uUsbIds.h

Bug fix (9) +188 / -56

main.cppAccount for stripped FCS in airtime +7/-3

Account for stripped FCS in airtime

• Adds four bytes to the on-air frame length when receive metadata reports that the MAC stripped the FCS. This preserves channel-occupancy calculations across backend behaviors.

examples/chanscout/main.cpp

main.cppPreserve FCS metadata through sensing calibration +16/-7

Preserve FCS metadata through sensing calibration

• Passes FCS presence into report parsing and stores it beside calibration frames for later reparsing. Raw report events now expose the same metadata.

examples/sense/main.cpp

BfReportDecode.hParse reports with optional trailing FCS +12/-3

Parse reports with optional trailing FCS

• Extends parse_report with an FCS-presence argument that defaults to the historical Realtek behavior. Length checks and angle slicing now reserve four bytes only when an FCS exists.

src/BfReportDecode.h

WiFiDriver.cppBlock MT7612U and failed probes before Jaguar1 +67/-8

Block MT7612U and failed probes before Jaguar1

• Checks known MT7612U VID:PID pairs before issuing Realtek vendor requests and refuses them because no backend exists. Returns nullopt for failed SYS_CFG2 transfers so unknown non-Realtek devices cannot reach the Jaguar1 fallback.

src/WiFiDriver.cpp

init.cppConstruct and destroy MT7612U devices safely +25/-11

Construct and destroy MT7612U devices safely

• Replaces calloc/free with exception-contained new/delete so mutex members are constructed correctly. Uses steady_clock for statistics timing and preserves existing C error returns.

src/mt7612u/init.cpp

frame_shape.cppAvoid clearing constructed mutex objects +12/-4

Avoid clearing constructed mutex objects

• Value-initializes device fixtures instead of applying memset over std::recursive_mutex members. Recreates loop-local devices to preserve the original per-case reset behavior.

src/mt7612u/tests/frame_shape.cpp

bf_report_decode.pyDecode FCS-less beamforming captures correctly +41/-14

Decode FCS-less beamforming captures correctly

• Carries FCS presence from structured events into frame and MU-SNR parsing and adds --no-fcs for bare MediaTek captures. Preserves legacy defaults and skips malformed events safely.

tools/bf_report_decode.py

bf_waterfall.pyConsume FCS metadata in live waterfall decoding +4/-3

Consume FCS metadata in live waterfall decoding

• Adapts to the report parser's tuple result and passes each event's FCS-presence flag into frame decoding.

tools/bf_waterfall.py

bf_waterfall_svg.pyConsume FCS metadata in SVG waterfall decoding +4/-3

Consume FCS metadata in SVG waterfall decoding

• Passes FCS presence from report events into offline frame parsing so FCS-less captures are not truncated.

tools/bf_waterfall_svg.py

Refactor (12) +222 / -147

async.cppPort asynchronous USB rings to standard C++ +66/-56

Port asynchronous USB rings to standard C++

• Replaces pthread mutexes, condition variables, and threads with standard C++ primitives and uses new/delete for constructed objects. Catches all allocation and thread-construction exceptions before they can cross the C ABI.

src/mt7612u/async.cpp

caps.cppCompile capability implementation as C++ +0/-0

Compile capability implementation as C++

• Moves the MT7612U capability implementation into the subtree's unified C++ compilation mode without changing its behavior.

src/mt7612u/caps.cpp

eeprom.cppCompile EEPROM implementation as C++ +0/-0

Compile EEPROM implementation as C++

• Moves the EEPROM implementation into the unified C++ build without functional changes.

src/mt7612u/eeprom.cpp

fw.cppMake firmware loading C++-compatible +9/-8

Make firmware loading C++-compatible

• Adds explicit allocation and libusb enum conversions required by C++ compilation. Firmware transfer behavior remains unchanged.

src/mt7612u/fw.cpp

internal.hReplace POSIX synchronization members with C++ types +35/-14

Replace POSIX synchronization members with C++ types

• Defines standard mutex, recursive mutex, condition variable, thread, and timing dependencies. Removes the io_lock_ready state by making the recursive lock an always-constructed device member.

src/mt7612u/internal.h

mcu.cppUse the constructed recursive MCU lock +3/-3

Use the constructed recursive MCU lock

• Replaces pthread lock operations with the device's std::recursive_mutex while retaining nested transaction semantics.

src/mt7612u/mcu.cpp

phy.cppUse the C++ recursive lock for PHY ticks +2/-2

Use the C++ recursive lock for PHY ticks

• Ports PHY tick locking to std::recursive_mutex without changing calibration or gain-update ordering.

src/mt7612u/phy.cpp

radiotap.cppAdd C++-safe packet pointer conversion +1/-1

Add C++-safe packet pointer conversion

• Adds the explicit void-pointer conversion required when compiling radiotap packet handling as C++.

src/mt7612u/radiotap.cpp

rx.cppCompile receive parsing as C++ +0/-0

Compile receive parsing as C++

• Moves the MT7612U receive implementation into the subtree's unified C++ compilation mode without functional changes.

src/mt7612u/rx.cpp

bringup.cppPort bring-up counters and casts to C++ +30/-25

Port bring-up counters and casts to C++

• Replaces C atomics with std::atomic and adds explicit pointer and enum conversions. The hardware gate behavior and relaxed counter semantics remain unchanged.

src/mt7612u/tools/bringup.cpp

tx.cppMake transmit construction C++-safe +2/-2

Make transmit construction C++-safe

• Adds explicit frame-pointer and bandwidth-enum conversions required by C++ compilation without changing generated transmit descriptors.

src/mt7612u/tx.cpp

usb.cppPort USB timing, locking, and platform guards +74/-36

Port USB timing, locking, and platform guards

• Uses standard C++ sleep and monotonic timing, ports recursive locking, and guards POSIX file-lock APIs on Windows. Device locks are now constructed with the owning object, eliminating the partial-initialization state.

src/mt7612u/usb.cpp

Tests (5) +295 / -0

bf_report_decode_selftest.cppTest tight FCS-less beamforming reports +46/-0

Test tight FCS-less beamforming reports

• Adds equivalent FCS-present and FCS-less report cases. Verifies that incorrectly assuming an FCS rejects a tight MU report instead of silently truncating angle data.

examples/sense/bf_report_decode_selftest.cpp

field_macros.cppCompile field macro tests as C++ +0/-0

Compile field macro tests as C++

• Moves the field-macro self-test into the same C++ mode as the library sources.

src/mt7612u/tests/field_macros.cpp

adapter_caps_selftest.cppPin MT7612U generation and bandwidth capabilities +13/-0

Pin MT7612U generation and bandwidth capabilities

• Verifies the MT7612U generation name and its 20/40/80 MHz-only capability mask, including explicit rejection of 5 and 10 MHz.

tests/adapter_caps_selftest.cpp

bf_report_fcs_selftest.pyTest Python FCS-aware report decoding +88/-0

Test Python FCS-aware report decoding

• Covers event metadata, legacy bare-hex defaults, malformed-event handling, and equivalent FCS-present and FCS-less decoding. Also protects the MU SNR parser's historical FCS-present behavior.

tests/bf_report_fcs_selftest.py

mt7612u_usb_ids_selftest.cppVerify MediaTek and Realtek USB IDs remain disjoint +148/-0

Verify MediaTek and Realtek USB IDs remain disjoint

• Checks all tabled MediaTek IDs and cross-validates them against at least 91 Realtek identities, including Jaguar witnesses. Pins exact-pair behavior and shared-vendor edge cases that make a vendor-only gate unsafe.

tests/mt7612u_usb_ids_selftest.cpp

Documentation (3) +93 / -44

logging.mdDocument FCS fields in beamforming events +2/-2

Document FCS fields in beamforming events

• Adds the per-frame fcs field to the documented bf.report_raw and bf.csi event schemas.

docs/logging.md

mt7612u.mdDocument build integration and FCS contract +32/-18

Document build integration and FCS contract

• Updates the MT7612U status to describe optional CMake compilation, explicit factory refusal, and per-frame FCS metadata. Clarifies remaining backend work and CI limitations.

docs/mt7612u.md

README.mdDocument C++ portability and optional integration +59/-24

Document C++ portability and optional integration

• Describes the optional CMake build, preserved C ABI, and absence of an IRadio backend. Records the standard-library synchronization conversion and Windows adapter-lock behavior.

src/mt7612u/README.md

Other (3) +121 / -16

cmake-multi-platform.ymlCompile MT7612U across CI configurations +18/-1

Compile MT7612U across CI configurations

• Enables DEVOURER_MT7612U in the multi-platform, MinGW, sanitizer, and selected stripped-build configurations. This makes portability and lifetime regressions visible outside the standalone Linux Makefile.

.github/workflows/cmake-multi-platform.yml

CMakeLists.txtAdd optional MT7612U sources and headless tests +67/-0

Add optional MT7612U sources and headless tests

• Introduces the default-off DEVOURER_MT7612U option and conditionally compiles the C++ subtree into libdevourer. Registers USB-ID and Python FCS self-tests while deliberately excluding MT7612U from backend availability checks.

CMakeLists.txt

MakefileBuild the MT7612U subtree as C++ +36/-15

Build the MT7612U subtree as C++

• Switches library, tools, and most tests to C++20 compilation and linking while keeping api_link.c compiled as C. This preserves direct validation of the exported C ABI.

src/mt7612u/Makefile

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Callers can open the wrong adapter ✓ Resolved 📎 Requirement gap ≡ Correctness

Description

open_selected() reads MT7612U_DEV inside the library even though the newly integrated
mt7612u_open() API provides no explicit device selector. When multiple adapters are connected or
the process inherits a stale value, construction can claim hardware other than the adapter the
caller intended to use.

Code

CMakeLists.txt[382]

+        src/mt7612u/usb.cpp

Evidence

Rules 9 and 20 require device selection to enter through configuration or an explicit API rather
than a library environment read. The PR adds usb.cpp to libdevourer; the exported
mt7612u_open() path reaches open_selected(), which reads MT7612U_DEV and uses it to choose
among devices.

Configure firmware and device selection without environment reads
CLAUDE.md: Keep Library Configuration Independent of Environment Variables: CLAUDE.md: Keep Library Configuration Independent of Environment Variables: CLAUDE.md: Keep Library Configuration Independent of Environment Variables: CLAUDE.md: Keep Library Configuration Independent of Environment Variables: CLAUDE.md: Keep Library Configuration Independent of Environment Variables: CLAUDE.md: Keep Library Configuration Independent of Environment Variables: CLAUDE.md: Keep Library Configuration Independent of Environment Variables: CLAUDE.md: Keep Library Configuration Independent of Environment Variables: CLAUDE.md: Keep Library Configuration Independent of Environment Variables: CLAUDE.md: Keep Library Configuration Independent of Environment Variables: CLAUDE.md: Keep Library Configuration Independent of Environment Variables: CLAUDE.md: Keep Library Configuration Independent of Environment Variables: CLAUDE.md: Keep Library Configuration Independent of Environment Variables: CLAUDE.md: Keep Library Configuration Independent of Environment Variables: CLAUDE.md: Keep Library Configuration Independent of Environment Variables: CLAUDE.md: Keep Library Configuration Independent of Environment Variables
CMakeLists.txt[370-390]
src/mt7612u/init.cpp[466-483]
src/mt7612u/usb.cpp[557-597]
src/mt7612u/include/mt7612u/mt7612u.h[103-127]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Enabling `DEVOURER_MT7612U` now links an exported open path into `libdevourer` that reads `MT7612U_DEV` internally, making adapter selection depend on ambient process state.
## Fix Focus Areas
- src/mt7612u/include/mt7612u/mt7612u.h[103-127]
- src/mt7612u/usb.cpp[557-597]
- src/mt7612u/init.cpp[466-483]
## Recommended Fix
Add an explicit selector parameter or open-with-selector API, pass it through to `open_selected()`, and remove `getenv("MT7612U_DEV")` from library code. Move any environment parsing needed by the standalone bring-up application into that application before it calls the library.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Radio diagnostics bypass the logger ✓ Resolved 📎 Requirement gap ◔ Observability

Description

mt_diag() writes every subtree diagnostic directly to stderr, and the exported C surface
provides no sink through which devourer's Logger can receive those messages. Once
DEVOURER_MT7612U adds usb.cpp and the other sources to libdevourer, initialization, firmware,
USB, RX and TX diagnostics all continue through this separate output path.

Code

CMakeLists.txt[R380-382]

+        src/mt7612u/rx.cpp
+        src/mt7612u/tx.cpp
+        src/mt7612u/usb.cpp

Evidence

Rule 10 requires a library sink connected to devourer's Logger and explicitly forbids subtree
diagnostics from continuing directly to stderr. The PR activates these sources in libdevourer,
while LOG, WARN, and ERR still call mt_diag(), whose only output is fwrite(..., stderr)
followed by fflush(stderr).

Integrate MT7612U diagnostics and JSONL events with devourer logging
CMakeLists.txt[370-390]
src/mt7612u/usb.cpp[21-48]
src/mt7612u/internal.h[365-372]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The newly integrated MT7612U library emits diagnostics directly to `stderr` and exposes no hook that can connect those messages to devourer's structured logging infrastructure.
## Fix Focus Areas
- src/mt7612u/usb.cpp[21-48]
- src/mt7612u/internal.h[365-372]
- src/mt7612u/include/mt7612u/mt7612u.h[103-127]
## Recommended Fix
Expose a C-compatible diagnostic sink callback, route `mt_diag()` through it, and connect the sink to devourer's `Logger` in the integrated path. If standalone tools still need terminal diagnostics, have those applications explicitly install their own stderr sink rather than writing there inside the library.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Tip of the day

💡 Did you know, you can turn these tips off under Display preferences

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[josephnef]

Approving.

The factory gate is the right shape and the reasoning holds up. Two things I checked rather than took on trust:

• The pair-vs-vendor argument. Mt7612uUsbIdsSelftest cross-checks against all 91 Realtek ids including the 64-entry Jaguar witness list, which is the half that matters — the interleaved vendors (Netgear, ELECOM, ASUS, TP-Link, Edimax, Mercury) all live there, and a Kestrel/8733B-only check would have been blind to exactly them.
• read_chip_id returning nullopt on transfer failure rather than a plain 0. Distinguishing "did not answer" from "answered 0x00" is what makes the unconditional-Jaguar1 fallback safe to close, and keeping a successful 0x00 as a value preserves the cold-boot transient behaviour.

Verified locally: -DDEVOURER_MT7612U=ON builds clean, 63/63 ctest. Default-OFF build also clean, 63/63, and still compiles the MediaTek gate — the header-only claim holds.

Two non-blocking notes:

1. mt_async_stop() clears a->running after the drain loop but does not cv.notify_all(), so a thread parked in mt_async_tx_submit's slot wait never wakes — and delete a then destroys the condition variable it is blocked on. #423 fixes this (6b73e9f, with a comment saying exactly why). Since this stack lands in order the exposure on master is only the window between this merge and #422's, but the two lines would be worth cherry-picking here if that window matters to you.

2. mt_async_start increments rx_inflight after libusb_submit_transfer succeeds, so rx_done's decrement can land first and take the counter transiently negative. The net converges and I could not construct a live failure from it, but increment-before-submit / decrement-on-failure is the shape that cannot go wrong.

read_chip_id also now refuses on a single transfer failure with no retry. That is a strict improvement in signal over the old fall-through, but one retry is cheap insurance and would only ever cost a control transfer on the failure path.