Skip to content

jaguar1: AC lifetime for DATA on the RTL8812A; TX-report BMC follows addr1 - #600

Open
snokvist wants to merge 2 commits into
OpenIPC:masterfrom
snokvist:upstream/8812au-ac-lifetime
Open

snokvist wants to merge 2 commits into
OpenIPC:masterfrom
snokvist:upstream/8812au-ac-lifetime

Conversation

@snokvist

Copy link
Copy Markdown
Collaborator

What

1. tx.data_on_be and tx.ac_lifetime_us, RTL8812A only. Both are opt-in and off by default.

  • tx.data_on_be: DATA frames go to the BE queue (QSEL 0) and its LOW bulk-OUT endpoint instead of MGMT.
  • tx.ac_lifetime_us: the MAC drops a frame that is still queued after this long, mid retry chain included.

The problem it solves: an injected frame on MGMT retries until the retry limit however old it is. A peer that stops ACKing therefore leaves seconds of stale frames in the queue.

src/AcTxQueue.h holds the register arithmetic, pinned by a new headless selftest. The environment variables are DEVOURER_TX_DATA_BE and DEVOURER_TX_AC_LIFETIME_US.

2. The TX descriptor's BMC bit follows addr1 on the RTL8812A. It was a constant 1. The firmware echoes it into the CCX TX report, so every unicast report read as a group frame.

This is the one change that applies with no knob set. It is its own commit, so it can be taken or left separately.

Scope: only what we could verify

The code applies on the RTL8812A with three bulk-OUT endpoints, the one part we measured.

  • The 8814A and 8821A share the Jaguar1 code. There the knobs log that they are not applied, and BMC keeps its constant.
  • Two-endpoint parts also log and skip.

Evidence

One RTL8812AU sends to an MT7612U on channel 100, near field. Every arm below ran on this branch, built on current master. "Stock" is master df65991.

Peer hears but never ACKs (500 fps of 1400 B at MCS4, retry 16, 10 s):

Build Delivered age max
Stock 3.3 s (grows with run length: 9.5 s in a 14 s run)
This PR, knobs off 3.1 s
ac_lifetime_us=68000 68.8 ms
ac_lifetime_us=20000 21.0 ms

Saturated MCS2, 7 s, interleaved (spread between runs is about 2 Mbit/s):

Build Mbit/s
Stock 9.5 / 10.6 / 10.9
This PR, knobs off 10.1 / 10.7
Knobs on 11.6 / 11.8

Knobs off: host RX frame counts match stock (231/223/199 against 235/220). The only difference is the BMC fix: unicast CCX reports go from 0 to about 7,000 per run.

Also:

  • ctest: 94/94 at each commit.
  • The same knobs ran in a downstream fork under live H.265 video for 323 s from an 8812AU: 241,159 of 241,159 frames delivered, 1.04 % retried.

