WiFiDriver.cpp

#include "WiFiDriver.h"

#include <cstdint>
#include <memory>
#include <optional>
#include <string>
#include <utility>

#include <libusb.h>

#include "RtlAdapter.h"
#include "UsbDeviceLock.h"
#include "UsbTransport.h" /* REALTEK_USB_VENQT_READ / USB_TIMEOUT for read_chip_id */
#if defined(DEVOURER_HAVE_PCIE)
#include "PcieTransport.h"
#endif
#if defined(DEVOURER_HAVE_JAGUAR1)
#include "jaguar1/RtlJaguarDevice.h"
#endif
#if defined(DEVOURER_HAVE_JAGUAR2)
#include "jaguar2/RtlJaguar2Device.h"
#endif
#if defined(DEVOURER_HAVE_JAGUAR3)
#include "jaguar3/RtlJaguar3Device.h"
#endif
#if defined(DEVOURER_HAVE_KESTREL)
#include "kestrel/RtlKestrelDevice.h"
#endif
#include "kestrel/KestrelUsbIds.h" /* header-only PID table, always compiled */
#if defined(DEVOURER_HAVE_8733B)
#include "rtl8733b/Rtl8733bDevice.h"
#endif
#include "rtl8733b/Rtl8733bUsbIds.h"
#include "mt7612u/Mt7612uUsbIds.h" /* header-only VID:PID table, always compiled */
#if defined(DEVOURER_HAVE_MT7612U)
#include "mt7612u/Mt7612uRadio.h"
#endif

namespace {

/* Hardware chip-id at REG_SYS_CFG2 (0x00FC), read with a single vendor control
 * transfer (no full RtlAdapter, so the Jaguar1 construction path is unchanged
 * and only one extra control read is added). Port of halmac get_chip_info
 * (chip_id = REG_READ_8(REG_SYS_CFG2)):
 *   0x04 / 0x05 / 0x08 = 8812A / 8821A / 8814A                -> Jaguar1
 *   0x09 = RTL8821C (RTL8811CU / RTL8821CU, 1T1R)             -> Jaguar2
 *   0x0a = RTL8822B (RTL8822BU, 2T2R)                         -> Jaguar2
 *   0x13 = RTL8822C, 0x17 = RTL8822E (RTL8812EU / RTL8822EU)  -> Jaguar3
 *   0x16 = RTL8733B (RTL8731BU / RTL8733BU, 1T1R)             -> RTL8733B
 * The chip-id (not the USB PID) is authoritative because the rtl8822e RTL8812EU
 * shares PID 0x8812 with the Jaguar1 RTL8812AU. (8821C = 0x09 hardware-verified
 * on a CF-811AC; it is a HalMAC/phydm Jaguar2 chip, NOT the page-write Jaguar1
 * the "8821C" name might suggest — routing it to Jaguar1 would fail at DLFW.)
 *
 * Returns nullopt when the control transfer itself failed, which is NOT the same
 * as reading 0x00 and matters: this request is Realtek's vendor protocol, so a
 * device that does not answer it is not Realtek silicon. Measured on the bench,
 * same transfer, both arms:
 *   RTL8812AU  0bda:8812  rc=1                      chip_id=0x04
 *   MT7612U    0e8d:7612  rc=-7 LIBUSB_ERROR_TIMEOUT, destination byte UNTOUCHED
 * (the MediaTek arm was run with a 0xAA poison byte, which survived — so the
 * value the caller sees is its own initialiser, never a reading). Discarding the
 * return code turned that into a plain 0, and 0 matches no id below, so the
 * device reached the unconditional Jaguar1 fallback and came up as an RTL8812AU.
 * Distinguishing the two lets CreateRadio refuse instead. A successful read of
 * 0x00 is deliberately still returned as a value, so any cold-boot transient
 * keeps its existing fall-through behaviour. */
std::optional<uint8_t> read_chip_id(libusb_device_handle *dev_handle) {
  uint8_t id = 0;
  int rc = libusb_control_transfer(dev_handle, REALTEK_USB_VENQT_READ, 5, 0x00FC,
                                   0, &id, sizeof(id), USB_TIMEOUT);
  if (rc != static_cast<int>(sizeof(id)))
    return std::nullopt;
  return id;
}

/* RTL8822B (Jaguar2) SYS_CFG2 chip-id. Read off a TP-Link Archer T3U
 * (RTL8822BU): REG_SYS_CFG2 (0x00FC) reads 0x0a in steady state (and in the
 * demo's post-libusb_reset path), with a transient 0x50 for a brief window
 * right after a cold VBUS power-cycle before the chip settles. Accept both.
 * Neither collides with the Jaguar1 (0x04/05/08/09) or Jaguar3 (0x13/0x17)
 * ids. (SYS_CFG1's low bytes are volatile, so 0xFC is the dispatch signal.)
 * CAVEAT: on Kestrel (11ax) silicon 0x00FC is R_AX_SYS_CHIPINFO, and the
 * 8852A die-id is 0x50 — indistinguishable from the 8822B cold transient by
 * this byte alone. Kestrel PIDs are therefore gated before this read; an
 * out-of-scope 8852A (PID not in the Kestrel table) falls through here and
 * fails at the Jaguar2 DLFW rather than being detected. */
constexpr uint8_t kChipId8822B = 0x0a;
constexpr uint8_t kChipId8822B_cold = 0x50;
bool is_8822b_chip_id(uint8_t id) {
  return id == kChipId8822B || id == kChipId8822B_cold;
}

/* RTL8821C (Jaguar2, 1T1R) SYS_CFG2 chip-id, hardware-verified on a CF-811AC
 * (RTL8811CU, 0bda:c811): 0x00FC reads 0x09 in steady state. Does not collide
 * with the Jaguar1 ids (0x04/05/08) it used to be lumped with, nor 8822B (0x0a)
 * or Jaguar3 (0x13/0x17). */
constexpr uint8_t kChipId8821C = 0x09;

} /* namespace */

