From 94812aad6ae0977bf7eb1d98f975e99b652acedf Mon Sep 17 00:00:00 2001
From: Stefano Avallone <stavallo@unina.it>
Date: Sat, 24 Aug 2024 16:40:24 +0200
Subject: [PATCH] wifi: Add a trace source to notify of block ack agreement
 established

---
 RELEASE_NOTES.md           |  1 +
 src/wifi/model/qos-txop.cc |  8 +++++++-
 src/wifi/model/qos-txop.h  | 14 ++++++++++++++
 3 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index 6d1517637..37e4730f1 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -40,6 +40,7 @@ The required Doxygen version for documentation generation is version 1.11.
 - (wifi) Each MSDU, A-MSDU or management MPDU now has its individual frame retry count and each Txop/QosTxop has its own SRC (Station Retry Count) to match the standard specifications.
 - (wifi) The `MaxSsrc` and `MaxSlrc` attributes of the `WifiRemoteStationManager` have been obsoleted and replaced by the `FrameRetryLimit` attribute of the `WifiMac`.
 - (wifi) Added the `IncrementRetryCountUnderBa` attribute to the  `WifiRemoteStationManager` to choose whether or not to increase the retry count of frames that are part of a block ack agreement; this attribute defaults to false to match the standard specifications.
+- (wifi) Added a new `BaEstablished` trace source to `QosTxop` to notify that a block ack agreement has been established with a given recipient for a given TID.
 
 ### Bugs fixed
 
diff --git a/src/wifi/model/qos-txop.cc b/src/wifi/model/qos-txop.cc
index ce77bc315..de46efe04 100644
--- a/src/wifi/model/qos-txop.cc
+++ b/src/wifi/model/qos-txop.cc
@@ -85,7 +85,12 @@ QosTxop::GetTypeId()
             .AddTraceSource("TxopTrace",
                             "Trace source for TXOP start and duration times",
                             MakeTraceSourceAccessor(&QosTxop::m_txopTrace),
-                            "ns3::QosTxop::TxopTracedCallback");
+                            "ns3::QosTxop::TxopTracedCallback")
+            .AddTraceSource("BaEstablished",
+                            "A block ack agreement is established with the given recipient for "
+                            "the given TID.",
+                            MakeTraceSourceAccessor(&QosTxop::m_baEstablishedCallback),
+                            "ns3::QosTxop::BaEstablishedCallback");
     return tid;
 }
 
@@ -653,6 +658,7 @@ QosTxop::GotAddBaResponse(const MgtAddBaResponseHeader& respHdr, Mac48Address re
     if (respHdr.GetStatusCode().IsSuccess())
     {
         NS_LOG_DEBUG("block ack agreement established with " << recipient << " tid " << +tid);
+        m_baEstablishedCallback(recipient, tid);
         // A (destination, TID) pair is "blocked" (i.e., no more packets are sent) when an
         // Add BA Request is sent to the destination. However, when the Add BA Request timer
         // expires, the (destination, TID) pair is "unblocked" and packets to the destination are
diff --git a/src/wifi/model/qos-txop.h b/src/wifi/model/qos-txop.h
index 4a0688d58..6b4cb5e8d 100644
--- a/src/wifi/model/qos-txop.h
+++ b/src/wifi/model/qos-txop.h
@@ -458,6 +458,20 @@ class QosTxop : public Txop
         TxopTracedCallback;
 
     TxopTracedCallback m_txopTrace; //!< TXOP trace callback
+
+    /**
+     * TracedCallback signature for block ack agreement established events.
+     *
+     * @param recipient the MAC address of the recipient
+     * @param tid the TID for which block ack agreement is established
+     */
+    typedef void (*BaEstablishedCallback)(Mac48Address recipient, uint8_t tid);
+
+    /// TracedCallback for block ack agreement established events typedef
+    using BaEstablishedTracedCallback = TracedCallback<Mac48Address, uint8_t>;
+
+    BaEstablishedTracedCallback
+        m_baEstablishedCallback; //!< traced callback for block ack agreement established events
 };
 
 } // namespace ns3