ieee80211: add per-receiver configured unicast data-frame rates

dataFrameBitrate fixes one rate for the whole interface, so a scenario
that needs different peers reached at different rates -- the usual setup
for studying rate diversity -- had to fall back on an adaptive rate
control and let the channel produce the spread indirectly, which is slow
to set up and hard to hold steady.

~RateSelection and ~QosRateSelection now accept dataFrameBitratePerReceiver,
a map from peer interface module path to bitrate. A unicast data frame
whose receiver matches an entry is sent at that rate; everything else
falls back to the existing rules. The parameter is empty by default, so
the capability is inert unless configured.

Resolution of the paths to MAC addresses is deferred to the first
transmitted data frame rather than done in initialize(): peer MAC
addresses are assigned during INITSTAGE_LINK_LAYER and the order of
modules within a stage is undefined, so reading them from initialize()
would be a race. By the time any data frame is sent, all init stages have
completed. Unresolvable paths and rates the mode set does not support
fail with an error naming the offending entry.

Author: adamgeorge309

src/inet/linklayer/ieee80211/mac/rateselection/QosRateSelection.cc

@@ -9,6 +9,7 @@
 
 #include "inet/common/ModuleAccess.h"
 #include "inet/common/Simsignals.h"
+#include "inet/networklayer/common/NetworkInterface.h"
 #include "inet/physicallayer/wireless/ieee80211/packetlevel/Ieee80211Tag_m.h"
 
 namespace inet {
@@ -40,6 +41,27 @@ void QosRateSelection::initialize(int stage)
     }
 }
 
