doc: Update wifi documentation

CHANGES.html

@@ -56,10 +56,11 @@ us a note on ns-developers mailing list.</p>
 <ul>
 <li>Added <b>FqCobalt</b> queue disc with L4S features and set associative hash.</li>
 <li>Added <b>FqPIE</b> queue disc with <b>L4S</b> mode</li>
+<li>Added the ability to configure the primary 20 MHz channel for 802.11 devices operating on channels of width greater than 20 MHz.</li>
 </ul>
 <h2>Changes to existing API:</h2>
 <ul>
-<li></li>
+<li>The WifiAckPolicySelector class has been replaced by the WifiAckManager class. Correspondingly, the ConstantWifiAckPolicySelector has been replaced by the WifiDefaultAckManager class. A new WifiProtectionManager abstract base class and WifiDefaultProtectionManager concrete class have been added to implement different protection policies.</li>
 </ul>
 <h2>Changes to build system:</h2>
 <ul>
@@ -69,6 +70,7 @@ us a note on ns-developers mailing list.</p>
 <ul>
 <li>The default <b>TCP congestion control</b> has been changed from NewReno to CUBIC.</li>
 <li>The PHY layer of the wifi module has been refactored: the amendment-specific logic has been ported to <b>PhyEntity</b> classes and <b>WifiPpdu</b> classes.</li>
+<li>The MAC layer of the wifi module has been refactored. The MacLow class has been replaced by a hierarchy of FrameExchangeManager classes, each adding support for the frame exchange sequences introduced by a given amendment.</li>
 <li>The 802.11a-like PHY configuration known as <b>Holland</b> has been removed from the wifi module. It was added in the 2005 timeframe for Wi-Fi rate control research but hasn't been used for quite some time.</li>
 <li>Support for <b>Greenfield mode</b> (aka <b>HT_GF</b>) has been dropped from wifi.</li>
 <li>Some wifi/src/model files were moved to <b>non-ht</b>, <b>ht</b>, <b>vht</b>, <b>he</b>, and <b>rate-control</b> subfolders.</li>

RELEASE_NOTES

@@ -28,9 +28,13 @@ New user-visible features
 -------------------------
 - (sixlowpan) Added support for stateful (i.e., context-based) RFC6282 compression.
 - (wifi) The PHY layer has been refactored: the amendment-specific logic has been ported to PhyEntity classes and WifiPpdu classes
+- (wifi) The MAC layer has been refactored. The MacLow class has been replaced by a hierarchy of FrameExchangeManager classes, each adding support for the frame exchange sequences introduced by a given amendment.
 - (wifi) Holland PHY configuration has been removed from the model
 - (wifi) HT Greenfield (HT_GF) preamble support has been removed from the model
+- (wifi) Added the ability to configure the primary 20 MHz channel for 802.11 devices operating on channels of width greater than 20 MHz
 - (wifi) Some wifi/src/model files were moved to the relevant subfolders (non-ht, ht, vht, he, and rate-control)
+- (wifi) Stations perform TXOP recovery if the transmission of a non-initial MPDU in a TXOP fails
+- (wifi) Stations keep track of the TXOP holder and ignore the NAV when they receive an RTS frame from the TXOP holder
 - (traffic-control) Added FqCobalt queue disc with L4S features and set associative hash.
 - (traffic-control) Added FqPIE queue disc with L4S mode.
 

doc/models/Makefile

@@ -139,6 +139,7 @@ SOURCEFIGS = \
 	$(SRC)/wifi/doc/source/figures/WifiArchitecture.dia \
 	$(SRC)/wifi/doc/source/figures/PhyEntityHierarchy.dia \
 	$(SRC)/wifi/doc/source/figures/WifiPpduHierarchy.dia \
+	$(SRC)/wifi/doc/source/figures/FemHierarchy.dia \
 	$(SRC)/wifi/doc/source/figures/snir.dia \
 	$(SRC)/wifi/doc/source/figures/clear-channel.eps \
 	$(SRC)/wifi/doc/source/figures/nist-frame-success-rate.eps \
@@ -358,6 +359,7 @@ IMAGES_EPS = \
 	$(FIGURES)/WifiArchitecture.eps \
 	$(FIGURES)/PhyEntityHierarchy.eps \
 	$(FIGURES)/WifiPpduHierarchy.eps \
+	$(FIGURES)/FemHierarchy.eps \
 	$(FIGURES)/snir.eps \
 	$(FIGURES)/WimaxArchitecture.eps \
 	$(FIGURES)/epc-ctrl-arch.eps \

src/wifi/doc/Makefile

