AdapterCaps: hardware-ARQ capability flags (ack_responder_ok / tx_retry_limit_ok) from the measured matrix (#365)

[josephnef]

Steps 1–2 of #365 (the 8821AU responder root-cause and the Kestrel retry H2C port remain open on the issue).

What ships

Two bench-derived capability flags, following the ldpc_rx_* convention (truth table doc-commented at the declaration, never a vendor advertisement):

• ack_responder_ok — SetAckResponder measurably closes a hardware-ARQ loop as the responder. From the six-cell on-air matrix (issue comment): true on 8812A/8814A/8822B/8822C/8822E (98%/98%/98%/69%/79% single-shot ACK closure vs 0% with the responder off), false on the 8821A die (0% closure, third independent confirmation) and false on Kestrel (SetAckResponder not implemented on the AX generation — measured, not assumed).
• tx_retry_limit_ok — DEVOURER_TX_RETRY_LIMIT drives hardware autonomous retransmission (the 12/0/12 A/B from Jaguar1/2/3: unified TX retry-limit knob (DEVOURER_TX_RETRY_LIMIT, default 0) #354's review). False on the 8814A die (vendor DATA_RETRY_LIMIT=0 carve-out kept, knob inert) and Kestrel (fw-level retry).

Both ride the adapter.caps event so integrators (PixelPilot et al.) can gate ARQ features per adapter instead of discovering a dead responder in the field.

Validation

On-air, all six plugged dies report exactly the measured matrix:

die	ack_responder	tx_retry_limit
RTL8822E	1	1
RTL8822C	1	1
RTL8822B	1	1
RTL8814A	1	0
RTL8821A	0	1
RTL8852C	0	0

ctest 49/49. One bring-up correction en route: the 8821A die's J1 enum is CHIP_8821, not CHIP_8821A (caught by the compiler, then re-validated per-die on air).

🤖 Generated with Claude Code

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Expose hardware-ARQ capability flags via adapter.caps (ack_responder/tx_retry_limit)

✨ Enhancement 📝 Documentation 🕐 20-40 Minutes

AI Description

• Add bench-derived hardware-ARQ capability flags to AdapterCaps (responder + retry limit).
• Populate flags per chip family and emit them in the adapter.caps event.
• Document new adapter.caps fields in the logging event schema.

Diagram

graph TD
  A["Rtl*Device GetAdapterCaps"] --> B["AdapterCaps (new flags)"] --> C["emit_adapter_caps()"] --> D["adapter.caps event"] --> E["Demos / integrators"]
  D --> F["docs/logging.md"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Runtime self-test / probe-based capability detection

• ➕ Avoids hard-coded per-die truth tables and stays correct across new revisions
• ➕ Can detect board/firmware anomalies beyond chip ID
• ➖ Requires a controlled RF/peer setup (or synthetic peer) and adds startup latency
• ➖ Hard to make deterministic in real RF environments; can be flaky or disruptive

2. Infer capabilities from vendor/firmware feature bits (efuse/HAL/FW API)

• ➕ More “automatic” than maintaining a measured matrix
• ➕ Potentially cheaper than on-air validation at runtime
• ➖ May not reflect real on-air behavior (the exact failure mode this PR is addressing)
• ➖ Feature bits can be missing, misleading, or vary by firmware

3. Expose tri-state caps (unknown/true/false) and let callers decide

• ➕ Avoids over-claiming on unmeasured chips
• ➕ Allows integrators to opt into riskier features
• ➖ Still pushes field discovery burden to callers
• ➖ Complicates API and downstream decision logic

Recommendation: Keep the PR’s bench-derived boolean flags as the primary contract: they encode observed on-air behavior and let integrators gate ARQ features deterministically. If future chips/variants expand, consider extending the model to tri-state (unknown vs proven) only where behavior is genuinely unmeasured; avoid runtime ARQ probing unless a deterministic lab-mode test harness is introduced.

Files changed (7) +36 / -1

Enhancement (6) +35 / -0

caps_event.hEmit ack_responder and tx_retry_limit in adapter.caps +2/-0

Emit ack_responder and tx_retry_limit in adapter.caps

• Extends emit_adapter_caps() to serialize the new AdapterCaps booleans as integer fields in the adapter.caps event payload.

examples/common/caps_event.h

AdapterCaps.hAdd hardware-ARQ capability flags to AdapterCaps +17/-0

Add hardware-ARQ capability flags to AdapterCaps

• Introduces ack_responder_ok and tx_retry_limit_ok with detailed doc-comments describing the measured/bench-derived truth table and contract reference.

src/AdapterCaps.h

RtlJaguarDevice.cppSet ARQ caps for Jaguar1 with per-die exceptions +5/-0

Set ARQ caps for Jaguar1 with per-die exceptions

• Populates ack_responder_ok and tx_retry_limit_ok for Jaguar1, disabling responder ARQ on the RTL8821A die and disabling the retry-limit knob on RTL8814A where it’s inert.

src/jaguar1/RtlJaguarDevice.cpp

RtlJaguar2Device.cppEnable ARQ caps for Jaguar2 (8822B/8821C recipe) +4/-0

Enable ARQ caps for Jaguar2 (8822B/8821C recipe)

• Sets both ack_responder_ok and tx_retry_limit_ok true for Jaguar2 devices, matching the measured/resolved shared MAC recipe for this generation.

src/jaguar2/RtlJaguar2Device.cpp

RtlJaguar3Device.cppEnable ARQ caps for Jaguar3 (measured responder + retry) +4/-0

Enable ARQ caps for Jaguar3 (measured responder + retry)

• Sets ack_responder_ok and tx_retry_limit_ok true for Jaguar3 devices, reflecting the measured responder matrix and retry A/B behavior for these dies.

src/jaguar3/RtlJaguar3Device.cpp

RtlKestrelDevice.cppExplicitly leave ARQ caps disabled for Kestrel +3/-0

Explicitly leave ARQ caps disabled for Kestrel

• Adds a clarifying comment that SetAckResponder is not implemented on AX/Kestrel and retry is firmware-level, so both ARQ capability flags remain false.

src/kestrel/RtlKestrelDevice.cpp

Documentation (1) +1 / -1

logging.mdDocument new adapter.caps ARQ fields +1/-1

Document new adapter.caps ARQ fields

• Updates the adapter.caps event schema row to include ack_responder and tx_retry_limit fields so log/event consumers can rely on them.

docs/logging.md

[qodo-free-for-open-source-projects]

Code Review by Qodo

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

1. Jaguar2 ack_responder_ok hardcoded ✓ Resolved 📎 Requirement gap ≡ Correctness

Description

RtlJaguar2Device::GetAdapterCaps() sets ack_responder_ok (and tx_retry_limit_ok) to true
unconditionally, while the new AdapterCaps doc-comment explicitly says some entries are "not
separately measured" (e.g., 8821C). This makes the shipped capability flags not strictly
bench-derived and risks mis-gating ARQ features on chips that were not actually measured.

Code

src/jaguar2/RtlJaguar2Device.cpp[R1127-1130]

+  /* Hardware ARQ (truth table at the AdapterCaps declarations): 8822B
+   * responder + retry knob measured; the 8821C shares the recipe. */
+  c.ack_responder_ok = true;
+  c.tx_retry_limit_ok = true;

Evidence

PR Compliance ID 2 requires bench-derived truth tables and per-chip resolution of the capability
flags at construction. The PR both (a) documents that some chips are "not separately measured" and
(b) hardcodes the Jaguar2 flags to true, which conflicts with the bench-derived/source-of-truth
requirement.

AdapterCaps includes bench-derived ARQ capability flags and emits them via adapter.caps
src/jaguar2/RtlJaguar2Device.cpp[1127-1130]
src/AdapterCaps.h[162-171]

Agent prompt

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

## Issue description
Jaguar2 currently reports `ack_responder_ok=1` and `tx_retry_limit_ok=1` for all Jaguar2 chips, but the `AdapterCaps` truth-table comment indicates at least some Jaguar2-family dies are "not separately measured" (by-recipe). This violates the requirement that these flags be bench-derived source-of-truth indicators.
## Issue Context
`AdapterCaps` ARQ flags are intended to be reliable per-chip capability gates for integrators. If a die is not bench-measured, either (a) measure it and update the truth table accordingly, or (b) report a conservative value (typically `false`) and document it as unmeasured.
## Fix Focus Areas
- src/jaguar2/RtlJaguar2Device.cpp[1127-1130]
- src/AdapterCaps.h[162-175]

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

---

2. Responder matrix not published ✓ Resolved 📎 Requirement gap ⚙ Maintainability

Description

New AdapterCaps ARQ flags state their measured contract is in docs/scheduled-mac.md, but that
file still lacks the required consolidated per-die responder capability matrix. Without the
published table, callers cannot reliably gate responder ARQ behavior per the checklist requirements.

Code

src/AdapterCaps.h[R162-164]

+  /* --- hardware-ARQ capability (bench-derived truth table, on-air responder
+   * matrix + retry-knob A/B; the measured contract is docs/scheduled-mac.md).
+   * ack_responder_ok: SetAckResponder measurably closes a hardware-ARQ loop

Evidence

PR Compliance IDs 1 and 6 require publishing a consolidated responder matrix table in
docs/scheduled-mac.md. The PR adds AdapterCaps documentation claiming the measured contract is
in docs/scheduled-mac.md, but the cited section shows only a TX-generation matrix plus brief
narrative responder notes (no consolidated per-die responder table).

Responder ARQ capability matrix measured and published
Acceptance criteria met: docs updated, caps shipped, 8821AU/8814A entries backed by fix or bench-confirmed exclusion
src/AdapterCaps.h[162-165]
docs/scheduled-mac.md[141-210]

Agent prompt

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

## Issue description
`docs/scheduled-mac.md` does not contain the required consolidated responder ARQ capability matrix table, even though the new `AdapterCaps` ARQ flags reference it as the measured contract.
## Issue Context
Compliance requires publishing a single responder capability matrix table in `docs/scheduled-mac.md` covering all owned dies measured as responders (including explicit measured outcomes for 8821AU and Kestrel/PCIe responders).
## Fix Focus Areas
- docs/scheduled-mac.md[141-210]
- src/AdapterCaps.h[162-175]

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

---

3. Kestrel retry knob inert 📎 Requirement gap ≡ Correctness

Description

Kestrel GetAdapterCaps() states DEVOURER_TX_RETRY_LIMIT is inert and leaves the ARQ capability
flags disabled, indicating the retry-limit knob still is not implemented via a mac_ax H2C path on
AX. This does not meet the requirement to make DEVOURER_TX_RETRY_LIMIT effective and
bench-validated on Kestrel.

Code

src/kestrel/RtlKestrelDevice.cpp[R786-788]

+  /* Hardware ARQ: SetAckResponder is not implemented on the AX generation
+   * (matrix-measured 0% closure) and retry is firmware-level here, so the
+   * DEVOURER_TX_RETRY_LIMIT knob is inert — both flags stay false. */

Evidence

PR Compliance ID 4 requires implementing the Kestrel/AX retry-limit knob via mac_ax H2C and
validating it. The PR-added Kestrel caps comment explicitly states the knob is inert and leaves the
corresponding capability flag false, showing the requirement is not met by this change set.

Kestrel (AX) retry limit knob implemented via mac_ax H2C and validated
src/kestrel/RtlKestrelDevice.cpp[786-788]

Agent prompt

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

## Issue description
On Kestrel/AX, `DEVOURER_TX_RETRY_LIMIT` is still documented as inert and `tx_retry_limit_ok` remains false, meaning the knob does not affect real retry behavior.
## Issue Context
Compliance requires wiring `DEVOURER_TX_RETRY_LIMIT` to the mac_ax retry-limit H2C mechanism on Kestrel and validating on-air that the setting changes actual retry behavior.
## Fix Focus Areas
- src/kestrel/RtlKestrelDevice.cpp[776-792]
- src/kestrel/KestrelFw.cpp[350-540]
- src/kestrel/HalKestrel.cpp[1500-1605]

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

---

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}