Skip to content

ieee80211: add Minstrel rate control for HT and VHT - #1186

Open
mgonzalezlopezudc wants to merge 12 commits into
inet-framework:masterfrom
mgonzalezlopezudc:feat/ieee80211-minstrel
Open

ieee80211: add Minstrel rate control for HT and VHT#1186
mgonzalezlopezudc wants to merge 12 commits into
inet-framework:masterfrom
mgonzalezlopezudc:feat/ieee80211-minstrel

Conversation

@mgonzalezlopezudc

@mgonzalezlopezudc mgonzalezlopezudc commented Sep 11, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

What

Add MinstrelHtRateControl, implementing the Linux v4.19 Minstrel-HT rate adaptation algorithm for IEEE 802.11 HT and VHT. This includes per-peer Q12 EWMA probability tracking, throughput ranking across modulation, channel width, guard interval, and spatial-stream groups, deterministic sampling permutations, and multi-rate retry plans.

Also introduces packet-aware rate control queries in IRateControl / RateControlBase and wires them through RateSelection and QosRateSelection, ensuring retry plans remain stable across repeated duration queries and independent QoS queues while preserving legacy AARF and Onoe behavior.

Why

Existing INET rate adaptation algorithms (AARF and Onoe) are designed for single-stream legacy rates and single scalar retry feedback. IEEE 802.11n (HT) and 802.11ac (VHT) introduce multi-dimensional operational spaces (MCS, 20/40/80/160 MHz bandwidths, short/long GI, and multiple spatial streams) where rates cannot simply be ordered by nominal bitrate:

  • Higher nominal bitrates can have lower throughput under packet error rates, and modes with different spatial streams or channel widths have different robustness profiles.
  • Linux's Minstrel-HT policy calculates expected throughput per airtime based on historical EWMA delivery probability, selects a primary rate, a second throughput rate, and a probability fallback rate, and manages dynamic group probing.
  • Repeated MAC duration queries and concurrent QoS access categories require each packet's retry sequence to remain stable and isolated, which packet-attached tag metadata enables.

Stack and reading order

Built on top of PR #1176 (fix/ieee80211-agent-rate-control, head 9dcd62d999a0b9e03655fbe33ece71f5e36e0b57).
Target: master. Range: 9dcd62d999..15c5984876.

The topic branch has been cleaned up into a 3-commit reviewable series:

  1. dba8b5d5e4 — ieee80211: pass packets to rate-control queries

    • Single decision & rationale: Extends IRateControl with getRateForFrame(Packet *frame) and threads borrowed frame access through RateSelection and QosRateSelection. Multirate retry controllers need packet identity to preserve retry plans across duration queries and independent QoS queues.
    • Dependency: Pinned base 9dcd62d999.
    • Component surface:
      • src/inet/linklayer/ieee80211/mac/contract/IRateControl.h
      • src/inet/linklayer/ieee80211/mac/ratecontrol/RateControlBase.h
      • src/inet/linklayer/ieee80211/mac/ratecontrol/RateControlBase.cc
      • src/inet/linklayer/ieee80211/mac/rateselection/RateSelection.h
      • src/inet/linklayer/ieee80211/mac/rateselection/RateSelection.cc
      • src/inet/linklayer/ieee80211/mac/rateselection/QosRateSelection.h
      • src/inet/linklayer/ieee80211/mac/rateselection/QosRateSelection.cc
    • Verification: RateControlBase delegates getRateForFrame to getRate(dest) to preserve legacy controller compatibility. Clean build; AARF and Onoe regression tests pass.
    • Baseline effect: None.

  2. dafe31ba2b — ieee80211: add Minstrel rate control for HT and VHT

    • Single decision & rationale: Implements the Linux v4.19 Minstrel-HT rate control algorithm (MinstrelHtRateControl) and its internal packet metadata tag (MinstrelRateControlTag). Implements Q12 EWMA estimates, airtime-throughput ranking across HT/VHT groups, deterministic sampling, and 4-stage multirate retry plans sized strictly below the segment airtime budget.
    • Dependency: Commit 1 (dba8b5d5e4).
    • Component surface:
      • src/inet/linklayer/ieee80211/mac/ratecontrol/MinstrelHtRateControl.h
      • src/inet/linklayer/ieee80211/mac/ratecontrol/MinstrelHtRateControl.cc
      • src/inet/linklayer/ieee80211/mac/ratecontrol/MinstrelHtRateControl.ned
      • src/inet/linklayer/ieee80211/mac/ratecontrol/MinstrelRateControlTag.msg
      • tests/module/MinstrelHtRateControlEligibility_1.test
      • tests/module/MinstrelHtRateControlHtExchange_1.test
      • tests/module/MinstrelHtRateControlReference_1.test
      • tests/module/MinstrelHtRateControlVhtExchange_1.test
    • Verification: 4 direct module tests verify Q12 math, throughput calculation, retry bounds, sample selection, peer capabilities, antenna limits, MCS masks, channel widths, and DCF/HCF frame exchanges with rate adaptation.
    • Baseline effect: None.

  3. 15c5984876 — examples: demonstrate Minstrel HT and VHT rate adaptation

    • Single decision & rationale: Adds runnable simulation showcase and developer documentation for Minstrel-HT rate adaptation in HT and VHT networks.
    • Dependency: Commit 2 (dafe31ba2b).
    • Component surface:
      • examples/wireless/minstrel/MinstrelRateControlNetwork.ned
      • examples/wireless/minstrel/omnetpp.ini
      • examples/wireless/minstrel/README.md
    • Verification: Runs Ht and Vht simulation configs delivering 2900 UDP packets with observable rate adaptation up to 130 Mbit/s (HT) and 173.33 Mbit/s (VHT).
    • Baseline effect: None.

