IEEE 802.11: fix Block Ack ADDBA transaction and agreement lifecycle

WHATSNEW

@@ -64,6 +64,166 @@ Notable backward incompatible changes are the following:
    counted arrivals or summed bytes reported twice the true value and now reports
    the true one.
 
+4. Packet queue extraction and lifecycle signals
+
+   IPacketQueue now supports queue-lifecycle signals and predicate-based extraction.
+   Direct C++ implementations of IPacketQueue must implement findPacket(), the
+   predicate overload of dequeuePacket(), and must emit packetQueueDeparture
+   with PacketQueueRemovalDetails exactly once whenever a packet is dequeued,
+   explicitly removed, or destructively dropped. Listeners subscribe to the queue
+   module and filter the source to exclude descendant queue emissions. Providers
+   connected to CompoundPacketQueueBase must also implement IPacketExtractor so
+   that a compound queue preserves the provider's scheduling policy when it
+   extracts a matching packet. Direct C++
+   implementations of IPacketExtractor must replace selected-pointer extraction
+   with findPacket(predicate) and dequeuePacket(predicate); predicates may be
+   evaluated repeatedly and must be stable and side-effect free throughout one
+   logical selection. WrrScheduler, LabelScheduler, and PriorityScheduler accept
+   ordinary IPassivePacketSource inputs; they require IPacketCollection only when
+   collection/aggregate access is used and IPacketExtractor only when predicate
+   extraction is used, reporting the unsupported operation lazily.
+   PriorityScheduler aggregate queries no longer return -1 when an input lacks
+   IPacketCollection; getNumPackets() and getTotalLength() now report that
+   unsupported operation with cRuntimeError. Update callers that treated -1 as
+   an unknown aggregate size, or connect collection-capable providers.
+   A-MSDU policies now receive the provider-selected anchor and frame-eligibility
+   predicate. Additional policy-selected members are removed through exact
+   predicate dequeues, preserving scheduler/flow accounting without requiring
+   collection enumeration order to match scheduling order.
+   BasicMsduAggregationPolicy conservatively considers only collection members
+   after the anchor and never bypasses an earlier blocked same-flow member.
+   IPacketBuffer::ICallback requires explicit handlePacketDropping() and
+   handlePacketDropped() implementations. The first detaches the packet; the
+   second publishes its departure after all victims of the overload operation
+   have been detached. Custom buffer owners must implement both phases. Compound
+   queues propagate destructive drops through arbitrary non-queue wrappers and
+   nested compound queues exactly once. PacketBuffer rejects packets owned by a
+   cPacketQueue whose owner cannot participate in the buffer callback contract.
+
+5. Block Ack DELBA agreement ownership
+
+   Custom IBlockAckAgreementHandlerCallback implementations must explicitly
+   implement releaseBlockAckAgreementFrames() and cancelBlockAckTeardown().
+   Custom IFrameSequenceHandler implementations must implement both
+   cancelFrameSequence() and abortFrameSequence(), preserving their deferred
+   and immediate cancellation contracts. Custom originator and recipient
+   agreement handlers must implement isDelbaPending(); recipient handlers must
+   also implement processAcknowledgedDelba(), processAbortedDelba() and
+   getPendingTeardownGenerationId(). These methods no longer supply default
+   behavior in the interfaces. The built-in implementations already provide
+   these operations.
+
+   IOriginatorBlockAckAgreementHandler::processReceivedDelba(),
+   IOriginatorBlockAckAgreementHandler::processTransmittedDelba(), and
+   IRecipientBlockAckAgreementHandler::processReceivedDelba() now return the
+   terminated agreement as a unique_ptr. Originator ADDBA response processing
+   now returns a typed outcome containing the established agreement and, when
+   local policy vetoes a successful response, its immediately terminated local
+   agreement and a best-effort initiator DELBA for Hcf to enqueue after emitting
+   the Added and Deleted signals. Such locally generated DELBAs carry
+   sender-local agreement-generation metadata (the originator reuses its ADDBA
+   transaction identity), and ordinary data continues with Normal Ack. They remain
+   eligible through the
+   final fragment; aborting one fragment cancels its siblings. After retry backoff,
+   a replacement ADDBA setup invalidates an older queued DELBA, so an unreported
+   disposal cannot suppress setup indefinitely and a delayed frame cannot
+   terminate a newer peer/TID agreement. The replacement setup reports that
+   obsolete identity so Hcf also removes all of its queued or in-progress packets.
+   Originator and recipient DELBA transmission handlers now receive the full
+   Packet so sender-local agreement-generation metadata is retained through
+   fragmentation and MAC retries. This changes
+   IRecipientBlockAckAgreementHandler::processTransmittedDelba() from accepting
+   only a DELBA header to accepting Packet*; custom handler implementations and
+   callers must migrate to the Packet form. A locally tagged DELBA carrying
+   agreement-generation metadata remains eligible across MAC retries and is
+   retired only when its final fragment is acknowledged or the teardown is
+   terminally aborted. Custom handler
+   implementations and callers must adopt processAcknowledgedDelba() and the
+   boolean processAbortedDelba() outcome; processTransmittedDelba() still returns
+   the agreement removed by an untagged DELBA, or null when none was removed.
+
+   OriginatorBlockAckAgreementPolicy now exposes the new `addbaResponseTimeout`
+   and `addbaRetryBackoff` NED parameters. C++ implementations of
+   IOriginatorBlockAckAgreementPolicy must replace computeAddbaFailureTimeout()
+   with getAddbaResponseTimeout() and implement computeAddbaRetryBackoff().
+
+6. Originator ADDBA Transactions and Eligible Frames
+
+   ADDBA response deadlines now begin at actual request transmission. Frames for a
+   pending peer/TID wait for a matching successful response or terminal failure, then
+   channel access resumes for eligible traffic. This changes affected Block Ack
+   trajectories. A-MSDU service now appears as dequeued traffic in queue counters and
+   graphical fingerprints, instead of administrative removal.
+
+7. Fragment Reassembly and Receive Lifetime
+
+   Fragmented management actions are dispatched only after their complete body is
+   reassembled. Shared fragment reassembly now expires incomplete bodies after
+   maxReceiveLifetime, whose default is 512 TUs. Late fragments can therefore be dropped
+   instead of completing an old body; affected application deliveries, forwarding
+   trajectories and fingerprints change.
+
+8. Block Ack Inactivity Timer Callbacks
+
+   Block Ack inactivity uses absolute per-agreement deadlines. The shared timer follows
+   the earliest enabled deadline and is cancelled when none remains. Agreement expiry is
+   safe when a bounded management queue drops a generated DELBA synchronously. Timers
+   and traffic may differ from runs that kept extending an inactivity interval.
+
+9. Fragment Identity Across Sequence Reuse
+
+   Receive reassembly separates fragment generations and sequence spaces. Late
+   fragments, retries and reused sequence numbers no longer combine bodies from
+   unrelated transmissions; affected receive drops and deliveries may change.
+
+10. Receive Lifetime in Block Ack Reordering
+
+   Receive lifetime now remains anchored to first reception while fragments wait in
+   Block Ack reordering. A later stage no longer gives an old incomplete body a fresh
+   lifetime, so delayed or incomplete bodies may be dropped earlier.
+
+11. Expired Agreement Quarantine and Frame Release
+
+   Expired Block Ack agreements are quarantined from data-plane use while teardown state
+   is retained. Outstanding frames are released through the normal
+   acknowledgment/recovery paths before teardown proceeds, including when callbacks
+   replace agreement state.
+
+12. Incomplete Data Released by a Block Ack Request
+
+   When a BAR releases data fragments that do not reassemble into a packet, recipient
+   processing skips data dispatch instead of dereferencing a null result.
+
+13. Recipient Block Ack Timeout Policy
+
+   Recipient Block Ack timeout selection now honors a nonzero local policy value; zero
+   inherits the request's advisory value. This corrects the previously reversed choice
+   and can change agreement expiry and subsequent traffic.
+
+14. A-MSDU Size and Fragmentation Limits
+
+   Basic A-MSDUs now include subframe headers and padding in size checks and avoid the
+   ordinary fragmentation path. Eligible members retain flow order. Aggregation,
+   transmissions and delivered traffic may change in configurations that previously
+   built oversized or fragmentable A-MSDUs.
+
+15. Serialized Management Fragment Bodies
+
+   Management fragmentation now slices the serialized body instead of repeating a
+   complete management header in each fragment. Reassembly preserves the original body
+   bytes and local transaction context.
+
+16. Malformed Peer Association IDs
+
+   Malformed peer association IDs now mark the decoded management header incorrect
+   instead of terminating the simulation during deserialization.
+
+17. Negotiated A-MSDU Support
+
+   An originator now retains the successful ADDBA response's A-MSDU support bit for the
+   agreement. Subsequent aggregation follows the negotiated response instead of the
+   request's initial capability.
+
 Notable backward compatible changes are the following:
 
 1. IEEE 802.11 per-station rate statistics

