feat(802.11n): add configurable HT Greenfield mode - #1127
feat(802.11n): add configurable HT Greenfield mode#1127mgonzalezlopezudc wants to merge 8 commits into
Conversation
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| createHtModeSet("n(mixed-2.4Ghz)", Ieee80211HtPreambleMode::HT_PREAMBLE_MIXED), | ||
| // IEEE Std 802.11-2024, 19.1.4, 19.3.9.5, 19.4.3: HT-greenfield is a distinct optional PPDU format with separate timing. | ||
| createHtModeSet("n(greenfield-2.4Ghz)", Ieee80211HtPreambleMode::HT_PREAMBLE_GREENFIELD), |
There was a problem hiding this comment.
🟡 Simulations crash when Greenfield and mixed 802.11n devices share the same wireless network
Devices configured for the new Greenfield operating mode now use transmission settings that a neighbouring mixed-mode device does not recognise, and the acknowledgement logic rejects them (getIsMandatory() at src/inet/linklayer/ieee80211/mac/rateselection/RateSelection.cc:84), so any simulation that mixes the two 802.11n modes aborts with an error as soon as the first frame must be acknowledged.
Impact: A user (or the PR's own runtime test, which puts a Greenfield host, a mixed access point and a mixed host in one network) sees the simulation stop with a fatal "Unknown mode" error instead of exchanging traffic.
Mode-set membership check on the acknowledgement rate path
Before this change, Ieee80211HtCompliantModes::getCompliantMode() keyed its cache only on (bandwidth, mcsIndex, guardInterval) (src/inet/physicallayer/wireless/ieee80211/mode/Ieee80211HtMode.cc:329), so a Greenfield request returned the very same Ieee80211HtMode object as the mixed request. The PR correctly separates them, which means the mode objects contained in n(greenfield-2.4Ghz) and n(mixed-2.4Ghz) are now distinct pointers.
On reception, Ieee80211Receiver tags the packet with the transmitter's mode object (src/inet/physicallayer/wireless/ieee80211/packetlevel/Ieee80211Receiver.cc:67). When the receiver must send an ACK and responseAckFrameBitrate is left at its default -1bps, RateSelection::computeResponseAckFrameMode() takes that mode and calls ASSERT(modeSet->containsMode(mode)) followed by modeSet->getIsMandatory(mode). Ieee80211ModeSet::findModeIndex() compares raw pointers (src/inet/physicallayer/wireless/ieee80211/mode/Ieee80211ModeSet.cc:494-499) and getIsMandatory() throws cRuntimeError("Unknown mode") for a mode that is not in the local set (src/inet/physicallayer/wireless/ieee80211/mode/Ieee80211ModeSet.cc:502-513).
So a mixed-mode AP acknowledging a Greenfield data frame (and vice versa) aborts the run. tests/module/Ieee80211HtGreenfieldRuntime.test:107-108 configures exactly this heterogeneous BSS (Greenfield host[0], mixed ap and host[1]) while relying on default ACK rate selection.
Possible mitigations: pin responseAckFrameBitrate/responseCtsFrameBitrate in the affected configurations, make the test homogeneous per BSS (two separate runs), or make response-rate selection resolve the received mode to an equivalent entry in the local mode set instead of relying on pointer identity.
Prompt for agents
Making HT Greenfield selectable creates a new, reachable configuration in which some stations use the n(greenfield-2.4Ghz) mode set while others use n(mixed-2.4Ghz). Because the HT mode cache is now keyed on the preamble format, the two sets contain different Ieee80211HtMode objects. On reception the packet is tagged with the transmitter's mode object (Ieee80211Receiver.cc), and RateSelection::computeResponseAckFrameMode()/computeResponseCtsFrameMode() then assert that this mode is contained in the local mode set and call Ieee80211ModeSet::getIsMandatory(), which throws cRuntimeError("Unknown mode") because Ieee80211ModeSet::findModeIndex() compares raw pointers. Result: the first ACK in a heterogeneous BSS aborts the simulation. tests/module/Ieee80211HtGreenfieldRuntime.test configures exactly such a BSS (Greenfield host[0], mixed ap and host[1]) with default responseAckFrameBitrate, so it is expected to hit this. Decide whether to (a) keep BSSes homogeneous in the example/test configurations (or pin responseAckFrameBitrate/responseCtsFrameBitrate), or (b) make response-rate selection tolerant of a received mode that is not pointer-identical to an entry in the local mode set (e.g. resolve by bitrate/bandwidth/spatial streams).
Was this helpful? React with 👍 or 👎 to provide feedback.
HT mixed and Greenfield modes are cached as distinct objects because their PPDU preambles and timing differ. A received mode can therefore be semantically equivalent to a local mode-set entry without being pointer-identical, which previously caused response-rate selection to reject the mode as unknown. Resolve mode-set membership and lookup by PHY mode properties while preserving distinct preamble-specific mode objects. Select the HT-mixed profile for HT ACK, CTS, and BlockAck responses, as required for HT control responses, and apply the mapping to both legacy and QoS rate selection. Extend unit coverage for cross-profile lookup and mixed control-response selection, and update the heterogeneous runtime test to observe both HT preamble formats without assuming every HT transmission uses the local preferred format. Validation: make MODE=release -j12; inet_run_unit_tests -m release -f 'Ieee80211HtGreenfield_1\.test'; inet_run_module_tests -f 'Ieee80211HtGreenfieldRuntime\.test'.
Restrict cross-profile mode equivalence to HT modes and compare the MCS index, bandwidth, guard interval, frequency band, and spatial stream count while intentionally ignoring the mixed/Greenfield preamble format. Discover the control-response mode set from the registered same-band HT-mixed profiles instead of hardcoding the 2.4 GHz profile, and fail explicitly when the counterpart is missing or ambiguous. Keep configured ACK, CTS, and BlockAck modes owned by each rate selector's active mode set, translating them to the control-response profile only when the response is computed. Add focused coverage for HT mixed/Greenfield mapping, 5 GHz rejection without a registered counterpart, strict ERP mode membership, and configured DCF/QoS response-mode caching and conversion.
Restore exact pointer identity for mode-set membership so receiver feasibility checks and transmitter validation do not treat HT mixed and Greenfield modes as interchangeable. Add a separate HT-equivalence lookup for control-response format translation and cache successful control-response resolutions. Preserve same-band mixed-format selection while rejecting modes outside the configured operation mode, including unsupported 5 GHz HT inputs. Include band and preamble format in the VHT compliant-mode cache key. Update the HT unit and runtime coverage, and remove the protected-to-public preprocessor workaround from the configured response-rate test.
Keep operational mode membership pointer-strict while modeling mandatory PHY capabilities separately. Greenfield HT profiles now explicitly support non-HT and HT-mixed response modes without making those modes selectable for normal data transmission. Apply IEEE 802.11-2024 control-response rules in DCF and QoS rate selection: ordinary HT ACK and Basic BlockAck responses use mandatory non-HT rates, CTS responses to HT-carried RTS frames use HT-mixed format, and configured response rates still derive their format from the eliciting PPDU. Preserve legacy and VHT override behavior and mandatory-rate fallback semantics. Remove fuzzy public mode lookup, the mutable process-global response cache, and repeated global mode-table scans. Precompute immutable response mappings, make the mode-set registry thread-local to match HT mode ownership, and re-resolve configured response modes after mode-set changes. Use explicit supported-mode validation for per-packet TX requests and RX feasibility while keeping default transmitter modes selectable and mode-set transitions atomic. Add strict membership and transmitter transition unit coverage, configured and dynamic ACK/CTS/BlockAck checks, and a two-station forced RTS/CTS runtime regression that observes HT-GF RTS, HT-MF CTS, HT-GF data, and non-HT ACK frames. Validated in debug mode with a clean build, 90/90 unit tests, 2/2 focused module tests, the HT-Greenfield example at 20/20 ping replies, and an unchanged focused fingerprint.
Honor responseCtsFrameBitrate for HT exchanges by translating the configured mode to its exact HT-mixed counterpart while preserving MCS, bandwidth, spatial streams, guard interval, and band. Keep standards-derived primary selection for the automatic path, and document the configured value as an explicit model override. Restrict supplementary HT-mixed and legacy DSSS/HR-DSSS/ERP capabilities to the Greenfield profile. This restores the established n(mixed-2.4Ghz) membership contract, HT ACK and Basic BlockAck selection, and strict transmitter/receiver acceptance behavior. Update unit and module coverage for mismatched configured and derived CTS MCS values, Greenfield-only supplementary support, mixed-profile response behavior, mode-set rebinding, and legacy-mode rejection. Validated with the debug build, all 90 unit tests, the focused configured-response and Greenfield runtime module tests, and the mixed-HT TXOP fingerprint.
Fail immediately during link-layer initialization when RateSelection has not received a mode set, while preserving the null-safe runtime refresh path. Document the bounded mandatory-index fallback used when no Basic HT-MCS Set is modeled, including the separate channel-width filtering and resulting 40 MHz candidate behavior. Add an expected-failure module test for the missing mode-set invariant and clarify the existing 40 MHz MCS 8 to MCS 0 unit-test expectation. Validated with the debug build, focused HT Greenfield and configured-response tests, the new negative initialization test, and related 802.11 fingerprints.
1 participant
Summary
Adds configurable IEEE 802.11n HT Greenfield preamble support and regression coverage.
Motivation
The HT Greenfield timing and enum support already existed, but the mode-set configuration exposed only
n(mixed-2.4Ghz). In addition, the HT mode cache key omitted the band and preamble format. A Greenfield lookup could therefore reuse an already-cached mixed-format mode.Changes
n(greenfield-2.4Ghz).opModeandmodeSetenums.Validation
inet_run_unit_tests -m release -f 'Ieee80211HtGreenfield_1\\.test'inet_run_module_tests -m release --build --no-concurrent -f 'Ieee80211HtGreenfieldRuntime.*'git diff --checkThe runtime test uses the real IEEE 802.11 radio and packet exchange path; it does not rely on generated captures or analysis output.
Scope
This change excludes generated captures, analysis output, HT40 CCA changes, HCF/MIB changes, and HE/EHT changes.