Standard-driver FHSS experiment 1/5: benchmark channel-switch primitives

[josephnef]

Summary

Establish a like-for-like latency and behavior matrix for every channel-switch primitive exposed by a standard Linux/Realtek driver before attempting firmware-assisted FHSS. Measure ordinary channel set, AP/CSA, remain-on-channel, TDLS channel-switch offload, and Realtek MCC/FCS on the same supported adapter and hop pair.

This is experiment 1 of 5. It is measurement-only except for minimal tracepoints/harness code; it must not yet change Devourer's hopping implementation.

Why

"Reuse DFS" is useful only if the low-level operation reached by DFS/CSA is substantially cheaper than the public control path. The public APIs also have different semantics: CSA is beacon/BSS oriented, remain-on-channel is off-channel discovery, TDLS alternates base/off-channel, and MCC time-slices channel contexts. We need distributions and an on-air oracle, not API-success timestamps.

Scope and fixed test matrix

Start with one Realtek adapter/driver combination that exposes the largest number of candidates; record USB ID, chip, firmware hash/version, driver commit, kernel, USB speed/topology, regulatory domain, channel width, and transport. Use legal non-DFS same-band channels initially (recommended: 36/40 at 20 MHz); never bypass cfg80211 regulatory checks.

For each available primitive:

1. Ordinary set-channel — monitor interface iw/nl80211 request and the driver's direct set-channel call.
2. CSA — AP channel switch with the minimum accepted CSA count; timestamp request, driver callback, hardware command, completion callback, and first valid frame on the destination.
3. Remain-on-channel — minimum accepted dwell, ready/expired callbacks, and return-to-base behavior.
4. TDLS channel switch — both driver-driven and firmware-offloaded variants where build/firmware support exists; do not claim support if association/peer prerequisites cannot be met.
5. MCC/FCS — two contexts if the chip/firmware advertises it; record firmware schedule granularity and observed dwell.

Run at least 1,000 same-band switches per usable path after 10 warm-ups. Also run cold-first-switch, reverse direction, 2.4 GHz pair, and one same-band 40 MHz pair. Cross-band is a negative/control case, not an FHSS candidate.

Instrumentation

• Add tracepoints/dynamic-debug probes at userspace request, cfg80211/mac80211 callback, vendor-driver entry/exit, H2C submit/completion, and queue stop/wake.
• Capture host CLOCK_MONOTONIC_RAW timestamps and, where exposed, firmware/TSF timestamps.
• Use a second Devourer receiver or B210 as the on-air oracle. Report last source-channel frame, first destination-channel energy, and first correctly decoded canonical-SA frame.
• Report median/p90/p99/max, failure count, lost/duplicated frames, and destination first-decode dead time. Separate host-command latency from actual RF transition.
• Preserve raw JSONL/CSV plus exact commands in a new docs/ measurement note; add a reusable script under tests/ rather than a one-off notebook.

Step-by-step

• Inventory kernel-driver and firmware capability flags; distinguish unsupported, compiled out, rejected by policy, and functional.
• Implement the common timestamp/event schema and on-air probe.
• Measure ordinary channel set and direct driver call.
• Measure CSA with documented beacon interval/count.
• Measure remain-on-channel including return transition.
• Measure TDLS driver/offload paths where supported.
• Measure MCC/FCS two-context switching where supported.
• Publish the matrix and nominate the primitive(s) for experiment 2.

Decision gates

• A candidate advances if steady-state on-air retune p99 is below 5 ms, it produces no cumulative RX/TX wedge across 1,000 switches, and its extra work is identifiable/removable.
• A 5–20 ms result may advance only as a slow slot-hopping prototype and must be labelled as such.
• Above 20 ms, or if timing is beacon/dwell constrained, retain it only as a control.
• API completion without destination-channel RF evidence is a failed measurement.

Acceptance criteria

• Reproducible matrix for all supported primitives with unsupported paths explicitly explained.
• Host and on-air latency distributions, raw artifacts, firmware/driver identities, and exact commands are committed.
• Queue behavior, first-decode dead time, and switch failures are quantified.
• No DFS/CAC bypass and no transmissions on unavailable DFS channels.
• A written go/no-go recommendation identifies the exact lower-layer function/H2C path to investigate next.