Skip to content

ieee80211: separate capability preparation from BSS state transitions - #1458

Open
mgonzalezlopezudc wants to merge 4 commits into
inet-framework:masterfrom
mgonzalezlopezudc:ieee80211-capability-bss-state
Open

mgonzalezlopezudc wants to merge 4 commits into
inet-framework:masterfrom
mgonzalezlopezudc:ieee80211-capability-bss-state

Conversation

@mgonzalezlopezudc

@mgonzalezlopezudc mgonzalezlopezudc commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

IEEE 802.11 capability preparation currently depends on initialization broadcasts. The MIB also mixes local PHY support with active BSS operation. This makes capability availability depend on initialization order and gives consumers access to state that management does not yet complete.

This PR gives each component a clear responsibility. The PHY reports local support. The MAC prepares the local capability profile. Management owns association and BSS transitions. The MIB stores the accepted state and notifies consumers after management completes each transition. Here, BSS means Basic Service Set. HT means High Throughput operation from IEEE 802.11n.

For example, a simplified STA must find its AP before network configuration. This must work with either node declaration order. The new preparation paths provide interface identity, local capabilities, and AP state before that association needs them. Repeated preparation preserves active protocol state.

The main compatibility risk affects custom Wi-Fi modules. This PR removes ModeSetListener, modesetChanged, and writable public BSS/profile fields without compatibility adapters. Custom PHY, management, and catalog consumers must use the new contracts. Initialization order also changes for all link-layer users. The verification below covers selected cases, rather than every model that can use these APIs.

How the components fit together

The configured mode catalog describes available modes. The local capability profile describes what this interface supports. BSS operation describes the accepted channel and operational restrictions. A peer capability result describes compatible capabilities in each direction. These data have different lifetimes and different owners.

flowchart TD
    PHY["PHY transmitter and receiver"] -->|Report local support| MAC["MAC prepares local capabilities"]
    MAC -->|Install local profile| MIB["MIB stores accepted state"]
    MGMT["Management owns BSS and peer transitions"] -->|Commit complete state| MIB
    MAC -->|Read-only mode catalog| USERS["MAC policies and rate algorithms"]
    MIB -->|Queries and complete state notifications| USERS
    MIB -->|Capabilities and current operation| SELECT["Rate selection checks current eligibility"]
Loading

Observers see a complete transition

During reassociation, management can remove the old relationship and install its replacement within one action. Consumers receive the complete replacement state. They receive no separate notification for the temporary empty state.

The MIB retains both signals. bssStateChanged reports BSS and relationship changes. rateStateChanged reports changes that affect rate selection. An association-status change alone emits only bssStateChanged. Both signals describe complete state. Equal updates emit no signal. The MIB rejects state mutation during either callback.

sequenceDiagram
    participant Peer as Peer or lifecycle event
    participant Mgmt as Management
    participant MIB as MIB
    participant Observer as MAC consumers
    Peer->>Mgmt: Trigger a state transition
    Mgmt->>MIB: Stage BSS, peer, capability, or rate changes
    Mgmt->>Mgmt: Complete timers and transactions
    Mgmt->>MIB: publishStateChange()
    opt Rate-relevant state changed
        MIB->>Observer: rateStateChanged
        Observer->>MIB: Query complete state
    end
    opt BSS or relationship state changed
        MIB->>Observer: bssStateChanged
        Observer->>MIB: Query complete state
    end
    Note over MIB,Observer: State mutation is rejected during callbacks
Loading

Retained capabilities do not grant HT transmission permission

An associated AP can advertise a valid Basic HT-MCS Set that the STA cannot satisfy. The STA retains its peer capability result but blocks HT transmission. A later usable operation restores HT eligibility. A malformed advertisement still follows the rejection path.

flowchart LR
    A["Associated STA retains peer capabilities"] --> B{"Accepted HT operation is locally usable?"}
    B -->|Yes| C["HT selection is eligible within current limits"]
    B -->|No| D["Block HT transmission and retain capabilities"]
    D -->|Later usable operation| C
    C -->|Later unusable operation| D
Loading

Rate selection therefore receives current operation and HT eligibility separately from cached capabilities. The coordination function also checks a retained transmission mode before frame submission. Association loss or replacement still clears the corresponding Block Ack, QoS, and rate state.

