rtl8733b: add RTL8731BU/RTL8733BU USB RX and TX

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

@@ -163,27 +163,29 @@ jobs:
       matrix:
         include:
           - name: jaguar1-only
-            flags: "-DDEVOURER_8814=OFF -DDEVOURER_JAGUAR3_8822C=OFF -DDEVOURER_JAGUAR3_8822E=OFF -DDEVOURER_JAGUAR2_8822B=OFF -DDEVOURER_JAGUAR2_8821C=OFF -DDEVOURER_KESTREL_8852B=OFF -DDEVOURER_KESTREL_8852C=OFF"
+            flags: "-DDEVOURER_8814=OFF -DDEVOURER_JAGUAR3_8822C=OFF -DDEVOURER_JAGUAR3_8822E=OFF -DDEVOURER_JAGUAR2_8822B=OFF -DDEVOURER_JAGUAR2_8821C=OFF -DDEVOURER_8733B=OFF -DDEVOURER_KESTREL_8852B=OFF -DDEVOURER_KESTREL_8852C=OFF"
           - name: jaguar1+8814
-            flags: "-DDEVOURER_JAGUAR3_8822C=OFF -DDEVOURER_JAGUAR3_8822E=OFF -DDEVOURER_JAGUAR2_8822B=OFF -DDEVOURER_JAGUAR2_8821C=OFF -DDEVOURER_KESTREL_8852B=OFF -DDEVOURER_KESTREL_8852C=OFF"
+            flags: "-DDEVOURER_JAGUAR3_8822C=OFF -DDEVOURER_JAGUAR3_8822E=OFF -DDEVOURER_JAGUAR2_8822B=OFF -DDEVOURER_JAGUAR2_8821C=OFF -DDEVOURER_8733B=OFF -DDEVOURER_KESTREL_8852B=OFF -DDEVOURER_KESTREL_8852C=OFF"
           - name: 8822b-only
-            flags: "-DDEVOURER_JAGUAR1=OFF -DDEVOURER_8814=OFF -DDEVOURER_JAGUAR2_8821C=OFF -DDEVOURER_JAGUAR3_8822C=OFF -DDEVOURER_JAGUAR3_8822E=OFF -DDEVOURER_KESTREL_8852B=OFF -DDEVOURER_KESTREL_8852C=OFF"
+            flags: "-DDEVOURER_JAGUAR1=OFF -DDEVOURER_8814=OFF -DDEVOURER_JAGUAR2_8821C=OFF -DDEVOURER_JAGUAR3_8822C=OFF -DDEVOURER_JAGUAR3_8822E=OFF -DDEVOURER_8733B=OFF -DDEVOURER_KESTREL_8852B=OFF -DDEVOURER_KESTREL_8852C=OFF"
           - name: 8821c-only
-            flags: "-DDEVOURER_JAGUAR1=OFF -DDEVOURER_8814=OFF -DDEVOURER_JAGUAR2_8822B=OFF -DDEVOURER_JAGUAR3_8822C=OFF -DDEVOURER_JAGUAR3_8822E=OFF -DDEVOURER_KESTREL_8852B=OFF -DDEVOURER_KESTREL_8852C=OFF"
+            flags: "-DDEVOURER_JAGUAR1=OFF -DDEVOURER_8814=OFF -DDEVOURER_JAGUAR2_8822B=OFF -DDEVOURER_JAGUAR3_8822C=OFF -DDEVOURER_JAGUAR3_8822E=OFF -DDEVOURER_8733B=OFF -DDEVOURER_KESTREL_8852B=OFF -DDEVOURER_KESTREL_8852C=OFF"
           - name: jaguar2-only
-            flags: "-DDEVOURER_JAGUAR1=OFF -DDEVOURER_8814=OFF -DDEVOURER_JAGUAR3_8822C=OFF -DDEVOURER_JAGUAR3_8822E=OFF -DDEVOURER_KESTREL_8852B=OFF -DDEVOURER_KESTREL_8852C=OFF"
+            flags: "-DDEVOURER_JAGUAR1=OFF -DDEVOURER_8814=OFF -DDEVOURER_JAGUAR3_8822C=OFF -DDEVOURER_JAGUAR3_8822E=OFF -DDEVOURER_8733B=OFF -DDEVOURER_KESTREL_8852B=OFF -DDEVOURER_KESTREL_8852C=OFF"
           - name: 8822c-only
