IEEE 802.11: add HT capability and operation signalling - #1154
Open
mgonzalezlopezudc wants to merge 19 commits into
Open
IEEE 802.11: add HT capability and operation signalling#1154mgonzalezlopezudc wants to merge 19 commits into
mgonzalezlopezudc wants to merge 19 commits into
Conversation
Mode-set timing must not depend on the entry that happens to sort first by bitrate. Store and validate an explicit reference mode and PHY family, and make timing and TXOP consumers use those authorities directly. Correct HT and VHT receive-start delay to the standards-defined 24 microseconds so response timeout calculations use the intended PHY timing. Focused mode-set, response-timeout, and TXOP tests cover reordered modes, invalid references, PHY defaults, and control-response timing. Record the seven directly affected debug WLAN trajectories in this commit. The corrected receive-start delay and explicit timing authority move the fragmentation, ad hoc QoS, 802.11ac ping, and TXOP event sequences; TXOP records the valid intermediate trajectory at this series boundary and advances again when negotiated peer-mode selection is introduced.
Management frame decoding and Supported Rates construction must preserve concrete frame subtype, basic-rate membership, and rates beyond the primary element. Validate Supported and Extended Supported Rates, derive one explicit legacy operational set from eligible modes, and reject mode sets that cannot advertise a representable legacy rate. Focused serializer and mode-set tests cover malformed elements, primary/extended splitting, basic membership, timing, and empty-set rejection. Record the 30 directly affected debug WLAN trajectories in this commit. Correct Supported and Extended Supported Rates content changes management-frame bytes, lengths, and downstream packet flow across the mapped infrastructure scenarios; their data-byte fingerprints advance again when fixed management fields become little-endian.
Introduce typed HT capability and operation state derived from the configured mode set, including exact MCS, channel-width, mandatory-rate, and short-guard-interval support. Make HT properties explicit in the mode interface, retain non-HT defaults in the base class, and serialize and print the corresponding management elements.
Populate the mixed 2.4 GHz HT mode set with every modeled MCS 0 through 31 across 20/40 MHz and long/short guard intervals. Keep only long-GI 20 MHz MCS 0 through 7 mandatory and verify the exact catalog and capability aggregation.
Distinguish channel widths described by the mode catalog from widths the configured packet PHY can actually transmit and receive. Publish a narrow PHY capability contract, intersect both directions in the MAC, and advertise only the operational widths and guard intervals through the MIB.
Introduce a typed management transaction tag, preserve it with packet and region semantics during fragmentation, and remove it at the layered PHY receive boundary. This keeps local completion correlation intact without leaking sender-local control state to the peer.
Preserve concrete association primitive types and model association and reassociation as correlated transactions with explicit pending state, subtype-aware confirmations, timer cleanup, and stale-response rejection. Restore the current AP channel when reassociation to a different AP fails without breaking the existing association.
Stations could not consistently recover HT state from serialized discovery frames or distinguish a genuinely legacy AP from malformed or incompatible HT signalling. Installing peer state from local or incomplete information would make association results and later rate selection unreliable. Advertise typed HT capabilities in discovery and association exchanges, recover the primary channel from received HT Operation elements, and classify absent, valid, and invalid HT responses explicitly. Install negotiated peer state only when the correlated association or reassociation transaction succeeds, and preserve the current AP channel after a failed reassociation to another peer. Focused unit and module tests cover serialized discovery, legacy fallback, invalid HT classification, missing channel metadata, peer-state visibility, and reassociation channel restoration.
IEEE 802.11 reserves the Basic HT-MCS Set in Association and Reassociation Responses, so interpreting those response bits made negotiated state depend on a field that must be transmitted as zero. Preserve Basic HT-MCS bits only for Beacon and Probe Response HT Operation elements. Validate a selected BSS from its cached discovery advertisement before transmitting an association request, and combine that cached Basic HT-MCS Set with the correlated response capabilities when installing peer state. Focused serializer and detailed-STA tests cover subtype-specific wire bits, discovery round trips, pre-transmission refusal, and successful negotiation from cached BSS state.
Individually addressed transmissions lacked an authoritative way to restrict configured, per-receiver, and rate-control candidates to modes supported by both the local catalog and negotiated peer state. Add a deterministic peer-mode selector that intersects exact MCS, channel-width, HT Operation, and guard-interval state with local mode membership. Wire the MIB into DCF and HCF rate selection, preserve the existing master rate-control and per-receiver policies, and when negotiated HT is unavailable or invalid choose a mandatory legacy operational fallback that does not exceed the requested candidate rate. Focused unit and module tests cover sparse MCS sets, 20/40 MHz operation, both guard intervals, local-mode membership, deterministic tie breaking, bounded legacy fallback including the MCS0 ACK/CTS path, and production DCF/HCF integration. Advance the TXOP showcase baseline from the C01 timing-only trajectory to the directly caused negotiated-mode trajectory. Its packet types, lengths, and cross-node flow now match the approved final debug run.
IEEE 802.11 transmits fixed-width numeric management fields least-significant octet first, and successful Association/Reassociation Responses carry a marked 14-bit logical AID. The existing serializer used big-endian fields and exposed raw/unvalidated AIDs. Encode and decode all modeled fixed numeric fields little-endian. Validate logical AID range/status semantics at the wire boundary and add/remove the 0xC000 marker without changing packet-domain IDs. Exact independent byte-vector tests cover every modeled management subtype, AID boundaries, malformed markers, unsuccessful responses, and existing rates/HT element integration. Advance the 30 management-frame data-byte fingerprints introduced with the corrected rate elements to their approved final values. The packet types, lengths, and cross-node flow remain unchanged from C02; only the serialized fixed fields and successful-response AID marker move the ~tND ingredient.
HT Operation carries standards channel numbers, while packet-level radios use internal zero-based channel indices. Treating the two as interchangeable made 2.4 GHz advertisements off by one and allowed impossible HT40 primary/secondary combinations. Add explicit bidirectional band mappings and a current-channel provider, keep the PHY band synchronized with channel changes, and convert HT Operation fields only at management boundaries. Move AP channel tracking into the common management base at this boundary, preserve the detailed AP legacy channel view through delegation, and expose the radio module on the simplified AP so both variants initialize independently. Make primary-channel availability explicit in the MIB, require received HT state to match the packet channel, and reject illegal AP HT40 tuples during initialization. Focused band, discovery, association-path, and mapped AP initialization checks cover channel-number conversion, missing/mismatched metadata, duplicate subscription prevention, and valid and invalid 2.4 GHz HT40 combinations.
Detailed STA management used untracked scan timers and several independent teardown paths. Deauthentication and disassociation also consulted the wrong address field or cleared state before preserving the pending transaction context. Track and cancel every scan timer, centralize current-association cleanup, and make peer-initiated termination preserve unrelated pending work while completing same-peer work deterministically. Clear peer HT state on all relevant teardown and stop paths, and reset discovery-test association state between exchanges. Focused module tests cover current, pending, foreign, cached, and uncached peers together with stop/start cycles and outstanding scan, authentication, association, and beacon timers.
A Disassociate primitive for one peer unconditionally canceled any pending association or reassociation, even when that transaction belonged to a different AP. Scope cancellation to the request's PeerSTAAddress. Preserve unrelated pending transactions while still canceling same-target work, for both initial association and reassociation. Extend the focused disassociation module test through current, target, and foreign peers, including late-response behavior after a same-target cancellation.
Management needs terminal delivery outcomes while the coordination function still owns the transmitted frame. Existing frame-sequence signals expose internal sequencing and do not provide one typed, ownership-safe contract across DCF and HCF. Add a synchronous non-retaining transmission callback discovered through the management gate. Report acknowledged and retry-limit outcomes for locally originated management frames from DCF and HCF, including RTS-protected and internal-collision terminal paths. This commit establishes and compiles the callback plumbing; policy consumers and focused end-to-end outcome coverage follow with the AP transaction commit.
A compound queue removes an overflow-selected packet from its child queue before emitting the drop. That removal releases ownership, so the subsequent drop path can observe a packet no longer owned by the compound module. Retake the selected packet after removal and before drop processing. Also keep the streaming push API publicly accessible through PacketQueueBase as required by its queue interface. Focused AP queue-drop integration coverage follows in C17, where the dropped management packet is inspected synchronously.
AP association state must become effective only after the exact response transaction reaches a terminal MAC outcome. Frame-sequence inference, eager AID publication, and uncorrelated queue drops could commit or tear down the wrong peer state. Reserve and commit AIDs transactionally, tag each response, snapshot negotiated HT state, and complete it on acknowledged, retry-limit, RTS-timeout, or pre-transmission-drop callbacks. Coalesce duplicate requests, clear pending state before synchronous notifications, preserve same-AP reassociation semantics, convert HT channels through the radio band, and keep simplified management restart-safe. Focused unit and module coverage spans AID reservation, correlation, DCF/HCF queue drops, HCF RTS timeout, reassociation snapshots, unavailable channels, simplified initialization, and an RTS-protected end-to-end HT association.
Use the retry counters of the EDCAF that actually lost an HCF internal collision, including management frames scheduled outside AC_BE. Verify AC_VO retry ownership and the resulting terminal management callback with a focused module test.
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
There was a problem hiding this comment.
Devin Review found 3 potential issues.
2 flags not posted on this PR by your GitHub settings — view them in Devin Review. (Configure)
Comment on lines
+96
to
+102
| for (int mcs = 0; mcs < 77; mcs++) { | ||
| localHtCapabilities.rxMcsSupported[mcs] = supportedMcs[mcs]; | ||
| if (mcs < 32 && supportedMcs[mcs]) { | ||
| int nss = mcs / 8; | ||
| localHtCapabilities.txMcsNss.maxMcsPerNss[nss] = std::max(localHtCapabilities.txMcsNss.maxMcsPerNss[nss], mcs % 8); | ||
| } | ||
| htOperation.basicMcsSupported[mcs] = mandatoryMcs[mcs]; |
There was a problem hiding this comment.
🔴 Single-antenna HT links can abort
With the default single antenna, updateLocalHtCapabilities advertises four-stream MCS values. Negotiated rate control can select one, and transmission then aborts.
Prompt for agents
Limit locally advertised HT receive and transmit MCS capabilities to modes the configured radio can actually process, including its antenna/spatial-stream count. Ieee80211Mib::updateLocalHtCapabilities currently receives only the mode set and channel widths, while Ieee80211Mac has access to the radio and its antenna. Propagate the operational spatial-stream limit into capability construction, ensure Basic HT-MCS construction remains valid, and add an end-to-end test using the default one-antenna n profile where rate control advances beyond MCS 7.
Was this helpful? React with 👍 or 👎 to provide feedback.
Comment on lines
+1103
to
+1112
| ap->htOperationPresent = body->getHtOperationPresent(); | ||
| if (ap->htOperationPresent) { | ||
| const auto& channelInd = packet->findTag<Ieee80211ChannelInd>(); | ||
| const auto *receivedChannel = channelInd != nullptr ? channelInd->getChannel() : nullptr; | ||
| if (receivedChannel == nullptr) | ||
| throw cRuntimeError("HT Operation discovery requires an IEEE 802.11 channel indication"); | ||
| ap->htOperation = makeHtOperation(receivedChannel->getBand(), body->getHtOperation()); | ||
| if (ap->htOperation.primaryChannel != receivedChannel->getChannelNumber()) | ||
| throw cRuntimeError("HT Operation primary channel %d does not match received channel index %d", | ||
| ap->htOperation.primaryChannel, receivedChannel->getChannelNumber()); |
There was a problem hiding this comment.
🔴 Malformed beacons abort simulations
A beacon with invalid HT channel data makes storeAPInfo throw. One malformed peer advertisement terminates the simulation instead of being discarded.
Prompt for agents
Treat invalid HT discovery information as a malformed peer frame, not a runtime invariant failure. In Ieee80211MgmtSta::storeAPInfo, validate the channel indication, band mapping, primary-channel match, secondary offset, and HT40 tuple without allowing cRuntimeError from makeHtOperation/getChannelIndex to escape. Drop or mark the AP advertisement unusable while leaving the simulation running. Avoid partially refreshing an existing ApInfo before validation completes, and add malformed Beacon and Probe Response tests.
Was this helpful? React with 👍 or 👎 to provide feedback.
Comment on lines
+1109
to
+1117
| ap->htOperation = makeHtOperation(receivedChannel->getBand(), body->getHtOperation()); | ||
| if (ap->htOperation.primaryChannel != receivedChannel->getChannelNumber()) | ||
| throw cRuntimeError("HT Operation primary channel %d does not match received channel index %d", | ||
| ap->htOperation.primaryChannel, receivedChannel->getChannelNumber()); | ||
| // IEEE Std 802.11-2024, Table 9-230 and 11.14: the HT Operation | ||
| // element is the authoritative advertisement of the BSS primary | ||
| // channel. Its standards-facing channel number has already been | ||
| // converted to the received radio's internal channel index above. | ||
| ap->channel = ap->htOperation.primaryChannel; |
There was a problem hiding this comment.
🟡 Invalid HT40 networks remain selectable
storeAPInfo accepts an unavailable secondary channel when the primary matches reception. The station can associate with an impossible 40 MHz configuration.
Prompt for agents
Validate received HT40 operation tuples during discovery and association. After decoding Ieee80211HtOperation, when operatingChannelWidth is 40 MHz, call the received band's isHt40OperationSupported(primaryChannel, secondaryChannelOffset). Reject or mark unusable any advertisement with a missing/invalid secondary channel. Apply the same validation to the Association/Reassociation Response before installing peer state, and add boundary tests such as 2.4 GHz channel 13 with secondary above.
Was this helpful? React with 👍 or 👎 to provide feedback.
Malformed HT Capabilities or HT Operation elements in Beacon, Probe Response, Association Response, and Reassociation Response frames were passed to strict conversion helpers. Missing reception-channel metadata, unmappable primary channels, and inconsistent channel-width/secondary-offset tuples could therefore abort the simulation or leave a partially refreshed AP cache. The STA could also accept a 40 MHz operation whose secondary channel did not exist. Treat these elements as peer input at the STA management boundary. Validate a complete candidate AP record before committing it, reject invalid discovery frames without refreshing the associated AP's beacon timeout, and translate response validation failures into the existing successful legacy fallback with one htNegotiationFailed notification. Accept 20 MHz operation only without a secondary channel. Accept 40 MHz operation only with an above or below offset whose complete channel pair is supported by the received band. Legacy STAs continue to ignore HT elements. Add focused unit and module coverage for all four response and discovery frame types, cache preservation, beacon deadlines, legal and invalid channel pairs, unmappable primary channels, and legacy STA behavior. Serialized-byte parsing and 5 GHz standards-channel mapping remain unchanged.
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
1 participant
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.
Summary
This PR adds model-backed IEEE 802.11 HT Capabilities and HT Operation signalling and uses the negotiated state throughout discovery, association, channel validation, and rate selection.
It also:
This is the review-ready reconstruction of the work from #1144 as an 18-commit, dependency-ordered series.
Motivation
The previous model did not represent and negotiate HT capability and operation state end to end. In particular:
The new implementation makes these authorities and state transitions explicit while preserving legacy operation for peers without negotiated HT support.
Reading order
The commits are ordered by dependency:
Each commit builds independently and includes its directly attributable tests and fingerprint updates.
Architectural surface
Contracts
Packet representation
State and ownership
Configuration and observability
htNegotiationFailedsignal for diagnosed negotiation failures.No changed source path is sealed. No new architecture or naming exception is required.
Validation
All builds and executions used debug artifacts.
doc/project/enforcement/check-commits.sh master..HEAD git diff --check master...HEAD make MODE=debug -j$(nproc)Result: PASS for all 18 commits; final debug build exited successfully.
Focused unit tests:
inet_run_unit_tests \ -m debug \ --build \ -f '(Ieee80211Band_1|Ieee80211HtCapabilities_1|Ieee80211HtMgmtElements_1|Ieee80211HtModeSet_1|Ieee80211MgmtApTransaction_1|Ieee80211MgmtFrameSerializer_1|Ieee80211MgmtProtocolPrinter_1|Ieee80211MgmtStaDiscovery_1|Ieee80211MgmtStaPrimitiveDispatch_1|Ieee80211MgmtTransactionTag_1|Ieee80211MibAssociationId_1|Ieee80211PeerModeSelection_1|Ieee80211ResponseTimeout_1|Ieee80211SupportedRates_1|Ieee80211TxopProcedure_1)\.test$'Result: 15/15 PASS.
Focused module tests:
inet_run_module_tests \ -m debug \ --build \ -f '(Ieee80211HcfInternalCollision_1|Ieee80211HtAssociation_1|Ieee80211MgmtApHcfQueueDrop_1|Ieee80211MgmtApHcfRtsTimeout_1|Ieee80211MgmtApQueueDrop_1|Ieee80211MgmtApReassociationSnapshot_1|Ieee80211MgmtApTimeout_1|Ieee80211MgmtApUnavailableChannel_1|Ieee80211MgmtStaDeauthentication_1|Ieee80211MgmtStaDisassociation_1|Ieee80211MgmtStaDiscovery_1|Ieee80211MgmtStaLifecycle_1|Ieee80211MgmtStaSimplifiedInitialization_1|Ieee80211PacketDomainTagBoundary_1)\.test$'Result: 14/14 PASS.
Focused queueing test:
inet_run_queueing_tests \ -m debug \ --build \ -f 'CompoundQueue_1\.test$'Result: 1/1 PASS.
The following reproduces the exact 37 fingerprint rows changed by this branch:
Result: 37/37 PASS.
Fingerprint updates
This PR updates 37 existing fingerprint rows:
tests/fingerprint/examples.csv;tests/fingerprint/showcases.csv;tests/fingerprint/tutorials.csv.The updates are carried by their causal commits:
The
tplx,~tNl, and~tNDvalues were verified. Graphicaltyfvalues are unchanged.Scope limits
The current packet PHY advertises operational HT20 only. HT40 catalogue, negotiation, selection, and channel validation are covered, but an end-to-end HT40 PHY exchange is outside this PR.
VHT capability negotiation is also outside the scope of this change.