doc/src/migration-guide/index.rst

@@ -4,6 +4,162 @@ Migrating Code from INET 3.x
 ============================
 Release: |release|
 
+Packet Queue Extraction and Departure Callbacks
+-----------------------------------------------
+
+Direct implementations of ``IPacketQueue`` must implement ``findPacket(predicate)`` and
+``dequeuePacket(predicate)``. Compound-queue providers must implement
+``IPacketExtractor`` for predicate selection. Select through the provider's scheduling
+policy; do not use collection index order as a replacement. Predicates may be evaluated
+repeatedly and must remain stable and free of side effects during selection.
+
+Emit ``packetQueueDeparture`` once at each logical queue boundary while the borrowed
+packet is alive. Supply ``PacketQueueRemovalDetails`` with ``DEQUEUED=0``, ``REMOVED=1``
+or ``DROPPED=2``. A prequeue filter rejection is a drop even when the leaf queue never
+owned the packet. Listeners on a compound queue must filter child-queue emissions to
+avoid handling an outcome twice.
+
+Buffer owners implementing ``IPacketBuffer::ICallback`` must explicitly implement both
+``handlePacketDropping()`` and ``handlePacketDropped()``. Detach a victim during the
+first phase; publish its departure during the second phase, after every victim in the
+overflow batch has been detached. Do not read a borrowed packet after the publisher
+deletes it.
+
+``PriorityScheduler`` aggregate queries now throw when an input lacks
+``IPacketCollection``. Replace callers that interpret ``-1`` as an unknown aggregate
+size, or provide collection-capable inputs. Predicate extraction similarly requires an
+extraction-capable provider only when that operation is used.
+
+Originator ADDBA Transactions and Eligible Frames
+-------------------------------------------------
+
+Custom ``IOriginatorBlockAckAgreementPolicy`` implementations must replace
+``computeAddbaFailureTimeout()`` with ``getAddbaResponseTimeout()`` and implement
+``computeAddbaRetryBackoff()``. Configure ``addbaResponseTimeout`` and
+``addbaRetryBackoff`` on the originator agreement policy. The response interval begins
+when the request is actually transmitted, so rejecting an unsent request must not arm
+it.
+
+Custom originator data services must implement ``setFrameEligibilityFunction()``,
+``isFrameEligible()`` and ``hasEligibleFrame()``. Keep availability queries free of
+dequeue side effects. A-MSDU policies now receive the provider-selected anchor and
+eligibility predicate; retain that anchor first and select only available, unique,
+eligible members in valid flow order. Dequeue those members through the provider,
+including scheduler accounting. Successful A-MSDU service therefore increments queue
+dequeue counters instead of administrative-removal counters.
+
+Custom originator agreement handlers must explicitly implement ``isDelbaPending()``.
+Adapt ADDBA response callers to the typed outcome and DELBA callers to ownership
+transfer through ``unique_ptr`` where declared by the interface. Do not keep an
+agreement pointer across a callback that may replace or remove it.
+
+Custom ADDBA request producers must assign a nonzero Dialog Token and preserve the local
+transaction tag through retries and fragments. Recipient responses must echo the request
+token. An originator accepts only a matching live response; a response using the old
+default token zero no longer completes a transaction.
+
+Recipient ADDBA Lifecycle
+-------------------------
+
+Update custom recipient handlers and callers to the current
+``processReceivedAddbaRequest()`` callback arguments and returned agreement. An accepted
+request establishes or replaces recipient state when the response is formed. Reset the
+receive/reordering state for a replacement agreement. Replaying a cached duplicate
+response must not establish the agreement again or reset its receive window. Use the
+returned ownership-bearing teardown result when publishing a deleted-agreement
+notification.
+
+Fragment Reassembly and Receive Lifetime
+----------------------------------------
+
+``RecipientMacDataService`` and ``RecipientQosMacDataService`` now expose
+``maxReceiveLifetime``, defaulting to ``524288us`` (512 TUs). Incomplete bodies are
+discarded when that receive lifetime expires. Models that relied on arbitrarily late
+completion will deliver fewer packets; select a deliberate lifetime for the study rather
+than treating the previous unbounded retention as a guarantee.
+
+Custom recipient services returning ``ManagementFrameReceptionResult`` must supply
+``completeHeader`` only when a complete management body is available. A duplicate
+fragment can be acknowledged without dispatching ADDBA or DELBA. Preserve local action
+context across fragmented transmission, reconstruct the complete action body, and
+dispatch its subtype only after reassembly. Fragmented on-air management headers do not
+carry a complete action body in every fragment.
+
+Management Frame Sequence Cancellation
+--------------------------------------
+
+Custom ``IFrameSequenceHandler`` implementations must explicitly implement
+``cancelFrameSequence()`` and ``abortFrameSequence()``. Preserve the distinction between
+requesting deferred cancellation and immediately aborting a sequence. Coordinate packet
+ownership with the caller: cancellation must not delete a packet still borrowed by an
+in-flight transmission or active sequence. Superseded AP management transactions must
+retire their queued siblings and terminal outcome exactly once.
+
+Generation-Aware Block Ack Teardown
+-----------------------------------
+
+Custom agreement callbacks must implement ``cancelBlockAckTeardown()``. Match the role,
+peer, TID and generation so cancellation cannot affect a replacement agreement. Preserve
+``Ieee80211BlockAckAgreementTag::generationId`` on locally generated DELBA fragments and
+retries; the role, peer and TID come from DELBA and its processing context.
+
+Recipient agreement handlers must explicitly implement ``isDelbaPending()``,
+``processAcknowledgedDelba()``, ``processAbortedDelba()`` and
+``getPendingTeardownGenerationId()``. Update ``processTransmittedDelba()``
+implementations and callers to the full ``Packet *`` form where required, so local
+generation metadata remains available. Keep teardown pending until its final fragment is
+acknowledged or the exchange terminates; do not retire a replacement generation from a
+stale completion.
+
+Block Ack Inactivity Timer Callbacks
+------------------------------------
+
+Schedule the shared Block Ack inactivity timer for the earliest enabled absolute
+agreement deadline and cancel it when no enabled deadline remains. Expiry callbacks can
+synchronously remove or replace the current agreement or a sibling. Keep
+peer/TID/generation values as the work list and relookup the live state before using it
+after a callback; incrementing a map iterator before calling out does not protect a
+removed sibling.
+
+Receive Lifetime in Block Ack Reordering
+----------------------------------------
+
+Custom receive/reordering implementations must retain the first-reception time of a
+fragmented body while it waits in a Block Ack reorder buffer. Moving fragments between
+receive stages must not restart their lifetime. Expire incomplete state and reject late
+fragments before delivering a reassembled body. ``IReassembly::purge()`` now returns
+owned packets; callers must report their final drop and delete them. Use
+``BlockAckReordering::processReceivedQoSFrameWithResult()`` to handle released frames
+and tombstoned fragments. Negative ``maxReceiveLifetime`` values are rejected; zero is a
+valid immediate-expiry setting.
+
+Expired Agreement Quarantine and Frame Release
+----------------------------------------------
+
+Custom ``IBlockAckAgreementHandlerCallback`` implementations must explicitly implement
+``releaseBlockAckAgreementFrames()`` and report whether they changed outstanding state.
+Retained teardown state is not an active data-plane agreement; use the active-agreement
+query for data transmission, acknowledgment and receive admission. Frame release may
+synchronously remove or replace an agreement, so relookup the original generation before
+generating its DELBA. If an implementation has no outstanding frames, returning false
+must be an explicit implementation decision.
+
+Recipient Block Ack Timeout Policy
+----------------------------------
+
+A nonzero recipient ``blockAckTimeoutValue`` policy overrides the advisory timeout in
+the ADDBA request. The model's zero-policy convention inherits the request timeout.
+Check configurations that previously depended on the reversed selection; the negotiated
+inactivity deadline may change.
+
+A-MSDU Size and Fragmentation Limits
+------------------------------------
+
+Basic A-MSDU selection must fit the configured limit including subframe headers and
+padding. It must not rely on ordinary MPDU fragmentation to split an oversized A-MSDU.
+Check aggregation and fragmentation thresholds together when reproducing a study that
+previously selected such aggregates.
+
 IEEE 802.11 Beacon and Probe Response Fields
 ------------------------------------------
 

doc/src/users-guide/ch-diffserv.rst

@@ -282,9 +282,11 @@ interface is ready to transmit one. They have several input gates and
 one output gate.
 
 Modules that are connected to the inputs of a scheduler must implement
-the :cpp:`IPacketQueue` C++ interface. Schedulers also implement the
-:cpp:`IPacketQueue` interface, so they can be cascaded to other
-schedulers and used as the output module of :ned:`IPacketQueue`'s.
+the :cpp:`IPassivePacketSource` C++ interface. Collection and predicate
+extraction operations additionally require the corresponding input provider
+to implement :cpp:`IPacketCollection` and :cpp:`IPacketExtractor`, respectively.
+Schedulers can be cascaded and used as the output module of compound packet
+queues when those additional interfaces are available.
 
 There are several possible scheduling disciplines (first come/first
 served, priority, weighted fair, weighted round-robin, deadline-based,