-            flags: "-DDEVOURER_JAGUAR1=OFF -DDEVOURER_8814=OFF -DDEVOURER_JAGUAR3_8822E=OFF -DDEVOURER_JAGUAR2_8822B=OFF -DDEVOURER_JAGUAR2_8821C=OFF -DDEVOURER_KESTREL_8852B=OFF -DDEVOURER_KESTREL_8852C=OFF"
+            flags: "-DDEVOURER_JAGUAR1=OFF -DDEVOURER_8814=OFF -DDEVOURER_JAGUAR3_8822E=OFF -DDEVOURER_JAGUAR2_8822B=OFF -DDEVOURER_JAGUAR2_8821C=OFF -DDEVOURER_8733B=OFF -DDEVOURER_KESTREL_8852B=OFF -DDEVOURER_KESTREL_8852C=OFF"
           - name: 8822e-only
-            flags: "-DDEVOURER_JAGUAR1=OFF -DDEVOURER_8814=OFF -DDEVOURER_JAGUAR3_8822C=OFF -DDEVOURER_JAGUAR2_8822B=OFF -DDEVOURER_JAGUAR2_8821C=OFF -DDEVOURER_KESTREL_8852B=OFF -DDEVOURER_KESTREL_8852C=OFF"
+            flags: "-DDEVOURER_JAGUAR1=OFF -DDEVOURER_8814=OFF -DDEVOURER_JAGUAR3_8822C=OFF -DDEVOURER_JAGUAR2_8822B=OFF -DDEVOURER_JAGUAR2_8821C=OFF -DDEVOURER_8733B=OFF -DDEVOURER_KESTREL_8852B=OFF -DDEVOURER_KESTREL_8852C=OFF"
           - name: jaguar3-only
-            flags: "-DDEVOURER_JAGUAR1=OFF -DDEVOURER_8814=OFF -DDEVOURER_JAGUAR2_8822B=OFF -DDEVOURER_JAGUAR2_8821C=OFF -DDEVOURER_KESTREL_8852B=OFF -DDEVOURER_KESTREL_8852C=OFF"
+            flags: "-DDEVOURER_JAGUAR1=OFF -DDEVOURER_8814=OFF -DDEVOURER_JAGUAR2_8822B=OFF -DDEVOURER_JAGUAR2_8821C=OFF -DDEVOURER_8733B=OFF -DDEVOURER_KESTREL_8852B=OFF -DDEVOURER_KESTREL_8852C=OFF"
           - name: kestrel-only
-            flags: "-DDEVOURER_JAGUAR1=OFF -DDEVOURER_8814=OFF -DDEVOURER_JAGUAR2_8822B=OFF -DDEVOURER_JAGUAR2_8821C=OFF -DDEVOURER_JAGUAR3_8822C=OFF -DDEVOURER_JAGUAR3_8822E=OFF"
+            flags: "-DDEVOURER_JAGUAR1=OFF -DDEVOURER_8814=OFF -DDEVOURER_JAGUAR2_8822B=OFF -DDEVOURER_JAGUAR2_8821C=OFF -DDEVOURER_JAGUAR3_8822C=OFF -DDEVOURER_JAGUAR3_8822E=OFF -DDEVOURER_8733B=OFF"
           - name: kestrel-8852b-only
-            flags: "-DDEVOURER_JAGUAR1=OFF -DDEVOURER_8814=OFF -DDEVOURER_JAGUAR2_8822B=OFF -DDEVOURER_JAGUAR2_8821C=OFF -DDEVOURER_JAGUAR3_8822C=OFF -DDEVOURER_JAGUAR3_8822E=OFF -DDEVOURER_KESTREL_8852C=OFF"
+            flags: "-DDEVOURER_JAGUAR1=OFF -DDEVOURER_8814=OFF -DDEVOURER_JAGUAR2_8822B=OFF -DDEVOURER_JAGUAR2_8821C=OFF -DDEVOURER_JAGUAR3_8822C=OFF -DDEVOURER_JAGUAR3_8822E=OFF -DDEVOURER_8733B=OFF -DDEVOURER_KESTREL_8852C=OFF"
           - name: kestrel-8852c-only
