ieee80211: publish management rate contexts

WHATSNEW

@@ -6,6 +6,46 @@ INET-4.7.x (in development)
 
 Notable backward incompatible changes are the following:
 
+IEEE 802.11 management rate context
+
+   Custom rate-selection models can query local, BSS, peer, and target rate
+   facts through Ieee80211Mib. Target references preserve the intended BSS
+   through queues, fragmentation, and RTS creation. Unknown target facts
+   remain unknown instead of using facts from the active BSS.
+
+   Access points reject association requests that lack required basic rates.
+   Custom management implementations must publish rate facts at each state
+   transition. The migration guide describes the publication contract.
+
+   Full STA management now puts the selected BSSID in Address 3 of transmitted
+   management frames. The frame format stays the same, but its bytes change.
+   The ~tND fingerprints change in simulations that use these frames.
+
+IEEE 802.11 HCF complete exchange admission
+
+   HCF checks complete exchange airtime when isBlockAckSupported is false.
+   The check includes protection, responses, and each required SIFS interval.
+   Execution uses the exact frames and modes from that check.
+   A refused continuation retains its frames for later channel access.
+   An oversized initial exchange without a supported exception reports a model-limit error.
+   Automatic fragmentation to an airtime budget remains unsupported.
+
+   The duration guarantee assumes zero propagation delay and responses at nominal SIFS.
+   Actual response modes and lengths must match the local predictions.
+   Block Ack configurations retain their existing execution path.
+   TXOP duration statistics still report elapsed time.
+
+   HCF restores finite Block Ack inactivity deadlines after stop or crash.
+   Downtime counts toward the deadline. Restart retires overdue agreements before channel access resumes.
+   Late Block Ack activity cannot renew an overdue agreement.
+   Recipient retirement clears the reorder buffer, so replacement ADDBA uses its new sequence window.
+   Active agreement statistics decrease once for each retirement.
+   Timeout zero still disables inactivity expiry.
+
+   External sequence, step, handler, ACK, timeout-policy, and Tx implementations
+   require source changes and a rebuild. The migration guide describes the new contracts.
+   External Block Ack agreement handlers, callbacks, and recipient data services also require source changes.
+
 1. IEEE 802.11 rate control per receiver
 
    IEEE 802.11 rate control now selects and adapts the transmission rate

doc/src/migration-guide/index.rst

@@ -4,6 +4,135 @@ Migrating Code from INET 3.x
 ============================
 Release: |release|
 
