Standard-driver FHSS experiment 2/5: isolate Realtek TDLS firmware channel-switch offload

[josephnef]

Summary

Trace, isolate, and benchmark Realtek's firmware-offloaded TDLS channel-switch operation as a possible monitor-injection retune primitive. Determine whether rtw_hal_ch_sw_oper_offload() (or the generation-specific equivalent) is genuinely firmware-executed, available on target firmware, and faster/more deterministic than Devourer's host-driven FastRetune.

Experiment 2 of 5; depends on the common harness and candidate selection in #269.

Starting point

The vendored rtl88x2eu-5mhz path in core/rtw_tdls.c::rtw_tdls_do_ch_sw():

1. sleeps the peer MAC ID;
2. submits rtw_hal_ch_sw_oper_offload(channel, offset, bw);
3. waits for firmware completion;
4. updates driver/HAL channel state;
5. optionally restores IQK information;
6. wakes the peer.

Do not assume the wrapper latency equals RF latency, or that every firmware image implements the operation.

Step-by-step

• Follow rtw_hal_ch_sw_oper_offload() through HAL ops to the exact H2C ID/payload, C2H/completion mechanism, timeout, supported-chip guards, and firmware feature/capability test. Document this call graph by generation.
• Decode every payload field and determine whether it carries one target or a reusable/scheduled table, bandwidth/offset, switch time, calibration slot, return channel, and queue/MAC-ID policy.
• Add tracepoints around MAC-ID sleep, TX drain, H2C submission, USB completion, C2H completion, IQK restore, state update, and wake.
• Build a minimal associated TDLS control run first, preserving all standard prerequisites, and prove destination-channel RF with the Standard-driver FHSS experiment 1/5: benchmark channel-switch primitives #269 on-air oracle.
• Add a research-only harness that calls the lowest safe offload operation outside TDLS while retaining locking/state updates. Gate it by explicit build/runtime opt-in; do not expose it as a production API.
• Test monitor RX, monitor injection, and bidirectional operation separately. Verify that the command does not require a valid TDLS peer/MAC ID and that firmware does not silently return to a base channel.
• Compare cold/warm and A→B/B→A latency against Devourer FastRetune using the same channel/BW matrix and ≥1,000 warm switches.
• Dump a small register-canary set before/after and after a full set-channel control to find state the firmware does or does not restore.

Implementation constraints

• Serialize with the driver's set-channel mutex and explicitly account for pending TX, RX URBs, power tracking, coexistence, and scan/ROC/MCC ownership.
• Driver software state (oper_ch, center channel, BW and prime offsets) must change atomically with successful hardware completion; on timeout, read back/corroborate hardware before choosing rollback.
• Never fake the completion event or remove the timeout to improve a benchmark.
• Keep same-band/same-BW as the fast candidate. Cross-band must take the full safe path unless measurements prove all RFE/calibration state is restored.
• Use non-DFS legal channels for this experiment.

Failure classification

Report distinctly: firmware feature absent, H2C rejected, C2H timeout, completion-before-RF, wrong destination, automatic return, TX queue wedge, RX first-decode failure, calibration/parity mismatch, and host-state divergence.

Acceptance criteria

• Exact H2C/C2H protocol and chip/firmware support matrix are documented with source pointers.
• Associated TDLS and research-harness results are corroborated on air, not just by return code.
• ≥1,000-switch latency distributions and failure counts are compared directly with FastRetune.
• Timeout/recovery leaves driver and hardware channel state consistent.
• A go/no-go conclusion states whether to build experiment 3 on TDLS offload, MCC/FCS, or stop this branch.