For the maintainer: what we found but did not put in code (unverified, or other hardware)

  • The lifetime unit is 256 µs, not 128. The vendor hal_com_reg.h gives HAL92C_MSDU_LIFE_TIME_UNIT 128, but 20,000 µs gave 21.0 ms and 68,000 µs gave 68.8 ms. 128 would halve both.
  • BE "fast retry" is not offered on the 8812A. This means clearing the BE TXOP, REG_EDCA_BE_PARAM 0x005EA42B → 0x0000442B. On the 8812A it cut saturated MCS2 to 3.5–10.1 Mbit/s, against 11.3–13.6 without it. The lifetime alone holds the bound: 68.7 ms with it, 68.9 ms without.
  • The RTL8733B, Jaguar2 and Jaguar3 have the same halmac lifetime registers. Our fork applies the same knobs there, plus BE fast retry, which helps on those chips. Measured earlier on an 8733BU, 8812BU, 8812CU and 8812EU, one unit each. A follow-up PR, if wanted, after re-measuring on current master.
  • 8814A and 8821A: the BMC constant and the knobs are left as they were, unmeasured. Unicast injection with BMC=0 should be checked on those before widening.
  • Two-endpoint parts (8811AU/8821AU): the vendor two_out_pipe and _InitNormalChipTwoOutEpPriority put BE/BK on the second pipe. Widening data_on_be there needs that endpoint map; we have no such part.
  • rx.own_addr_only on Jaguar1 and RCR_ADF: our fork also clears RCR_ADF under own_addr_only. Master's rx filters: Jaguar1 port, identity refusal, caps flag (#597) #599 leaves it set. Our test could not isolate whether ADF matters, so it is not in this PR. A three-station test (a unicast link on the same channel, a listener on another address) would settle it.
  • rx.drop_ctrl on Jaguar1: the vendor header puts BlockAck/BAR/PS-Poll under ADF. This matches rx filters: Jaguar1 port, identity refusal, caps flag (#597) #599's note that BlockAcks still arrive.
  • The endpoint map: with the knob on, VI goes to NORMAL and VO/MGT/HIGH go to HIGH, as _InitNormalChipThreeOutEpPriority_8812AUsb maps them. We exercised only BE (DATA) and MGMT on air.
  • The examples' environment parsing clamps with std::min<unsigned long long>. A std::min<long>(v, UINT_MAX) form would give min(v, -1) where long is 32 bits (ARM32), turning any value into the 16.8 s maximum. Arithmetic only; not run on an ARM32 board.

🤖 Generated with Claude Code

…ifetime_us)

Two opt-in TX knobs, both off by default:

- tx.data_on_be: DATA frames use the BE queue (QSEL 0) and its LOW bulk-OUT
  endpoint instead of MGMT (0x12, HIGH). A USB-aggregated URB never mixes
  DATA with other frames.
- tx.ac_lifetime_us: the MAC drops a frame still queued after this long,
  retry chain included (REG_LIFETIME_EN 0x0426 bits 0..3,
  REG_PKT_LIFE_TIME 0x04C0, 256 us units).

Without them an injected frame on MGMT retries until the retry limit no
matter how old it is, so a peer that stops ACKing leaves seconds of stale
frames queued.

Scope: Jaguar1 on the RTL8812A with three bulk-OUT endpoints, the only
part measured. The 8814A, 8821A and two-endpoint parts log that the knobs
are not applied. src/AcTxQueue.h holds the register arithmetic, pinned by
tests/ac_tx_queue_selftest.cpp.

Measured, one 8812AU -> MT7612U, ch 100, near field, 500 fps of 1400 B at
MCS4, retry 16, a peer that never ACKs: delivered age max 3.3 s stock,
68.8 ms at 68000 us, 21.0 ms at 20000 us (so the unit is 256 us; the vendor
header names 128). Saturated MCS2, interleaved: stock 9.5 / 10.6 / 10.9
Mbit/s, knobs off 10.1 / 10.7, knobs on 11.6 / 11.8.
build_tx_block set BMC to a constant 1. The firmware echoes the bit into
the CCX TX report (TxReport::bmc), so every unicast frame's report read as
a group frame and a reader filtering group reports saw none.

On the RTL8812A, BMC now follows addr1's group bit. The MAC takes its ACK
decision from addr1 either way: delivery and retries were unchanged, and
unicast reports appeared (0 -> about 7,000 per 7 s saturated run). The
8814A and 8821A keep the constant 1: they share this code but were not
measured.

This changes behaviour with no knob set, for RTL8812A users of TX reports.
@qodo-free-for-open-source-projects

qodo-free-for-open-source-projects Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

PR Summary by Qodo

Bound RTL8812A DATA queue age and correct unicast TX reports

✨ Enhancement 🐞 Bug fix 🧪 Tests 📝 Documentation 🕐 20-40 Minutes

Grey Divider

AI Description

• Add opt-in BE routing and AC lifetime to prevent stale RTL8812A DATA retries.
• Derive the RTL8812A TX descriptor’s BMC bit from addr1 so unicast reports read correctly.
• Restrict queue changes to measured hardware and add headless register-arithmetic tests.
Merge Risk 🟡 Medium

