ieee80211: repair Basic Block Ack agreement lifecycle

[mgonzalezlopezudc]

Block Ack setup and teardown can leave the two stations with different agreement state. The parent dispatches duplicate Actions, accepts unchecked setup responses, and treats absolute inactivity deadlines as relative delays. Setup can also consume sequence numbers before the agreement exists. These defects can repeat agreement changes, retain obsolete work, or let DATA use the wrong agreement.

This PR completes S3b, the agreement lifecycle stage. HCF, the hybrid coordination function, coordinates accepted Actions, agreement owners, DATA eligibility, and safe cleanup. The recipient data service checks duplicates before HCF dispatches an Action. Agreement handlers validate setup and retire obsolete work before resource release. Setup and recovery defer DATA for the affected peer and traffic identifier (TID), while other eligible traffic can continue.

Basic remains the default and retains legacy ad hoc and non-HT compatibility. HCF still rejects Compressed selection during initialization. This PR supplies lifecycle behavior that later Compressed exchanges will need. The main integration risks affect custom module contracts, queue accounting, and exchanges that the radio accepts before retirement. The migration guide explains the required changes.

Setup preserves the first sequence number

ADDBA establishes an agreement through a request and response. An ACK for the request confirms reception; only a matched successful response activates the originator agreement. The response must match the peer, TID, and dialog token. The handlers also validate status, immediate policy, profile, and supported parameters.

HCF first resolves DATA that already has sequence numbers. It defers further extraction for the same peer and TID before it creates ADDBA. The data service supplies the next sequence number without consumption. After acceptance, the first extracted DATA therefore receives the request number.

sequenceDiagram
    participant Q as Originator DATA queue
    participant O as Originator HCF
    participant R as Recipient
    O->>O: Resolve already numbered DATA
    O->>Q: Defer new extraction for this peer and TID
    Q-->>O: Next unassigned sequence number N
    O->>R: ADDBA Request with N, TID, and token
    R-->>O: Immediate ACK
    Note over O: Start response timer, default 100 ms
    R->>R: Validate request and create accepted agreement
    R->>O: ADDBA Response with accepted parameters
    O->>O: Match identity and validate response
    O-->>R: Immediate ACK
    O->>Q: Permit eligible extraction
    Q-->>O: First DATA receives sequence number N
    O->>R: DATA under the accepted agreement

Loading

The recipient response supplies the buffer size and inactivity timeout for both agreement owners. The built-in Basic recipient selects the smaller of 64 and its configured maximum. Request size zero supplies no size guidance. Both negotiated A-MSDU flags must permit aggregation. These rules give both owners the same accepted parameters.

One DATA frame without a successor causes no empty setup request. After an eligible Normal Ack transmission, the handler can wait for a later successor without an Action or timer. HCF starts setup before it extracts that successor. Peer reset clears this state.

Retries apply each accepted Action once

A valid MAC retry still receives its immediate ACK. The recipient data service returns only complete, nonduplicate Actions for agreement dispatch. The dialog token identifies setup; it does not replace MAC duplicate checks.

flowchart TD
    RX["Addressed ADDBA or DELBA"] --> C["Recipient service checks<br/>complete-frame state and duplicates"]
    C -->|Duplicate| D["Retain immediate ACK behavior<br/>No agreement dispatch"]
    C -->|Accepted complete Action| H["HCF dispatches once<br/>to the agreement owner"]
    H --> W{"Does the Action resolve<br/>the active procedure?"}
    W -->|Yes| S["Apply the result before exchange cleanup<br/>Suppress obsolete failure feedback"]
    W -->|No| F["Keep ordinary failure feedback<br/>for the interrupted exchange"]

Loading

For example, the request ACK can be lost before a successful ADDBA Response arrives during the request's final ACK wait. The originator accepts that response before obsolete request failure can cause teardown or DATA disposal. The frame-sequence handler owns the interruption outcome after recipient processing. An unrelated Action retains the interrupted exchange's ordinary failure result. The diagram shows decisions, not ACK timing.

Uncertain setup requires teardown before DATA resumes

DELBA ends an agreement. After any possible request transmission, response loss does not prove that the recipient lacks an agreement. The response timeout therefore starts DELBA recovery. DATA lifetime continues to limit deferred DATA throughout setup and recovery.

flowchart TD
    P["Setup pending<br/>DATA deferred"] -->|Matched success| A["Active agreement<br/>Release eligible DATA"]
    P -->|Initial rejection or cancellation<br/>before an accepted request attempt| N["No agreement<br/>Normal Ack DATA can resume"]
    P -->|Attempted request fails<br/>or response deadline expires| T["DELBA pending<br/>DATA remains deferred"]
    T -->|DELBA receives ACK| N
    T -->|Originator DELBA fails<br/>or suffers queue disposal| R["Discard current deferred batch<br/>Retain recovery state"]
    R -->|New DATA arrives| T

Loading

