wifi: Add PHY callback for start of PSDU reception

CHANGES.html

@@ -74,6 +74,7 @@ allows to request an acknowledgment after a configurable number of MPDUs have be
 transmitted.</li>
 <li>The MaxSize attribute is removed from the QueueBase base class and moved to subclasses. A new MaxSize attribute is therefore added to the DropTailQueue class, while the MaxQueueSize attribute of the WifiMacQueue class is renamed as MaxSize for API consistency.</li>
 <li>The applications have now a "EnableE2EStats" attribute.</li>
+<li>Added a new trace source <b>PhyRxPayloadBegin</b> in WifiPhy for tracing begin of PSDU reception.</li>
 </ul>
 <h2>Changes to existing API:</h2>
 <ul>

src/wifi/doc/source/wifi-design.rst

@@ -339,7 +339,9 @@ packet to schedule this.  The second event to schedule is
 have been received and the payload is about to start.
 
 The next event at ``StartReceivePayload ()`` checks, using the interference
-helper and error model, whether the header was successfully decoded. 
+helper and error model, whether the header was successfully decoded, and if so,
+a ``PhyRxPayloadBegin`` callback (equivalent to the PHY-RXSTART primitive)
+is triggered.
 The PHY header is often transmitted
 at a lower modulation rate than is the payload.  The portion of the packet
 corresponding to the PHY header is evaluated for probability of error

src/wifi/model/wifi-phy.cc

@@ -353,6 +353,11 @@ WifiPhy::GetTypeId (void)
                      "by the device",
                      MakeTraceSourceAccessor (&WifiPhy::m_phyRxBeginTrace),
                      "ns3::Packet::TracedCallback")
+    .AddTraceSource ("PhyRxPayloadBegin",
+                     "Trace source indicating the reception of the "
+                     "payload of a PPDU has begun",
+                     MakeTraceSourceAccessor (&WifiPhy::m_phyRxPayloadBeginTrace),
+                     "ns3::WifiPhy::PhyRxPayloadBeginTracedCallback")
     .AddTraceSource ("PhyRxEnd",
                      "Trace source indicating a packet "
                      "has been completely received from the channel medium "
@@ -2894,7 +2899,8 @@ WifiPhy::StartReceivePayload (Ptr<Event> event)
         {
           m_state->SwitchToRx (payloadDuration);
           m_endRxEvent = Simulator::Schedule (payloadDuration, &WifiPhy::EndReceive, this, event);
-          NS_LOG_DEBUG ("Receiving payload");
+          NS_LOG_DEBUG ("Receiving PSDU");
+          m_phyRxPayloadBeginTrace (txVector, payloadDuration); //this callback (equivalent to PHY-RXSTART primitive) is triggered only if headers have been correctly decoded and that the mode within is supported
           if (txMode.GetModulationClass () == WIFI_MOD_CLASS_HE)
             {
               HePreambleParameters params;

src/wifi/model/wifi-phy.h

@@ -1312,6 +1312,14 @@ public:
    */
   typedef void (* EndOfHePreambleCallback)(HePreambleParameters params);
 
+  /**
+   * TracedCallback signature for start of PSDU reception events.
+   *
+   * \param txVector the TXVECTOR decoded from the PHY header
+   * \param psduDuration the duration of the PSDU
+   */
+  typedef void (* PhyRxPayloadBeginTracedCallback)(WifiTxVector txVector, Time psduDuration);
+
   /**
    * Assign a fixed random variable stream number to the random variables
    * used by this model. Return the number of streams (possibly zero) that
@@ -1865,6 +1873,22 @@ private:
    */
   TracedCallback<Ptr<const Packet> > m_phyRxBeginTrace;
 
+  /**
+   * The trace source fired when the reception of the PHY payload (PSDU) begins.
+   *
+   * This traced callback models the behavior of the PHY-RXSTART
+   * primitive which is launched upon correct decoding of
+   * the PHY header and support of modes within.
+   * We thus assume that it is sent just before starting
+   * the decoding of the payload, since it's there that
+   * support of the header's content is checked. In addition,
+   * it's also at that point that the correct decoding of
+   * HT-SIG, VHT-SIGs, and HE-SIGs are checked.
+   *
+   * \see class CallBackTraceSource
+   */
+  TracedCallback<WifiTxVector, Time> m_phyRxPayloadBeginTrace;
+
   /**
    * The trace source fired when a packet ends the reception process from
    * the medium.