Repository navigation
ieee80211: separate capability preparation from BSS state transitions - #1458
Open
mgonzalezlopezudc wants to merge 4 commits into
Open
mgonzalezlopezudc wants to merge 4 commits into
mgonzalezlopezudc wants to merge 4 commits into
Conversation
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
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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"]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.
bssStateChangedreports BSS and relationship changes.rateStateChangedreports changes that affect rate selection. An association-status change alone emits onlybssStateChanged. 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 callbacksRetained 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| DRate 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
22fed88393moves the VHT capability fixture to module tests without content changes. This prepares its later use of the production MAC.73ef256804makes interface identity ready before link-layer initialization. This shared prerequisite supports peer discovery independently of module declaration order.53323a4383separates capability preparation, management transitions, and state publication. This commit changes behavior and migrates the dependent consumers and tests together.7a8749d7baseparates 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:
IIeee80211ModeSetProviderandModeSetModuleBaseIIeee80211MacConfiguration::prepareLocalCapabilities()IIeee80211TransmitterCapabilitiesandIIeee80211ReceiverCapabilitiesIIeee80211BssProviderpublishStateChange()Catalog consumers declare a
modeSetModuleNED 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 is91219b0fa7d2794ee67ac8a3dd45c3a09cfc45b0. Upstreammasteradvanced after that base. The tests do not verify the merge result with the newer upstream commits.tplx,~tNl, and~tNDThe 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.reportentry ininet.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: