Skip to content

rx: follow-ups to the monitor RX filters (#595 review notes 1-3) - #598

Merged
josephnef merged 1 commit into
OpenIPC:masterfrom
snokvist:fix/rx-filter-followups
Nov 21, 2026
Merged

josephnef merged 1 commit into
OpenIPC:masterfrom
snokvist:fix/rx-filter-followups

Conversation

@snokvist

Copy link
Copy Markdown
Collaborator

What changed and why

The review of #595 left four notes. This PR covers 1–3, plus one stale comment. Note 4 (Jaguar1 has the same registers but ignores both knobs) is not here and would be its own PR.

  1. Jaguar3: a TX-only bring-up followed by an RX bring-up on the same object. InitWrite sets _rx_filters_closed (src/jaguar3/RtlJaguar3Device.cpp:1136), and Init never cleared it. With bf.beamformee_of and drop_ctrl:

    • Init arms the beamformee (RXFLTMAP1 |= 0x30);
    • StartRxLoop then saw the stale flag and rewrote the maps, putting RXFLTMAP1 back to 0.

    Init now clears the flag right after rtw_hal_init, which has just written this session's own maps through monitor_rx_cfg.

  2. One identity under own_addr_only. The DeviceConfig.h comment now says that an ACK responder on another address overwrites the MACID a beamformee arm wrote. Comment only: refusing the combination would be a behaviour change.

  3. Silent loss of all unicast. Jaguar2/3 StartRxLoop logs one warning when own_addr_only is set and MACID still reads 00:00:00:00:00:00. It reuses ack::macid_is from AckResponder.h. On Jaguar3 the read is under _reg_mu, like the other register access there.

  4. IRadio.h's station note said the default NOACK stream radiotap "never retries". Only the MT7612U reads that flag (RadiotapBuilder.h already says so). The Realtek descriptors take the retry count from tx.retry_limit (src/jaguar2/RtlJaguar2Device.cpp:1900, src/jaguar3/RtlJaguar3Device.cpp:2905, which zero it only in A-MPDU no-ack mode). A unicast frame sent with NOACK on an RTL8733B still aired 5.5 times on average with retry_limit 16.

Evidence

Note 3, on an RTL8812BU (0bda:b812, USB3), rxdemo, ch36, DEVOURER_RX_OWN_ADDR_ONLY=1:

Run Log
no identity [W] Jaguar2: rx.own_addr_only with MACID 00:00:00:00:00:00: no unicast passes until SetAckResponder or a station or beacon arm sets an identity
DEVOURER_ACK_RESPONDER=02:57:4e:11:22:33 (control) hardware ACK responder armed for 02:57:4e:11:22:33, no warning

With the knob off the condition is false, so no read and no log.

Verification

  • Build: Release, default options. The unique warning set is the same as master's (9).
  • Tests: ctest 93/93.
  • Hardware: note 3 on the 8812BU only, once per arm.

Not verified

  • Note 1 on hardware. No in-tree example runs InitWrite and then Init on the same object. The fix follows the code path the review traced.
  • Note 3 on Jaguar3: same code; not run on an 8812CU or 8812EU.

Blast radius

  • Note 1: only a Jaguar3 object that ran InitWrite and then Init. A plain RX or a plain TX session is unchanged.
  • Note 3: one register read and at most one log line per StartRxLoop, only with own_addr_only set.
  • Notes 2 and 4: comments only.

🤖 Generated with Claude Code

- Jaguar3 Init clears _rx_filters_closed: rtw_hal_init wrote this
  session's own filter maps, so a TX-only InitWrite earlier on the same
  object must not make StartRxLoop rewrite RXFLTMAP1 over the beamformee
  arm (note 1).
- DeviceConfig.h: own_addr_only holds one identity; an ACK responder on
  another address overwrites a beamformee arm's MACID (note 2).
- Jaguar2/3 StartRxLoop warns once when own_addr_only is set and MACID
  still reads all-zero (note 3), using AckResponder.h's macid_is.
- IRadio.h: only the MT7612U reads the radiotap NOACK flag; the Realtek
  descriptors retry a unicast frame tx.retry_limit times either way.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011dReg158JQxkhEWGPBro5f
@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

Preserve Jaguar3 RX filters and warn about an unset RX identity

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

Grey Divider

AI Description

• Clear stale Jaguar3 TX-only filter state after RX initialization to preserve beamformee reception.
• Warn when address-only RX filtering has no MACID identity on Jaguar2 or Jaguar3.
• Clarify shared MACID identity and backend-specific NOACK retry behavior.
Merge Risk 🟢 Low

Blast radius 🟢 Low 💥 0 capabilities

  • Fault-specific containment limits risk to the originating changed behavior.
Behavioral complexity 🟢 Low 🧩 Straightforward

  • Before: Jaguar3 retained _rx_filters_closed across the full RX bring-up, allowing StartRxLoop's retrofit branch to run based on stale TX-only state; Jaguar2/Jaguar3 had no startup diagnostic for an all-zero MACID under own-address-only filtering.
  • After: Jaguar3 explicitly clears the state after rtw_hal_init, and both generations perform a guarded MACID equality check before logging.
  • The new correctness condition is a direct predicate: warn only when the configured address-only filter has an all-zero current MACID, while avoiding filter-map rewrites after a bring-up that already established the RX configuration.
  • This uses existing register access, locking, and filter infrastructure without introducing new interacting states or algorithms.
Sources

src/jaguar3/RtlJaguar3Device.cpp[114-117]

  /* rtw_hal_init wrote this session's monitor filter maps. A TX-only
   * InitWrite earlier on this object no longer applies: re-opening the maps
   * in StartRxLoop would undo the beamformee arm's RXFLTMAP1 below. */
  _rx_filters_closed = false;

src/jaguar3/RtlJaguar3Device.cpp[284-293]

  /* rx.own_addr_only passes only unicast to MACID, which this bring-up never
   * programs: say so if nothing has armed an identity by now. */
  static constexpr uint8_t kNoMac[6] = {};
  if (_cfg.rx.own_addr_only) {
    std::lock_guard<std::mutex> lk(_reg_mu); /* against the coex tick */
    if (devourer::ack::macid_is(_device, kNoMac))
      _logger->warn("Jaguar3: rx.own_addr_only with MACID 00:00:00:00:00:00: no "
                    "unicast passes until SetAckResponder or a station or beacon "
                    "arm sets an identity");
  }

src/jaguar2/RtlJaguar2Device.cpp[667-673]

  /* rx.own_addr_only passes only unicast to MACID, which this bring-up never
   * programs: say so if nothing has armed an identity by now. */
  static constexpr uint8_t kNoMac[6] = {};
  if (_cfg.rx.own_addr_only && devourer::ack::macid_is(_device, kNoMac))
    _logger->warn("Jaguar2: rx.own_addr_only with MACID 00:00:00:00:00:00: no "
                  "unicast passes until SetAckResponder or a station or beacon "
                  "arm sets an identity");
Potential damage 🟢 Low 🩹 Cosmetic

  • Conservative damage bound for the originating changed behavior; downstream capabilities remain contained.
  • The plausible fault is an inaccurate startup warning, not a wrong captured result or unavailable RX capability.
  • MACID read failures are explicitly swallowed by macid_is(), and the caller only emits a log.
  • There is no persistent state corruption, external side effect, or downstream consumer affected by the diagnostic.
  • The Jaguar3 state change is supported by the RX bring-up ordering and preserves the beamformee filter map rather than introducing a new failure path.
  • Immediate: no repair is required for the warning-only fault; a later startup or explicit identity arm can provide a correct diagnostic.
  • Reverting code is not needed to restore RX behavior.
  • If the underlying MACID read or identity programming is genuinely faulty, the existing SetAckResponder/station/beacon arm path must be repaired or re-run; the PR does not automate that recovery.
Sources

src/jaguar3/RtlJaguar3Device.cpp[114-117]

  /* rtw_hal_init wrote this session's monitor filter maps. A TX-only
   * InitWrite earlier on this object no longer applies: re-opening the maps
   * in StartRxLoop would undo the beamformee arm's RXFLTMAP1 below. */
  _rx_filters_closed = false;

src/jaguar3/RtlJaguar3Device.cpp[284-293]

  /* rx.own_addr_only passes only unicast to MACID, which this bring-up never
   * programs: say so if nothing has armed an identity by now. */
  static constexpr uint8_t kNoMac[6] = {};
  if (_cfg.rx.own_addr_only) {
    std::lock_guard<std::mutex> lk(_reg_mu); /* against the coex tick */
    if (devourer::ack::macid_is(_device, kNoMac))
      _logger->warn("Jaguar3: rx.own_addr_only with MACID 00:00:00:00:00:00: no "
                    "unicast passes until SetAckResponder or a station or beacon "
                    "arm sets an identity");
  }

src/jaguar2/RtlJaguar2Device.cpp[667-673]

  /* rx.own_addr_only passes only unicast to MACID, which this bring-up never
   * programs: say so if nothing has armed an identity by now. */
  static constexpr uint8_t kNoMac[6] = {};
  if (_cfg.rx.own_addr_only && devourer::ack::macid_is(_device, kNoMac))
    _logger->warn("Jaguar2: rx.own_addr_only with MACID 00:00:00:00:00:00: no "
                  "unicast passes until SetAckResponder or a station or beacon "
                  "arm sets an identity");
Assessed commit 9698a8e
Diagram

graph TD
  TX["TX-only InitWrite"] --> INIT["Jaguar3 Init"] --> HAL["HAL filter maps"] --> J3["Jaguar3 RX loop"] --> OWN{"Own address only?"} --> ZERO{"MACID all zero?"} --> WARN["Warn once per loop"]
  J2["Jaguar2 RX loop"] --> OWN
Loading
High-Level Assessment

Keep the targeted flag reset and read the hardware MACID at RX-loop start. Refusing combinations of identity arms would change behavior, while caching an identity could diverge from the register shared by those arms.

Files changed (4) +31 / -4

Enhancement (1) +8 / -0
RtlJaguar2Device.cppWarn when address-only RX has no Jaguar2 identity +8/-0

Warn when address-only RX has no Jaguar2 identity

• At RX-loop start, checks MACID only when own_addr_only is enabled and warns if it remains all-zero. Reuses ack::macid_is for the hardware read.

src/jaguar2/RtlJaguar2Device.cpp

Bug fix (1) +15 / -0
RtlJaguar3Device.cppReset stale RX-filter state and diagnose missing identity +15/-0

Reset stale RX-filter state and diagnose missing identity

• Clears _rx_filters_closed after RX HAL initialization so a prior TX-only session cannot cause StartRxLoop to overwrite the current beamformee filter map. Also warns on an all-zero MACID under _reg_mu when own_addr_only is enabled.

src/jaguar3/RtlJaguar3Device.cpp

Documentation (2) +8 / -4
DeviceConfig.hDocument address-only RX identity constraints +4/-1

Document address-only RX identity constraints

• Explains the new zero-MACID warning and that an ACK responder can overwrite a beamformee's MACID, preventing its sounding frames from passing the address-only filter.

src/DeviceConfig.h

IRadio.hCorrect station NOACK retry guidance +4/-3

Correct station NOACK retry guidance

• Clarifies that only MT7612U reads the radiotap NOACK flag, while Realtek unicast retries depend on tx.retry_limit regardless of that flag.

src/IRadio.h

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

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

Copy link
Copy Markdown

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

Grey Divider


Remediation recommended

1. MACID read failures hide RX diagnostics 🐞 Bug ◔ Observability
Description
The new StartRxLoop warning uses ack::macid_is, which converts any MACID register-read exception
into false, the same result as a nonzero identity. When own_addr_only is enabled and either read
fails, both Jaguar2 and Jaguar3 enter their RX loops without reporting that they could not verify
the identity.
Code

src/jaguar2/RtlJaguar2Device.cpp[670]

+  if (_cfg.rx.own_addr_only && devourer::ack::macid_is(_device, kNoMac))
Evidence
macid_is catches all exceptions and returns false, while each newly added warning runs only when
it returns true. Thus a transport failure suppresses the diagnostic rather than producing a separate
indication that MACID could not be checked.

src/AckResponder.h[63-74]
src/jaguar2/RtlJaguar2Device.cpp[667-673]
src/jaguar3/RtlJaguar3Device.cpp[284-293]

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

## Issue description
Both new `own_addr_only` warnings treat a failed MACID read as proof that the MACID is nonzero, so neither reports an inability to verify the RX identity.
## Fix Focus Areas
- src/jaguar2/RtlJaguar2Device.cpp[667-673]
- src/jaguar3/RtlJaguar3Device.cpp[284-293]
- src/AckResponder.h[63-74]
## Recommended Fix
Use a read result that distinguishes zero, nonzero, and read failure at both warning sites. Keep the existing zero-MACID warning, and emit a distinct diagnostic when the register value cannot be read.

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


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

@josephnef josephnef left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving. Built locally, ctest 93/93, and I ran the two items the description lists as not verified.

Note 1 on hardware (8812CU, 0bda:c812, ch36). A small out-of-tree harness does what no example does: a TX-only InitWrite, then Init on the same object with bf.beamformee_of and drop_ctrl set, then a raw vendor read of RXFLTMAP1 (0x06A2) once the RX loop is up.

Build RXFLTMAP1
without the flag clear 0x0000 (NDPA / report-poll closed again)
this branch 0x0030

One unit, one run per arm.

Note 3 on Jaguar3 too. rxdemo, ch36, four runs in this order on each of an 8812CU, an 8812BU and an 8812EU:

Run Warning
own_addr_only, no identity yes
own_addr_only + DEVOURER_ACK_RESPONDER no
own_addr_only, no identity, straight after the armed run yes
knob off no

The third row was the one I wanted: a MACID left over from the previous session would have silenced a register-read check, and it does not on any of the three.

On note 2: I'd go one step further than the comment and refuse the beamformee + other-address responder combination under own_addr_only at bring-up. I have that, a caps flag for the two knobs, and the remaining #597 items on a branch based on this one and will open it once this lands.

@josephnef josephnef added the skip-qodo-gate Bypass the Qodo review gate (outage / maintainer decision) label Nov 21, 2026
@josephnef
josephnef merged commit f0f90e7 into OpenIPC:master Nov 21, 2026
30 of 31 checks passed
josephnef added a commit that referenced this pull request Nov 21, 2026
## What this is

The rest of #597, on top of #598 (which landed the Jaguar3 `Init` flag
clear, the MACID-zero warning and the comments).