Blast radius 🟡 Medium 💥 3 capabilities

  • 3 affected capabilities within one bounded functional scope: Jaguar1 RTL8812A monitor-injection TX.
  • The changed descriptor QSEL, USB endpoint, aggregation boundary, and lifetime register form one end-to-end data-transmission behavior.
  • They are separate implementation hops of the same delivered DATA-frame outcome, and the source limits their joint application to the Jaguar1 RTL8812A three-endpoint path.
  • AC expiration affects the same end-to-end DATA transmission capability: it changes how long queued/retrying DATA remains eligible for delivery, rather than creating a separate storage or consumer feature.
  • This is a distinct system outcome from packet delivery: the descriptor bit is echoed into the CCX report and affects consumers interpreting whether a transmission was group or unicast.
  • It remains within the same bounded Jaguar1 TX integration and is not a separate deployment or storage scope.
Behavioral complexity 🟡 Medium 🧩 Interacting branches, Coordinated invariants

  • Before: Jaguar1 used the MGMT QSEL/first-endpoint path and aggregation did not need to keep DATA and non-DATA frames on separate endpoints.
  • After: DATA classification, supported-hardware gating, final-QSEL precedence, endpoint routing, aggregation segmentation, and AC register state jointly determine transmission.
  • New correctness conditions: the endpoint must match the final descriptor QSEL; one URB must contain only frames compatible with one endpoint; lifetime programming must target the queue actually carrying DATA; and fallback behavior must remain unchanged when the gate is false.
  • These are newly interacting conditions, not complexity inherited merely from the existing register or aggregation helpers.
Potential damage 🟡 Medium 🩹 Recoverable

  • A wrong queue/endpoint choice or premature lifetime expiration can reduce or lose DATA-frame delivery.
  • Reverting configuration/code restores future transmissions, but frames already dropped by the MAC are not restored; application-level retransmission or a higher-layer retry is required.
  • The source states that expiry is silent and includes the retry chain, so this is not merely latency or cosmetic impact.
  • Future behavior is recoverable by disabling/reverting the knobs and reinitializing the device.
  • Already expired frames require the sender/application to retry; no automatic repair or delivery compensation is shown.
Assessed commit 443e7bf
Diagram

graph TD
  CFG["TX configuration"] --> GATE{"8812A three OUT?"} --> LIFE["AC lifetime registers"]
  CFG --> DESC["TX descriptor"] --> ROUTE["Queue endpoint"] --> ADAPTER["RtlAdapter TX"] --> USB["USB transport"]
  ADDR["Frame addr1"] --> DESC
  GATE -->|"BE routing eligible"| DESC
Loading
High-Level Assessment

The following are alternative approaches to this PR:

1. Expire frames in the host queue
  • ➕ Could avoid chip-specific lifetime registers.
  • ➖ Cannot stop a frame already queued in the MAC or partway through its retry chain, so it cannot provide the measured age bound.

Recommendation: Keep the scoped hardware-lifetime approach: moving DATA to an AC queue lets the MAC terminate stale retries, which host-side expiration cannot do. Retain the RTL8812A three-endpoint guard until other chips and endpoint layouts are measured.

Files changed (10) +354 / -6

Enhancement (5) +148 / -6
AcTxQueue.hDefine AC lifetime arithmetic and register application +66/-0

Define AC lifetime arithmetic and register application

• Adds the 256 µs lifetime conversion, DATA-frame predicate, and register writes. Zero lifetime leaves registers untouched; enabling lifetime preserves unrelated control bits.

src/AcTxQueue.h

RtlAdapter.cppSupport endpoint-specific asynchronous TX +5/-2

Support endpoint-specific asynchronous TX

• Routes ordinary sends through a new endpoint-aware method while preserving the configured endpoint override.

src/RtlAdapter.cpp

RtlAdapter.hDeclare endpoint-aware packet submission +2/-0

Declare endpoint-aware packet submission

