Per-packet TX-power control on Jaguar1 (8812/8821/8814) and Jaguar3 (8822C/E): no working knob found — magic register wanted

[josephnef]

Summary

Jaguar2 (8822BU/8821CU) has a real per-packet TX-power lever — the TX-descriptor TXPWR_OFSET field, a hardware ±dB LUT applied per-frame at zero USB cost (shipped in #194). Jaguar1 and Jaguar3 do not have an equivalent that we could find or make work. This issue documents the investigation so someone with deeper Realtek knowledge (or a datasheet) can find a knob we missed.

To be clear about terminology, there are two things:

• Per-rate power (each packet's rate selects a pre-programmed TXAGC row): supported on all three generations already, and runtime-shiftable via SetTxPowerOffsetQdb (Runtime TX-power API: quarter-dB offset + unified knobs + thermal readout on all three generations #188). This is what the vendor/forum call "per rate, per packet".
• Per-packet power offset (a ±dB trim applied to a frame independent of its rate, e.g. boost one critical frame at the same MCS): this is what's missing on Jaguar1/Jaguar3.

Everything below is about the second one.

What we want it for

An adaptive-link / UEP controller wants to nudge the power of an individual injected frame without a TXAGC register rewrite (~60–160 USB transfers) and without changing its rate. On Jaguar2 the descriptor bitfield does this for free. We'd like the same on the other families.

Jaguar1 (8812AU / 8821AU / 8814AU) — no descriptor field at all

These predate HalMAC and use the old-style TX descriptor (rtl8812a_fill_txdesc). There is no TXPWR_OFSET-equivalent bitfield anywhere in the 40-byte descriptor — the vendor tree has no SET_TX_DESC_TXPWR_OFSET_8812/_8814 and no dynamic-TX-power desc fill for these chips. Per-packet power on Jaguar1 is therefore purely rate selection today.

Open question for helpers: is there an undocumented per-frame power bitfield in the 8812A/8814A TX descriptor, or a MAC/BB register that applies a transient offset keyed to the next TX (a "one-shot txagc" or MP-mode per-frame gain)? The 8814A in particular (4T4R, 3081 MCU) might have MCU-mediated per-frame power we haven't explored.

Jaguar3 (8822C / 8822E) — field exists but measured inert

The HalMAC descriptor on 8822C/8822E has bits 0x14[28:29] named TXPWR_OFSET_TYPE — a 2-bit "type" selector, not the 8822B/8821C 3-bit dB-level TXPWR_OFSET (that macro is guarded to 8821C/8198F/8197G, not Jaguar3). The vendor's dynamic-TX-power switch (hal_dm.c:297) has cases only for 8822B/8821C, so fill_desc_dyntxpwr is null on 8822C/E, and there is no type → dB mapping anywhere in phydm that we could find.

We wired it anyway and measured it on-air (instrumented fill_data_tx_desc_8822c writing 0x14[28:3], second-adapter per-frame RSSI as the sensor, sweeping the field; TX at a fixed rate + fixed base power):

step (value)	8822BU (reference, works)	8822CU	8822EU
0	rssi 96 (base)	rssi 52 (base)	rssi 38 (base)
+6 dB nominal	+5	0 (52)	0 (38)
+3 dB nominal	+2	0 (52)	0 (38)
−3 dB nominal	−4	−2	0 (38)
−11 dB nominal	−13	−2	0 (38)

• 8822EU: fully inert — RSSI didn't budge across the whole range.
• 8822CU: effectively inert — no positive gain at all, and at most −2 raw (non-monotonic) on the negative steps.
• 8822BU (control): clean — tracks the vendor LUT (−3/−7/−11/+3/+6 dB).

So the field either needs a companion enable we didn't find, or is genuinely not wired to the TXAGC adder on these parts. This confirms the community gist's note that it's "unwired for 8822E … coarse (~8 steps) even if it worked" — and upgrades it to measured inert on both Jaguar3 variants.

Open questions for helpers:

1. What does TXPWR_OFSET_TYPE (values 0–3) actually select on 8822C/8822E? Is there a per-type offset table (register block) that must be programmed first for the field to have any effect?
2. Is there a MAC/BB enable bit that gates per-descriptor power offset on Jaguar3 (analogous to a CONFIG_SUPPORT_DYNAMIC_TXPWR HW switch)?
3. Does the 8822E TXPWR_OFSET (3-bit, defined under the wrong #if guard in the header) physically exist and do anything if written as bits 0x14[28:30]?

How to reproduce / extend

The measurement is cheap — a descriptor bitfield write + a second-adapter RSSI sweep (no SDR needed; a WiFi chip's per-frame RSSI is the right sensor at bench range). The reusable harness pattern is in tests/txpkt_pwr_ofset_onair.sh (Jaguar2). A helper investigating this would:

1. Add the candidate descriptor write (or companion register) to fill_data_tx_desc_8822c / the Jaguar1 descriptor.
2. Sweep it while a second devourer adapter logs <devourer-stream> per-frame RSSI at a fixed TX rate/power.
3. If any value moves on-air power monotonically → you found the knob; report the register/bit + the value→dB mapping and we'll wire it properly.

What already works (so nobody re-does it)

• Jaguar2 per-packet TXPWR_OFSET — merged (Jaguar2: per-packet TX power via TX-descriptor TXPWR_OFSET (radiotap-driven) #194).
• Per-rate power + runtime quarter-dB offset on all three generations — merged (Runtime TX-power API: quarter-dB offset + unified knobs + thermal readout on all three generations #188).
• The Jaguar3 DIG / static-IGI question (separate) — measured, not needed (Jaguar3: no dynamic initial gain (DIG) — IGI is static after bring-up (parity gap vs Jaguar1/2) #190).

Pointers welcome. If you have a Realtek TX-descriptor datasheet for the 8812A / 8814A / 8822C / 8822E that documents a per-frame power field, that alone would likely settle it.