Architectural Surface

• Modules touched / added:
• src/inet/linklayer/ieee80211/mac/contract/IRateControl.h
• src/inet/linklayer/ieee80211/mac/ratecontrol/RateControlBase.h
• src/inet/linklayer/ieee80211/mac/ratecontrol/RateControlBase.cc
• src/inet/linklayer/ieee80211/mac/ratecontrol/MinstrelHtRateControl.h
• src/inet/linklayer/ieee80211/mac/ratecontrol/MinstrelHtRateControl.cc
• src/inet/linklayer/ieee80211/mac/ratecontrol/MinstrelHtRateControl.ned
• src/inet/linklayer/ieee80211/mac/ratecontrol/MinstrelRateControlTag.msg
• src/inet/linklayer/ieee80211/mac/rateselection/RateSelection.h
• src/inet/linklayer/ieee80211/mac/rateselection/RateSelection.cc
• src/inet/linklayer/ieee80211/mac/rateselection/QosRateSelection.h
• src/inet/linklayer/ieee80211/mac/rateselection/QosRateSelection.cc
• examples/wireless/minstrel/MinstrelRateControlNetwork.ned
• examples/wireless/minstrel/omnetpp.ini
• examples/wireless/minstrel/README.md
• tests/module/MinstrelHtRateControlEligibility_1.test
• tests/module/MinstrelHtRateControlHtExchange_1.test
• tests/module/MinstrelHtRateControlReference_1.test
• tests/module/MinstrelHtRateControlVhtExchange_1.test
• Contracts and protocols:
• IRateControl gains packet-aware selector const physicallayer::IIeee80211Mode *getRateForFrame(Packet *frame). RateControlBase routes this to getRate(dest) by default to preserve legacy controller compatibility.
• RateSelection and QosRateSelection pass Packet * into protected computeDataOrMgmtFrameMode.
• Packet representation:
• Transient MinstrelRateControlTag (extends TagBase) attaches rate and retry plan state to packets within the node. No packet wire formats, headers, or serialized chunks are modified.
• Configuration surface:
• New NED module MinstrelHtRateControl (inet.linklayer.ieee80211.mac.ratecontrol.MinstrelHtRateControl) with shipped parameters:
• interval (double, @unit(s), default: 50ms): positive statistics update interval.
• packetLength (int, @unit(B), default: 1200B): positive reference MPDU length for airtime ranking.
• retrySegmentDuration (double, @unit(s), default: 6ms): positive per-stage airtime budget for retry count sizing.
• maxRetryCount (int, default: 7): cap for sizing retry stages in [2, 64] (MAC recovery owns termination).
• maxChannelWidth (double, @unit(Hz), default: 20MHz): positive common operational channel width ceiling.
• maxNumSpatialStreams (int, default: -1): -1 uses local antenna count; otherwise positive peer ceiling.
• probeEnabled (bool, default: true): enables sampling probes (disable only for controlled fixed-candidate experiments).
• Module references: mibModule (default: "^.^.^.mib"), radioModule (default: "^.^.^.radio").
• Feature descriptors: None modified.
• Seals and audit exceptions: All modified source paths under src/inet/ are unsealed. No new architectural deviations (AV-*) or naming deviations (NV-*) introduced.

Baselines

No fingerprint or statistical baseline updates required. Existing rate-control fingerprints remain unchanged.

Verification Evidence

(Recorded from commit validation and examples/wireless/minstrel/README.md):

  1. Compilation:
    make MODE=debug -j$(nproc)
    Status: Clean build in debug mode (libINET_dbg.so).

  2. Mechanical gates:
    • doc/project/enforcement/check-commits.sh 9dcd62d999..HEAD (PASS, 3 commits)
    • doc/project/enforcement/check-source-seals.sh --base 9dcd62d999 (PASS)
    • Scoped naming and architecture checks on src/inet/linklayer/ieee80211/mac (PASS)

  3. Direct module tests:
    • tests/module/MinstrelHtRateControlReference_1.test (PASS): verifies EWMA Q12 math, throughput calculation, retry plans, and sample selection boundaries.
    • tests/module/MinstrelHtRateControlEligibility_1.test (PASS): verifies peer capabilities, antenna limits, MCS masks, and channel widths.
    • tests/module/MinstrelHtRateControlHtExchange_1.test (PASS): verifies DCF and HCF HT 20 MHz exchanges, probe and fallback transmissions, and upward rate adaptation.
    • tests/module/MinstrelHtRateControlVhtExchange_1.test (PASS): verifies DCF and HCF VHT 80 MHz exchanges, probes, fallbacks, and adaptation.

  4. Existing regressions and baselines:
    • tests/module/AarfRateControlRetryFeedback_1.test (PASS)
    • tests/module/OnoeRateControlRetryFeedback_1.test (PASS)
    • tests/module/OnoeRateControlInterleavedFeedback_1.test (PASS)
    • tests/module/Ieee80211HtAntennaRateControl_1.test (PASS)
    • ./fingerprinttest -d -m 'wireless/ratecontrol' -f 'tplx' -f '~tNl' -f '~tND' (PASS: all 3 rate-control fingerprints unchanged)

  5. Example network execution:
    • inet --debug -u Cmdenv -f omnetpp.ini -c Ht -r 0 (delivers 2900 UDP packets; preferred PHY rate adapts up to 130 Mbit/s)
    • inet --debug -u Cmdenv -f omnetpp.ini -c Vht -r 0 (delivers 2900 UDP packets; preferred PHY rate adapts up to 173.33 Mbit/s)

@mgonzalezlopezudc
ieee80211: normalize final newlines in changed files
bfdff40 
Keep incidental end-of-file changes separate from the rate-control fixes so
their functional diffs contain only the behavior being reviewed.
Remove surplus final blank lines from the affected MAC files and terminate
the migration guide with a newline.
@mgonzalezlopezudc
ieee80211agentsta: scope beacon loss to its interface
790d97b 
Host-level beacon-loss subscriptions receive notifications from other WLANs.
Scanning in response disassociates healthy interfaces and can interrupt an
existing scan. Match the notification payload to the containing NIC.

Cover independent beacon timeouts and overlapping scans on two WLANs.
@mgonzalezlopezudc
aarfratecontrol: follow packet feedback semantics
de5e514 
Elapsed-time probing and failure handling diverged from INRIA RR-5208,
Appendix A. Failed attempts preserved success streaks, triggered fallback
too early or ended recovery before a successful transmission.

Advance the timer from packet feedback and space ordinary fallback using
the MAC retry count. Keep recovery until success, adapt the packet timeout
with the success threshold, and cap threshold growth. Only an actual rate
increase starts a probe; idle queries cannot change adaptation state.

Replace interval with packet-timer parameters and document migration. Cover
DCF/HCF feedback, receiver isolation, recovery, timer boundaries and rate
bounds, and adapt the showcase configuration to the packet timer.

AarfRateControl and InstrumentShowcase both use the corrected controller.
Their existing tplx, ~tNl and ~tND expectations in showcases.csv and
store.json belong with this correction: the packet-feedback transitions
change adaptation and delivery trajectories. Module assertions cover the
intended state transitions. Graphical expectations remain unchanged.
@mgonzalezlopezudc
onoeratecontrol: adapt from completed packet samples
b0c4cda 
Counting individual retries mixed unfinished packets into samples and could
count a failure again at success. Small samples earned credit too quickly,
and failed-only intervals could leave the controller at an unusable rate.

Follow MadWifi ath_rate/onoe/onoe.c at revision
a7531fd223a1f454d3fd74a975b4581cde5411bb for completed normal-ACK feedback.
Consume terminal recovery counts once before evaluating a due sample.
Require ten completions for ordinary decisions, compare retries directly
with successes, prohibit upward credit after errors, and retain small
samples unless the rate changes. Failed-only samples can lower the rate.

