wifi: Update documentation

CHANGES.html

@@ -59,6 +59,7 @@ us a note on ns-developers mailing list.</p>
 <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>
 <li>Added new <b>ThompsonSamplingWifiManager</b> rate control algorithm.</li>
 <li>Added new <b>PhasedArrayModel</b>, providing a flexible interface for modeling a number of Phase Antenna Array (PAA) models.</li>
+<li>Added a new <b>RrMultiUserScheduler</b>, providing a basic round robin scheduler for DL and UL OFDMA.</li>
 </ul>
 <h2>Changes to existing API:</h2>
 <ul>

RELEASE_NOTES

@@ -37,6 +37,7 @@ New user-visible features
 - (wifi) Stations keep track of the TXOP holder and ignore the NAV when they receive an RTS frame from the TXOP holder
 - (wifi) The TxOkHeader and TxErrHeader trace sources of RegularWifiMac have been obsoleted and replaced by trace sources that better capture the result of a transmission (AckedMpdu, NAckedMpdu, DroppedMpdu, MpduResponseTimeout and PsduResponseTimeout)
 - (wifi) Add ThompsonSamplingWifiManager rate control algorithm.
+- (wifi) Add support for 802.11ax DL and UL OFDMA
 - (traffic-control) Added FqCobalt queue disc with L4S features and set associative hash.
 - (traffic-control) Added FqPIE queue disc with L4S mode.
 - (antenna) Added PhasedArrayModel, providing a flexible interface for modeling a number of Phase Antenna Array (PAA) models

doc/models/Makefile