• Exposes send_packet_ep for callers that select a bulk-OUT endpoint from the TX descriptor.

src/RtlAdapter.h

RtlJaguarDevice.cppRoute eligible DATA to BE and correct RTL8812A BMC +72/-4

Route eligible DATA to BE and correct RTL8812A BMC

• Applies lifetime settings on eligible hardware, selects USB endpoints from final QSEL, and separates DATA from other frames in aggregated transfers. Sets RTL8812A BMC from addr1 while retaining the previous value on unmeasured chips.

src/jaguar1/RtlJaguarDevice.cpp

RtlJaguarDevice.hDeclare Jaguar1 queue eligibility and routing helpers +3/-0

Declare Jaguar1 queue eligibility and routing helpers

• Adds private helpers for the supported-device check, lifetime application, and descriptor-based endpoint selection.

src/jaguar1/RtlJaguarDevice.h

Tests (2) +148 / -0
CMakeLists.txtRegister the AC queue headless selftest +7/-0

Register the AC queue headless selftest

• Builds the new selftest and adds it to CTest.

CMakeLists.txt

ac_tx_queue_selftest.cppTest lifetime conversion and register writes +141/-0

Test lifetime conversion and register writes

• Checks rounding, saturation, DATA classification, disabled behavior, preservation of unrelated register bits, and write-failure reporting using a fake transport.

tests/ac_tx_queue_selftest.cpp

Documentation (1) +30 / -0
CLAUDE.mdDocument Jaguar1 queue scope and measurements +30/-0

Document Jaguar1 queue scope and measurements

• Records the supported hardware, endpoint mapping, lifetime-unit evidence, performance measurements, and BMC report behavior.

src/jaguar1/CLAUDE.md

Other (2) +28 / -0
env_config.cppParse opt-in DATA routing and lifetime settings +6/-0

Parse opt-in DATA routing and lifetime settings

• Reads DEVOURER_TX_DATA_BE and positive DEVOURER_TX_AC_LIFETIME_US values, clamping the latter to the configuration field’s range.

examples/common/env_config.cpp

DeviceConfig.hExpose disabled-by-default TX queue knobs +22/-0

Expose disabled-by-default TX queue knobs

• Adds DATA-on-BE and AC-lifetime fields with their hardware scope, defaults, and delivery tradeoffs documented.

src/DeviceConfig.h

@qodo-free-for-open-source-projects

Copy link
Copy Markdown

Code Review by Qodo

🐞 Bugs (4) 📘 Rule violations (1) 📜 Skill insights (0)

Grey Divider


Remediation recommended

1. Doc omits the lifetime's drop cost 📘 Rule violation ◔ Observability
Description
The AC-lifetime table in src/jaguar1/CLAUDE.md presents the knobs-on delivered-age bound and
saturated throughput as favourable results, without stating that the lifetime drops frames a
slow-to-ACK peer would still have taken and that those drops are unreported. That adversarial
counterpart appears only in the DeviceConfig.h comment, so a reader of the nested doc sees the
gain without the cost when deciding whether to enable tx.ac_lifetime_us.
Code

src/jaguar1/CLAUDE.md[R159-160]

+| Peer never ACKs, delivered age max (10 s run) | 3.3 s | 3.1 s | 21.0 ms at 20000, 68.8 ms at 68000 |
+| Saturated MCS2, Mbit/s (7 s runs, interleaved) | 9.5 / 10.6 / 10.9 | 10.1 / 10.7 | 11.6 / 11.8 |
Evidence
The table quotes the knobs-on delivered-age bound and the knobs-on saturated throughput as
favourable results with no drop-cost counterpart in the same file. The adversarial counterpart
(frames dropped by a slow-to-ACK peer, reported nowhere) appears only in the DeviceConfig header.

