rr-multi-user-scheduler.cc

Go to the documentation of this file.

/*
 * Copyright (c) 2020 Universita' degli Studi di Napoli Federico II
 *
 * SPDX-License-Identifier: GPL-2.0-only
 *
 * Author: Stefano Avallone <stavallo@unina.it>
 */
 
#include "rr-multi-user-scheduler.h"
 
#include "he-configuration.h"
#include "he-phy.h"
 
#include "ns3/eht-frame-exchange-manager.h"
#include "ns3/log.h"
#include "ns3/wifi-acknowledgment.h"
#include "ns3/wifi-mac-queue.h"
#include "ns3/wifi-protection.h"
#include "ns3/wifi-psdu.h"
 
#include <algorithm>
#include <numeric>
 
namespace ns3
{
 
NS_LOG_COMPONENT_DEFINE("RrMultiUserScheduler");
 
NS_OBJECT_ENSURE_REGISTERED(RrMultiUserScheduler);
 
TypeId
RrMultiUserScheduler::GetTypeId()
{
    static TypeId tid =
        TypeId("ns3::RrMultiUserScheduler")
            .SetParent<MultiUserScheduler>()
            .SetGroupName("Wifi")
            .AddConstructor<RrMultiUserScheduler>()
            .AddAttribute("NStations",
                          "The maximum number of stations that can be granted an RU in a DL MU "
                          "OFDMA transmission",
                          UintegerValue(4),
                          MakeUintegerAccessor(&RrMultiUserScheduler::m_nStations),
                          MakeUintegerChecker<uint8_t>(1, 74))
            .AddAttribute("EnableTxopSharing",
                          "If enabled, allow A-MPDUs of different TIDs in a DL MU PPDU.",
                          BooleanValue(true),
                          MakeBooleanAccessor(&RrMultiUserScheduler::m_enableTxopSharing),
                          MakeBooleanChecker())
            .AddAttribute("ForceDlOfdma",
                          "If enabled, return DL_MU_TX even if no DL MU PPDU could be built.",
                          BooleanValue(false),
                          MakeBooleanAccessor(&RrMultiUserScheduler::m_forceDlOfdma),
                          MakeBooleanChecker())
            .AddAttribute("EnableUlOfdma",
                          "If enabled, return UL_MU_TX if DL_MU_TX was returned the previous time.",
                          BooleanValue(true),
                          MakeBooleanAccessor(&RrMultiUserScheduler::m_enableUlOfdma),
                          MakeBooleanChecker())
            .AddAttribute("EnableBsrp",
                          "If enabled, send a BSRP Trigger Frame before an UL MU transmission.",
                          BooleanValue(true),
                          MakeBooleanAccessor(&RrMultiUserScheduler::m_enableBsrp),
                          MakeBooleanChecker())
            .AddAttribute(
                "UlPsduSize",
                "The default size in bytes of the solicited PSDU (to be sent in a TB PPDU)",
                UintegerValue(500),
                MakeUintegerAccessor(&RrMultiUserScheduler::m_ulPsduSize),
                MakeUintegerChecker<uint32_t>())
            .AddAttribute("UseCentral26TonesRus",
                          "If enabled, central 26-tone RUs are allocated, too, when the "
                          "selected RU type is at least 52 tones.",
                          BooleanValue(false),
                          MakeBooleanAccessor(&RrMultiUserScheduler::m_useCentral26TonesRus),
                          MakeBooleanChecker())
            .AddAttribute(
                "MaxCredits",
                "Maximum amount of credits a station can have. When transmitting a DL MU PPDU, "
                "the amount of credits received by each station equals the TX duration (in "
                "microseconds) divided by the total number of stations. Stations that are the "
                "recipient of the DL MU PPDU have to pay a number of credits equal to the TX "
                "duration (in microseconds) times the allocated bandwidth share",
                TimeValue(Seconds(1)),
                MakeTimeAccessor(&RrMultiUserScheduler::m_maxCredits),
                MakeTimeChecker());
    return tid;
}
 
RrMultiUserScheduler::RrMultiUserScheduler()
{
    NS_LOG_FUNCTION(this);
}
 
RrMultiUserScheduler::~RrMultiUserScheduler()
{
    NS_LOG_FUNCTION_NOARGS();
}
 
void
RrMultiUserScheduler::DoInitialize()
{
    NS_LOG_FUNCTION(this);
    NS_ASSERT(m_apMac);
    m_apMac->TraceConnectWithoutContext(
        "AssociatedSta",
        MakeCallback(&RrMultiUserScheduler::NotifyStationAssociated, this));
    m_apMac->TraceConnectWithoutContext(
        "DeAssociatedSta",
        MakeCallback(&RrMultiUserScheduler::NotifyStationDeassociated, this));
    for (const auto& ac : wifiAcList)
    {
        m_staListDl.insert({ac.first, {}});
    }
    MultiUserScheduler::DoInitialize();
}
 
void
RrMultiUserScheduler::DoDispose()
{
    NS_LOG_FUNCTION(this);
    m_staListDl.clear();
    m_staListUl.clear();
    m_candidates.clear();
    m_txParams.Clear();
    m_apMac->TraceDisconnectWithoutContext(
        "AssociatedSta",
        MakeCallback(&RrMultiUserScheduler::NotifyStationAssociated, this));
    m_apMac->TraceDisconnectWithoutContext(
        "DeAssociatedSta",
        MakeCallback(&RrMultiUserScheduler::NotifyStationDeassociated, this));
    MultiUserScheduler::DoDispose();
}
 
MultiUserScheduler::TxFormat
RrMultiUserScheduler::SelectTxFormat()
{
    NS_LOG_FUNCTION(this);
 
    Ptr<const WifiMpdu> mpdu = m_edca->PeekNextMpdu(m_linkId);
 
    if (mpdu && !m_apMac->GetHeSupported(mpdu->GetHeader().GetAddr1()))
    {
        return SU_TX;
    }
 
    if (m_enableUlOfdma && m_enableBsrp &&
        (GetLastTxFormat(m_linkId) == DL_MU_TX ||
         ((m_initialFrame || m_trigger.GetType() != TriggerFrameType::BSRP_TRIGGER) && !mpdu)))
    {
        TxFormat txFormat = TrySendingBsrpTf();
 
        if (txFormat != DL_MU_TX)
        {
            return txFormat;
        }
    }
    else if (m_enableUlOfdma && ((GetLastTxFormat(m_linkId) == DL_MU_TX) ||
                                 (m_trigger.GetType() == TriggerFrameType::BSRP_TRIGGER) || !mpdu))
    {
        TxFormat txFormat = TrySendingBasicTf();
 
        if (txFormat != DL_MU_TX)
        {
            return txFormat;
        }
    }
 
    return TrySendingDlMuPpdu();
}
 
WifiTxVector
RrMultiUserScheduler::GetTxVectorForUlMu(std::function<bool(const MasterInfo&)> canBeSolicited)
{
    NS_LOG_FUNCTION(this);
 
    auto heConfiguration = m_apMac->GetHeConfiguration();
    NS_ASSERT(heConfiguration);
 
    WifiTxVector txVector;
    txVector.SetChannelWidth(m_allowedWidth);
    txVector.SetGuardInterval(heConfiguration->GetGuardInterval());
    txVector.SetBssColor(heConfiguration->m_bssColor);
    txVector.SetPreambleType(WIFI_PREAMBLE_HE_TB);
 
    const auto firstCandidate =
        std::find_if(m_staListUl.begin(), m_staListUl.end(), canBeSolicited);
    if (firstCandidate == m_staListUl.cend())
    {
        NS_LOG_DEBUG("No candidate");
        return txVector;
    }
 
    // determine RUs to allocate to stations
    const auto isEht =
        (m_apMac->GetEhtSupported() && m_apMac->GetEhtSupported(firstCandidate->address));
    auto count = std::min<std::size_t>(m_nStations, m_staListUl.size());
    std::size_t nCentral26TonesRus;
    WifiRu::GetEqualSizedRusForStations(m_allowedWidth,
                                        count,
                                        nCentral26TonesRus,
                                        isEht ? WIFI_MOD_CLASS_EHT : WIFI_MOD_CLASS_HE);
    NS_ASSERT(count >= 1);
 
    if (!m_useCentral26TonesRus)
    {
        nCentral26TonesRus = 0;
    }
 
    if (isEht)
    {
        txVector.SetPreambleType(WIFI_PREAMBLE_EHT_TB);
        txVector.SetEhtPpduType(0);
    }
    // TODO otherwise make sure the TX width does not exceed 160 MHz
 
    // iterate over the associated stations until an enough number of stations is identified
    auto staIt = firstCandidate;
    m_candidates.clear();
 
    while (staIt != m_staListUl.end() &&
           txVector.GetHeMuUserInfoMap().size() <
               std::min<std::size_t>(m_nStations, count + nCentral26TonesRus))
    {
        NS_LOG_DEBUG("Next candidate STA (MAC=" << staIt->address << ", AID=" << staIt->aid << ")");
 
        if (txVector.GetPreambleType() == WIFI_PREAMBLE_EHT_TB &&
            !m_apMac->GetEhtSupported(staIt->address))
        {
            NS_LOG_DEBUG(
                "Skipping non-EHT STA because this Trigger Frame is only soliciting EHT STAs");
            staIt = std::find_if(++staIt, m_staListUl.end(), canBeSolicited);
            continue;
        }
 
        // prepare the MAC header of a frame that would be sent to the candidate station,
        // just for the purpose of retrieving the TXVECTOR used to transmit to that station
        WifiMacHeader hdr(WIFI_MAC_QOSDATA);
        hdr.SetAddr1(GetWifiRemoteStationManager(m_linkId)
                         ->GetAffiliatedStaAddress(staIt->address)
                         .value_or(staIt->address));
        hdr.SetAddr2(m_apMac->GetFrameExchangeManager(m_linkId)->GetAddress());
        WifiTxVector suTxVector =
            GetWifiRemoteStationManager(m_linkId)->GetDataTxVector(hdr, m_allowedWidth);
        txVector.SetHeMuUserInfo(staIt->aid,
                                 {HeRu::RuSpec(), // assigned later by FinalizeTxVector
                                  suTxVector.GetMode().GetMcsValue(),
                                  suTxVector.GetNss()});
        m_candidates.emplace_back(staIt, nullptr);
 
        // move to the next candidate station in the list
        staIt = std::find_if(++staIt, m_staListUl.end(), canBeSolicited);
    }
 
    if (txVector.GetHeMuUserInfoMap().empty())
    {
        NS_LOG_DEBUG("No suitable station");
        return txVector;
    }
 
    FinalizeTxVector(txVector);
    return txVector;
}
 
bool
RrMultiUserScheduler::CanSolicitStaInBsrpTf(const MasterInfo& info) const
{
    // check if station has setup the current link
    if (!m_apMac->GetStaList(m_linkId).contains(info.aid))
    {
        NS_LOG_INFO("STA with AID " << info.aid << " has not setup link " << +m_linkId
                                    << ": skipping station");
        return false;
    }
 
    uint8_t tid = 0;
    while (tid < 8)
    {
        // check that a BA agreement is established with the receiver for the
        // considered TID, since ack sequences for UL MU require block ack
        if (m_apMac->GetBaAgreementEstablishedAsRecipient(info.address, tid))
        {
            break;
        }
        ++tid;
    }
    if (tid == 8)
    {
        NS_LOG_DEBUG("No Block Ack agreement established with " << info.address
                                                                << ": skipping station");
        return false;
    }
 
    auto mldAddr = GetWifiRemoteStationManager(m_linkId)->GetMldAddress(info.address);
 
    // remaining checks are for MLDs only
    if (!mldAddr)
    {
        return true;
    }
 
    // check if at least one TID is mapped on the current link in the UL direction
    bool mapped = false;
    for (uint8_t tid = 0; tid < 8; ++tid)
    {
        if (m_apMac->TidMappedOnLink(*mldAddr, WifiDirection::UPLINK, tid, m_linkId))
        {
            mapped = true;
            break;
        }
    }
 
    if (!mapped)
    {
        NS_LOG_DEBUG("MLD " << *mldAddr << " has not mapped any TID on link " << +m_linkId
                            << ": skipping station");
        return false;
    }
 
    // check if the station is an EMLSR client that is using another link
    if (GetWifiRemoteStationManager(m_linkId)->GetEmlsrEnabled(info.address) &&
        (m_apMac->GetTxBlockedOnLink(AC_BE,
                                     {WIFI_QOSDATA_QUEUE, WIFI_UNICAST, *mldAddr, 0},
                                     m_linkId,
                                     WifiQueueBlockedReason::USING_OTHER_EMLSR_LINK) ||
         m_apMac->GetTxBlockedOnLink(AC_BE,
                                     {WIFI_QOSDATA_QUEUE, WIFI_UNICAST, *mldAddr, 0},
                                     m_linkId,
                                     WifiQueueBlockedReason::WAITING_EMLSR_TRANSITION_DELAY)))
    {
        NS_LOG_INFO("EMLSR client " << *mldAddr << " is using another link: skipping station");
        return false;
    }
 
    return true;
}
 
MultiUserScheduler::TxFormat
RrMultiUserScheduler::TrySendingBsrpTf()
{
    NS_LOG_FUNCTION(this);
 
    if (m_staListUl.empty())
    {
        NS_LOG_DEBUG("No HE stations associated: return SU_TX");
        return TxFormat::SU_TX;
    }
 
    auto txVector = GetTxVectorForUlMu(
        std::bind(&RrMultiUserScheduler::CanSolicitStaInBsrpTf, this, std::placeholders::_1));
 
    if (txVector.GetHeMuUserInfoMap().empty())
    {
        NS_LOG_DEBUG("No suitable station found");
        return TxFormat::DL_MU_TX;
    }
 
    m_trigger = CtrlTriggerHeader(TriggerFrameType::BSRP_TRIGGER, txVector);
    txVector.SetGuardInterval(m_trigger.GetGuardInterval());
 
    auto item = GetTriggerFrame(m_trigger, m_linkId);
    m_triggerMacHdr = item->GetHeader();
 
    m_txParams.Clear();
    // set the TXVECTOR used to send the Trigger Frame
    m_txParams.m_txVector =
        m_apMac->GetWifiRemoteStationManager(m_linkId)->GetRtsTxVector(m_triggerMacHdr.GetAddr1(),
                                                                       m_allowedWidth);
 
    // If this BSRP TF is an ICF, we need to add padding and adjust the TXVECTOR
    if (auto ehtFem =
            DynamicCast<EhtFrameExchangeManager>(m_apMac->GetFrameExchangeManager(m_linkId)))
    {
        auto prevPaddingSize = m_trigger.GetPaddingSize();
        ehtFem->SetIcfPaddingAndTxVector(m_trigger, m_txParams.m_txVector);
        // serialize again if padding has been added
        if (m_trigger.GetPaddingSize() != prevPaddingSize)
        {
            auto packet = Create<Packet>();
            packet->AddHeader(m_trigger);
            item = Create<WifiMpdu>(packet, item->GetHeader());
        }
    }
 
    if (!GetHeFem(m_linkId)->TryAddMpdu(item, m_txParams, m_availableTime))
    {
        // sending the BSRP Trigger Frame is not possible, hence return NO_TX. In
        // this way, no transmission will occur now and the next time we will
        // try again sending a BSRP Trigger Frame.
        NS_LOG_DEBUG("Remaining TXOP duration is not enough for BSRP TF exchange");
        return NO_TX;
    }
 
    // Compute the time taken by each station to transmit 8 QoS Null frames
    Time qosNullTxDuration;
    for (const auto& userInfo : m_trigger)
    {
        Time duration = WifiPhy::CalculateTxDuration(GetMaxSizeOfQosNullAmpdu(m_trigger),
                                                     txVector,
                                                     m_apMac->GetWifiPhy(m_linkId)->GetPhyBand(),
                                                     userInfo.GetAid12());
        qosNullTxDuration = Max(qosNullTxDuration, duration);
    }
 
    NS_ASSERT(m_txParams.m_txDuration.has_value());
    m_triggerTxDuration = m_txParams.m_txDuration.value();
 
    if (m_availableTime != Time::Min())
    {
        // TryAddMpdu only considers the time to transmit the Trigger Frame
        NS_ASSERT(m_txParams.m_protection && m_txParams.m_protection->protectionTime.has_value());
        NS_ASSERT(m_txParams.m_acknowledgment &&
                  m_txParams.m_acknowledgment->acknowledgmentTime.has_value() &&
                  m_txParams.m_acknowledgment->acknowledgmentTime->IsZero());
 
        if (*m_txParams.m_protection->protectionTime + *m_txParams.m_txDuration // BSRP TF tx time
                + m_apMac->GetWifiPhy(m_linkId)->GetSifs() + qosNullTxDuration >
            m_availableTime)
        {
            NS_LOG_DEBUG("Remaining TXOP duration is not enough for BSRP TF exchange");
            return NO_TX;
        }
    }
 
    uint16_t ulLength;
    std::tie(ulLength, qosNullTxDuration) = HePhy::ConvertHeTbPpduDurationToLSigLength(
        qosNullTxDuration,
        m_trigger.GetHeTbTxVector(m_trigger.begin()->GetAid12()),
        m_apMac->GetWifiPhy(m_linkId)->GetPhyBand());
    NS_LOG_DEBUG("Duration of QoS Null frames: " << qosNullTxDuration.As(Time::MS));
    m_trigger.SetUlLength(ulLength);
 
    return UL_MU_TX;
}
 
bool
RrMultiUserScheduler::CanSolicitStaInBasicTf(const MasterInfo& info) const
{
    // in addition to the checks performed when sending a BSRP TF, also check if the station
    // has reported a null queue size
    if (!CanSolicitStaInBsrpTf(info))
    {
        return false;
    }
 
    return m_apMac->GetMaxBufferStatus(info.address) > 0;
}
 
MultiUserScheduler::TxFormat
RrMultiUserScheduler::TrySendingBasicTf()
{
    NS_LOG_FUNCTION(this);
 
    if (m_staListUl.empty())
    {
        NS_LOG_DEBUG("No HE stations associated: return SU_TX");
        return TxFormat::SU_TX;
    }
 
    // check if an UL OFDMA transmission is possible after a DL OFDMA transmission
    NS_ABORT_MSG_IF(m_ulPsduSize == 0, "The UlPsduSize attribute must be set to a non-null value");
 
    auto txVector = GetTxVectorForUlMu(
        std::bind(&RrMultiUserScheduler::CanSolicitStaInBasicTf, this, std::placeholders::_1));
 
    if (txVector.GetHeMuUserInfoMap().empty())
    {
        NS_LOG_DEBUG("No suitable station found");
        return TxFormat::DL_MU_TX;
    }
 
    uint32_t maxBufferSize = 0;
 
    for (const auto& candidate : txVector.GetHeMuUserInfoMap())
    {
        auto address = m_apMac->GetMldOrLinkAddressByAid(candidate.first);
        NS_ASSERT_MSG(address, "AID " << candidate.first << " not found");
 
        uint8_t queueSize = m_apMac->GetMaxBufferStatus(*address);
        if (queueSize == 255)
        {
            NS_LOG_DEBUG("Buffer status of station " << *address << " is unknown");
            maxBufferSize = std::max(maxBufferSize, m_ulPsduSize);
        }
        else if (queueSize == 254)
        {
            NS_LOG_DEBUG("Buffer status of station " << *address << " is not limited");
            maxBufferSize = 0xffffffff;
        }
        else
        {
            NS_LOG_DEBUG("Buffer status of station " << *address << " is " << +queueSize);
            maxBufferSize = std::max(maxBufferSize, static_cast<uint32_t>(queueSize * 256));
        }
    }
 
    if (maxBufferSize == 0)
    {
        return DL_MU_TX;
    }
 
    m_trigger = CtrlTriggerHeader(TriggerFrameType::BASIC_TRIGGER, txVector);
    txVector.SetGuardInterval(m_trigger.GetGuardInterval());
 
    auto item = GetTriggerFrame(m_trigger, m_linkId);
    m_triggerMacHdr = item->GetHeader();
 
    // compute the maximum amount of time that can be granted to stations.
    // This value is limited by the max PPDU duration
    Time maxDuration = GetPpduMaxTime(txVector.GetPreambleType());
 
    m_txParams.Clear();
    // set the TXVECTOR used to send the Trigger Frame
    m_txParams.m_txVector =
        m_apMac->GetWifiRemoteStationManager(m_linkId)->GetRtsTxVector(m_triggerMacHdr.GetAddr1(),
                                                                       m_allowedWidth);
 
    if (!GetHeFem(m_linkId)->TryAddMpdu(item, m_txParams, m_availableTime))
    {
        // an UL OFDMA transmission is not possible, hence return NO_TX. In
        // this way, no transmission will occur now and the next time we will
        // try again performing an UL OFDMA transmission.
        NS_LOG_DEBUG("Remaining TXOP duration is not enough for UL MU exchange");
        return NO_TX;
    }
 
    NS_ASSERT(m_txParams.m_txDuration.has_value());
    m_triggerTxDuration = m_txParams.m_txDuration.value();
 
    if (m_availableTime != Time::Min())
    {
        // TryAddMpdu only considers the time to transmit the Trigger Frame
        NS_ASSERT(m_txParams.m_protection && m_txParams.m_protection->protectionTime.has_value());
        NS_ASSERT(m_txParams.m_acknowledgment &&
                  m_txParams.m_acknowledgment->acknowledgmentTime.has_value());
 
        maxDuration = Min(maxDuration,
                          m_availableTime - *m_txParams.m_protection->protectionTime -
                              *m_txParams.m_txDuration - m_apMac->GetWifiPhy(m_linkId)->GetSifs() -
                              *m_txParams.m_acknowledgment->acknowledgmentTime);
        if (maxDuration.IsNegative())
        {
            NS_LOG_DEBUG("Remaining TXOP duration is not enough for UL MU exchange");
            return NO_TX;
        }
    }
 
    // Compute the time taken by each station to transmit a frame of maxBufferSize size
    Time bufferTxTime;
    for (const auto& userInfo : m_trigger)
    {
        Time duration = WifiPhy::CalculateTxDuration(maxBufferSize,
                                                     txVector,
                                                     m_apMac->GetWifiPhy(m_linkId)->GetPhyBand(),
                                                     userInfo.GetAid12());
        bufferTxTime = Max(bufferTxTime, duration);
    }
 
    if (bufferTxTime < maxDuration)
    {
        // the maximum buffer size can be transmitted within the allowed time
        maxDuration = bufferTxTime;
    }
    else
    {
        // maxDuration may be a too short time. If it does not allow any station to
        // transmit at least m_ulPsduSize bytes, give up the UL MU transmission for now
        Time minDuration;
        for (const auto& userInfo : m_trigger)
        {
            Time duration =
                WifiPhy::CalculateTxDuration(m_ulPsduSize,
                                             txVector,
                                             m_apMac->GetWifiPhy(m_linkId)->GetPhyBand(),
                                             userInfo.GetAid12());
            minDuration = (minDuration.IsZero() ? duration : Min(minDuration, duration));
        }
 
        if (maxDuration < minDuration)
        {
            // maxDuration is a too short time, hence return NO_TX. In this way,
            // no transmission will occur now and the next time we will try again
            // performing an UL OFDMA transmission.
            NS_LOG_DEBUG("Available time " << maxDuration.As(Time::MS) << " is too short");
            return NO_TX;
        }
    }
 
    // maxDuration is the time to grant to the stations. Finalize the Trigger Frame
    uint16_t ulLength;
    std::tie(ulLength, maxDuration) =
        HePhy::ConvertHeTbPpduDurationToLSigLength(maxDuration,
                                                   txVector,
                                                   m_apMac->GetWifiPhy(m_linkId)->GetPhyBand());
    NS_LOG_DEBUG("TB PPDU duration: " << maxDuration.As(Time::MS));
    m_trigger.SetUlLength(ulLength);
    // set Preferred AC to the AC that gained channel access
    for (auto& userInfo : m_trigger)
    {
        userInfo.SetBasicTriggerDepUserInfo(0, 0, m_edca->GetAccessCategory());
    }
 
    UpdateCredits(m_staListUl, maxDuration, txVector);
 
    return UL_MU_TX;
}
 
void
RrMultiUserScheduler::UpdateTriggerFrameAfterProtection(uint8_t linkId,
                                                        CtrlTriggerHeader& trigger,
                                                        WifiTxParameters& txParams) const
{
    NS_LOG_FUNCTION(this << linkId << &txParams);
 
    // remove unprotected EMLSR clients, unless this is a BSRP TF (which acts as ICF)
    if (trigger.IsBsrp())
    {
        NS_LOG_INFO("BSRP TF is an ICF for unprotected EMLSR clients");
        return;
    }
 
    NS_LOG_INFO("Checking unprotected EMLSR clients");
    RemoveRecipientsFromTf(linkId, trigger, txParams, m_isUnprotectedEmlsrClient);
}
 
void
RrMultiUserScheduler::UpdateDlMuAfterProtection(uint8_t linkId,
                                                WifiPsduMap& psduMap,
                                                WifiTxParameters& txParams) const
{
    NS_LOG_FUNCTION(this << linkId << &txParams);
 
    NS_LOG_INFO("Checking unprotected EMLSR clients");
    RemoveRecipientsFromDlMu(linkId, psduMap, txParams, m_isUnprotectedEmlsrClient);
}
 
Time
RrMultiUserScheduler::GetExtraTimeForBsrpTfDurationId(uint8_t linkId) const
{
    auto phy = m_apMac->GetWifiPhy(linkId);
    BlockAckType baType(BlockAckType::MULTI_STA);
    uint16_t aid{0};
    Mac48Address staAddress;
 
    // we assume that a Basic Trigger Frame is sent after a BSRP Trigger Frame. In order to
    // compute the TX duration of the Multi-STA BlockAck, we need to find the bitmap length
    // for each STA solicited by the Trigger Frame
    for (const auto& userInfo : m_trigger)
    {
        aid = userInfo.GetAid12();
        auto it = m_apMac->GetStaList(linkId).find(aid);
        NS_ASSERT(it != m_apMac->GetStaList(linkId).cend());
        staAddress = it->second;
 
        // find a TID for which a BA agreement exists with the given originator
        uint8_t tid = 0;
        while (tid < 8 && !m_apMac->GetBaAgreementEstablishedAsRecipient(staAddress, tid))
        {
            ++tid;
        }
        NS_ASSERT_MSG(tid < 8, "No Block Ack agreement established with originator " << staAddress);
 
        baType.m_bitmapLen.push_back(
            m_apMac->GetBaTypeAsRecipient(staAddress, tid).m_bitmapLen.at(0));
    }
 
    NS_ASSERT_MSG(aid != 0, "No User Info field in the Trigger Frame");
 
    auto multiStaBaTxVector =
        GetWifiRemoteStationManager(linkId)->GetBlockAckTxVector(staAddress,
                                                                 m_trigger.GetHeTbTxVector(aid));
 
    auto multiStaBaDuration = WifiPhy::CalculateTxDuration(GetBlockAckSize(baType),
                                                           multiStaBaTxVector,
                                                           phy->GetPhyBand());
 
    return m_triggerTxDuration + m_defaultTbPpduDuration + multiStaBaDuration + 3 * phy->GetSifs();
}
 
void
RrMultiUserScheduler::NotifyStationAssociated(uint16_t aid, Mac48Address address)
{
    NS_LOG_FUNCTION(this << aid << address);
 
    if (!m_apMac->GetHeSupported(address))
    {
        return;
    }
 
    auto mldOrLinkAddress = m_apMac->GetMldOrLinkAddressByAid(aid);
    NS_ASSERT_MSG(mldOrLinkAddress, "AID " << aid << " not found");
 
    for (auto& staList : m_staListDl)
    {
        // if this is not the first STA of a non-AP MLD to be notified, an entry
        // for this non-AP MLD already exists
        const auto staIt = std::find_if(staList.second.cbegin(),
                                        staList.second.cend(),
                                        [aid](auto&& info) { return info.aid == aid; });
        if (staIt == staList.second.cend())
        {
            staList.second.push_back(MasterInfo{aid, *mldOrLinkAddress, 0.0});
        }
    }
 
    const auto staIt = std::find_if(m_staListUl.cbegin(), m_staListUl.cend(), [aid](auto&& info) {
        return info.aid == aid;
    });
    if (staIt == m_staListUl.cend())
    {
        m_staListUl.push_back(MasterInfo{aid, *mldOrLinkAddress, 0.0});
    }
}
 
void
RrMultiUserScheduler::NotifyStationDeassociated(uint16_t aid, Mac48Address address)
{
    NS_LOG_FUNCTION(this << aid << address);
 
    if (!m_apMac->GetHeSupported(address))
    {
        return;
    }
 
    auto mldOrLinkAddress = m_apMac->GetMldOrLinkAddressByAid(aid);
    NS_ASSERT_MSG(mldOrLinkAddress, "AID " << aid << " not found");
 
    if (m_apMac->IsAssociated(*mldOrLinkAddress))
    {
        // Another STA of the non-AP MLD is still associated
        return;
    }
 
    for (auto& staList : m_staListDl)
    {
        staList.second.remove_if([&aid](const MasterInfo& info) { return info.aid == aid; });
    }
    m_staListUl.remove_if([&aid](const MasterInfo& info) { return info.aid == aid; });
}
 
MultiUserScheduler::TxFormat
RrMultiUserScheduler::TrySendingDlMuPpdu()
{
    NS_LOG_FUNCTION(this);
 
    AcIndex primaryAc = m_edca->GetAccessCategory();
 
    if (m_staListDl[primaryAc].empty())
    {
        NS_LOG_DEBUG("No HE stations associated: return SU_TX");
        return TxFormat::SU_TX;
    }
 
    std::size_t count =
        std::min(static_cast<std::size_t>(m_nStations), m_staListDl[primaryAc].size());
    std::size_t nCentral26TonesRus{0};
 
    uint8_t currTid = wifiAcList.at(primaryAc).GetHighTid();
 
    Ptr<WifiMpdu> mpdu = m_edca->PeekNextMpdu(m_linkId);
 
    if (mpdu && mpdu->GetHeader().IsQosData())
    {
        currTid = mpdu->GetHeader().GetQosTid();
    }
 
    // determine the list of TIDs to check
    std::vector<uint8_t> tids;
 
    if (m_enableTxopSharing)
    {
        for (auto acIt = wifiAcList.find(primaryAc); acIt != wifiAcList.end(); acIt++)
        {
            uint8_t firstTid = (acIt->first == primaryAc ? currTid : acIt->second.GetHighTid());
            tids.push_back(firstTid);
            tids.push_back(acIt->second.GetOtherTid(firstTid));
        }
    }
    else
    {
        tids.push_back(currTid);
    }
 
    Ptr<HeConfiguration> heConfiguration = m_apMac->GetHeConfiguration();
    NS_ASSERT(heConfiguration);
 
    m_txParams.Clear();
    m_txParams.m_txVector.SetPreambleType(WIFI_PREAMBLE_HE_MU);
    m_txParams.m_txVector.SetChannelWidth(m_allowedWidth);
    m_txParams.m_txVector.SetGuardInterval(heConfiguration->GetGuardInterval());
    m_txParams.m_txVector.SetBssColor(heConfiguration->m_bssColor);
 
    // The TXOP limit can be exceeded by the TXOP holder if it does not transmit more
    // than one Data or Management frame in the TXOP and the frame is not in an A-MPDU
    // consisting of more than one MPDU (Sec. 10.22.2.8 of 802.11-2016).
    // For the moment, we are considering just one MPDU per receiver.
    Time actualAvailableTime = (m_initialFrame ? Time::Min() : m_availableTime);
 
    // iterate over the associated stations until an enough number of stations is identified
    auto staIt = m_staListDl[primaryAc].begin();
    m_candidates.clear();
 
    std::vector<uint8_t> ruAllocations;
    const auto numRuAllocs = Count20MHzSubchannels(m_txParams.m_txVector.GetChannelWidth());
    ruAllocations.resize(numRuAllocs);
    NS_ASSERT((m_candidates.size() % numRuAllocs) == 0);
 
    RuType ruType{RuType::RU_TYPE_MAX};
    while (staIt != m_staListDl[primaryAc].end() &&
           m_candidates.size() <
               std::min(static_cast<std::size_t>(m_nStations), count + nCentral26TonesRus))
    {
        NS_LOG_DEBUG("Next candidate STA (MAC=" << staIt->address << ", AID=" << staIt->aid << ")");
 
        if (m_txParams.m_txVector.GetPreambleType() == WIFI_PREAMBLE_EHT_MU &&
            !m_apMac->GetEhtSupported(staIt->address))
        {
            NS_LOG_DEBUG("Skipping non-EHT STA because this DL MU PPDU is sent to EHT STAs only");
            staIt++;
            continue;
        }
 
        // check if the AP has at least one frame to be sent to the current station
        for (uint8_t tid : tids)
        {
            AcIndex ac = QosUtilsMapTidToAc(tid);
            NS_ASSERT(ac >= primaryAc);
            // check that a BA agreement is established with the receiver for the
            // considered TID, since ack sequences for DL MU PPDUs require block ack
            if (m_apMac->GetBaAgreementEstablishedAsOriginator(staIt->address, tid))
            {
                mpdu = m_apMac->GetQosTxop(ac)->PeekNextMpdu(m_linkId, tid, staIt->address);
 
                // we only check if the first frame of the current TID meets the size
                // and duration constraints. We do not explore the queues further.
                if (mpdu)
                {
                    mpdu = GetHeFem(m_linkId)->CreateAliasIfNeeded(mpdu);
                    // Use a temporary TX vector including only the STA-ID of the
                    // candidate station to check if the MPDU meets the size and time limits.
                    // An RU of the computed size is tentatively assigned to the candidate
                    // station, so that the TX duration can be correctly computed.
                    WifiTxVector suTxVector =
                        GetWifiRemoteStationManager(m_linkId)->GetDataTxVector(mpdu->GetHeader(),
                                                                               m_allowedWidth);
 
                    WifiTxVector txVectorCopy = m_txParams.m_txVector;
 
                    // the first candidate STA determines the preamble type for the DL MU PPDU
                    if (m_candidates.empty())
                    {
                        WifiModulationClass mc = WIFI_MOD_CLASS_HE;
                        if (suTxVector.GetPreambleType() == WIFI_PREAMBLE_EHT_MU)
                        {
                            m_txParams.m_txVector.SetPreambleType(WIFI_PREAMBLE_EHT_MU);
                            m_txParams.m_txVector.SetEhtPpduType(
                                0); // indicates DL OFDMA transmission
                            mc = WIFI_MOD_CLASS_EHT;
                        }
                        ruType = WifiRu::GetEqualSizedRusForStations(m_allowedWidth,
                                                                     count,
                                                                     nCentral26TonesRus,
                                                                     mc);
                        NS_ASSERT(count >= 1);
                        if (!m_useCentral26TonesRus)
                        {
                            nCentral26TonesRus = 0;
                        }
                    }
 
                    NS_ASSERT(ruType != RuType::RU_TYPE_MAX);
                    const auto currRuType =
                        (m_candidates.size() < count ? ruType : RuType::RU_26_TONE);
                    const auto ru =
                        (m_txParams.m_txVector.GetPreambleType() == WIFI_PREAMBLE_EHT_MU)
                            ? WifiRu::RuSpec(EhtRu::RuSpec{currRuType, 1, true, true})
                            : WifiRu::RuSpec(HeRu::RuSpec{currRuType, 1, true});
                    m_txParams.m_txVector.SetHeMuUserInfo(
                        staIt->aid,
                        {ru, suTxVector.GetMode().GetMcsValue(), suTxVector.GetNss()});
 
                    if (!GetHeFem(m_linkId)->TryAddMpdu(mpdu, m_txParams, actualAvailableTime))
                    {
                        NS_LOG_DEBUG("Adding the peeked frame violates the time constraints");
                        m_txParams.m_txVector = txVectorCopy;
                    }
                    else
                    {
                        // the frame meets the constraints
                        NS_LOG_DEBUG("Adding candidate STA (MAC=" << staIt->address
                                                                  << ", AID=" << staIt->aid
                                                                  << ") TID=" << +tid);
                        m_candidates.emplace_back(staIt, mpdu);
                        break; // terminate the for loop
                    }
                }
                else
                {
                    NS_LOG_DEBUG("No frames to send to " << staIt->address << " with TID=" << +tid);
                }
            }
        }
 
        // move to the next station in the list
        staIt++;
    }
 
    if (m_candidates.empty())
    {
        if (m_forceDlOfdma)
        {
            NS_LOG_DEBUG("The AP does not have suitable frames to transmit: return NO_TX");
            return NO_TX;
        }
        NS_LOG_DEBUG("The AP does not have suitable frames to transmit: return SU_TX");
        return SU_TX;
    }
 
    return TxFormat::DL_MU_TX;
}
 
void
RrMultiUserScheduler::FinalizeTxVector(WifiTxVector& txVector)
{
    // Do not log txVector because GetTxVectorForUlMu() left RUs undefined and
    // printing them will crash the simulation
    NS_LOG_FUNCTION(this);
    NS_ASSERT(txVector.GetHeMuUserInfoMap().size() == m_candidates.size());
 
    // compute how many stations can be granted an RU and the RU size
    std::size_t nRusAssigned = m_candidates.size();
    std::size_t nCentral26TonesRus;
    const auto ruType = WifiRu::GetEqualSizedRusForStations(m_allowedWidth,
                                                            nRusAssigned,
                                                            nCentral26TonesRus,
                                                            txVector.GetModulationClass());
 
    NS_LOG_DEBUG(nRusAssigned << " stations are being assigned a " << ruType << " RU");
 
    if (!m_useCentral26TonesRus || m_candidates.size() == nRusAssigned)
    {
        nCentral26TonesRus = 0;
    }
    else
    {
        nCentral26TonesRus = std::min(m_candidates.size() - nRusAssigned, nCentral26TonesRus);
        NS_LOG_DEBUG(nCentral26TonesRus << " stations are being assigned a 26-tones RU");
    }
 
    // re-allocate RUs based on the actual number of candidate stations
    WifiTxVector::HeMuUserInfoMap heMuUserInfoMap;
    std::swap(heMuUserInfoMap, txVector.GetHeMuUserInfoMap());
 
    const auto mc = IsEht(txVector.GetPreambleType()) ? WIFI_MOD_CLASS_EHT : WIFI_MOD_CLASS_HE;
    auto candidateIt = m_candidates.begin(); // iterator over the list of candidate receivers
    auto ruSet = WifiRu::GetRusOfType(m_allowedWidth, ruType, mc);
    auto ruSetIt = ruSet.begin();
    auto central26TonesRus = WifiRu::GetCentral26TonesRus(m_allowedWidth, ruType, mc);
    auto central26TonesRusIt = central26TonesRus.begin();
 
    for (std::size_t i = 0; i < nRusAssigned + nCentral26TonesRus; i++)
    {
        NS_ASSERT(candidateIt != m_candidates.end());
        auto mapIt = heMuUserInfoMap.find(candidateIt->first->aid);
        NS_ASSERT(mapIt != heMuUserInfoMap.end());
 
        txVector.SetHeMuUserInfo(mapIt->first,
                                 {(i < nRusAssigned ? *ruSetIt++ : *central26TonesRusIt++),
                                  mapIt->second.mcs,
                                  mapIt->second.nss});
        candidateIt++;
    }
 
    // remove candidates that will not be served
    m_candidates.erase(candidateIt, m_candidates.end());
}
 
void
RrMultiUserScheduler::UpdateCredits(std::list<MasterInfo>& staList,
                                    Time txDuration,
                                    const WifiTxVector& txVector)
{
    NS_LOG_FUNCTION(this << txDuration.As(Time::US) << txVector);
 
    // find how many RUs have been allocated for each RU type
    std::map<RuType, std::size_t> ruMap;
    for (const auto& userInfo : txVector.GetHeMuUserInfoMap())
    {
        ruMap.insert({WifiRu::GetRuType(userInfo.second.ru), 0}).first->second++;
    }
 
    // The amount of credits received by each station equals the TX duration (in
    // microseconds) divided by the number of stations.
    double creditsPerSta = txDuration.ToDouble(Time::US) / staList.size();
    // Transmitting stations have to pay a number of credits equal to the TX duration
    // (in microseconds) times the allocated bandwidth share.
    double debitsPerMhz =
        txDuration.ToDouble(Time::US) /
        std::accumulate(ruMap.begin(), ruMap.end(), 0, [](uint16_t sum, auto pair) {
            return sum + pair.second * WifiRu::GetBandwidth(pair.first);
        });
 
    // assign credits to all stations
    for (auto& sta : staList)
    {
        sta.credits += creditsPerSta;
        sta.credits = std::min(sta.credits, m_maxCredits.ToDouble(Time::US));
    }
 
    // subtract debits to the selected stations
    for (auto& candidate : m_candidates)
    {
        auto mapIt = txVector.GetHeMuUserInfoMap().find(candidate.first->aid);
        NS_ASSERT(mapIt != txVector.GetHeMuUserInfoMap().end());
 
        candidate.first->credits -=
            debitsPerMhz * WifiRu::GetBandwidth(WifiRu::GetRuType(mapIt->second.ru));
    }
 
    // sort the list in decreasing order of credits
    staList.sort([](const MasterInfo& a, const MasterInfo& b) { return a.credits > b.credits; });
}
 
MultiUserScheduler::DlMuInfo
RrMultiUserScheduler::ComputeDlMuInfo()
{
    NS_LOG_FUNCTION(this);
 
    if (m_candidates.empty())
    {
        return DlMuInfo();
    }
 
    DlMuInfo dlMuInfo;
    std::swap(dlMuInfo.txParams.m_txVector, m_txParams.m_txVector);
    FinalizeTxVector(dlMuInfo.txParams.m_txVector);
 
    m_txParams.Clear();
    Ptr<WifiMpdu> mpdu;
 
    // Compute the TX params (again) by using the stored MPDUs and the final TXVECTOR
    Time actualAvailableTime = (m_initialFrame ? Time::Min() : m_availableTime);
 
    for (const auto& candidate : m_candidates)
    {
        mpdu = candidate.second;
        NS_ASSERT(mpdu);
 
        bool ret [[maybe_unused]] =
            GetHeFem(m_linkId)->TryAddMpdu(mpdu, dlMuInfo.txParams, actualAvailableTime);
        NS_ASSERT_MSG(ret,
                      "Weird that an MPDU does not meet constraints when "
                      "transmitted over a larger RU");
    }
 
    // We have to complete the PSDUs to send
    Ptr<WifiMacQueue> queue;
 
    for (const auto& candidate : m_candidates)
    {
        // Let us try first A-MSDU aggregation if possible
        mpdu = candidate.second;
        NS_ASSERT(mpdu);
        uint8_t tid = mpdu->GetHeader().GetQosTid();
        NS_ASSERT_MSG(mpdu->GetOriginal()->GetHeader().GetAddr1() == candidate.first->address,
                      "RA of the stored MPDU must match the stored address");
 
        NS_ASSERT(mpdu->IsQueued());
        Ptr<WifiMpdu> item = mpdu;
 
        if (!mpdu->GetHeader().IsRetry())
        {
            // this MPDU must have been dequeued from the AC queue and we can try
            // A-MSDU aggregation
            item = GetHeFem(m_linkId)->GetMsduAggregator()->GetNextAmsdu(mpdu,
                                                                         dlMuInfo.txParams,
                                                                         m_availableTime);
 
            if (!item)
            {
                // A-MSDU aggregation failed or disabled
                item = mpdu;
            }
            m_apMac->GetQosTxop(QosUtilsMapTidToAc(tid))->AssignSequenceNumber(item);
        }
 
        // Now, let's try A-MPDU aggregation if possible
        std::vector<Ptr<WifiMpdu>> mpduList =
            GetHeFem(m_linkId)->GetMpduAggregator()->GetNextAmpdu(item,
                                                                  dlMuInfo.txParams,
                                                                  m_availableTime);
 
        if (mpduList.size() > 1)
        {
            // A-MPDU aggregation succeeded, update psduMap
            dlMuInfo.psduMap[candidate.first->aid] = Create<WifiPsdu>(std::move(mpduList));
        }
        else
        {
            dlMuInfo.psduMap[candidate.first->aid] = Create<WifiPsdu>(item, true);
        }
    }
 
    NS_ASSERT(dlMuInfo.txParams.m_txDuration.has_value());
    AcIndex primaryAc = m_edca->GetAccessCategory();
    UpdateCredits(m_staListDl[primaryAc],
                  *dlMuInfo.txParams.m_txDuration,
                  dlMuInfo.txParams.m_txVector);
 
    NS_LOG_DEBUG("Next station to serve has AID=" << m_staListDl[primaryAc].front().aid);
 
    return dlMuInfo;
}
 
MultiUserScheduler::UlMuInfo
RrMultiUserScheduler::ComputeUlMuInfo()
{
    return UlMuInfo{m_trigger, m_triggerMacHdr, std::move(m_txParams)};
}
 
} // namespace ns3