+void QosRateSelection::ensurePerReceiverModesResolved()
+{
+    if (perReceiverResolved)
+        return;
+    perReceiverResolved = true;
+    auto perReceiverBitrate = check_and_cast<cValueMap *>(par("dataFrameBitratePerReceiver").objectValue());
+    for (auto& [path, value] : perReceiverBitrate->getFields()) {
+        auto module = findModuleByPath(path.c_str());
+        if (module == nullptr)
+            throw cRuntimeError("dataFrameBitratePerReceiver: cannot resolve receiver interface module path '%s'", path.c_str());
+        auto networkInterface = check_and_cast<NetworkInterface *>(module);
+        try {
+            auto mode = modeSet->getMode(bps(value.doubleValueInUnit("bps")), Hz(par("dataFrameBandwidth")), par("dataFrameNumSpatialStreams"));
+            perReceiverDataFrameMode[networkInterface->getMacAddress()] = mode;
+        }
+        catch (const cRuntimeError& e) {
+            throw cRuntimeError("dataFrameBitratePerReceiver: cannot use rate '%s' for receiver '%s': %s", value.str().c_str(), path.c_str(), e.what());
+        }
+    }
+}
+
 const IIeee80211Mode *QosRateSelection::getMode(Packet *packet, const Ptr<const Ieee80211MacHeader>& header)
 {
     const auto& modeReqTag = packet->findTag<Ieee80211ModeReq>();
@@ -119,6 +141,15 @@ const IIeee80211Mode *QosRateSelection::computeResponseBlockAckFrameMode(Packet
 
 const IIeee80211Mode *QosRateSelection::computeDataOrMgmtFrameMode(const Ptr<const Ieee80211DataOrMgmtHeader>& dataOrMgmtHeader)
 {
+    // Per-receiver override for originated unicast data frames (see dataFrameBitratePerReceiver).
+    // Wins over the interface-wide dataFrameMode / rate control; group-addressed and management
+    // frames are left to the existing rules below.
+    if (dynamicPtrCast<const Ieee80211DataHeader>(dataOrMgmtHeader) && !dataOrMgmtHeader->getReceiverAddress().isMulticast()) {
+        ensurePerReceiverModesResolved();
+        auto it = perReceiverDataFrameMode.find(dataOrMgmtHeader->getReceiverAddress());
+        if (it != perReceiverDataFrameMode.end())
+            return it->second;
+    }
     if (dynamicPtrCast<const Ieee80211DataHeader>(dataOrMgmtHeader) && dataFrameMode)
         return dataFrameMode;
     if (dynamicPtrCast<const Ieee80211MgmtHeader>(dataOrMgmtHeader) && mgmtFrameMode)

src/inet/linklayer/ieee80211/mac/rateselection/QosRateSelection.h

@@ -48,18 +48,31 @@ class INET_API QosRateSelection : public IQosRateSelection, public ModeSetListen
     const physicallayer::IIeee80211Mode *responseCtsFrameMode = nullptr;
     const physicallayer::IIeee80211Mode *responseBlockAckFrameMode = nullptr;
 
+    // per-receiver unicast data-frame modes, resolved lazily from dataFrameBitratePerReceiver
+    std::map<MacAddress, const physicallayer::IIeee80211Mode *> perReceiverDataFrameMode;
+    bool perReceiverResolved = false;
+
   protected:
     virtual int numInitStages() const override { return NUM_INIT_STAGES; }
     virtual void initialize(int stage) override;
     virtual void receiveSignal(cComponent *source, simsignal_t signalID, cObject *obj, cObject *details) override;
 
+    // Builds perReceiverDataFrameMode on first use. Deferred out of initialize() because peer
+    // MAC addresses are assigned during INITSTAGE_LINK_LAYER with undefined intra-stage module
+    // ordering; the first transmitted data frame occurs after all init stages, so this is race-free.
+    virtual void ensurePerReceiverModesResolved();
+
     virtual const physicallayer::IIeee80211Mode *getMode(Packet *packet, const Ptr<const Ieee80211MacHeader>& header);
     virtual const physicallayer::IIeee80211Mode *computeControlFrameMode(const Ptr<const Ieee80211MacHeader>& header, TxopProcedure *txopProcedure);
     virtual const physicallayer::IIeee80211Mode *computeDataOrMgmtFrameMode(const Ptr<const Ieee80211DataOrMgmtHeader>& dataOrMgmtHeader);
 
     virtual bool isControlResponseFrame(const Ptr<const Ieee80211MacHeader>& header, TxopProcedure *txopProcedure);
 
   public:
+    // Per-receiver configured data-frame modes (resolved lazily from dataFrameBitratePerReceiver);
+    // used by the IEEE 802.11 rate visualizer to show configured rates before any traffic.
+    const std::map<MacAddress, const physicallayer::IIeee80211Mode *>& getPerReceiverDataFrameModes() { ensurePerReceiverModesResolved(); return perReceiverDataFrameMode; }
+
     // A control response frame is a control frame that is transmitted as a response to the reception of a frame a SIFS
     // time after the PPDU containing the frame that elicited the response, e.g. a CTS in response to an RTS
     // reception, an ACK in response to a DATA reception, a BlockAck in response to a BlockAckReq reception. In

src/inet/linklayer/ieee80211/mac/rateselection/QosRateSelection.ned

@@ -34,6 +34,14 @@ simple QosRateSelection extends SimpleModule
         double dataFrameBandwidth @unit(Hz) = default(nan Hz); // Unspecified by default
         int dataFrameNumSpatialStreams = default(-1); // Unspecified by default
 
+        // Per-receiver unicast data-frame rate. Keys are peer interface module paths (e.g.
+        // "host1.wlan[0]"), resolved to MAC addresses at run time; values are bitrates (bps).
+        // A unicast data frame whose receiver matches a key is transmitted at that rate;
+        // unmatched receivers fall back to dataFrameBitrate / the rate-control module. The
+        // bandwidth and spatial-stream count are taken from dataFrameBandwidth /
+        // dataFrameNumSpatialStreams. Empty by default (capability inert).
+        object dataFrameBitratePerReceiver = default({});
+
         double mgmtFrameBitrate @unit(bps) = default(-1bps); // Fastest
         double controlFrameBitrate @unit(bps) = default(-1bps);
         @display("i=block/cogwheel");

src/inet/linklayer/ieee80211/mac/rateselection/RateSelection.cc

@@ -60,6 +60,27 @@ void RateSelection::initialize(int stage)
     }
 }
 
+void RateSelection::ensurePerReceiverModesResolved()
+{
+    if (perReceiverResolved)
+        return;
+    perReceiverResolved = true;
+    auto perReceiverBitrate = check_and_cast<cValueMap *>(par("dataFrameBitratePerReceiver").objectValue());
+    for (auto& [path, value] : perReceiverBitrate->getFields()) {
+        auto module = findModuleByPath(path.c_str());
+        if (module == nullptr)
+            throw cRuntimeError("dataFrameBitratePerReceiver: cannot resolve receiver interface module path '%s'", path.c_str());
+        auto networkInterface = check_and_cast<NetworkInterface *>(module);
+        try {
+            auto mode = modeSet->getMode(bps(value.doubleValueInUnit("bps")), Hz(par("dataFrameBandwidth")), par("dataFrameNumSpatialStreams"));
+            perReceiverDataFrameMode[networkInterface->getMacAddress()] = mode;
+        }
+        catch (const cRuntimeError& e) {
+            throw cRuntimeError("dataFrameBitratePerReceiver: cannot use rate '%s' for receiver '%s': %s", value.str().c_str(), path.c_str(), e.what());
+        }
+    }
+}
+
 const IIeee80211Mode *RateSelection::getMode(Packet *packet, const Ptr<const Ieee80211MacHeader>& header)
 {
     const auto& modeReqTag = packet->findTag<Ieee80211ModeReq>();
@@ -114,6 +135,15 @@ const IIeee80211Mode *RateSelection::computeResponseCtsFrameMode(Packet *packet,
 //
 const IIeee80211Mode *RateSelection::computeDataOrMgmtFrameMode(const Ptr<const Ieee80211DataOrMgmtHeader>& dataOrMgmtHeader)
 {
+    // Per-receiver override for originated unicast data frames (see dataFrameBitratePerReceiver).
+    // Wins over the interface-wide dataFrameMode / rate control; group-addressed and management
+    // frames are left to the existing rules below.
+    if (dynamicPtrCast<const Ieee80211DataHeader>(dataOrMgmtHeader) && !dataOrMgmtHeader->getReceiverAddress().isMulticast()) {
+        ensurePerReceiverModesResolved();
+        auto it = perReceiverDataFrameMode.find(dataOrMgmtHeader->getReceiverAddress());
+        if (it != perReceiverDataFrameMode.end())
+            return it->second;
+    }
     if (dataOrMgmtHeader->getReceiverAddress().isMulticast() && multicastFrameMode)
         return multicastFrameMode;
     if (dynamicPtrCast<const Ieee80211DataHeader>(dataOrMgmtHeader) && dataFrameMode)

src/inet/linklayer/ieee80211/mac/rateselection/RateSelection.h

@@ -48,16 +48,29 @@ class INET_API RateSelection : public IRateSelection, public SimpleModule, publi
     const physicallayer::IIeee80211Mode *responseAckFrameMode = nullptr;
     const physicallayer::IIeee80211Mode *responseCtsFrameMode = nullptr;
 
+    // per-receiver unicast data-frame modes, resolved lazily from dataFrameBitratePerReceiver
+    std::map<MacAddress, const physicallayer::IIeee80211Mode *> perReceiverDataFrameMode;
+    bool perReceiverResolved = false;
+
   protected:
     virtual int numInitStages() const override { return NUM_INIT_STAGES; }
     virtual void initialize(int stage) override;
     virtual void receiveSignal(cComponent *source, simsignal_t signalID, cObject *obj, cObject *details) override;
 
+    // Builds perReceiverDataFrameMode on first use. Deferred out of initialize() because peer
+    // MAC addresses are assigned during INITSTAGE_LINK_LAYER with undefined intra-stage module
+    // ordering; the first transmitted data frame occurs after all init stages, so this is race-free.
+    virtual void ensurePerReceiverModesResolved();
+
     virtual const physicallayer::IIeee80211Mode *getMode(Packet *packet, const Ptr<const Ieee80211MacHeader>& header);
     virtual const physicallayer::IIeee80211Mode *computeControlFrameMode(const Ptr<const Ieee80211MacHeader>& header);
     virtual const physicallayer::IIeee80211Mode *computeDataOrMgmtFrameMode(const Ptr<const Ieee80211DataOrMgmtHeader>& dataOrMgmtHeader);
 
   public:
+    // Per-receiver configured data-frame modes (resolved lazily from dataFrameBitratePerReceiver);
+    // used by the IEEE 802.11 rate visualizer to show configured rates before any traffic.
+    const std::map<MacAddress, const physicallayer::IIeee80211Mode *>& getPerReceiverDataFrameModes() { ensurePerReceiverModesResolved(); return perReceiverDataFrameMode; }
+
     static void setFrameMode(Packet *packet, const Ptr<const Ieee80211MacHeader>& header, const physicallayer::IIeee80211Mode *mode);
 
     // A control response frame is a control frame that is transmitted as a response to the reception of a frame a SIFS

src/inet/linklayer/ieee80211/mac/rateselection/RateSelection.ned

@@ -29,6 +29,14 @@ simple RateSelection extends SimpleModule like IRateSelection
         double dataFrameBandwidth @unit(Hz) = default(nan Hz); // Unspecified by default
         int dataFrameNumSpatialStreams = default(-1); // Unspecified by default
 
+        // Per-receiver unicast data-frame rate. Keys are peer interface module paths (e.g.
+        // "host1.wlan[0]"), resolved to MAC addresses at run time; values are bitrates (bps).
+        // A unicast data frame whose receiver matches a key is transmitted at that rate;
+        // unmatched receivers fall back to dataFrameBitrate / the rate-control module. The
+        // bandwidth and spatial-stream count are taken from dataFrameBandwidth /
+        // dataFrameNumSpatialStreams. Empty by default (capability inert).
+        object dataFrameBitratePerReceiver = default({});
+
         double mgmtFrameBitrate @unit(bps) = default(-1bps); // Fastest
         double controlFrameBitrate @unit(bps) = default(-1bps);
         @display("i=block/cogwheel");