This INET profile treats the DELBA ACK as teardown confirmation. Failed originator DELBA discards the current deferred batch. Later DATA starts one fresh recovery exchange; no periodic retry timer runs. Failed recipient-role DELBA clears its procedure without disposal of opposite-direction DATA. Valid Block Ack-policy DATA or BAR without an agreement triggers recipient-role DELBA. That DATA receives no upper delivery, and that BAR creates no receive state.

HCF schedules the earliest absolute inactivity deadline across both agreement roles. A zero negotiated inactivity value disables expiration. The response timer starts after the request ACK, with a positive, finite configurable default of 100 ms. These timers have different purposes and remain separate.

Teardown preserves the correct DATA boundary

Directional teardown removes only the selected local role. The originator discards transmitted, unacknowledged DATA for that agreement. It also discards unsent fragments through the highest transmitted allocation index. The QoS data service assigns this local index before fragmentation; all fragments retain it in Ieee80211DataSequenceTag. The agreement retains the highest transmitted index after ACK processing removes an earlier fragment. Older retransmissions cannot move this boundary backward, and wire sequence numbers remain unchanged.

The fragment regression supplies a concrete example. DATA with sequence 0 transmits. The fixture allocates intervening DATA through the production data service and deletes that DATA without transmission. Fragment 0 of sequence 2048 then transmits. Allocation indices advance the boundary correctly despite the sequence gap; teardown removes unsent siblings and preserves later intact DATA.

This case tests an allocation gap; it does not test lifetime expiry of the intervening DATA. The fixture also checks sequence wraparound and teardown after fragment 0 receives its Normal Ack. These cases retain unrelated-peer DATA.

flowchart TD
    E["Agreement retirement"] --> O["Ordinary originator teardown"]
    O --> OD["Discard transmitted, unacknowledged DATA<br/>and unsent fragments through the transmitted boundary"]
    O --> OK["Preserve later intact DATA<br/>and the opposite agreement role"]
    E --> R["Ordinary recipient teardown"]
    R --> RD["Deliver complete buffered units in cyclic order<br/>Discard incomplete units"]
    E --> A["Association reset"]
    A --> AD["Clear both roles and old peer work<br/>Discard old receive buffers"]

Loading

The recipient delivers complete buffered units across gaps before resource release. For example, complete units 101 and 102 reach the upper process despite absent unit 100. This release across a gap is INET policy. Association reset instead discards old buffered units. With Block Ack enabled, reset also discards old-peer queued and in-progress QoS DATA, including unsent Normal Ack DATA without an agreement.

Management supplies the old peer identity before association replacement, even when the new capabilities equal the old capabilities. HCF detaches both roles before deletion callbacks. Another peer retains its agreements, DATA, and lifetime records. The MIB retains its boolean notification and coherent committed state.

First-DATA disposal needs a separate guard. If an internal collision discards the negotiated first DATA before transmission, HCF retires the agreement and queues DELBA. The successor remains deferred. Lifetime expiry and RTS failure use the same retirement mechanism.

Deferral preserves access for eligible traffic

A nonempty queue does not prove that its DATA can contend. HCF uses a pure eligibility query for contention and extraction. Deferred work cannot charge valid traffic in another access category an internal collision.

flowchart LR
    subgraph Q["Configured queue service order"]
        A["Peer A, TID 2<br/>Setup pending: deferred"]
        B["Peer B, TID 5<br/>Eligible"]
        C["Peer A, TID 2<br/>Deferred"]
        A --- B --- C
    end
    B --> X["Queue owner extracts B<br/>with ordinary pull effects"]
    A -.-> W["Keep queued DATA<br/>and its original lifetime"]
    C -.-> W

Loading

An optional queue contract permits extraction past deferred DATA. Each queue layer applies its ordinary ownership transfer, residence metadata, events, and accounting once. An eligible advertised head needs no optional capability. If a required bypass lacks support, the service refuses it before ownership or sequence state changes.

Physical completion does not authorize retired work

Logical retirement cannot delete a context that the radio still uses. An accepted exchange retains its physical completion context and records physical statistics. Its later callbacks cannot submit retired work after CTS. The frame-sequence handler destroys the context before deferred frame copies.

sequenceDiagram
    participant H as HCF
    participant T as Radio and transmitter
    participant M as Management
    H->>T: Submit RTS for DATA A
    T-->>H: Accept transmission
    M->>H: Reset old peer
    H->>H: Retire DATA A and detach agreements
    Note over H,T: Keep the accepted exchange context
    T-->>H: CTS arrives for the accepted exchange
    H->>H: Refuse retired DATA A after CTS
    H->>H: Complete physical accounting and release context

Loading

Commits and integration surface

The comparison starts at master commit 675655fc3559231c56b12d651384cb8695255abc and ends at 0c234006883d25a5d47458bdf68abfc29d85f96d. These four commits form the exact S3b prefix of #1363. Corrective collision and fragment retirement changes reside in their lifecycle owner.

1. 435fc0866d adds selected extraction with ordinary queue effects; it prepares the lifecycle consumer.
2. 2c6b1df761 connects Action delivery, setup, retirement, reset, and deferred DATA selection.
3. 832dc3672c gives the frame-sequence handler ownership of interruption outcomes.
4. 0c23400688 records S3b completion and its verification scope.

The lifecycle conversion changes its contracts, handlers, and HCF together. Its first retirement path needs Action invalidation and safe exchange completion. A partial caller conversion would leave unsafe frame references or eligible obsolete Actions.

The integration surface includes agreement handlers, recipient services, management reset, frame-sequence interruption, and optional queue selection. The migration guide describes each changed contract. In particular, custom frame-sequence handlers implement interruptFrameSequence(). Agreement callbacks implement scheduleInactivityTimer() without an argument. Originator code calls recordTransmittedData(allocationIndex) to preserve the teardown boundary after ACK processing. This replaces markFirstDataTransmitted() and the former cyclic-sequence overload.

Custom QoS data services must supply Ieee80211DataSequenceTag before fragmentation. The agreement exposes its highest transmitted allocation index through getHighestTransmittedDataIndex(), which replaces getHighestTransmittedSequence().

The configuration adds addbaFailureTimeout to the originator agreement policy. The PR adds Ieee80211DataSequenceTag.msg for local metadata; it changes no wire format, serializer, or feature descriptor. Changed source paths are unsealed. No new architecture or naming exception forms part of this PR.

The scope excludes Compressed exchanges, final-transfer arbitration, MAC stop/start recovery, delayed policy, Multi-TID, and A-MPDU support. Basic remains historical INET compatibility. Its reserved type value does not establish current-standard support. S4 and later Compressed stages are outside this PR.

The completed S3b summary explains component ownership. The execution record separates final verification from earlier results. Completion records the branch state; it does not assert a merge into master.

Verification and limits

Fresh debug and release builds pass at 0c234006883d25a5d47458bdf68abfc29d85f96d with all 12 available CPUs. The debug campaign covers every changed test fixture in the master comparison. All selected fixtures report their expected successful result.

Check	Result
Debug and release compilation	Both PASS.
Module fixtures	14 PASS.
Functional fingerprint cases	7 PASS, with unchanged expectations.
Series and description gates	All five PASS.
Source seals and scoped MAC architecture	PASS.
Global architecture, naming, and interface gates	The same inherited findings remain. These gates retain exit code 1.

The global comparison checks the finding text. Counts of unchanged interfaces and examined declarations can differ between stages. These counts do not introduce new findings.

Executed commands and selectors

The build commands run from this PR's checkout root:

make MODE=debug -j12
make MODE=release -j12
opp_repl --load /home/user/omnetpp-6.4.0aipre2/.venv/lib/python3.14/site-packages/opp_repl/opp/inet.opp -p inet

The opp_repl adapter selects this checkout's inet_project. It calls the checked-out test functions with these exact arguments. It rejects empty selections and unexpected results.

run_module_tests(simulation_project=inet_project, mode="debug", filter=r"(?:Ieee80211BlockAckActionDelivery_1\.test|Ieee80211BlockAckActionDispatch_1\.test|Ieee80211BlockAckActionDisposal_1\.test|Ieee80211BlockAckAdmission_1\.test|Ieee80211BlockAckAssociationReset_1\.test|Ieee80211BlockAckDataSelection_1\.test|Ieee80211BlockAckDeferral_1\.test|Ieee80211BlockAckDeferredCollision_1\.test|Ieee80211BlockAckFragmentRetirement_1\.test|Ieee80211BlockAckLifecycle_1\.test|Ieee80211BlockAckNegotiation_1\.test|Ieee80211BlockAckResponseWait_1\.test|Ieee80211BlockAckRetiredData_1\.test|PacketSelectiveExtraction_1\.test)$", concurrent=False)

The fingerprint command runs from tests/fingerprint:

./fingerprinttest -d -F tyf -t 3 -m 'showcases/wireless/blockack/|showcases/wireless/fragmentation/.*-c HCFfragblockack |showcases/wireless/txop/|examples/adhoc/qos/.*-c MacQos -r 1|examples/wireless/qos/.*-c MacQosWithBlockAck ' showcases.csv examples.csv

The mechanical checks use the pinned master base 675655fc3559231c56b12d651384cb8695255abc. They cover the complete series and description, source seals, scoped MAC architecture, and the three global gates. This campaign changes no recorded expectation.

Seven previously approved functional fingerprint rows remain with the lifecycle change in 2c6b1df761. Numbered DATA resolves before setup, and setup waits for a later successor instead of an empty request. The collision and fragment repairs introduce no further baseline change. This synchronization changes no baseline value.

All four commits retain their scoped debug results from the #1363 reconstruction. The final tree exactly equals the former PR head, 39fd321b0d3c0f4d93ae5cfd16c72c8a7df74907. Fresh checks below cover the synchronized head.

Release behavioral tests, graphical tyf fingerprints, sanitizers, and other platforms remain unverified. This synchronization supplies no new independent correctness audit. Local test results do not establish CI results.