CLAUDE.md: Pair Favorable Measurements with Adversarial Results
src/jaguar1/CLAUDE.md[157-161]
src/DeviceConfig.h[329-335]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The AC-lifetime section of `src/jaguar1/CLAUDE.md` quotes the knobs-on delivered-age bound and throughput gain without the adversarial counterpart: a lifetime drops frames a slow-to-ACK peer would still have taken, and the drop is not reported.

## Fix Focus Areas
- src/jaguar1/CLAUDE.md[157-161]
- src/DeviceConfig.h[329-335]

## Recommended Fix
In the measurement paragraph after the table, state that knobs-on frames are dropped at the lifetime even when a slow peer would have accepted them, and that the drops are unreported. Keep the table as is, and point to the `DeviceConfig.h` comment for the full statement rather than duplicating it.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


2. A stalled transmit endpoint stays halted 🐞 Bug ☼ Reliability
Description
send_packet_ep() now submits frames to different endpoints, but UsbTransport records a transmit
stall as one shared flag and clears the endpoint used by the next send. If a low-endpoint transfer
stalls and the next frame uses the high endpoint, recovery clears the high endpoint and leaves the
stalled one halted.
Code

src/jaguar1/RtlJaguarDevice.cpp[863]

+  return _device.send_packet_ep(tx_ep_for(usb_frame.data()), usb_frame.data(), usb_frame.size());
Evidence
The changed send path can select different endpoints, whereas a STALL sets a single flag and the
next submission consumes it using that submission's endpoint.

src/jaguar1/RtlJaguarDevice.cpp[892-902]
src/RtlAdapter.cpp[90-99]
src/UsbTransport.cpp[1141-1158]
src/UsbTransport.cpp[1281-1289]
src/UsbTransport.h[234-241]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Per-frame endpoint routing activates a shared stall-recovery flag that can clear a different endpoint from the one that stalled.
## Fix Focus Areas
- src/jaguar1/RtlJaguarDevice.cpp[892-902]
- src/UsbTransport.h[234-241]
- src/UsbTransport.cpp[1141-1158]
- src/UsbTransport.cpp[1281-1289]
## Recommended Fix
Record the stalled transfer's endpoint in the completion callback and clear that endpoint's halt before retrying traffic on it. Preserve pending recovery for other stalled endpoints.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


3. Failed lifetime setup leaves the radio up 🐞 Bug ☼ Reliability
Description
apply_ac_tx_queue_knobs() throws when a lifetime-register write fails but does not roll back the
bring-up state or partially completed register programming. Because both initialization paths set
_brought_up before this call, a caller retaining the device after the exception can still reach
APIs that treat it as initialized.
Code

src/jaguar1/RtlJaguarDevice.cpp[R883-885]

+  std::lock_guard<std::recursive_mutex> lock(_port0_mu);
+  if (!devourer::apply_ac_tx_queue(_device, _cfg.tx))
+    throw std::runtime_error("Jaguar1: AC lifetime could not be set");
Evidence
The new failure path runs after StartWithMonitorMode() marks the device brought up. The helper
attempts two register writes before reporting failure, and later APIs consult _brought_up to
determine whether hardware state is valid.

src/jaguar1/RtlJaguarDevice.cpp[2179-2185]
src/jaguar1/RtlJaguarDevice.cpp[139-142]
src/jaguar1/RtlJaguarDevice.cpp[1786-1789]
src/AcTxQueue.h[52-61]
src/jaguar1/RtlJaguarDevice.cpp[1099-1109]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A failed AC lifetime write propagates from initialization after the device has been marked brought up, potentially leaving partially programmed registers.
## Fix Focus Areas
- src/jaguar1/RtlJaguarDevice.cpp[883-885]
- src/jaguar1/RtlJaguarDevice.cpp[139-142]
- src/jaguar1/RtlJaguarDevice.cpp[1786-1789]
- src/AcTxQueue.h[52-61]
## Recommended Fix
Handle failure in both bring-up paths so the device is not exposed as successfully brought up. Account for a write that reports failure after changing a register, either by restoring the prior values or by requiring a full reset before reuse.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