@@ -12,7 +12,8 @@ IMAGES_DIA = \
 	$(FIGURES)/snir.dia \
 	$(FIGURES)/WifiArchitecture.dia \
 	$(FIGURES)/PhyEntityHierarchy.dia \
-	$(FIGURES)/WifiPpduHierarchy.dia
+	$(FIGURES)/WifiPpduHierarchy.dia \
+	$(FIGURES)/FemHierarchy.dia
 
 # specify eps figures from which .png and .pdf figures need to be built
 
@@ -21,6 +22,7 @@ IMAGES_EPS = \
 	$(FIGURES)/WifiArchitecture.eps \
 	$(FIGURES)/PhyEntityHierarchy.eps \
 	$(FIGURES)/WifiPpduHierarchy.eps \
+	$(FIGURES)/FemHierarchy.eps \
         $(FIGURES)/clear-channel.eps \
         $(FIGURES)/nist-frame-success-rate.eps \
         $(FIGURES)/nist-frame-success-rate-n.eps \

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

@@ -51,9 +51,9 @@ The implementation is modular and provides roughly three sublayers of models:
 * the **PHY layer models**: they model amendment-specific and common
   PHY layer operations and functions.
 * the so-called **MAC low models**: they model functions such as medium
-  access (DCF and EDCA), RTS/CTS and ACK.  In |ns3|, the lower-level MAC
-  is further subdivided into a **MAC low** and **MAC middle** sublayering,
-  with channel access grouped into the **MAC middle**.   
+  access (DCF and EDCA), frame protection (RTS/CTS) and acknowledgment (ACK/BlockAck).
+  In |ns3|, the lower-level MAC is comprised of a **Frame Exchange Manager** hierarchy,
+  a **Channel Access Manager** and a **MAC middle** entity.
 * the so-called **MAC high models**: they implement non-time-critical processes
   in Wifi such as the MAC-level beacon generation, probing, and association 
   state machines, and a set of **Rate control algorithms**.  In the literature,
@@ -102,17 +102,16 @@ MAC low layer
 
 The **MAC low layer** is split into three main components:
 
-#. ``ns3::MacLow`` which takes care of RTS/CTS/DATA/ACK transactions and also
-   performs MPDU aggregation.
-#. ``ns3::ChannelAccessManager`` and ``ns3::DcfState`` which implements the DCF and EDCAF
+#. ``ns3::FrameExchangeManager`` a class hierarchy which implement the frame exchange
+   sequences introduced by the supported IEEE 802.11 amendments. It also handles
+   frame aggregation, frame retransmissions, protection and acknowledgment.
+#. ``ns3::ChannelAccessManager`` which implements the DCF and EDCAF
    functions.
-#. ``ns3::Txop`` and ``ns3::QosTxop`` which handle the packet queue,
-   packet fragmentation, and packet retransmissions if they are needed.
+#. ``ns3::Txop`` and ``ns3::QosTxop`` which handle the packet queue.
    The ``ns3::Txop`` object is used by high MACs that are not QoS-enabled,
    and for transmission of frames (e.g., of type Management)
    that the standard says should access the medium using the DCF. 
-   ``ns3::QosTxop`` is is used by QoS-enabled high MACs and also
-   performs MSDU aggregation.
+   ``ns3::QosTxop`` is used by QoS-enabled high MACs.
 
 PHY layer models
 ================
@@ -845,6 +844,84 @@ deal with:
 * MSDU aggregation,
 * etc.
 