WiFiDriver::WiFiDriver(Logger_t logger) : _logger{std::move(logger)} {}

std::unique_ptr<IRadio>
WiFiDriver::CreateRadio(libusb_device_handle *dev_handle,
                            libusb_context *ctx,
                            std::shared_ptr<devourer::UsbDeviceLock> usb_lock,
                            const devourer::DeviceConfig &cfg) {
  uint16_t pid = 0;
  libusb_device *dev = libusb_get_device(dev_handle);
  if (dev != nullptr) {
    libusb_device_descriptor desc{};
    if (libusb_get_device_descriptor(dev, &desc) == 0)
      pid = desc.idProduct;
  }

  /* Exclusive per-adapter USB lock (see UsbDeviceLock.h). The recommended open
   * path (devourer::claim_interface_then_reset) already took this lock BEFORE
   * the reset and hands it in here — in that case we must NOT re-acquire (a
   * same-process flock on the same file would self-conflict); we just hold it
   * for the device lifetime. A caller that opened/claimed the handle itself
   * passes null, so acquire our own here as a best-effort second gate: genuine
   * contention -> refuse (return nullptr, same contract as an unsupported chip);
   * a lock-infrastructure error degrades to a warning. Either way the lock rides
   * into the RtlAdapter below and is released at device destruction. */
  if (!usb_lock) {
    auto lock = std::make_shared<devourer::UsbDeviceLock>();
    std::string lock_why;
    switch (lock->try_acquire(dev, &lock_why, cfg.usb.lock_dir)) {
    case devourer::UsbDeviceLock::Result::Busy:
      _logger->error("USB adapter in use — refusing to open ({})", lock_why);
      return nullptr;
    case devourer::UsbDeviceLock::Result::Error:
      _logger->warn("USB adapter lock unavailable ({}) — proceeding without "
                    "exclusive access",
                    lock_why);
      break;
    case devourer::UsbDeviceLock::Result::Acquired:
      _logger->info("USB adapter {} locked for exclusive access", lock->key());
      usb_lock = std::move(lock);
      break;
    }
  }

  /* Kestrel (Wi-Fi 6 / 802.11ax, RTL8852B/8852C) gates on the USB VID:PID
   * BEFORE the SYS_CFG2 read: on AX silicon 0x00FC is R_AX_SYS_CHIPINFO (the
   * D-die id), not the 11ac chip-id — and the 8852A die-id (0x50) collides
   * with the 8822B cold-boot transient accepted below, so the register byte
   * alone cannot dispatch this generation. The Kestrel PID set (vendor
   * usb_intf.c id tables, see kestrel/KestrelUsbIds.h) is disjoint from every
   * 11ac PID devourer handles, which makes the PID gate authoritative here
   * while SYS_CFG2 stays authoritative for the 11ac families (the RTL8812EU /
   * RTL8812AU PID collision rationale below is untouched). The die-id is read
   * back inside the HAL as confirmation. */
  uint16_t vid = 0;
  if (dev != nullptr) {
    libusb_device_descriptor desc{};
    if (libusb_get_device_descriptor(dev, &desc) == 0)
      vid = desc.idVendor;
  }
  if (auto kvariant = kestrel::variant_for_usb_id(vid, pid)) {
#if defined(DEVOURER_HAVE_KESTREL)
    const bool is_8852b = *kvariant == kestrel::ChipVariant::C8852B;
#if !defined(DEVOURER_HAVE_KESTREL_8852B)
    if (is_8852b) {
      _logger->error("RTL8852B ({:04x}:{:04x}) detected but 8852B support not "
                     "compiled in (DEVOURER_KESTREL_8852B=OFF)",
                     vid, pid);
      return nullptr;
    }
#endif
#if !defined(DEVOURER_HAVE_KESTREL_8852C)
    if (!is_8852b) {
      _logger->error("RTL8852C ({:04x}:{:04x}) detected but 8852C support not "
                     "compiled in (DEVOURER_KESTREL_8852C=OFF)",
                     vid, pid);
      return nullptr;
    }
#endif
    _logger->info("Creating RtlKestrelDevice {} ({:04x}:{:04x})",
                  is_8852b ? "C8852B" : "C8852C", vid, pid);
    return std::make_unique<RtlKestrelDevice>(
        RtlAdapter(dev_handle, _logger, ctx, usb_lock, cfg), _logger, *kvariant,
        cfg);
#else
    _logger->error("Kestrel chip ({:04x}:{:04x}) detected but Kestrel support "
                   "not compiled in (DEVOURER_KESTREL_8852B/_8852C=OFF)",
                   vid, pid);
    return nullptr;
#endif
  }

  /* MediaTek MT7612U gates on the USB VID:PID BEFORE the SYS_CFG2 read, for the
   * same reason Kestrel does above — but with a sharper failure mode. On this
   * silicon the Realtek vendor request read_chip_id() issues (bRequest 5) is not
   * implemented at all, so the control transfer stalls. Before the nullopt
   * return below existed, that failure was discarded, `id` stayed 0, 0 matched
   * no Realtek chip-id, and the adapter reached the unconditional Jaguar1
   * fallback at the end of this function — coming up as an RTL8812AU with every
   * subsequent register access addressed at the wrong MAC.
   *
   * The pair set is disjoint from all 91 Realtek ids devourer can serve, but the
   * VENDOR ids are NOT: six of them ship both silicon families, and Netgear,
   * ELECOM and ASUS interleave the two within one vendor's product-id range. So
   * this must stay a vid:pid test and must never be widened to "not a Realtek
   * vendor id". Mt7612uUsbIds.h carries the table and the evidence;
   * Mt7612uUsbIdsSelftest.cpp fails if a later id addition breaks it. */
  if (mt7612u::is_usb_id(vid, pid)) {
#if defined(DEVOURER_HAVE_MT7612U)
    _logger->info("Creating Mt7612uRadio ({:04x}:{:04x})", vid, pid);
    return std::make_unique<Mt7612uRadio>(dev_handle, ctx, std::move(usb_lock),
                                          _logger, cfg);
#else
    _logger->error("MediaTek MT7612U ({:04x}:{:04x}) detected but MediaTek "
                   "support is not compiled in (DEVOURER_MT7612U=OFF) — "
                   "refusing rather than misdetecting it as Realtek",
                   vid, pid);
    return nullptr;
#endif
  }

  /* A vendor read that did not complete means this device is not speaking the
   * Realtek protocol at all — refuse instead of dropping through to the Jaguar1
   * fallback at the end of this function, which would bring an unknown part up
   * as an RTL8812AU. This is the generation-independent half of the same guard
   * the MediaTek gate above applies by id: the gate names the parts we know,
   * this catches the ones we do not. It deliberately keys on TRANSFER FAILURE
   * and not on "vid is not 0x0bda": devourer already serves Realtek silicon
   * behind ASUS, Edimax, D-Link, ZyXEL, MSI and Mercury vendor ids, and every
   * one of those answers this read normally (measured: an RTL8812AU returns
   * 0x04), so a vendor-id rule would refuse working adapters. */
  std::optional<uint8_t> chip_id_read = read_chip_id(dev_handle);
  if (!chip_id_read) {
    _logger->error("SYS_CFG2 chip-id read failed on {:04x}:{:04x} — not a "
                   "Realtek vendor-protocol device; refusing rather than "
                   "falling through to Jaguar1",
                   vid, pid);
    return nullptr;
  }
  uint8_t chip_id = *chip_id_read;

  if (rtl8733b::is_chip_id(chip_id)) {
#if defined(DEVOURER_HAVE_8733B)
    _logger->info("Creating Rtl8733bDevice ({:04x}:{:04x}, chip-id 0x{:02x})",
                  vid, pid, chip_id);
    return std::make_unique<Rtl8733bDevice>(
        RtlAdapter(dev_handle, _logger, ctx, usb_lock, cfg), _logger, cfg);
#else
    _logger->error("RTL8733B (chip-id 0x16) detected but support not compiled "
                   "in (DEVOURER_8733B=OFF)");
    return nullptr;
#endif
  }

  /* A failed/transient register read on a known 8733B PID must not route the
   * adapter into Jaguar1 merely because that is the historical fallback. */
  if (rtl8733b::is_usb_id(vid, pid)) {
    _logger->error("Known RTL8733B USB device {:04x}:{:04x} reported unexpected "
                   "SYS_CFG2 chip-id 0x{:02x}; refusing Jaguar fallback",
                   vid, pid, chip_id);
    return nullptr;
  }

  if (is_8822b_chip_id(chip_id)) {
#if defined(DEVOURER_HAVE_JAGUAR2)
    _logger->info("Creating RtlJaguar2Device (PID 0x{:04x}, chip-id 0x{:02x})",
                  pid, chip_id);
    return std::make_unique<RtlJaguar2Device>(
        RtlAdapter(dev_handle, _logger, ctx, usb_lock, cfg), _logger,
        jaguar2::ChipVariant::C8822B, cfg);
#else
    _logger->error("RTL8822B (chip-id 0x{:02x}) detected but Jaguar2 support "
                   "not compiled in (DEVOURER_JAGUAR2=OFF)",
                   chip_id);
    return nullptr;
#endif
  }

  if (chip_id == kChipId8821C) {
#if defined(DEVOURER_HAVE_JAGUAR2_8821C)
    _logger->info("Creating RtlJaguar2Device C8821C (PID 0x{:04x}, chip-id "
                  "0x{:02x})",
                  pid, chip_id);
    return std::make_unique<RtlJaguar2Device>(
        RtlAdapter(dev_handle, _logger, ctx, usb_lock, cfg), _logger,
        jaguar2::ChipVariant::C8821C, cfg);
#else
    _logger->error("RTL8821C (chip-id 0x09) detected but 8821C support not "
                   "compiled in (DEVOURER_JAGUAR2_8821C=OFF)");
    return nullptr;
#endif
  }

  if (chip_id == 0x13 || chip_id == 0x17) {
#if defined(DEVOURER_HAVE_JAGUAR3)
    /* Reject the variant whose support wasn't compiled in (0x13 = 8822C,
     * 0x17 = 8822E) rather than construct a device whose PHY-table /
     * calibration dispatchers were built out. */
#if !defined(DEVOURER_HAVE_JAGUAR3_8822C)
    if (chip_id == 0x13) {
      _logger->error("RTL8822C (chip-id 0x13) support not compiled in "
                     "(DEVOURER_JAGUAR3_8822C=OFF)");
      return nullptr;
    }
#endif
#if !defined(DEVOURER_HAVE_JAGUAR3_8822E)
    if (chip_id == 0x17) {
      _logger->error("RTL8822E (chip-id 0x17) support not compiled in "
                     "(DEVOURER_JAGUAR3_8822E=OFF)");
      return nullptr;
    }
#endif
    auto variant = chip_id == 0x17 ? jaguar3::ChipVariant::C8822E
                                   : jaguar3::ChipVariant::C8822C;
    _logger->info("Creating RtlJaguar3Device (PID 0x{:04x}, chip-id 0x{:02x})",
                  pid, chip_id);
    return std::make_unique<RtlJaguar3Device>(
        RtlAdapter(dev_handle, _logger, ctx, usb_lock, cfg), _logger, variant,
        cfg);
#else
    _logger->error("Jaguar3 chip (chip-id 0x{:02x}) detected but Jaguar3 "
                   "support not compiled in",
                   chip_id);
    return nullptr;
#endif
  }

#if defined(DEVOURER_HAVE_JAGUAR1)
  _logger->info("Creating RtlJaguarDevice (PID 0x{:04x}, chip-id 0x{:02x})", pid,
                chip_id);
  /* Pass ctx so RtlAdapter::_ctx is set: the Jaguar1 RX loop now drives an
   * async URB queue (bulk_read_async_loop) whose event pump needs the same
   * libusb context the handle was opened on (as Jaguar2/3 already do above). */
  return std::make_unique<RtlJaguarDevice>(
      RtlAdapter(dev_handle, _logger, ctx, usb_lock, cfg), _logger, cfg);
#else
  _logger->error("Jaguar1 chip (PID 0x{:04x}, chip-id 0x{:02x}) detected but "
                 "Jaguar1 support not compiled in",
                 pid, chip_id);
  return nullptr;
#endif
}

