jaguar2: init-time firmware register IO-offload (HalMAC cfg_param)

[josephnef]

What

Cold-boot init on the HalMAC generations is register-write-bound — the BB/AGC/RF phy-table load is thousands of synchronous USB register control transfers (measured: 8822E ~1.4 s / 9207 writes; 8812BU ~5.7 s of writes). Realtek's HalMAC firmware exposes cfg_param (SUB_CMD 0x08, class FW_OFFLOAD) — the 11ac ancestor of the mac_ax CMD_OFLD shipped for Kestrel in #328: a buffer of register-write commands the on-chip CPU replays. This routes the static phy-table writes through it, collapsing the control-transfer stream into a handful of bulk transfers.

• New src/HalmacCfgParam.{h,cpp} — generation-agnostic 12-byte-per-command packer + flush with injected transport (dl_rsvd_page + send_h2c_pkt + a BB read-back verify). Table entries are full-register writes (MSK_EN=0), so the fw writes the value verbatim.
• Self-validating: each flush reads back the batch's last BB write and polls until it lands — this confirms the firmware actually replayed the buffer (vs silently dropping the H2C) and gates reuse of the reserved page. A mismatch fails the offload so the caller redoes the tables direct (idempotent) — the chip is never left half-configured.
• Wired on Jaguar2 via DEVOURER_FW_TABLE_OFLD (tuning.fw_table_offload, default 0): bit 1 = BB+AGC, bit 2 = also the RF radio tables (RF_W).

Result (on-air, RTL8812BU)

	InitWrite
direct	6480 ms
offload (BB+AGC+RF)	5486 ms

The read-back verify passes (firmware replays correctly; RF state matches the direct path) and 2768 register writes move off the control-transfer path. This DUT's init is dominated by a fixed-cost LCK-timeout poll, so the exposed write fraction (~15%) understates the effect — the config-identity (offloaded == direct) is the real proof.

Gating / safety

DEVOURER_FW_TABLE_OFLD=0 (default) is byte-identical to before. A transport error or a read-back mismatch triggers a full direct re-apply. Opt-in — init is higher blast-radius than a hop.

Jaguar3 (follow-up)

Investigated but not shipped here. A config-dump A/B proved the 8822C/E firmware does replay cfg_param (5/6 core BB registers match the direct path with fw-only writes), but it replays lazily (needs an end-of-apply verify, not a per-batch read-back) and its reserved-page download stalls ~1 s per batch. Left as a documented follow-up.

Validation

• On-air 8812BU: read-back verify passes, init 6.5 s → 5.5 s, config matches direct.
• ctest 36/36; per-chip build-config matrix unaffected (new file is in the always-compiled core).
• tests/fw_table_offload.sh: cold-cycle A/B harness (init-time + read-back verdict).

🤖 Generated with Claude Code