Skip to content

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

Open
mgonzalezlopezudc wants to merge 4 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 4 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 four-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.
    • Per-commit baseline updates (PR-SPLIT-BASELINE): The corrected wire bytes shift serialized data (~tND) fingerprints across 6 simulations in examples/ and showcases/. Per PR-SPLIT-BASELINE, all 6 updated expectations travel directly within this commit alongside independent golden-octet unit tests. Event (tplx) and length (~tNl) fingerprints remain strictly unchanged.
  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).
    • Per-commit baseline updates (PR-SPLIT-BASELINE): Outer QoS data headers encapsulating A-MSDUs now carry valid TA and BSSID fields rather than zero-filled addresses, altering the serialized bytes in examples/wireless/qos (MacQos, MacQosWithRtsCts, and MacQosWithBlockAck run 0) and showcases/wireless/qos (Qos run 0). Per PR-SPLIT-BASELINE, these 4 updated ~tND expectations travel directly within this commit. Event (tplx) and length (~tNl) fingerprints remain strictly identical, and non-aggregated QoS transmissions (MacQosWithoutAggregation) remain unchanged.

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, PR-SPLIT-BASELINE):

  1. ba81fd177b — 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 all 6 resulting serialized-data (~tND) baseline updates.
    • Component surface:
      • src/inet/linklayer/ieee80211/mac/Ieee80211Frame.msg
      • src/inet/linklayer/ieee80211/mac/Ieee80211MacHeaderSerializer.cc
      • tests/fingerprint/examples.csv
      • tests/fingerprint/showcases.csv
      • tests/unit/Ieee80211BlockAckActionWire_1.test
    • Direct tests & baseline effect: Ieee80211BlockAckActionWire_1.test PASS; carries the 6 serialized-data (~tND) baseline updates shifted by Block Ack action wire layout changes (MacQosWithBlockAck run 0, MacQos run 1, NoFragmentation, Fragmentation, MixedTraffic run 0, and HCFfragblockack run 0). Event and length fingerprints remain unchanged.

  2. f4e70386a3 — 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. 62f78e31eb — 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. 24e213e473 — 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. Carries independent unit tests and all 4 resulting serialized-data (~tND) baseline updates.
    • Component surface:
      • src/inet/linklayer/ieee80211/mac/aggregation/MsduAggregation.cc
      • src/inet/linklayer/ieee80211/mac/aggregation/MsduDeaggregation.cc
      • tests/fingerprint/examples.csv
      • tests/fingerprint/showcases.csv
      • tests/unit/Ieee80211MsduAggregation_1.test
    • Direct tests & baseline effect: Ieee80211MsduAggregation_1.test PASS; updates ~tND expectations for MacQos, MacQosWithRtsCts, and MacQosWithBlockAck run 0 in examples/wireless/qos, as well as Qos run 0 in showcases/wireless/qos. Event and length fingerprints remain unchanged.

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 and travel directly within the commit causing them per PR-SPLIT-BASELINE:

1. In Commit ba81fd177b (tests/fingerprint/examples.csv:R10,R661, tests/fingerprint/showcases.csv:R202-204,R270)

  • Block Ack action wire layout fixes:
    • examples/wireless/qos MacQosWithBlockAck run 0 (line 661):
      • Serialized data (~tND): 7147-4f5b -> ade8-e6a9.
      • Scope & Cause: ADDBA and DELBA action frames transmitted during Block Ack setup now use little-endian wire layouts and parameter sets.
      • Invariants: Event (tplx: d094-b008) and length (~tNl: 173a-e3fb) fingerprints remain identical.
    • examples/adhoc/qos MacQos run 1 (line 10):
      • Serialized data (~tND): 5aaf-cc7c -> a50d-9ad8.
      • Invariants: Event (tplx: 783f-d09a) and length (~tNl: 13d1-ec15) fingerprints remain identical.
    • showcases/wireless/blockack NoFragmentation run 0 (line 202):
      • Serialized data (~tND): 1470-1e1b -> 8b71-c964.
      • Invariants: Event (tplx: aa2d-5d35) and length (~tNl: 2094-1f2a) fingerprints remain identical.
    • showcases/wireless/blockack Fragmentation run 0 (line 203):
      • Serialized data (~tND): 9c41-dc97 -> 9b1c-22eb.
      • Invariants: Event (tplx: 7ae9-e07d) and length (~tNl: db8b-3b81) fingerprints remain identical.
    • showcases/wireless/blockack MixedTraffic run 0 (line 204):
      • Serialized data (~tND): 62c4-cbc2 -> 153d-3bdf.
      • Invariants: Event (tplx: 462d-10c7) and length (~tNl: 727b-d26a) fingerprints remain identical.
    • showcases/wireless/fragmentation HCFfragblockack run 0 (line 270):
      • Serialized data (~tND): 9a04-4420 -> f819-daf7.
      • Invariants: Event (tplx: 0702-c692) and length (~tNl: 1bf9-b035) fingerprints remain identical.

Reversing only the serializer correction recovers all six prior values; event and length fingerprints are unchanged.

2. In Commit 24e213e473 (tests/fingerprint/examples.csv:R658,R660,R661, tests/fingerprint/showcases.csv:R317)

  • A-MSDU transmitter/BSSID population and header length fixes:
    • examples/wireless/qos 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.
    • examples/wireless/qos 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.
    • examples/wireless/qos MacQosWithBlockAck run 0 (line 661):
      • Serialized data (~tND): ade8-e6a9 -> 6541-bd60.
      • Scope & Cause: Extends MacQos with Block Ack enabled. Demonstrates sequential evolution across the series: master (7147-4f5b) -> commit 1 ba81fd177b (ade8-e6a9, due to Block Ack action frame layout) -> commit 4 24e213e473 (6541-bd60, due to A-MSDU outer header address population). Both intermediate and final trees pass their tests independently (PR-SERIES-BUILDS).
      • Invariants: Event (tplx: d094-b008) and length (~tNl: 173a-e3fb) fingerprints are unchanged.
    • examples/wireless/qos MacQosWithoutAggregation run 0 (line 659) — Negative control:
      • Serialized data (~tND): Unchanged at 75d4-11f9. Confirms that non-aggregated QoS transmissions are unaffected.
    • showcases/wireless/qos Qos run 0 (line 317):
      • Serialized data (~tND): 10fc-7bb0 -> 1f84-a860.
      • Scope & Cause: A-MSDU frame headers carry populated TA and BSSID fields.
      • Invariants: Event (tplx: 1a49-72b3) and length (~tNl: e605-d79d) fingerprints are unchanged.

Reversing only this A-MSDU correction recovers the prior values; event and length fingerprints are 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: 4 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 14.842s).
      • 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
mgonzalezlopezudc force-pushed the fix-ieee80211-wire-and-amsdu branch from ac44838 to 33e402e Compare September 11, 2026 05:33
@mgonzalezlopezudc
ieee80211: correct Block Ack action wire encoding
ba81fd1 
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.

Also carry the five data-fingerprint expectations affected by this encoding
correction: blockack NoFragmentation, Fragmentation and MixedTraffic run 0,
fragmentation HCFfragblockack run 0, and adhoc qos MacQos run 1. Reversing
only the serializer correction recovers all five prior values; event and
length fingerprints are unchanged.
@mgonzalezlopezudc
ieee80211: correct HT MPDU delimiter wire encoding
f4e7038 
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
62f78e3 
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
24e213e 
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

Also carry wireless qos showcase Qos run 0's data fingerprint, changing
10fc-7bb0 to 1f84-a860 (~tND). Reversing only this A-MSDU correction recovers
the prior value; event and length fingerprints are unchanged.
@mgonzalezlopezudc
mgonzalezlopezudc force-pushed the fix-ieee80211-wire-and-amsdu branch from a5ffcd5 to 24e213e Compare September 11, 2026 09:31
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