#if defined(DEVOURER_HAVE_PCIE)
std::unique_ptr<IRadio> WiFiDriver::CreateRadioPcie(
    std::shared_ptr<devourer::PcieTransport> transport,
    const devourer::DeviceConfig &cfg) {
  if (!transport) {
    _logger->error("CreateRadioPcie: null transport");
    return nullptr;
  }
  /* AX parts first, by PCI device id — on that silicon 0x00FC is
   * R_AX_SYS_CHIPINFO (die-id), not a Jaguar chip-id, mirroring the USB
   * factory's PID-first Kestrel dispatch. */
  if (auto kvariant = kestrel::variant_for_pci_id(transport->pci_vendor_id(),
                                                  transport->pci_device_id())) {
    if (*kvariant != kestrel::ChipVariant::C8852C) {
      _logger->error("PCI {:04x}:{:04x} at {} is an RTL8852BE: its PCIe power "
                     "sequence is unported — refusing rather than running the "
                     "USB one",
                     transport->pci_vendor_id(), transport->pci_device_id(),
                     transport->bdf());
      return nullptr;
    }
#if defined(DEVOURER_HAVE_KESTREL_8852C)
    _logger->info("Creating RtlKestrelDevice C8852C over PCIe ({}; PCI "
                  "{:04x}:{:04x})",
                  transport->bdf(), transport->pci_vendor_id(),
                  transport->pci_device_id());
    return std::make_unique<RtlKestrelDevice>(
        RtlAdapter(std::move(transport), _logger, cfg), _logger,
        kestrel::ChipVariant::C8852C, cfg);
#else
    _logger->error("RTL8852CE detected but 8852C support not compiled in "
                   "(DEVOURER_KESTREL_8852C=OFF)");
    return nullptr;
#endif
  }

  /* Chip identity from SYS_CFG2 (0x00FC) over BAR2 MMIO — the same dispatch
   * signal the USB factory reads via a vendor control transfer. */
  const uint8_t chip_id =
      *reinterpret_cast<volatile uint8_t *>(transport->mmio() + 0x00FC);

  if (chip_id == kChipId8821C) {
#if defined(DEVOURER_HAVE_JAGUAR2_8821C)
    _logger->info("Creating RtlJaguar2Device C8821C over PCIe ({}; chip-id "
                  "0x{:02x})",
                  transport->bdf(), chip_id);
    return std::make_unique<RtlJaguar2Device>(
        RtlAdapter(std::move(transport), _logger, cfg), _logger,
        jaguar2::ChipVariant::C8821C, cfg);
#else
    _logger->error("RTL8821C[E] (chip-id 0x09) detected but 8821C support not "
                   "compiled in (DEVOURER_JAGUAR2_8821C=OFF)");
    return nullptr;
#endif
  }

  _logger->error("PCIe chip-id 0x{:02x} at {} is not supported over PCIe "
                 "(RTL8821C[E] chip-id 0x09, or RTL8852CE by PCI id 10ec:c852)",
                 chip_id, transport->bdf());
  return nullptr;
}
#endif /* DEVOURER_HAVE_PCIE */