View review recommended (1)
4. Four-endpoint RTL8812A parts get an unmeasured mapping 🐞 Bug ≡ Correctness
Description
ac_queue_ok() accepts RTL8812A devices with four bulk-OUT endpoints, so tx_ep_for() applies its
three-endpoint table even though _InitQueuePriority_8812AUsb selects a different four-endpoint
map. On those devices, VO goes to HIGH rather than its mapped NORMAL queue and MGT goes to HIGH
rather than EXTRA, while the knobs apply without a 'not applied' warning.
Code

src/jaguar1/RtlJaguarDevice.cpp[R870-873]

+bool RtlJaguarDevice::ac_queue_ok() const {
+  return _eepromManager->version_id.ICType == CHIP_8812 &&
+         _device.bulk_out_ep_count() >= 3;
+}
Evidence
The guard at src/jaguar1/RtlJaguarDevice.cpp[870-873] admits any RTL8812A with at least three
bulk-OUT endpoints, including four-endpoint devices. Queue-priority initialization branches on
OutEpNumber and assigns a distinct map for four endpoints, but tx_ep_for() uses the
three-endpoint routing table for devices admitted by the guard.

src/jaguar1/HalModule.cpp[1434-1448]
src/jaguar1/HalModule.cpp[1613-1636]
src/jaguar1/RtlJaguarDevice.cpp[892-903]
src/jaguar1/RtlJaguarDevice.cpp[870-873]
src/jaguar1/RtlJaguarDevice.cpp[892-902]
src/jaguar1/HalModule.cpp[1417-1447]
src/jaguar1/HalModule.cpp[1613-1630]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`ac_queue_ok()` enables the three-endpoint AC queue routing knobs on four-endpoint RTL8812A devices. Their queue-priority map assigns VO to NORMAL and MGT to EXTRA, but `tx_ep_for()` uses the three-endpoint table, and the knobs apply without a 'not applied' warning.

## Fix Focus Areas
- src/jaguar1/RtlJaguarDevice.cpp[870-873]

## Recommended Fix
Require `_device.bulk_out_ep_count() == 3` before applying either knob or its endpoint routing. Preferably also require `_device.OutEpNumber == 3`, matching the value `_InitQueuePriority_8812AUsb` branches on. Leave other endpoint configurations on their existing path so four-endpoint devices receive the 'not applied' warning.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools



Informational

5. Lifetime-unit comment cites a different measurement 🐞 Bug ⚙ Maintainability
Description
The kLifetimeUnitUs comment says 68000 us gave 70.1 ms, while the commit message, the PR
description and the jaguar1 CLAUDE.md table all say 68.8 ms. A reader checking the 256 us unit
against the documented numbers meets two different figures for the same measurement.
Code

src/AcTxQueue.h[R33-36]

+/* Lifetime unit: 256 us, measured on the RTL8812A (a peer that never ACKs:
+ * 20000 us gave a delivered age max of 21.0 ms, 68000 us gave 70.1 ms). The
+ * vendor header's HAL92C_MSDU_LIFE_TIME_UNIT says 128, which would give half;
+ * halmac's later chips also convert with `us >> 8`. */
Evidence
The comment says 70.1 ms. CLAUDE.md line 159 and DeviceConfig.h line 332 say 68.8 ms, and
DeviceConfig gives the range 68.8-71 ms.

src/AcTxQueue.h[33-37]
src/jaguar1/CLAUDE.md[157-161]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The AcTxQueue.h comment quotes 70.1 ms for 68000 us, while the other docs quote 68.8 ms.

## Fix Focus Areas
- src/AcTxQueue.h[33-36]

## Recommended Fix
Use the same figure everywhere (68.8 ms, or the 68.8-71 ms range given in DeviceConfig.h).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


Grey Divider

Context sources
Review mode: Auto: 🧠 Deep: Multiple independent hardware, descriptor, endpoint, batching, and configuration paths changed.

Grey Divider

Tip of the day
💡 Did you know, you can add REVIEW.md to your repo root and Qodo follows it on every PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant