Skip to content

ieee80211: correct Block Ack and aggregation frame representations - #1188

Open
mgonzalezlopezudc wants to merge 5 commits into
inet-framework:masterfrom
mgonzalezlopezudc:fix-ieee80211-wire-and-amsdu
Open

ieee80211: correct Block Ack and aggregation frame representations#1188
mgonzalezlopezudc wants to merge 5 commits into
inet-framework:masterfrom
mgonzalezlopezudc:fix-ieee80211-wire-and-amsdu

Conversation

@mgonzalezlopezudc

@mgonzalezlopezudc mgonzalezlopezudc commented Sep 11, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

IEEE 802.11 Block Ack Action Wire Formatting, Delimiter CRC, Management Timestamps & A-MSDU Address Fixes

Topic and Rationale

This pull request corrects multiple standards-compliance defects in IEEE 802.11 frame wire serialization, aggregation, and management timestamp processing across a five-commit series:

  1. Block Ack Action wire byte encoding & parameter sets (IEEE Std 802.11-2024 §§ 9.2.2, 9.4.1.13–16, 9.6.4.2–4):
    ADDBA and DELBA parameter sets used MSB-first bit packing and big-endian numeric fields in Ieee80211MacHeaderSerializer.cc, causing symmetric round-trips to conceal incorrect on-wire byte layouts. This fix aligns bit and byte fields with little-endian wire layouts, ensures a zero fragment number in ADDBA requests, preserves common Action fields when decoding DELBA frames, and adjusts Ieee80211Delba chunk length to exclude the FCS (LENGTH_DELBA - B(4)), which is carried separately by Ieee80211MacTrailer.
  2. HT MPDU delimiter representation & CRC validation (IEEE Std 802.11-2024 §§ 9.7.1, 9.7.2):
    HT MPDU delimiters previously placed the MPDU length in the wrong bit positions and lost high bits during decoding. Length is now correctly packed in bits B4–B15 of the 16-bit delimiter prefix, with out-of-range lengths ($< 0$ or $> 4095$) rejected. In addition, the 8-bit CRC is computed and validated using generator polynomial $x^8 + x^2 + x + 1$ with complemented remainder, and corrupted delimiters or invalid signatures (!= 0x4E) are marked incorrect (markIncorrect()).
  3. Management timestamp (TSF) processing (IEEE Std 802.11-2024 §§ 9.4.1.10, 11.1.3.1):
    Beacon and Probe Response deserialization passed raw wire bytes into SimTime::setRaw(), which converts from simulation-resolution ticks and could overflow SimTime range on large counter values. Because the model does not retain the TSF timestamp, the 8 wire octets are consumed directly without constructing an unused SimTime.
  4. A-MSDU Transmitter Address (TA), BSSID, and header lengths (IEEE Std 802.11-2024 §§ 9.3.2.1–2):
    Basic A-MSDU aggregate frame construction omitted the Transmitter Address (TA) and left BSSID fields zero, preventing recipients from correctly deriving the ACK target address. This fix populates TA and BSSID per Table 9-60 (using transmitting AP address for AP-to-AP) and accounts for the optional 6-byte Address4 field in both aggregation and deaggregation header length accounting (26-byte vs 32-byte QoS data header).
    • Baseline impact across QoS configurations: In examples/wireless/qos/omnetpp.ini, MacQos enables MSDU aggregation (BasicMsduAggregationPolicy). Because MacQosWithRtsCts and MacQosWithBlockAck inherit from MacQos, all three configurations transmit aggregated QoS data frames whose serialized headers now carry the populated transmitter and BSSID addresses rather than all zeros. Consequently, the serialized-data (~tND) fingerprints of all three configurations move, while event (tplx) and length (~tNl) fingerprints remain identical. The negative-control configuration MacQosWithoutAggregation explicitly disables aggregation (msduAggregationPolicy.typename = "") and is unaffected.
  5. Coverage of missing data fingerprints across showcases and adhoc QoS (tests/fingerprint/):
    Records the six data fingerprints (~tND) shifted by the Block Ack action encoding (commit 2dab9fc11f) and A-MSDU header population (commit 33e402e68e) across tests/fingerprint/examples.csv and tests/fingerprint/showcases.csv. Reversing each fix in isolation confirms exact recovery of previous fingerprints. All event (tplx) and length (~tNl) hashes remain strictly identical.

Reading Order

This series is ordered with prerequisites first so each commit compiles and passes all applicable tests independently (PR-SERIES-BUILDS, PR-SERIES-ORDER):

  1. 2dab9fc11f — ieee80211: correct Block Ack action wire encoding

    • Single decision & rationale: Corrects ADDBA and DELBA wire byte encoding to little-endian numerical fields and bit packing, retains DELBA action fields on decode, sets zero fragment number in ADDBA requests, and excludes FCS from DELBA declared chunk length. Carries independent golden-octet unit tests and the resulting MacQosWithBlockAck run 0 serialized-data baseline update.
    • Component surface:
      • src/inet/linklayer/ieee80211/mac/Ieee80211Frame.msg
      • src/inet/linklayer/ieee80211/mac/Ieee80211MacHeaderSerializer.cc
      • tests/fingerprint/examples.csv
      • tests/unit/Ieee80211BlockAckActionWire_1.test
    • Direct tests & baseline effect: Ieee80211BlockAckActionWire_1.test PASS; MacQosWithBlockAck run 0 ~tND updated (7147-4f5b -> ade8-e6a9).

  2. fe1f8dca4a — ieee80211: correct HT MPDU delimiter wire encoding

    • Single decision & rationale: Encodes 12-bit HT MPDU delimiter length in B4–B15, rejects invalid lengths, computes 8-bit CRC-8 with complemented remainder, verifies delimiter signature (0x4E), and marks corrupted delimiters incorrect.
    • Component surface:
      • src/inet/linklayer/ieee80211/mac/Ieee80211MacHeaderSerializer.cc
      • tests/unit/Ieee80211MpduDelimiterWire_1.test
    • Direct tests & baseline effect: Ieee80211MpduDelimiterWire_1.test PASS; no baseline change.

  3. 1601c2b2c4 — ieee80211: consume management timestamps as unsigned values

    • Single decision & rationale: Consumes the 8-byte TSF counter in Beacon and Probe Response frames as an unsigned 64-bit wire counter without constructing an unused SimTime, avoiding simulation-resolution integer overflow on large counter values.
    • Component surface:
      • src/inet/linklayer/ieee80211/mgmt/Ieee80211MgmtFrameSerializer.cc
      • tests/unit/Ieee80211MgmtFrameSerializer_1.test
    • Direct tests & baseline effect: Ieee80211MgmtFrameSerializer_1.test PASS; no baseline change.

  4. 33e402e68e — ieee80211: preserve A-MSDU header addresses and lengths

    • Single decision & rationale: Populates TA and Basic A-MSDU BSSID per IEEE Std 802.11-2024 Table 9-60 to preserve recipient ACK targeting; accounts for Address4 in QoS data header length (26 vs 32 bytes) during aggregation and deaggregation.
    • Component surface:
      • src/inet/linklayer/ieee80211/mac/aggregation/MsduAggregation.cc
      • src/inet/linklayer/ieee80211/mac/aggregation/MsduDeaggregation.cc
      • tests/fingerprint/examples.csv
      • tests/unit/Ieee80211MsduAggregation_1.test
    • Direct tests & baseline effect: Ieee80211MsduAggregation_1.test PASS; examples/wireless/qos run 0 ~tND expectations updated for all three configurations using A-MSDU (MacQos: 540d-c0a4 -> 9839-8fb0, MacQosWithRtsCts: 8fe3-d7a6 -> 4757-c17b, MacQosWithBlockAck: ade8-e6a9 -> 6541-bd60). Event and length fingerprints remain unchanged.

  5. a5ffcd51ae — tests: record missing fingerprints for IEEE 802.11 wire fixes

    • Single decision & rationale: Records missing serialized data (~tND) expectations across showcase and ad-hoc wireless examples shifted by earlier wire fixes in commits 2dab9fc11f and 33e402e68e.
    • Component surface:
      • tests/fingerprint/examples.csv
      • tests/fingerprint/showcases.csv
    • Direct tests & baseline effect: Updates 6 ~tND expectations across 5 simulation suites: examples/adhoc/qos (MacQos run 1), showcases/wireless/blockack (NoFragmentation, Fragmentation, MixedTraffic run 0), showcases/wireless/fragmentation (HCFfragblockack run 0), and showcases/wireless/qos (Qos run 0). All event (tplx) and length (~tNl) hashes remain identical.

Architectural Surface

  • Modules touched:
    • src/inet/linklayer/ieee80211/mac/Ieee80211MacHeaderSerializer.cc
    • src/inet/linklayer/ieee80211/mac/aggregation/MsduAggregation.cc
    • src/inet/linklayer/ieee80211/mac/aggregation/MsduDeaggregation.cc
    • src/inet/linklayer/ieee80211/mgmt/Ieee80211MgmtFrameSerializer.cc
    • src/inet/linklayer/ieee80211/mac/Ieee80211Frame.msg
  • Contracts and protocols: IEEE 802.11 MAC header serializers (Ieee80211MacHeaderSerializer, Ieee80211MpduSubframeHeaderSerializer, Ieee80211MgmtFrameSerializer), MSDU aggregation/deaggregation (MsduAggregation, MsduDeaggregation).
  • Packet representation:
    • Ieee80211Delba chunk length adjusted to LENGTH_DELBA - B(4) (FCS is represented separately by Ieee80211MacTrailer).
    • Corrected wire serialization and deserialization for Ieee80211AddbaRequest, Ieee80211AddbaResponse, Ieee80211Delba, and Ieee80211MpduSubframeHeader.
    • Outer QoS data headers accurately reflect actual wire length including Address4 when both ToDS and FromDS are set (26-byte vs 32-byte chunk lengths).
  • Configuration surface: None.
  • Feature descriptors: None.
  • Seals and audit exceptions: All modified source files under src/inet/ are unsealed (doc/project/enforcement/check-source-seals.sh PASS). No architectural deviations (AV-*) or naming deviations (NV-*) introduced.

Baselines

The baseline movements are documented per TR-BASELINE-PROVENANCE / PR-REQ-STORY:

1. In Commit 2dab9fc11f (tests/fingerprint/examples.csv:R661)

  • MacQosWithBlockAck run 0 (line 661):
    • Serialized data (~tND): 7147-4f5b -> ade8-e6a9.
    • Cause: Wire byte layout and parameter set endianness fixes for ADDBA and DELBA action frames.
    • Invariants: Event (tplx: d094-b008) and length (~tNl: 173a-e3fb) fingerprints remain identical.

2. In Commit 33e402e68e (tests/fingerprint/examples.csv:R658-661)

  • MacQos run 0 (line 658):
    • Serialized data (~tND): 540d-c0a4 -> 9839-8fb0.
    • Scope & Cause: MacQos configures BasicMsduAggregationPolicy. Outer QoS data frame headers encapsulating A-MSDUs now carry the transmitter address (TA) and BSSID rather than zero-filled addresses, altering the serialized bytes in the data stream.
    • Invariants: Event (tplx: 31b0-6212) and length (~tNl: 82ec-9fde) fingerprints are unchanged.
  • MacQosWithRtsCts run 0 (line 660):
    • Serialized data (~tND): 8fe3-d7a6 -> 4757-c17b.
    • Scope & Cause: Extends MacQos with rtsThreshold = 100B. A-MSDU frames transmitted under RTS/CTS now carry valid TA and BSSID header fields.
    • Invariants: Event (tplx: 9ece-fbfb) and length (~tNl: c1af-29ff) fingerprints are unchanged.
  • MacQosWithBlockAck run 0 (line 661):
    • Serialized data (~tND): ade8-e6a9 -> 6541-bd60.
    • Scope & Cause: Extends MacQos with Block Ack enabled. A-MSDU frames transmitted under Block Ack agreements now carry valid TA and BSSID header fields.
    • Invariants: Event (tplx: d094-b008) and length (~tNl: 173a-e3fb) fingerprints are unchanged.
  • Negative control — MacQosWithoutAggregation run 0 (line 659):
    • Serialized data (~tND): Unchanged at 75d4-11f9. Confirms that non-aggregated QoS transmissions are unaffected.

3. In Commit a5ffcd51ae (tests/fingerprint/examples.csv:R10, tests/fingerprint/showcases.csv:R202-204,R270,R317)

  • Block Ack action wire layout fixes (provenance: 2dab9fc11f):
    • examples/adhoc/qos MacQos run 1 (line 10): ~tND 5aaf-cc7c -> a50d-9ad8 (tplx: 783f-d09a, ~tNl: 13d1-ec15 unchanged).
    • showcases/wireless/blockack NoFragmentation run 0 (line 202): ~tND 1470-1e1b -> 8b71-c964 (tplx: aa2d-5d35, ~tNl: 2094-1f2a unchanged).
    • showcases/wireless/blockack Fragmentation run 0 (line 203): ~tND 9c41-dc97 -> 9b1c-22eb (tplx: 7ae9-e07d, ~tNl: db8b-3b81 unchanged).
    • showcases/wireless/blockack MixedTraffic run 0 (line 204): ~tND 62c4-cbc2 -> 153d-3bdf (tplx: 462d-10c7, ~tNl: 727b-d26a unchanged).
    • showcases/wireless/fragmentation HCFfragblockack run 0 (line 270): ~tND 9a04-4420 -> f819-daf7 (tplx: 0702-c692, ~tNl: 1bf9-b035 unchanged).
  • A-MSDU transmitter/BSSID population fixes (provenance: 33e402e68e):
    • showcases/wireless/qos Qos run 0 (line 317): ~tND 10fc-7bb0 -> 1f84-a860 (tplx: 1a49-72b3, ~tNl: e605-d79d unchanged).

Verification Evidence

  1. Compilation:
    • make -j$(nproc) MODE=debug: PASS (libINET_dbg.so).
    • make -j$(nproc) MODE=release: PASS (libINET.so).
  2. Mechanical gates:
    • doc/project/enforcement/check-source-seals.sh --base upstream/master: PASS (all touched files unsealed).
    • doc/project/enforcement/check-architecture.sh src/inet/linklayer/ieee80211: PASS (clean architecture).
    • doc/project/enforcement/check-naming.sh --base upstream/master: PASS for changed declarations in branch (0 naming candidates in changed files).
    • doc/project/enforcement/check-commits.sh upstream/master..HEAD: 5 linear commits on upstream/master.
  3. Direct unit tests:
    • inet_run_unit_tests -m debug -f 'Ieee80211(BlockAckActionWire|MgmtFrameSerializer|MpduDelimiterWire|MsduAggregation|OnWireBitCompliance).*': PASS (5 passed in 2.755s).
      • Ieee80211BlockAckActionWire_1.test: PASS
      • Ieee80211MpduDelimiterWire_1.test: PASS
      • Ieee80211MgmtFrameSerializer_1.test: PASS
      • Ieee80211MsduAggregation_1.test: PASS
      • Ieee80211OnWireBitCompliance_1.test: PASS
  4. Focused fingerprint regression tests (tests/fingerprint/examples.csv & tests/fingerprint/showcases.csv):
    • tests/fingerprint/fingerprinttest -d -F tyf tests/fingerprint/examples.csv -m '^/examples/wireless/qos/.*-c MacQos ': PASS (9839-8fb0/~tND).
    • tests/fingerprint/fingerprinttest -d -F tyf tests/fingerprint/examples.csv -m '^/examples/wireless/qos/.*-c MacQosWithRtsCts ': PASS (4757-c17b/~tND).
    • tests/fingerprint/fingerprinttest -d -F tyf tests/fingerprint/examples.csv -m '^/examples/wireless/qos/.*-c MacQosWithBlockAck ': PASS (6541-bd60/~tND).
    • tests/fingerprint/fingerprinttest -d -F tyf tests/fingerprint/examples.csv -m '^/examples/wireless/qos/.*-c MacQosWithoutAggregation ': PASS (75d4-11f9/~tND, unchanged control).
    • tests/fingerprint/fingerprinttest -d -F tyf tests/fingerprint/examples.csv -m '^/examples/adhoc/qos/.*-c MacQos -r 1': PASS (a50d-9ad8/~tND).
    • tests/fingerprint/fingerprinttest -d -F tyf tests/fingerprint/showcases.csv -m '^/showcases/wireless/blockack/.*': PASS (NoFragmentation: 8b71-c964/~tND, Fragmentation: 9b1c-22eb/~tND, MixedTraffic: 153d-3bdf/~tND).
    • tests/fingerprint/fingerprinttest -d -F tyf tests/fingerprint/showcases.csv -m '^/showcases/wireless/fragmentation/.*-c HCFfragblockack': PASS (f819-daf7/~tND).
    • tests/fingerprint/fingerprinttest -d -F tyf tests/fingerprint/showcases.csv -m '^/showcases/wireless/qos/.*-c Qos': PASS (1f84-a860/~tND).