Preserve integer truncation and bounded credit, suppress false rate-change
signals, and keep queries from consuming deadlines. Cover arithmetic and
sample boundaries, receiver isolation, mode resets and real DCF/HCF
completion counts, including interleaved HCF retries.
@mgonzalezlopezudc
ieee80211: include RTS failures in completion feedback
c3578da 
Lost CTS responses were absent from Onoe retry samples, and RTS exhaustion
did not report a completed error. Supply the protected packet's short-plus-
long retry total through DCF and HCF before recovery cleanup so each
terminal outcome is counted once.

Retire both recovery counters at completion to avoid stale totals when
identities are reused. RateControlBase adapters preserve legacy data-attempt
feedback, including AARF behavior. Document the new hooks, overload visibility
and migration requirements for direct IRateControl implementations.

Cover mixed RTS/data failures, both exhaustion paths, recovery cleanup and
protected management frames.
@mgonzalezlopezudc
qosrecoveryprocedure: isolate retry histories by receiver
53b45d6 
QoS sequence numbers are allocated per receiver and TID, so different peers
can have identical sequence and fragment numbers. Include the receiver in
the shared retry key to prevent interleaved feedback and completion cleanup
from reading or erasing another peer's counters.

Cover clean reads, short and long counters, retry limits and terminal cleanup
with interleaved peers in the recovery module test.
@mgonzalezlopezudc
onoeratecontrol: apply the legacy startup rate policy
2dd70f0 
Use the MadWifi startup ceiling for automatic local OFDM/ERP selection, so
the built-in 11a/11g sets start at 36 Mbps. HR-DSSS starts at its fastest rate.
Explicit initialRate values retain precedence, and HT/VHT retain the
fastest-mandatory default.

The contract supplies local modes without negotiated legacy peer rates;
document that limit while preserving shared RateControlBase behavior.
Cover defaults, overrides, invalid rates, peer initialization, signals and
mode-set resets.
@mgonzalezlopezudc
ieee80211: report internal-collision exhaustion to rate control
b0da8c1 
HCF discarded packets at the internal-collision retry limit without reporting
a completed sample to Onoe. Notify rate control before recovery clears the
short and long counters so Onoe records the give-up and its full retry total.

Use a distinct terminal-drop hook with a no-op RateControlBase default to
preserve legacy AARF attempt feedback. Document internal-collision accounting
as an INET modeling choice and cover QoS data and management drops with pure
and mixed recovery histories.
@mgonzalezlopezudc
doc: define the Onoe multirate retry contract
9dcd62d 
Record the Onoe alignment plan and its multirate retry design so attempt
ownership, retry-limit precedence and PHY-rate verification requirements
are reviewable before implementation.
@mgonzalezlopezudc
ieee80211: pass packets to rate-control queries
dba8b5d 
Rate controllers that retain a retry plan need the packet identity when
selecting a mode, including repeated queries used to calculate protection
durations. Pass the borrowed packet through both DCF and HCF selectors.

RateControlBase forwards the new query to the receiver-address query so
existing AARF and Onoe controllers retain their selection behavior.
Direct IRateControl implementations must implement getRateForFrame; selector
subclasses must accept the leading Packet argument in their override.
@mgonzalezlopezudc
ieee80211: add Minstrel rate control for HT and VHT
dafe31b 
HT/VHT adaptation must compare expected delivery per airtime across MCS,
channel width, guard interval and spatial-stream groups. Use the Linux
v4.19 Minstrel-HT policy for per-peer Q12 EWMA estimates, throughput ranking,
probing and multirate retry plans.

Keep each packet's plan stable across duration queries and independent QoS
queues. Credit feedback to the transmitted mode and invalidate stale plans
when the mode set or negotiated HT capabilities change. Count additional
retry attempts only while total airtime stays strictly below the segment
budget, retaining the two-attempt minimum and configured retry cap.

Reuse the PHY catalog and HT peer eligibility. Individual normal-ACK
feedback is required; VHT width and stream limits remain configured because
VHT capabilities are not negotiated by this model.

Reference tests cover arithmetic and retry boundaries; eligibility tests
cover negotiated constraints and invalidation. HT/VHT exchange tests exercise
probes, fallbacks, delivery and adaptation through DCF and HCF.
@mgonzalezlopezudc
examples: demonstrate Minstrel HT and VHT rate adaptation
15c5984 
Provide associated HT and configured-capability VHT traffic examples so
users can select the controller and observe preferred and transmitted
rates. Dimensional radios represent spectral overlap during width changes.

Document the pinned Linux v4.19 rules, INET airtime adaptations, normal-ACK
feedback limits, extension API migration and focused validation commands.
The examples establish functional delivery rather than a statistical
throughput advantage.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@mgonzalezlopezudc