+IEEE 802.11 Management Rate Context
+----------------------------------
+
+Management publishes local, BSS, peer, and target rate facts through ``Ieee80211Mib``.
+``Ieee80211RateSetState`` preserves unknown facts and known empty sets.
+``snapshotRateContext()`` returns an owned ``RateContextSnapshot`` with copied rates and identities.
+The query takes the peer, frame subtype, optional BSSID, and optional ``BssRateContextRef``.
+An unresolved or conflicting identity returns ``known == false``.
+An unknown target never falls back to the active BSS.
+
+``Ieee80211RateContextTag`` carries a sender-local reference through queues, copies, fragmentation, and RTS creation.
+The receiver discards this tag and resolves its own context.
+The tag contains no rate values and changes no wire format.
+``Ieee80211MgmtTransactionTag`` still identifies association response outcomes.
+
+Custom management implementations must publish facts at their actual commit points.
+Use ``Ieee80211Mib::RateUpdate`` around related management and MIB changes.
+Its outer scope emits ``rateStateChanged`` after the transition completes.
+Install a new target with generation zero and a transaction identifier that remains unique across restart.
+Bind its expected incoming subtype before the first frame enters the queue.
+Use the matching snapshot to obtain the MIB-assigned reference with its nonzero generation.
+Retain that exact reference for queued frames and target removal.
+Target removal also removes its incoming bindings.
+
+These records do not change rate-selection or TXOP policies.
+
+IEEE 802.11 Prepared Exchanges and Tx Requests
+---------------------------------------------
+
+HCF uses prepared exchanges when ``isBlockAckSupported`` is false.
+The existing sequence tree selects the frames, modes, ACK policy, and protection branch before transmission.
+``TxopProcedure`` checks the complete exchange cost.
+Each continuation includes its leading SIFS.
+The separate TXNAV check uses the reservation from this station's actual transmissions.
+
+The duration guarantee assumes zero propagation delay and responses after nominal SIFS.
+The actual response mode and complete frame length must match the prediction.
+HCF uses actual elapsed time for each continuation check.
+An oversized initial exchange without a supported exception raises a model-limit error before transmission.
+The model does not fragment a frame automatically to meet an airtime budget.
+``TxopProcedure::getDuration()`` keeps its elapsed-time meaning.
+
+External implementations require these changes:
+
+* Implement ``IFrameSequence::planSequence()`` and ``startPlannedSequence()``.
+  Return ``READY``, ``EMPTY``, or ``UNSUPPORTED`` as appropriate.
+  Duration refusal is a separate admission result.
+  Prepared execution must use the recorded choices without another selector call.
+* Implement ``ITransmitStep::getPreparedTransmit()`` and ``IReceiveStep::getPreparedReceive()``.
+  Return a null record for a legacy step.
+  Plans own prepared steps and generated controls.
+  The frame store retains ownership of staged data and management frames.
+* Add the prepared record argument to the handler's ``transmitFrame()`` callback.
+  Implement ``frameSequenceStarted()`` to report the start before any synchronous transmission or cancellation.
+  Implement ``setPendingTransmission()``, ``pendingTransmissionCanceled()``, and ``resetForLifecycle()`` in custom handlers.
+  Preserve borrowed objects until all synchronous callbacks return.
+  Implement ``beginCallback()`` and ``endCallback()`` to defer disposal across Tx callbacks too.
+* Implement ``IAckHandler::snapshotFrameState()`` and ``dropFrame()``.
+  The snapshot query must preserve the exact phase without insertion or protocol progress.
+  A staged frame without an ACK registration is an error.
+* Implement ``IOriginatorQoSAckPolicy::getAckTimeoutForMode()`` and ``IRtsPolicy::getCtsTimeoutForMode()``.
+  These methods use the supplied response mode and preserve configured timeout overrides.
+  They must not select another mode.
+* Replace unidentified Tx calls with ``transmitFrame(id, packet, header, ifs, callback)``.
+  The MAC allocates ``TxRequestId`` before the call.
+  The identity contains a lifecycle epoch and a serial.
+  Implement ``cancelPendingTransmission()``, ``resetForLifecycle()``, and ``hasTransmission()``.
+* Implement the Tx callbacks ``isTransmissionPermitted()``, ``transmissionStarted()``, and ``transmissionCanceled()``.
+  Implement ``beginCallback()`` and ``endCallback()`` to protect borrowed sequence objects throughout each callback scope.
+  Add the request identity to ``transmissionComplete()``.
+  The final permission check runs for zero IFS too.
+  Tx must check the identity again after a callback that can replace the request.
+
+Cancellation distinguishes ``CANCELED``, ``TOO_LATE``, and ``NOT_FOUND``.
+Only ``CANCELED`` removes the matching delayed copy.
+Explicit cancellation emits no completion callback.
+The caller reports successful explicit cancellation to the matching handler once.
+An on-air request keeps its normal completion path unless lifecycle cleanup aborts it.
+Ordinary radio commands wait until an accepted recipient response completes.
+``InProgressFrames`` calls its typed removal callback before it removes a referenced frame.
+HCF registers ``IInProgressFramesCallback`` through ``setRemovalCallback()``.
+Custom frame stores must preserve the ``frameWillBeRemoved()`` call before removal.
+Contexts retain frame references until their deferred disposal completes.
+``clearDroppedFrames()`` preserves originals while a context still borrows them.
+
+DCF uses the legacy path with null prepared metadata.
+HCF configurations with Block Ack support retain the existing path without the new duration guarantee.
+Rebuild all external implementations after these interface changes.
+
+IEEE 802.11 Block Ack Inactivity Deadlines
+----------------------------------------
+
+HCF retains Block Ack agreements across stop and crash.
+Downtime counts toward each absolute inactivity deadline.
+Restart retires overdue agreements before timeout DELBA or other traffic requests channel access.
+HCF restores the earliest deadline from the remaining agreements.
+An agreement with timeout zero has no inactivity deadline.
+Late Block Ack activity cannot renew an overdue agreement.
+HCF discards a data frame that reaches an overdue recipient agreement.
+
+Recipient retirement releases the corresponding reorder buffer.
+A replacement ADDBA therefore uses its own starting sequence number and buffer size.
+HCF emits one deletion notification for each retired agreement.
+Delayed timeout DELBA completion preserves a replacement agreement without another deletion notification.
+
+External implementations require these changes:
+
+* Implement ``getEarliestExpirationTime() const`` in both agreement handlers.
+  Return the earliest active absolute deadline, or ``SIMTIME_MAX`` if none exists.
+* Change ``blockAckAgreementExpired()`` to accept an agreement callback and return timeout DELBA chunks.
+  Remove all overdue entries before deletion callbacks.
+  HCF queues the chunks after both roles complete retirement.
+* Implement ``IBlockAckAgreementHandlerCallback::expireBlockAckAgreements()`` to coordinate both roles.
+  Implement ``originatorBlockAckAgreementDeleted()`` and ``recipientBlockAckAgreementDeleted()``.
+  The handler owns each borrowed agreement until the deletion callback returns.
+  The callback must not retain or modify the agreement.
+  Complete recipient buffer cleanup before the deletion notification.
+* Add the agreement callback argument to ``processReceivedDelba()`` and ``processTransmittedDelba()``.
+  Notify only when the handler removes an agreement.
+* Return false from ``qosFrameReceived()`` when the frame reaches an overdue agreement.
+  Request expiry before this return. The caller discards the frame.
+* Implement ``IRecipientQosMacDataService::clearReorderBuffer(originatorAddress, tid)``.
+  Release only that peer and TID's buffer, including its retained frames.
+  Other peers and TIDs keep their buffers.
+
+The timer callback uses ``IBlockAckAgreementHandlerCallback::scheduleInactivityTimer()`` without an argument.
+The callback reads both handlers and schedules their earliest absolute deadline.
+Rebuild external agreement handlers, callbacks, and recipient data services after these interface changes.
+
 IEEE 802.11 PHY Mode Properties
 -------------------------------