Commits in review order

  1. 22fed88393 moves the VHT capability fixture to module tests without content changes. This prepares its later use of the production MAC.
  2. 73ef256804 makes interface identity ready before link-layer initialization. This shared prerequisite supports peer discovery independently of module declaration order.
  3. 53323a4383 separates capability preparation, management transitions, and state publication. This commit changes behavior and migrates the dependent consumers and tests together.
  4. 7a8749d7ba separates the read-only catalog provider from capability preparation. This narrows the contract for catalog-only consumers.

The shared initialization prerequisite remains in this PR because simplified association needs initialized peer identities before network configuration.

Architecture and migration

The public contracts divide these responsibilities:

Responsibility Contract or API
Read the configured mode catalog IIeee80211ModeSetProvider and ModeSetModuleBase
Prepare the local capability profile IIeee80211MacConfiguration::prepareLocalCapabilities()
Report transmitter and receiver support IIeee80211TransmitterCapabilities and IIeee80211ReceiverCapabilities
Prepare a simplified AP and install or remove its peers IIeee80211BssProvider
Read accepted state and publish completed changes MIB queries and publishStateChange()

Catalog consumers declare a modeSetModule NED parameter. The MAC supplies the default path for its descendants. Standalone consumers must configure a provider. Algorithm initialization moves from the removed broadcast callback to link-layer initialization.

This PR changes C++ contracts, their NED interfaces, module parameters, initialization dependencies, and MIB access. It changes no packet format or feature descriptor. It adds no architecture or naming exception. Source and document seal checks pass.

The migration guide gives the required changes for custom modules.

Verification

The tested branch head is 7a8749d7ba12f4fa248108e8c5f0681f6ef15567. Its base is 91219b0fa7d2794ee67ac8a3dd45c3a09cfc45b0. Upstream master advanced after that base. The tests do not verify the merge result with the newer upstream commits.

Check Result
All enabled source files, debug and release builds Pass
Selected unit fixtures 9 pass
Selected module fixtures 33 pass
Selected Wi-Fi protocol fixtures 7 pass
Fingerprints: MacNonQos and MacQos, run 0, 10 seconds Both pass with tplx, ~tNl, and ~tND
Commit-series gates Pass
Source and document seals Pass
Architecture, naming, and interface gates Same 36, 24, and 16 findings as the pinned base, with no additional findings

The tests cover preparation, provider contracts, declaration order, association, reassociation, beacon updates, lifecycle cleanup, response selection, and notification boundaries. They also cover an HT receiver in a legacy BSS with a known channel but no HT operation. The old library fails that added case. The final local-interval fixture passes all 52 selected runs.

No fingerprint or statistical baseline changes form part of this PR. Behavioral tests use debug mode. Release verification covers compilation. Per-commit builds, the full regression suites, and the newer upstream merge result remain unverified.

Commands, selectors, and environment limits

Disk capacity required build outputs on a separate volume. The tests used byte-identical library copies on an executable volume. The installed runner also rejects the unused coverage.report entry in inet.opp. Temporary runner configurations omit that entry. They preserve simulation parameters and baselines.

The evidence report gives the exact configuration preparation and build commands. The scope file gives every selected fixture. The verification record records feature state, input hashes, library hashes, and results.

The following commands use the temporary configurations from that report:

artifact_root=/home/user/.cache/ccache/inet-coap-build-20261115
CCACHE_DISABLE=1 make -C src -j4 MODE=debug PROJECT_OUTPUT_DIR="$artifact_root" LN='ln -sf'
CCACHE_DISABLE=1 make -C src -j4 MODE=release PROJECT_OUTPUT_DIR="$artifact_root" LN='ln -sf'