- **Jaguar1 applies `rx.drop_ctrl` and `rx.own_addr_only`.**
`own_addr_only` uses the shared `monitor_rcr()`; Jaguar1 bring-up
already programs MACID from EFUSE, so it needs no identity arm.
`drop_ctrl` clears RCR `ACF` as well as RXFLTMAP1, because on this MAC
the map alone filtered nothing.
- **Jaguar2/3 refuse one combination at bring-up:** `own_addr_only` with
a beamformee arm and an ACK responder on a different address. MACID
holds one address, so that session could not receive both. Same address,
or promiscuous RX, is unaffected. #598 documented this; this makes it an
error (`std::runtime_error`, like a failed responder arm).
- **Jaguar3 `InitWrite` clears the "RX filters closed" state** after its
bring-up, as `Init` now does.
- **`AdapterCaps::rx_mac_filters_ok`** (`rx_mac_filters` in
`adapter.caps`): whether the backend applies the two knobs. Jaguar1,
Jaguar2, Jaguar3, RTL8733B.
- `DeviceConfig.h`: a few control frames admitted during bring-up can
still reach the host under `drop_ctrl`.

## Measured

All ch36, one unit per die. The flood is a T3U sending unicast QoS-Data
to address X; a hardware ACK responder for X puts control frames on air.
Counts are the DUT's own per-frame events over a 10 s cell (8 s for the
last two rows).