-            flags: "-DDEVOURER_JAGUAR1=OFF -DDEVOURER_8814=OFF -DDEVOURER_JAGUAR2_8822B=OFF -DDEVOURER_JAGUAR2_8821C=OFF -DDEVOURER_JAGUAR3_8822C=OFF -DDEVOURER_JAGUAR3_8822E=OFF -DDEVOURER_KESTREL_8852B=OFF"
+            flags: "-DDEVOURER_JAGUAR1=OFF -DDEVOURER_8814=OFF -DDEVOURER_JAGUAR2_8822B=OFF -DDEVOURER_JAGUAR2_8821C=OFF -DDEVOURER_JAGUAR3_8822C=OFF -DDEVOURER_JAGUAR3_8822E=OFF -DDEVOURER_8733B=OFF -DDEVOURER_KESTREL_8852B=OFF"
+          - name: rtl8733b-only
+            flags: "-DDEVOURER_JAGUAR1=OFF -DDEVOURER_8814=OFF -DDEVOURER_JAGUAR2_8822B=OFF -DDEVOURER_JAGUAR2_8821C=OFF -DDEVOURER_JAGUAR3_8822C=OFF -DDEVOURER_JAGUAR3_8822E=OFF -DDEVOURER_KESTREL_8852B=OFF -DDEVOURER_KESTREL_8852C=OFF"
     steps:
       - uses: actions/checkout@v4
 
@@ -243,6 +245,7 @@ jobs:
           if cmake -B build-none -DDEVOURER_JAGUAR1=OFF -DDEVOURER_8814=OFF \
                 -DDEVOURER_JAGUAR3_8822C=OFF -DDEVOURER_JAGUAR3_8822E=OFF \
                 -DDEVOURER_JAGUAR2_8822B=OFF -DDEVOURER_JAGUAR2_8821C=OFF \
+                -DDEVOURER_8733B=OFF \
                 -DDEVOURER_KESTREL_8852B=OFF -DDEVOURER_KESTREL_8852C=OFF \
                 -S "${{ github.workspace }}" 2>err.log; then
             echo "ERROR: configure should have failed (no chip selected)"; cat err.log; exit 1

.gitmodules

@@ -35,3 +35,8 @@
 	path = reference/rtl8852cu
 	url = https://github.com/josephnef/rtl8852cu.git
 	shallow = true
+[submodule "reference/rtl8733bu-20230626"]
+	path = reference/rtl8733bu-20230626
+	url = https://github.com/libc0607/rtl8733bu-20230626.git
+	branch = v5.13.0.1
+	shallow = true

CLAUDE.md

@@ -248,12 +248,21 @@ those are the ones listed below.
   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.
+- `DEVOURER_THERMAL_POLL_MS=N` — emit `thermal` events from the RF 0x42 meter,
+  on every generation (the poller rides `IRtlDevice::GetThermalStatus`).
   `raw` is 0..63 thermal units (~1.5–2 °C each, **not** absolute °C); `delta`
-  = raw − EFUSE baseline, and a rising delta is the early TX-degradation
-  warning.
+  = 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

CMakeLists.txt

@@ -25,6 +25,7 @@ option(DEVOURER_JAGUAR2_8822B "RTL8822BU (Jaguar2, rtl8822b, 2T2R USB)"
 option(DEVOURER_JAGUAR2_8821C "RTL8811CU / 8821CU (Jaguar2, rtl8821c, 1T1R)"    ON)
 option(DEVOURER_JAGUAR3_8822C "RTL8812CU / 8822CU (Jaguar3, rtl8822c)"          ON)
 option(DEVOURER_JAGUAR3_8822E "RTL8812EU / 8822EU (Jaguar3, rtl8822e)"          ON)
+option(DEVOURER_8733B         "RTL8731BU / RTL8733BU USB support"               ON)
 # Kestrel — the Wi-Fi 6 / 802.11ax generation (Realtek "G6 phl" architecture,
 # vendor trees reference/rtl8852bu + reference/rtl8852cu): monitor RX, TX
 # injection and channel/BW on-air validated on both chips (see
@@ -82,11 +83,13 @@ else()
     set(DEVOURER_KESTREL OFF)
 endif()
 if(NOT DEVOURER_JAGUAR1 AND NOT DEVOURER_JAGUAR2 AND NOT DEVOURER_JAGUAR3
+   AND NOT DEVOURER_8733B
    AND NOT DEVOURER_KESTREL)
     message(FATAL_ERROR
         "No chip support selected. Enable at least one of DEVOURER_JAGUAR1 / "
         "DEVOURER_JAGUAR2_8822B / DEVOURER_JAGUAR2_8821C / DEVOURER_JAGUAR3_8822C "
-        "/ DEVOURER_JAGUAR3_8822E / DEVOURER_KESTREL_8852B / DEVOURER_KESTREL_8852C.")
+        "/ DEVOURER_JAGUAR3_8822E / DEVOURER_8733B / DEVOURER_KESTREL_8852B "
+        "/ DEVOURER_KESTREL_8852C.")
 endif()
 if(DEVOURER_PCIE)
     if(NOT CMAKE_SYSTEM_NAME STREQUAL "Linux")
@@ -388,6 +391,21 @@ if(DEVOURER_JAGUAR3_8822E)
     target_compile_definitions(devourer PUBLIC DEVOURER_HAVE_JAGUAR3_8822E=1)
 endif()
 
+# RTL8733B is an 802.11n HALMAC 87xx part, not a Jaguar3 variant. Keep the
+# backend isolated: it has its own power/FW/MAC/PHY path, descriptors, and
+# conservative capabilities.
+if(DEVOURER_8733B)
+    target_sources(devourer PRIVATE
+        src/rtl8733b/Rtl8733bDevice.cpp src/rtl8733b/Rtl8733bDevice.h
+        src/rtl8733b/Rtl8733bBringup.cpp src/rtl8733b/Rtl8733bBringup.h
+        src/rtl8733b/Halmac8733bMac.cpp src/rtl8733b/Halmac8733bMac.h
+        src/rtl8733b/Phy8733b.cpp src/rtl8733b/Phy8733b.h
+        src/rtl8733b/Rtl8733bUsbIds.h
+        hal/hal8733b_fw.c hal/hal8733b_fw.h
+        hal/hal8733b_tables.c hal/hal8733b_tables.h)
+    target_compile_definitions(devourer PUBLIC DEVOURER_HAVE_8733B=1)
+endif()
+
 # --- Kestrel (Wi-Fi 6 / 802.11ax: RTL8852BU / RTL8852CU) ---
 # Fourth generation, ported from the vendor "G6 phl" trees (reference/
 # rtl8852bu, reference/rtl8852cu): mac_ax MAC/FW plane, halbb PHY tables,
@@ -546,6 +564,19 @@ if(DEVOURER_KESTREL)
     target_include_directories(kestrelprobe PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/examples/common)
 endif()
 
+# rtl8733bprobe — staged USB bring-up prober for the RTL8733B (HALMAC 87xx),
+# the pcieprobe/kestrelprobe sibling: identity -> power-on + EFUSE -> firmware
+# -> MAC/PHY -> TSSI audit stages, used alongside normal factory dispatch. It
+# never substitutes for the production IRtlDevice path.
+if(DEVOURER_8733B)
+    add_executable(rtl8733bprobe
+        examples/rtl8733bprobe/main.cpp
+    )
+    target_link_libraries(rtl8733bprobe PUBLIC devourer PRIVATE PkgConfig::libusb)
+    # DeviceSession.h (shared teardown-order holder) lives in examples/common/.
+    target_include_directories(rtl8733bprobe PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/examples/common)
+endif()
+
 # reglat — register round-trip latency microbench (USB ctrl-xfer vs PCIe MMIO).
 # Times RtlAdapter::rtw_read32; the PCIe path compiles only with DEVOURER_PCIE
 # (inherited via the devourer PUBLIC DEVOURER_HAVE_PCIE define). See its header.
@@ -1004,6 +1035,32 @@ target_link_libraries(AdapterCapsSelftest PRIVATE devourer)
 
 add_test(NAME adapter_caps_derive COMMAND AdapterCapsSelftest)
 
+if(DEVOURER_8733B)
+    add_executable(Rtl8733bEfuseSelftest
+        tests/rtl8733b_efuse_selftest.cpp
+    )
+    target_link_libraries(Rtl8733bEfuseSelftest PRIVATE devourer)
+    add_test(NAME rtl8733b_efuse_parse COMMAND Rtl8733bEfuseSelftest)
+
+    add_executable(Rtl8733bPhyTableSelftest
+        tests/rtl8733b_phy_table_selftest.cpp
+    )
+    target_link_libraries(Rtl8733bPhyTableSelftest PRIVATE devourer)
+    add_test(NAME rtl8733b_phy_tables COMMAND Rtl8733bPhyTableSelftest)
+
+    add_executable(Rtl8733bRxParseSelftest
+        tests/rtl8733b_rx_parse_selftest.cpp
+    )
+    target_link_libraries(Rtl8733bRxParseSelftest PRIVATE devourer)
+    add_test(NAME rtl8733b_rx_parse COMMAND Rtl8733bRxParseSelftest)
+
+    add_executable(Rtl8733bTxDescSelftest
+        tests/rtl8733b_tx_desc_selftest.cpp
+    )
+    target_link_libraries(Rtl8733bTxDescSelftest PRIVATE devourer)
+    add_test(NAME rtl8733b_tx_desc COMMAND Rtl8733bTxDescSelftest)
+endif()
+
 # Headless guard for the per-UE RX attribution seed (src/cell/UeRxAttribution.h)
 # — TA extraction over the addr2-carrying frame types, the per-TA windowed
 # aggregate folding, drain semantics, and the bounded-table eviction accounting