WIP: Jaguar3 (RTL8822CU / RTL8812EU) userspace port — software datapath (needs hardware testers)

[josephnef]

What this is

A work-in-progress port adding the Realtek "Jaguar3" 802.11ac USB family
— RTL8822CU / RTL8812EU / RTL8822EU — to devourer, alongside the existing
Jaguar wave-1 chips (8812AU/8811AU/8821AU/8814AU).

It is opened as a draft so people with Jaguar3 hardware can test the on-air
bring-up — the entire software datapath is implemented and unit-validated, but
the remaining milestones genuinely need a device + usbmon diffing against the
kernel rtl88x2eu driver.

Motivation

FPV narrowband (5/10 MHz) TX. That underclock-the-baseband trick lives at
baseband registers 0x9b0/0x9b4, which exist on Jaguar3 but not on
Jaguar1 (Jaguar1's baseband has no clock divider). So narrowband on devourer
requires adding the Jaguar3 family. The narrowband register recipe is already
captured in RadioManagement8822c for when bring-up reaches it.

Architecture

• New IRtlDevice interface; WiFiDriver::CreateRtlDevice dispatches per
  chip family. The Jaguar1 path (RtlJaguarDevice) is unchanged in behaviour.
• New src/jaguar3/: RtlJaguar3Device (orchestrator), Hal8822c
  (power/queue/tables + chip-version decode), Halmac8822cFw (verbatim HalMAC
  DLFW port incl. rsvd-page transport), RadioManagement8822c (channel/BW +
  narrowband recipe), FrameParser8822c (48B TX / 24B RX descriptor + checksum
  • radiotap→desc), PhyTableLoader8822c (the newer "halbb" table walker).
• BB/AGC/RF tables generated by tools/extract_8822c_phy_tables.py; NIC firmware
  blob in hal/hal8822c_fw.c.

Done & unit-validated without hardware

• halbb table walker vs the real 8822c tables (phy_reg→1289 writes, first
  0x1d0c=0x00410000; agc_tab→450; radioa/b)
• HalMAC DLFW header parse vs the real NIC firmware (200624 B → exact section sizes)
• 8822C TX/RX descriptor field maps + checksum self-consistency; radiotap→desc
• SYS_CFG1 chip-version (cut/vendor/RF) bit extraction
• Full cmake --build is green; Jaguar1 demos unaffected

Needs hardware (the open milestones — see docs/jaguar3-bringup.md)

• M2: hand-rolled power-on (PWR_SEQ), EFUSE read → rfe_type, queue/page
  allocation (_rsvd_boundary), RF-table apply (odm_set_rf_reg)
• M3: confirm DLFW boots (REG_MCUFW_CTRL==0xC078) — the hard gate
• M4/M5: on-air RX then TX (sniffer/SDR)
• M6: narrowband 10/5 MHz, SDR-confirmed

Testing notes for hardware owners

• Force the family while detection matures: DEVOURER_FAMILY=jaguar3 (PID-based
  detection is reliable for RTL8822CU 0xc82c/0xc82e/0xc812, but an 8812EU can
  collide with the 8812AU 0x8812 — resolved properly once SYS_CFG family
  detection lands).
• The intended bring-up method is usbmon capture of the kernel rtl88x2eu
  driver vs devourer, register-canary diffing, RX-before-TX — same approach that
  landed the 8814.

docs/jaguar3-bringup.md has the full milestone map, the halbb table format,
the narrowband register table, and the bring-up runbook.

🤖 Generated with Claude Code