**Jaguar1, 8812AU** (on a second host, RF-coupled to the bench):

| Cell | Control frames | Flood frames to X |
|---|---|---|
| off | 4951 | 4210 |
| `drop_ctrl` | 143 (all BlockAck) | 4240 |
| `own_addr_only`, EFUSE identity | 0 | 0 |
| `own_addr_only`, identity X | 0 | 4270 |
| `own_addr_only`, identity Y | 0 | 0 |
| both, identity X | 0 | 4263 |

Management frames were 364–368 in every cell. With RXFLTMAP1 = 0 alone,
`drop_ctrl` read 4184 control frames against 4234 off.

**8812AU as transmitter, `drop_ctrl` on its own RX** (peer: an 8812BU
hardware responder; TX reports OK):

| | open | `drop_ctrl` | no responder |
|---|---|---|---|
| unicast, retry limit 6 | 86% | 87% | 0% |
| A-MPDU | 78% | 77% | 0% |

**BlockAck under A-MPDU with `drop_ctrl` on the transmitter** (the item
#595 left unmeasured), TX reports OK, open / `drop_ctrl` / no responder:
8812CU 96 / 96 / 0%, 8812BU 95 / 97 / 0%, 8733BU 95 / 97 / 0%. Under
aggregation the per-frame retry count reads 0 in every cell, including
no responder, so only the OK share discriminates.

**The refusal**, `rxdemo` with `DEVOURER_RX_OWN_ADDR_ONLY=1
DEVOURER_BF_ARM_BFEE=…`, on an 8812CU and an 8812BU: responder on
another address exits with the error; responder on the beamformee
address runs; the same pair without `own_addr_only` runs.

**The leaked control frames** from the #595 review (1–3 per cell on
Jaguar3 and the RTL8733B): all sat in the first ~40 events of a session,
while an ambient NDPA source ran at ~60/s for the whole unfiltered cell.
They are frames admitted during bring-up before the monitor filter is
written. Later runs had 0 or 1.

**Regression on this build:** the #595 filter cells on the 8812CU and
8733BU: `drop_ctrl` 1 and 0 control frames against 3396 and 2678;
`own_addr_only` 0 flood frames without the identity, 1545 and 1470 with
it.

`ctest` 96/96.

## Not verified

- **The 8812AU as ACK responder under `drop_ctrl`.** The cross-rig loop
did not close with both knobs off either (the transmitter retried every
frame to its limit with the responder armed), so the run says nothing
about the knob.
- The RTL8811AU, RTL8821AU and RTL8814AU: same code path as the 8812AU,
not run.
- The 8821C and the PCIe parts.
- One observation not chased: a scratch harness doing `InitWrite` then
`Init` on one Jaguar3 object, then `Stop`, logged a clean de-init and
did not exit in two of three runs.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

skip-qodo-gate Bypass the Qodo review gate (outage / maintainer decision)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants