RTL8822E: close all open quirks/unknowns and produce a definitive quirks doc

[josephnef]

Goal

The RTL8822E family (WiFi-only RTL8812EU 0bda:a81a + BT-combo RTL8822EU 0bda:e822, chip-id 0x17, Jaguar3) carries several documented-but-not-root-caused quirks and untested areas. This issue tracks a systematic campaign to (a) root-cause the open ones, (b) confirm the ones we work around blindly, and (c) land a definitive docs/8822e-quirks.md so nothing about this chip is folklore.

Known quirks — root-caused vs OPEN

#	Quirk	Status	Code
1	Path-B OFDM TXAGC (0x41e8) desenses RX — any nonzero write near-deafens the RX, value-independent, field-specific. Neutralized structurally (skip_path_b_ofdm_ref gated on _rx_wanted); cost = path-B OFDM TX pinned to table default in TX+RX.	ROOT CAUSE OPEN — "suspected path-B TSSI/gain-stage asymmetry vs the kernel's"	RadioManagementJaguar3.{h,cpp} (apply_power_by_rate_8822e, wr(0x41e8,…)), RtlJaguar3Device.h (_rx_wanted)
2	2.4 GHz RX-deaf without a 3-wire re-tune — BB-window RF writes don't push RF18/RXBB to the 2G analog front-end; needs the 0x1830[29]/0x4130[29] brackets. Fixed, but fragile (5 GHz survives on init defaults).	fixed, needs validation	RadioManagementJaguar3.cpp:172
3	2.4 GHz TX throughput anomaly — bench ch6 = 8 Mbps vs ch36 = 51 / ch149 = 47 (~6× low on 2.4 GHz).	UNEXPLAINED	README bench row
4	OTP/efuse only reliably readable at init (burst mode + sw-power-cut, one-shot; probe refused post-bring-up by design).	by-design, document	HalJaguar3.cpp (cache_efuse_8822e, efuse_pwr_cut_8822e), RtlJaguar3Device.cpp:1068
5	Retrofit RX is unreliable — DEVOURER_TX_WITH_RX must be set before InitWrite; post-hoc filter re-open + enable_rx_path is unreliable.	known, document + test	RtlJaguar3Device.h:45
6	IQK clears the 40 MHz TX_CCK_IND bit (hardware-observed on the 8812EU) — calibration-order fix-up.	fixed, verify	RadioManagementJaguar3.h:204
7	The BT-combo RTL8822EU (0bda:e822) is entirely untested — all EU validation to date is the WiFi-only 8812EU. Does the combo part need the coex runtime thread the way the CU does?	UNKNOWN	Jaguar3Calibration.h:20, coex thread notes in CLAUDE.md

Test matrix to close the gaps

• Small mods to build on android #1 (the big one): bisect devourer's TXAGC bring-up sequence against the vendor kernel's (tests/eu_txagc_regdiff.sh + tests/decode_txagc.py already diff 0x18e8/0x41e8). Determine whether a correct path-B TSSI/gain-stage setup lets 0x41e8 be programmed without desense — i.e. recover path-B OFDM TX power in TX+RX mode. Confirm/refute the TSSI-asymmetry hypothesis with RX-sensitivity (MDS) measurements as 0x41e8 and the path-B TSSI regs are swept.
• Log libusb error code in rtw_read #2: validate 2.4 GHz RX across every channel switch and bandwidth (20/40/80 + 5/10 narrowband), incl. 5↔2.4 GHz band hops (tests/eu_rx_validate.sh), asserting the front-end actually re-tunes each time.
• Fix unreadable code in logs #3: root-cause the 2.4 GHz TX shortfall — PA bias (efuse PPG_PABIAS_2G*), TXAGC reference, or the same 2G-front-end path as Log libusb error code in rtw_read #2 on the TX side. SDR duty × PHY-rate on-air (tests/bench_onair.py), compared to the vendor driver.
• Fix build on Windows #4/Remove colored console output on Windows #5/Remove color code in logger #6: confirm behaviours and document the constraints with reproducers.
• Devourer Experimental TX implementation #7: acquire an RTL8822EU (BT combo) and run the full matrix; determine the coex-thread requirement for the EU.
• Board variance: repeat on ≥2 different 8812EU/8822EU boards (efuse RFE-type / PA-bias layouts differ — HalJaguar3.cpp:101 handles rfe_type 21..24).

Full per-band × per-bandwidth × RX/TX/full-duplex matrix via tests/regress.py (EU rows already present) + the on-air/SDR benches.

Deliverable

docs/8822e-quirks.md — every confirmed behaviour, each quirk marked root-caused or worked-around, the residual costs (e.g. path-B TX power in TX+RX), and the reproducers. Update the README bench row once #3 is understood.

Hardware

Reference: LB-LINK BL-M8812EU2 (0bda:a81a, WiFi-only). Needed additionally: an RTL8822EU (BT combo, 0bda:e822) and a second 8812EU/8822EU board for variance. VM per tests/setup_vm.sh for the kernel-cross-validation cells.

[snokvist]

RTL8822E MCS5-7 (16/64-QAM) TX failure: root cause = path-B two-chain under-calibration (kernel-proven fixable, not a HW/EVM ceiling)

Sharing a bench-verified root cause for one of the open 8822E quirks — the 8822E (8812EU) being usable at MCS0-2 but garbling at MCS4+ on TX.

Symptom (reproduced cleanly)

8822E TX → 8822C RX, 5 GHz / 20 MHz / ~30 cm, single QoS-Data frames, rate/EVM read from the RX descriptor:

• MCS0/MCS2 (BPSK/QPSK): deliver clean, correct rate.
• MCS4/MCS5/MCS7 (16/64-QAM): 0 clean — the RX can't even lock the HT rate (frames misdetect as legacy).

It is NOT a hardware EVM ceiling — the kernel proves it

Loading the vendor rtl88x2eu driver on the same 8822E adapter (monitor, ch36, 5 dBm) and injecting HT frames → 8822C RX decodes MCS7 rate 19 clean, EVM −53 dB. So the silicon transmits clean 64-QAM; the gap is in devourer's calibration, and it's fixable.

Direction swap confirms isolation: 8822C→8822E delivers MCS5/MCS7 fine (EVM −57/−58). So RX, link, and the peer TX all handle MCS7 — the fault is exclusively the 8822E transmit path at dense modulation.

Root cause

On this module 5 GHz TX is routed to both antennas (BB_PATH_AB) — 5 GHz output collapses if not routed to both — so both PAs are driven even for 1SS HT. Path A matches the kernel (OFDM ref 0x18e8, path-A IQK applied), but path B is under-calibrated: the path-B OFDM TXAGC ref 0x41e8 (kernel programs the efuse value 0x53) plus the path-B gain/IQK bring-up are wrong/absent. A path-B gain/phase error relative to path A corrupts the two-chain (CDD) combined constellation, and the distortion scales with symbol density — 64/16-QAM shred while BPSK/QPSK ride through. Exact match for the symptom and the direction-swap result.

Note: forcing the 0x41e8 ref alone does not fix it — necessary but not sufficient; the path-B analog calibration (gain/IQK) is also needed. We're prototyping the path-B TX-bring-up port now and will share results.

Ruled out (with corrected methodology)

Thermal drift (fails cold), A-MPDU (paggr=0, single MPDUs), TX power path (flat and efuse-calibrated both fail), path-A IQK (applied; DEVOURER_SKIP_IQK changes nothing), DACK, TXGAPK, and the per-rate TXAGC 0x3a00 table (correct once byte order is decoded).

Methodology notes (may save others time)