+Frame Exchange Managers
+#######################
+As the IEEE 802.11 standard evolves, more and more features are added and it is
+more and more difficult to have a single component handling all of the allowed
+frame exchange sequences. A hierarchy of FrameExchangeManager classes has been
+introduced to make the code clean and scalable, while avoiding code duplication.
+Each FrameExchangeManager class handles the frame exchange sequences introduced
+by a given amendment. The FrameExchangeManager hierarchy is depicted in Figure
+:ref:`fem-hierarchy`.
+
+.. _fem-hierarchy:
+
+.. figure:: figures/FemHierarchy.*
+
+   *FrameExchangeManager hierarchy*
+
+The features supported by every FrameExchangeManager class are as follows:
+
+* ``FrameExchangeManager`` is the base class. It handles the basic sequences
+  for non-QoS stations: MPDU followed by Normal Ack, RTS/CTS and CTS-to-self,
+  NAV setting and resetting, MPDU fragmentation
+* ``QosFrameExchangeManager`` adds TXOP support: multiple protection setting,
+  TXOP truncation via CF-End, TXOP recovery, ignore NAV when responding to an
+  RTS sent by the TXOP holder
+* ``HtFrameExchangeManager`` adds support for Block Ack (compressed variant),
+  A-MSDU and A-MPDU aggregation, Implicit Block Ack Request policy
+* ``VhtFrameExchangeManager`` adds support for S-MPDUs
+* ``HeFrameExchangeManager`` is empty for now
+
+Ack manager
+###########
+
+Since the introduction of the IEEE 802.11e amendment, multiple acknowledgment policies
+are available, which are coded in the Ack Policy subfield in the QoS Control field of
+QoS Data frames (see Section 9.2.4.5.4 of the IEEE 802.11-2016 standard). For instance,
+an A-MPDU can be sent with the *Normal Ack or Implicit Block Ack Request* policy, in which
+case the receiver replies with a Normal Ack or a Block Ack depending on whether the A-MPDU
+contains a single MPDU or multiple MPDUs, or with the *Block Ack* policy, in which case
+the receiver waits to receive a Block Ack Request in the future to which it replies with
+a Block Ack.
+
+``WifiAckManager`` is the abstract base class introduced to provide an interface
+for multiple ack managers. Currently, the default ack manager is
+the ``WifiDefaultAckManager``.
+
+WifiDefaultAckManager
+#####################
+
+The ``WifiDefaultAckManager`` allows to determine which acknowledgment policy
+to use depending on the value of its attributes:
+
+* UseExplicitBar: used to determine the ack policy to use when a response is needed from
+  the recipient and the current transmission includes multiple frames (A-MPDU) or there are
+  frames transmitted previously for which an acknowledgment is needed. If this attribute is
+  true, the *Block Ack* policy is used. Otherwise, the *Implicit Block Ack Request* policy is used.
+* BaThreshold: used to determine when the originator of a Block Ack agreement needs to
+  request a response from the recipient. A value of zero means that a response is requested
+  at every frame transmission. Otherwise, a non-zero value (less than or equal to 1) means
+  that a response is requested upon transmission of a frame whose sequence number is distant
+  at least BaThreshold multiplied by the transmit window size from the starting sequence
+  number of the transmit window.
+
+Protection manager
+##################
+
+The protection manager is in charge of determining the protection mechanism to use,
+if any, when sending a frame.
+
+``WifiProtectionManager`` is the abstract base class introduced to provide an interface
+for multiple protection managers. Currently, the default protection manager is
+the ``WifiDefaultProtectionManager``.
+
+WifiDefaultProtectionManager
+############################
+
+The ``WifiDefaultProtectionManager`` selects a protection mechanism based on the
+information provided by the remote station manager.
+
 Rate control algorithms
 #######################
 
@@ -954,39 +1031,6 @@ MinstrelHtWifiManager
 
 This is the extension of minstrel for 802.11n/ac/ax.
 
-Ack policy selection
-####################
-
-Since the introduction of the IEEE 802.11e amendment, multiple acknowledgment policies
-are available, which are coded in the Ack Policy subfield in the QoS Control field of
-QoS Data frames (see Section 9.2.4.5.4 of the IEEE 802.11-2016 standard). For instance,
-an A-MPDU can be sent with the *Normal Ack or Implicit Block Ack Request* policy, in which
-case the receiver replies with a Normal Ack or a Block Ack depending on whether the A-MPDU
-contains a single MPDU or multiple MPDUs, or with the *Block Ack* policy, in which case
-the receiver waits to receive a Block Ack Request in the future to which it replies with
-a Block Ack.
-
-``WifiAckPolicySelector`` is the abstract base class introduced to provide an interface
-for multiple ack policy selectors. Currently, the default ack policy selector is
-the ``ConstantWifiAckPolicySelector``.
-
-ConstantWifiAckPolicySelector
-#############################
-
-The ``ConstantWifiAckPolicySelector`` allows to determine which acknowledgment policy
-to use depending on the value of its attributes:
-
-* UseExplicitBar: used to determine the ack policy to use when a response is needed from
-  the recipient and the current transmission includes multiple frames (A-MPDU) or there are
-  frames transmitted previously for which an acknowledgment is needed. If this attribute is
-  true, the *Block Ack* policy is used. Otherwise, the *Implicit Block Ack Request* policy is used.
-* BaThreshold: used to determine when the originator of a Block Ack agreement needs to
-  request a response from the recipient. A value of zero means that a response is requested
-  at every frame transmission. Otherwise, a non-zero value (less than or equal to 1) means
-  that a response is requested upon transmission of a frame whose sequence number is distant
-  at least BaThreshold multiplied by the transmit window size from the starting sequence
-  number of the transmit window.
-
 802.11ax OBSS PD spatial reuse
 ##############################