@@ -141,6 +141,14 @@ SOURCEFIGS = \
 	$(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/ack-su-format.pdf \
+	$(SRC)/wifi/doc/source/figures/ack-su-format.png \
+	$(SRC)/wifi/doc/source/figures/mu-bar.pdf \
+	$(SRC)/wifi/doc/source/figures/mu-bar.png \
+	$(SRC)/wifi/doc/source/figures/aggr-mu-bar.pdf \
+	$(SRC)/wifi/doc/source/figures/aggr-mu-bar.png \
+	$(SRC)/wifi/doc/source/figures/ul-ofdma.pdf \
+	$(SRC)/wifi/doc/source/figures/ul-ofdma.png \
 	$(SRC)/wifi/doc/source/figures/clear-channel.eps \
 	$(SRC)/wifi/doc/source/figures/nist-frame-success-rate.eps \
 	$(SRC)/wifi/doc/source/figures/nist-frame-success-rate-n.eps \

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

@@ -22,6 +22,7 @@ on the IEEE 802.11 standard [ieee80211]_. We will go into more detail below but
 * basic 802.11 DCF with **infrastructure** and **adhoc** modes
 * **802.11a**, **802.11b**, **802.11g**, **802.11n** (both 2.4 and 5 GHz bands), **802.11ac** and **802.11ax** (2.4, 5 and 6 GHz bands) physical layers
 * **MSDU aggregation** and **MPDU aggregation** extensions of 802.11n, and both can be combined together (two-level aggregation)
+* 802.11ax **DL OFDMA** and **UL OFDMA**
 * QoS-based EDCA and queueing extensions of **802.11e**
 * the ability to use different propagation loss models and propagation delay models,
   please see the chapter on :ref:`Propagation` for more detail
@@ -163,14 +164,13 @@ packets.  Interference from other wireless technologies is only modeled
 when the SpectrumWifiPhy is used.
 The following details pertain to the physical layer and channel models:
 
-* 802.11ax OFDMA is not supported (but some code changes are progressively being added)
+* 802.11ax MU-RTS/CTS and the MU EDCA Parameter set are not yet supported
 * 802.11ac/ax MU-MIMO is not supported, and no more than 4 antennas can be configured
 * 802.11n/ac/ax beamforming is not supported
 * 802.11n RIFS is not supported
 * 802.11 PCF/HCF/HCCA are not implemented
 * Authentication and encryption are missing
 * Processing delays are not modeled
-* The current implementation assumes that secondary channels are always higher than primary channels
 * Channel bonding implementation only supports the use of the configured channel width
   and does not perform CCA on secondary channels
 * Cases where RTS/CTS and ACK are transmitted using HT/VHT/HE formats are not supported
@@ -872,7 +872,95 @@ The features supported by every FrameExchangeManager class are as follows:
 * ``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
+* ``HeFrameExchangeManager`` adds support for the transmission and reception of
+  multi-user frames via DL OFDMA and UL OFDMA, as detailed below.
+
+.. _wifi-mu-ack-sequences:
+
+Multi-user transmissions
+########################
+
+Since the introduction of the IEEE 802.11ax amendment, multi-user (MU) transmissions are
+possible, both in downlink (DL) and uplink (UL), by using OFDMA and/or MU-MIMO. Currently,
+ns-3 only supports multi-user transmissions via OFDMA. Three acknowledgment sequences are
+implemented for DL OFDMA.
+
+The first acknowledgment sequence is made of multiple BlockAckRequest/BlockAck frames sent
+as single-user frames, as shown in Figure :ref:`fig-ack-su-format-80211ax`.
+
+.. _fig-ack-su-format-80211ax:
+
+.. figure:: figures/ack-su-format.*
+   :align: center
+
+   Acknowledgment of DL MU frames in single-user format
+
+For the second acknowledgment sequence, an MU-BAR Trigger Frame is sent (as a single-user
+frame) to solicit BlockAck responses sent in TB PPDUs, as shown in Figure :ref:`fig-mu-bar-80211ax`.
+
+.. _fig-mu-bar-80211ax:
+
+.. figure:: figures/mu-bar.*
+   :align: center
+
+   Acknowledgment of DL MU frames via MU-BAR Trigger Frame sent as single-user frame
+
+For the third acknowledgment sequence, an MU-BAR Trigger Frame is aggregated to every PSDU
+included in the DL MU PPDU and the BlockAck responses are sent in TB PPDUs, as shown in
+Figure :ref:`fig-aggr-mu-bar-80211ax`.
+
+.. _fig-aggr-mu-bar-80211ax:
+
+.. figure:: figures/aggr-mu-bar.*
+   :align: center
+
+   Acknowledgment of DL MU frames via aggregated MU-BAR Trigger Frames
+
+For UL OFDMA, both BSRP Trigger Frames and Basic Trigger Frames are supported, as shown in
+Figure :ref:`fig-ul-ofdma-80211ax`. A BSRP Trigger Frame is sent by an AP to solicit stations
+to send QoS Null frames containing Buffer Status Reports. A Basic Trigger Frame is sent by an AP
+to solicit stations to send data frames in TB PPDUs, which are acknowledged by the AP via a
+Multi-STA BlockAck frame.
+
+.. _fig-ul-ofdma-80211ax:
+
+.. figure:: figures/ul-ofdma.*
+   :align: center
+
+   Acknowledgment of DL MU frames via aggregated MU-BAR Trigger Frames
+
+Multi-User Scheduler
+####################
+
+A new component, named **MultiUserScheduler**, is in charge of determining what frame exchange
+sequence the aggregated AP has to perform when gaining a TXOP (DL OFDMA, UL OFDMA or BSRP Trigger
+Frame), along with the information needed to perform the selected frame exchange sequence (e.g.,
+the set of PSDUs to send in case of DL OFDMA). ``MultiUserScheduler`` is an abstract base class.
+Currently, the only available subclass is **RrMultiUserScheduler**. By default, no multi-user
+scheduler is aggregated to an AP (hence, OFDMA is not enabled).
+
+Round-robin Multi-User Scheduler
+################################
+The Round-robin Multi-User Scheduler dynamically assigns a priority to each station to ensure
+airtime fairness in the selection of stations for DL multi-user transmissions. The ``NStations``
+attribute enables to set the maximum number of stations that can be the recipients of a DL
+multi-user frame. Therefore, every time an HE AP accesses the channel to transmit a DL
+multi-user frame, the scheduler determines the number of stations the AP has frames to send
+to (capped at the value specified through the mentioned attribute) and attempts to allocate
+equal sized RUs to as many such stations as possible without leaving RUs of the same size
+unused. For instance, if the channel bandwidth is 40 MHz and the determined number of stations
+is 5, the first 4 stations (in order of priority) are allocated a 106-tone RU each (if 52-tone
+RUs were allocated, we would have three 52-tone RUs unused). If central 26-tone RUs can be
+allocated (as determined by the ``UseCentral26TonesRus`` attribute), possible stations that
+have not been allocated an RU are assigned one of such 26-tone RU. In the previous example,
+the fifth station would have been allocated one of the two available central 26-tone RUs.
+
+When UL OFDMA is enabled (via the ``EnableUlOfdma`` attribute), every DL OFDMA frame exchange
+is followed by an UL OFDMA frame exchange involving the same set of stations and the same RU
+allocation as the preceding DL multi-user frame. The transmission of a BSRP Trigger Frame can
+optionally (depending on the value of the ``EnableBsrp`` attribute) precede the transmission
+of a Basic Trigger Frame in order for the AP to collect information about the buffer status
+of the stations.
 
 Ack manager
 ###########
@@ -896,16 +984,20 @@ 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
+* ``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
+* ``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.
+* ``DlMuAckSequenceType``: used to select the acknowledgment sequence for DL MU frames
+  (acknowledgment in single-user format, acknowledgment via MU-BAR Trigger Frame sent as
+  single-user frame, or acknowledgment via MU-BAR Trigger Frames aggregated to the data
+  frames).
 
 Protection manager
 ##################

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

@@ -60,3 +60,7 @@ References
 .. [porat2016] \ R. Porat et al., "11ax Evaluation Methodology", IEE P802.11 Wireless LANs, 11-14-0571r3, 2016. 
 
 .. [krotov2020rate] \ A. Krotov, A. Kiryanov, E. Khorov., `Rate Control With Spatial Reuse for Wi-Fi 6 Dense Deployments <https://doi.org/10.1109/ACCESS.2020.3023552>`__, IEEE Access, September 2020
+
+.. [magrin2021mu] \ D. Magrin, S. Avallone, S. Roy, and M. Zorzi, 'Validation of the ns-3 802.11ax OFDMA implementation', in Proceedings of WNS3 2021.
+
+.. [avallone2021wcm] \ S. Avallone, P. Imputato, G. Redieteab, C. Ghosh and S. Roy, "Will OFDMA Improve the Performance of 802.11 WiFi Networks?", in IEEE Wireless Communications Magazine, DOI: 10.1109/MWC.001.2000332, to appear.

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

@@ -291,3 +291,12 @@ When run for 802.11g 6 Mbit/s in infrastucture mode, the output is:
    :align: center
 
    Bianchi throughput validation results for 802.11g 6 Mbps in infrastructure configuration
+
+Multi-user transmissions validation
+***********************************
+
+The implementation of the OFDMA support has been validated against a theoretical model [magrin2021mu]_ .
+
+A preliminary evaluation of the usage of OFDMA in 802.11ax, in terms of latency in non-saturated
+conditions, throughput in saturated conditions and transmission range with UL OFDMA, is provided
+in [avallone2021wcm]_ .

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

@@ -599,6 +599,22 @@ in an infrastructure network where the AP has SSID ``ns-3-ssid``::
                           "BE_MaxAmsduSize", UintegerValue (7935),
                           "ActiveProbing", BooleanValue (false));
 
+802.11ax APs support sending multi-user frames via DL OFDMA and UL OFDMA if a Multi-User Scheduler is
+aggregated to the wifi MAC (by default no scheduler is aggregated). WifiMacHelper enables to aggregate
+a Multi-User Scheduler to an AP and set its parameters::
+
+    WifiMacHelper wifiMacHelper;
+    wifiMacHelper.SetMultiUserScheduler ("ns3::RrMultiUserScheduler",
+                                        "EnableUlOfdma", BooleanValue (true),
+                                        "EnableBsrp", BooleanValue (false));
+
+The Ack Manager is in charge of selecting the acknowledgment method among the three
+available methods (see section :ref:`wifi-mu-ack-sequences` ). The default ack manager
+enables to select the acknowledgment method, e.g.::
+
+    Config::SetDefault ("ns3::WifiDefaultAckManager::DlMuAckSequenceType",
+                       EnumValue (WifiAcknowledgment::DL_MU_AGGREGATE_TF));
+
 Selection of the Access Category (AC)
 +++++++++++++++++++++++++++++++++++++