• Measure with QoS-Data frames + the RX rx.frame rate/EVM, not beacons (beacons don't carry the pinned MCS) and not rx.pkt (decimated: first 10 then every 100th).
• Don't set a flat TX_PWR override — it zeroes the per-rate diffs; use the efuse-calibrated default.
• usbmon prints wValue as the true register; watch byte order when parsing.

Bonus: a separate real bug found + fixed

Halrf8822e::rf_write routed RF reg 0x0 through the direct 0x3c00/0x4c00 window like every other RF reg, but on 8822E reg 0x0 must go through the legacy FON path 0x1808/0x4108 (per config_phydm_write_rf_reg_8822e). This silently no-op'd every rf_write(path, 0x0, …) — most visibly the TXGAPK gain-index select, so the 5 GHz gain-table readback came back all-zero and TXGAPK was skipped. Fix = port the reg_addr==0x0 branch; verified passively (the 5 GHz readback then matches the kernel gain ramp exactly). It's a correctness fix, not the MCS5-7 cause.

Happy to share the full usbmon TX-path register diff, the repro scripts, and the kernel-TX injector if useful. We'll follow up with the path-B port.

[snokvist]

✅ RTL8822E MCS4+/64-QAM TX failure — root cause found + fix (bench-verified)

Follow-up that supersedes my earlier "path-B under-calibration" comment above. That comment was right about the direction (path B) but I reported a wrong null: I said "forcing the 0x41e8 ref alone does not fix it." That was because I forced only the [16:10] power-index field (mask 0x1fc00). The fix is the rest of the register. Here's the corrected, bench-verified story.

Symptom

8822E (8812EU, rfe-21) TX: MCS0/2 (BPSK/QPSK) clean, MCS4/5/7 (16/64-QAM) garbled — frames too corrupt for the RX to even lock the HT rate (misdetect as legacy). Power-invariant, present cold. Direction-swap (8822C→8822E) is clean at MCS7, and loading the vendor rtl88x2eu on the same adapter injects clean MCS7 (EVM −53 dB) — so it's a calibration/software gap, not a HW EVM ceiling. (DPK is not it — the kernel do_dpk_8822e force-bypasses rfe-21/22 too, so both drivers run DPK-bypassed.)

Root cause

Devourer programs only the [16:10] index of the OFDM TXAGC reference registers 0x18e8 (path A) / 0x41e8 (path B) and leaves the rest of the register at a wrong value; the vendor kernel programs the full register. Captured end-states (ch36):

reg	devourer (fail)	kernel (works)
0x18e8	00 20 81 00	00 70 80 00
0x41e8	00 4e 01 00	00 9e 00 00

Bench proof (EU→CU, MCS7 QoS-Data, ~30 cm, calibrated power, adapter-doctor HEALTHY before/after)

Forcing devourer's 0x18e8/0x41e8 to the kernel values, MCS7 clean-frame count (RX descriptor rate=19), with an MCS0 control:

                    MCS0 (control)     MCS7
baseline (devourer)      3376             0
+override both           3391          1308  (EVM -41 dB)   <- 64-QAM needs ~-27

Bisect: 0x41e8 (path B) alone = 434 ✅, 0x18e8 (path A) alone = 0, both = 1308. Path B is necessary, path A additive.

Fix

RadioManagementJaguar3::apply_ofdm_ref_upper_8822e() — full-DWORD write 0x18e8 <= 0x00807000, 0x41e8 <= 0x00009e00 (chip u32 = little-endian of the wire bytes above).

Two gotchas that cost me time:

1. Placement. The FW power-mode / coex H2C steps in InitWrite reprogram 0x18e8/0x41e8 wholesale in firmware, clobbering any earlier apply. The fix must be the last bring-up write (end of InitWrite, after the coex steps).
2. phy_set_bb_reg shifts the value by the mask's trailing-zero count — a non-contiguous mask (e.g. [24:17]|bit8) is silently mangled. Use a full-DWORD write or split into contiguous fields.

Verified via a clean OFF/ON toggle (no register override): fix OFF → MCS7 = 0; fix ON → MCS7 = 996 clean, EVM −41.3 dB (MCS0 ~3360 both, doctor HEALTHY).

Open for the maintainers (you have the efuse/cal context I don't)

The 0x18e8/0x41e8 values here are ch36-captured constants. The kernel's derivation is #if 0'd out in halrf_tssi_8822e.c (_halrf_set_efuse_kfree_offset_8822e / the TSSI codeword writers, mask 0x01fe0000), so I couldn't trace the general per-channel/efuse formula. Someone with the kfree/TSSI-offset context should confirm the correct channel-general values before shipping unconditionally — my patch keeps it env-gated (DEVOURER_8822E_OFDM_REF_FIX_OFF, values tunable) for that reason.

Happy to open a PR with the change + the register-override/bisect test harness if useful. Also note the RX-desense quirk #1: on this module path-B 0x41e8 writes are gated while RX is up — the MCS4+ TX fix and that RX-desense mitigation will need reconciling for concurrent TX+RX.

[josephnef]

@snokvist — the MCS4+/64-QAM TX fix is merged to master (b5a6df7, PR #268). Could you confirm on your unit (rfe-21 8812EU) that the problem is gone with a plain master build, without your register-override harness / env-gated 0x18e8/0x41e8 writes?

What actually landed (it reconciles with, but supersedes, the full-DWORD-refs fix from your follow-up):

• Root cause on our unit was front-end routing, not the TXAGC refs: the DPDT antenna switch was never routed to WL control (REG_LED_CFG 0x4c[24] = BIT_DPDT_WLBT_SEL — the halmac pin-mux step devourer's MAC init skipped; 0x204c is a readable mirror of 0x4c, which is why it surfaced there in end-state diffs), plus OFDM 1SS TX now rides a single path per kernel txpath_1ss semantics (0x820=0x32 at 5 GHz). On our unit your captured ref values alone did not fix MCS7 — the register pair above did, at any power including the efuse default.
• Your gotcha Small mods to build on android #1 was real and is fixed: the FW power-mode/coex H2Cs rewrite the TXAGC refs during bring-up, so all construction-time power state used to be inert; the authoritative TXAGC apply now runs after them. (Your 5 dBm kernel baseline vs the kernel's near-silent default power on our unit both reproduce, FWIW.)
• Your RF reg 0x0 FON-path bug is fixed exactly as you described (both halrf impls and the radio-table loader — the vendor tables carry reg-0 entries), verified by the gain-table readback you used.
• The 0x41e8 RX-desense quirk you flagged for reconciling is resolved — it was another artifact of the same front-end mis-config; path-B OFDM power is applied unconditionally now, TX+RX included (full-duplex validated).

Quick check on your side: DEVOURER_CHANNEL=36 DEVOURER_TX_RATE=MCS7 build/txdemo against your 8822C ground — expect clean rate-19 delivery at efuse default power (our bench: ~5k/12 s, EVM −48; matched-power EVM parity with the kernel at −60). Reproducers under tests/ (eu_mcs7_txagc_fix.sh is parametrized for the rate×power matrix), and the full behavior inventory is in docs/8822e-quirks.md.

If your unit still garbles at any rate on master, that would be the first confirmed board-variance data point (issue's open item) — a tests/eu_bb_endstate_diff.sh run on your rig would be gold in that case.

[snokvist]

This was only an initial finding and it seems to help only on ch36. It's an interesting lead but not an overall fix for 8812eu higher mcs. LLM overstated the fix suggestion, but at least it should not make things worse than before.