scope_file=plan/done/80211htcapop-rebase-20261115-scopes.json
unit_filter="$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1]))["unit"]["filter"])' "$scope_file")"
module_filter="$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1]))["module"]["filter"])' "$scope_file")"
CCACHE_DISABLE=1 opp_run_unit_tests --load /tmp/inet-coap-rebase-compatible.opp --no-build --no-concurrent -m debug -u Cmdenv -f "$unit_filter"
CCACHE_DISABLE=1 opp_run_module_tests --load /tmp/inet-coap-rebase-compatible.opp --no-build --no-concurrent -m debug -u Cmdenv -f "$module_filter"
CCACHE_DISABLE=1 opp_run_protocol_tests --load /tmp/inet-coap-rebase-compatible.opp -p inet --no-build --no-concurrent -m debug -w '^tests/protocol/wifi$' -f '(Wifi(HtAssociation|Association|Reassociation|Deauth|RifsPermission|LocalInterframeInputs)|Ac_BlockAckFallback)\.test$'
CCACHE_DISABLE=1 opp_run_fingerprint_tests --load /tmp/inet-coap-rebase-fingerprint.opp -p inet --no-build --no-concurrent -m debug -w '^examples/adhoc/qos$' -c '^Mac(NonQos|Qos)$' -r 0 --ingredients tplx --ingredients '~tNl' --ingredients '~tND'

Devin Review

The capability refactor moves HT assembly from the MIB to the MAC. The fixture therefore needs the module test category.

This commit moves Ieee80211VhtHtCapabilities_1.test from tests/unit to tests/module without a content change. The subsequent capability commit changes the fixture to call the production MAC. This preparation preserves the fixture's contents and expected results.

Plan: plan/done/80211htcapop-rebase-20261115.md
Change: tests | location | - | ieee80211-htcapop-v3
Link-layer initialization may resolve peer interfaces by their configured
addresses. Declare network-interface configuration as a prerequisite so these
queries see initialized identities regardless of module declaration order.
The physical-layer prerequisite remains in place.

This ordering supplies the shared readiness contract used by simplified
wireless association before network configuration.

No fingerprint or statistical baseline is changed. The selected regression
contract covers MacNonQos and MacQos, run 0, in examples/adhoc/qos, plus
simplified association and AP lifecycle module tests in debug mode.

Plan: plan/done/80211htcapop-refactor-v3.md
Change: src.common.InitStages | behavior.change | test | ieee80211-htcapop-v3
Capability preparation previously depended on initialization broadcasts and
mixed local PHY support with active BSS operation. Make the MAC prepare an
idempotent profile through typed PHY contributors, and let management own
accepted BSS transitions and simplified peer installation.

Keep directional peer capabilities immutable and evaluate operation and HT
eligibility separately. Publish committed MIB changes after management
bookkeeping, guard state mutation, and replace modesetChanged listeners
with explicit configuration providers. Prepare simplified associations
before network configuration, independently of node declaration order.

Keep simplified legacy STAs associated without accepting HT operation from
an HT AP. Cover both declaration orders and shutdown/crash restart, while
retaining BSS identity and channel and removing AP-side peer resources on stop.

Migrate dependent consumers and regression fixtures together with the
contracts. Document public API migration and the notification lifetime.

Validation scope: debug build; 3 focused unit and 9 module cases covering
capability preparation, provider wiring, association, lifecycle, beacon and
channel updates; MacNonQos and MacQos run 0 fingerprints at 10s with unchanged
tplx expectations. No fingerprint or statistical baseline changes.

Plan: plan/done/80211htcapop-refactor-v3.md
Change: src.ieee80211 | behavior.change | test expected whatsnew migration | ieee80211-htcapop-v3
Catalog-only consumers should not require capability preparation. Introduce
a paired C++/NED IIeee80211ModeSetProvider contract and make MAC
configuration extend it with the preparation operation used by management.
ModeSetModuleBase now depends only on the read-only provider.

Migrate the replacement-provider fixture to the narrow contract, removing
its throwing preparation stub. Update architecture, migration guidance and
release notes to identify the contract custom catalog providers implement.

Validation of the integrated changes: debug build, 5 focused module tests,
3 unit tests and 18 unchanged Wi-Fi/Ethernet/VLAN/configurator fingerprint
cases pass. Scoped architecture checks pass; interface checking reports
only the existing AV-CONTRACT-02 bodies. No recorded baseline changes.

Plan: plan/done/80211htcapop-refactor-v3.md
Change: src.ieee80211 | refactor | whatsnew migration | ieee80211-htcapop-v3

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

Devin Review

This branch has not been deployed

No deployments
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