@mgonzalezlopezudc
ieee80211: correct Block Ack action wire encoding
2dab9fc 
ADDBA and DELBA parameter sets used MSB-first bit packing and big-endian
numeric fields, so symmetric round trips concealed incorrect wire bytes.
Use the little-endian layouts in IEEE Std 802.11-2024 9.4.1.13-16 and
9.6.4.2-4, including the zero fragment number in ADDBA requests.

Retain DELBA's common Action fields when decoding and exclude the FCS,
which is carried separately, from its declared header length. Independent
golden-octet tests cover both directions and parameter boundaries.

The corrected Action bytes change MacQosWithBlockAck run 0's serialized
data fingerprint from 7147-4f5b to ade8-e6a9 (~tND). Event and length
fingerprints remain unchanged; carry that expectation with this fix.
@mgonzalezlopezudc
ieee80211: correct HT MPDU delimiter wire encoding
fe1f8dc 
HT delimiters placed the MPDU length in the wrong bit positions and lost
its high bits during decoding. Encode all 12 length bits in B4-B15 as
specified by IEEE Std 802.11-2024 9.7.1, and reject lengths that cannot be
represented in that field.

The delimiter previously carried a zero CRC and accepted any CRC or
signature. Compute the CRC defined by 9.7.2 and mark corrupt delimiters
incorrect. Independent golden bytes exercise boundary lengths and each
corrupt delimiter octet, avoiding symmetric round-trip false positives.
@mgonzalezlopezudc
ieee80211: consume management timestamps as unsigned values
1601c2b 
Beacon and Probe Response decoding fed the TSF field into a SimTime raw
tick value even though the model does not retain that timestamp. TSF is
an unsigned microsecond counter under IEEE Std 802.11-2024 9.4.1.10 and
11.1.3.1, not a simulation-resolution tick count.

Consume the eight wire octets without constructing an unused SimTime.
Exercise both management frames with ordinary and full-range uint64 TSF
bytes, checking that the following fields remain intact.
@mgonzalezlopezudc
ieee80211: preserve A-MSDU header addresses and lengths
33e402e 
A-MSDU construction omitted the transmitter address used for the ACK
recipient and left the outer BSSID fields zero. Populate the common TA
and the Basic A-MSDU BSSID fields according to IEEE Std 802.11-2024
9.3.2.1.2, Table 9-60. The modeled AP-to-AP case uses the transmitting
AP address for the BSSID.

Account for Address4 in aggregation and deaggregation header lengths.
Exercise all four DS combinations with independent outer-address bytes,
ACK-target checks, header serialization and payload/address restoration.

Corrected serialized headers change the following examples/wireless/qos
run 0 ~tND expectations; event and length fingerprints remain unchanged:
  MacQos: 540d-c0a4 -> 9839-8fb0
  MacQosWithRtsCts: 8fe3-d7a6 -> 4757-c17b
  MacQosWithBlockAck: ade8-e6a9 -> 6541-bd60
@mgonzalezlopezudc
mgonzalezlopezudc force-pushed the fix-ieee80211-wire-and-amsdu branch from ac44838 to 33e402e Compare September 11, 2026 05:33
@mgonzalezlopezudc
tests: record missing fingerprints for IEEE 802.11 wire fixes
a5ffcd5 
Six data fingerprints still expected bytes from before two IEEE 802.11
corrections, causing CI failures despite unchanged event and length hashes.

The Block Ack action encoding fix in 2dab9fc changes ADDBA and DELBA
parameter packing and byte order. It accounts for blockack showcase
NoFragmentation, Fragmentation and MixedTraffic run 0, fragmentation
HCFfragblockack run 0, and adhoc qos MacQos run 1.

The A-MSDU header fix in 33e402e preserves transmitter and BSSID
addresses. It accounts for wireless qos showcase Qos run 0.

Reversing each correction in isolation recovers the corresponding old
fingerprints. The Block Ack golden-octet and A-MSDU aggregation unit tests
pass with the corrected source. Record only the six approved ~tND values;
all other CSV fields remain unchanged.

Validation: all six affected fingerprint cases pass in debug mode with
tplx, ~tNl and ~tND. git diff --check passes.
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