LteMacBase.h Source File¶

Simu5G: LteMacBase.h Source File
Simu5G
//
//                  Simu5G
//
// Copyright (C) 2012-2021 Giovanni Nardini, Giovanni Stea, Antonio Virdis et al. (University of Pisa)
// Copyright (C) 2022-2026 Giovanni Nardini, Giovanni Stea et al. (University of Pisa)
//
// This file is part of a software released under the license included in file
// "license.pdf". Please read LICENSE and README files before using it.
// The above files and the present reference are part of the software itself,
// and cannot be removed from it.
//
 
#ifndef _LTE_LTEMACBASE_H_
#define _LTE_LTEMACBASE_H_
 
#include <inet/common/ModuleRefByPar.h>
 
#include "simu5g/common/binder/Binder.h"
#include "simu5g/common/LteCommon.h"
#include "simu5g/common/LteControlInfo.h"
 
namespace simu5g {
 
using namespace omnetpp;
 
class LteHarqBufferTx;
class LteHarqBufferRx;
class Binder;
class FlowControlInfo;
class LteMacBuffer;
typedef std::map<MacNodeId, LteHarqBufferTx *> HarqTxBuffers;
typedef std::map<MacNodeId, LteHarqBufferRx *> HarqRxBuffers;
 
/*
 * MultiMap associating a LCG group with all connections belonging to it and
 * corresponding virtual buffer pointer
 */
typedef std::pair<MacCid, LteMacBuffer *> CidBufferPair;
typedef std::pair<Lcg, CidBufferPair> LcgPair;
typedef std::multimap<Lcg, CidBufferPair> LcgMap;
 
// The RLC/logical-channel configuration of one logical channel, as the configuring
// entity (RRC) pushes it at bearer establishment via configureLogicalChannel().
// Mirrors the info MAC gets from RLC-BearerConfig / mac-LogicalChannelConfig in
// TS 38.331. One record per channel (MacCid = remote node + LCID), shared by the
// outgoing and incoming direction.
struct LogicalChannelConfig {
    RlcMode rlcMode = UM;            // rlc-Config: TM, UM or AM
    bool soFraming = false;             // wire format: false = LTE FI/concatenation (TS 36.322), true = NR SI/SO (TS 38.322)
    unsigned int snFieldLength = 12;    // sn-FieldLength, in bits
    Lcg lcg = Lcg(0);                   // logicalChannelGroup
};
 
inline std::ostream& operator<<(std::ostream& os, const LogicalChannelConfig& e) {
    os << "rlcMode=" << e.rlcMode << " soFraming=" << e.soFraming
       << " snFieldLength=" << e.snFieldLength << " lcg=" << e.lcg;
    return os;
}
class LteMacBase : public cSimpleModule
{
    friend class LteHarqBufferTx;
    friend class LteHarqBufferRx;
    // LteHarqBufferRxD2D needs the protected sendLowerPackets() (like LteHarqBufferRx);
    // LteHarqBufferTxD2D touches no protected LteMacBase member, so it is not a friend.
    // This is one of the three places the core names a class from the D2D package (the
    // other two are in LteSchedulerEnb.h, documented there). A name only: no include,
    // no NED import, no type lookup, so the core still builds with Simu5G_D2D disabled.
    // Dropping it would mean making sendLowerPackets() public, which would equally
    // dissolve LteHarqBufferRx's grant -- a core decision, not a D2D one.
    friend class LteHarqBufferRxD2D;
 
  protected:
 
    unsigned int totalOverflowedBytes_ = 0;
    static simsignal_t macBufferOverflowDlSignal_;
    static simsignal_t macBufferOverflowUlSignal_;
    static simsignal_t receivedPacketFromUpperLayerSignal_;
    static simsignal_t receivedPacketFromLowerLayerSignal_;
    static simsignal_t sentPacketToUpperLayerSignal_;
    static simsignal_t sentPacketToLowerLayerSignal_;
 
    /*
     * Data Structures
     */
    inet::ModuleRefByPar<Binder> binder_;
 
    /*
     * Gates
     */
    cGate *upInGate_ = nullptr;     
    cGate *upOutGate_ = nullptr;    
    cGate *downInGate_ = nullptr;   
    cGate *downOutGate_ = nullptr;  
 
    /*
     * MAC MIB Params
     */
    int harqProcesses_;
    cMessage *ttiTick_ = nullptr;
    double ttiPeriod_ = TTI;
    MacNodeId nodeId_ = NODEID_NONE;
 
    opp_component_ptr<cModule> networkNode_;
    MacCellId cellId_;
    unsigned int queueSize_;
 
  public:
    /*
     * Outgoing connection information structure
     * Consolidates connection descriptor, real buffer, and virtual buffer
     */
    struct OutgoingConnectionInfo {
        FlowDescriptor flowInfo;        // Connection flow information
        LteMacQueue *queue = nullptr;   // Real MAC buffer for actual packets
        LteMacBuffer *buffer = nullptr; // Virtual buffer for scheduling decisions
 
        OutgoingConnectionInfo() {}
        OutgoingConnectionInfo(const FlowDescriptor& info, LteMacQueue *q, LteMacBuffer *buf) : flowInfo(info), queue(q), buffer(buf) {}
    };
 
  protected:
    std::map<MacCid, OutgoingConnectionInfo> connDescOut_;
    std::map<GHz, MacPduList> macPduList_;
    std::map<GHz, HarqTxBuffers> harqTxBuffers_;
    std::map<GHz, HarqRxBuffers> harqRxBuffers_;
 
    /* Incoming Connection Descriptors:
     * a connection is stored at the first MAC SDU delivered to the RLC
     */
    std::map<MacCid, FlowDescriptor> connDescIn_;
    std::map<MacCid, LogicalChannelConfig> lcConfig_;
 
    /* LCG to CID and buffers map - used for supporting LCG - based scheduler operations
     * TODO: delete/update entries on handover
     */
    LcgMap lcgMap_;
 
    // Node Type
    RanNodeType nodeType_;
 
    // LTE or NR
    bool isNr_ = false;
 
    // record the last TTI that HARQ processes for a given UE have been aborted (useful for D2D switching)
    std::map<MacNodeId, simtime_t> resetHarq_;
 
    // reference to the phy layer
    opp_component_ptr<PhyBase> phy_;
 
    // signals for PacketFlowObserver
    static simsignal_t macPduAckedSignal_;
    static simsignal_t macPduDiscardedSignal_;
    static simsignal_t rlcPduDiscardedSignal_;
    static simsignal_t grantSentSignal_;
    static simsignal_t ulMacPduArrivedSignal_;
 
    // support to different numerologies
    struct NumerologyPeriodCounter {
        unsigned int max;
        unsigned int current;
 
        friend std::ostream& operator<<(std::ostream& os, const NumerologyPeriodCounter& e) {
            os << "max=" << e.max << " current=" << e.current;
            return os;
        }
    };
    std::map<NumerologyIndex, NumerologyPeriodCounter> numerologyPeriodCounter_;
 
    // statistics in visualization
    bool statDisplay_;
    uint64_t nrFromUpper_ = 0;
    uint64_t nrFromLower_ = 0;
    uint64_t nrToUpper_ = 0;
    uint64_t nrToLower_ = 0;
 
    // support to print harqErrorRate at the end of the simulation
    unsigned int totalHarqErrorRateDlSum_ = 0;
    unsigned int totalHarqErrorRateUlSum_ = 0;
    unsigned int totalHarqErrorRateDlCount_ = 0;
    unsigned int totalHarqErrorRateUlCount_ = 0;
 
  protected:
 
    unsigned int getNumerologyPeriodCounter(NumerologyIndex index) { return numerologyPeriodCounter_[index].current; }
    virtual void decreaseNumerologyPeriodCounter();
 
  public:
    ~LteMacBase() override;
    virtual void deleteQueues(MacNodeId nodeId);
    virtual void deleteQueuesRadioLinkFailure(MacNodeId nodeId);
 
    //* public utility function - drops ownership of an object
    void dropObj(cOwnedObject *obj)
    {
        drop(obj);
    }
 
    //* public utility function - takes ownership of an object
    void takeObj(cOwnedObject *obj)
    {
        take(obj);
    }
 
    /*
     * DRB ID <-> LCID mapping
     *
     * In the current implementation, DRB IDs (used in PDCP/RLC) map 1:1 to
     * Logical Channel IDs (used in MAC). These methods make the mapping explicit.
     */
    LogicalCid drbIdToLcid(DrbId drbId) { return LogicalCid(num(drbId)); }
    DrbId lcidToDrbId(LogicalCid lcid) { return DrbId(num(lcid)); }
    virtual MacCid ctrlInfoToMacCid(const FlowControlInfo *info) {
        return MacCid(ctrlInfoToUeId(info), drbIdToLcid(info->getDrbId()));
    }
 
    /*
     * Getters
     */
 
    double getTtiPeriod()
    {
        return ttiPeriod_;
    }
 
    PhyBase *getPhy()
    {
        return phy_;
    }
 
    MacNodeId getMacNodeId()
    {
        ASSERT(nodeId_ != NODEID_NONE);
        return nodeId_;
    }
 
    MacCellId getMacCellId()
    {
        return cellId_;
    }
 
    // Returns the virtual buffer for a specific CID
    LteMacBuffer* getMacBuffer(MacCid cid)
    {
        auto it = connDescOut_.find(cid);
        if (it == connDescOut_.end())
            throw cRuntimeError("LteMacBase::getMacBuffer - Buffer for CID %s not found", cid.str().c_str());
        return it->second.buffer;
    }
 
    // Returns list of active buffer CIDs
    std::vector<MacCid> getActiveMacBufferCids()
    {
        return getActiveConnectionCids();
    }
 
    // Returns the LCG-to-cid mapping
    const LcgMap& getLcgMap()
    {
        return lcgMap_;
    }
 
    // Returns flow control info for a specific CID
    const FlowDescriptor& getConnDesc(MacCid cid)
    {
        auto it = connDescOut_.find(cid);
        if (it == connDescOut_.end())
            throw cRuntimeError("LteMacBase: Connection %s not found", cid.str().c_str());
        return it->second.flowInfo;
    }
 
    // Returns list of active connection CIDs
    std::vector<MacCid> getActiveConnectionCids()
    {
        std::vector<MacCid> activeCids;
        activeCids.reserve(connDescOut_.size());
        for (const auto& [cid,_] : connDescOut_)
            activeCids.push_back(cid);
        return activeCids;
    }
 
    // Returns the harq tx buffers
    std::map<GHz, HarqTxBuffers> *getHarqTxBuffers()
    {
        return &harqTxBuffers_;
    }
 
    // Returns the harq rx buffers
    std::map<GHz, HarqRxBuffers> *getHarqRxBuffers()
    {
        return &harqRxBuffers_;
    }
 
    // Returns the harq tx buffers for the given carrier
    HarqTxBuffers *getHarqTxBuffers(GHz carrierFrequency)
    {
        if (harqTxBuffers_.find(carrierFrequency) == harqTxBuffers_.end())
            return nullptr;
        return &harqTxBuffers_[carrierFrequency];
    }
 
    // Returns the harq rx buffers for the given carrier
    HarqRxBuffers *getHarqRxBuffers(GHz carrierFrequency)
    {
        if (harqRxBuffers_.find(carrierFrequency) == harqRxBuffers_.end())
            return nullptr;
        return &harqRxBuffers_[carrierFrequency];
    }
 
    // Returns the outgoing connection information map (for iteration)
    const std::map<MacCid, OutgoingConnectionInfo>& getOutgoingConnectionInfoMap() const
    {
        return connDescOut_;
    }
 
    // Returns the incoming connection descriptor map (for iteration)
    const std::map<MacCid, FlowDescriptor>& getIncomingConnectionInfoMap() const
    {
        return connDescIn_;
    }
 
    // Returns number of Harq Processes
    unsigned int harqProcesses() const
    {
        return harqProcesses_;
    }
 
    RanNodeType getNodeType()
    {
        return nodeType_;
    }
 
    // check whether HARQ processes have been aborted during this TTI
    bool isHarqReset(MacNodeId srcId)
    {
        if (resetHarq_.find(srcId) != resetHarq_.end()) {
            if (resetHarq_[srcId] == NOW)
                return true;
        }
        return false;
    }
 
    // record that HARQ processes for the given node have been aborted during this TTI (e.g., D2D mode switch)
    void recordHarqReset(MacNodeId srcId)
    {
        resetHarq_[srcId] = NOW;
    }
 
    virtual void unregisterHarqBufferRx(MacNodeId nodeId);
    virtual void sendUpperPackets(cPacket *pkt);
 
    // visualization
    void refreshDisplay() const override;
 
    virtual void recordHarqErrorRate(unsigned int sample, Direction dir);
    virtual double getHarqErrorRate(Direction dir);
 
    /*
     * @author Alessandro Noferi
     *
     * methods called by mac layer and the HarqBuffers to notify
     * MAC pdus events to packetFlowObserver
     */
    virtual void harqAckToFlowObserver(const inet::Packet *macPdu);
    virtual void discardMacPdu(const inet::Packet *macPdu);
 
  protected:
 
    int numInitStages() const override { return inet::NUM_INIT_STAGES; }
    void initialize(int stage) override;
    void handleMessage(cMessage *msg) override;
    void deleteModule() override;
    virtual void handleSelfMessage() = 0;
    virtual void sendLowerPackets(cPacket *pkt);
 
    /*
     * Functions to be redefined by derived classes
     */
 
    virtual void macPduMake(MacCid cid = MacCid()) = 0;
    virtual void macPduUnmake(cPacket *pkt) = 0;
 
  public:
    virtual void createOutgoingConnection(MacCid cid, const FlowDescriptor& connInfo);
    virtual void deleteOutgoingConnection(MacCid cid);
    virtual void clearOutgoingConnectionBuffers(MacCid cid);
    virtual void createIncomingConnection(MacCid cid, const FlowDescriptor& connInfo);
    virtual void configureLogicalChannel(MacCid cid, const LogicalChannelConfig& cfg);
    const LogicalChannelConfig *findLogicalChannelConfig(MacCid cid) const
    {
        auto it = lcConfig_.find(cid);
        return it != lcConfig_.end() ? &it->second : nullptr;
    }
    const LogicalChannelConfig& getLogicalChannelConfig(MacCid cid) const;
 
  protected:
    virtual bool bufferizePacket(cPacket *pkt);
    virtual void handleUpperMessage(cPacket *pkt)
    {
        bufferizePacket(pkt);
    }
    virtual void macHandleFeedbackPkt(cPacket *pkt)
    {
    }
 
    /*
     * Receives and handles scheduling grants - implemented in LteMacUe
     */
    virtual void macHandleGrant(cPacket *pkt)
    {
    }
 
    /*
     * Receives and handles RAC requests (eNodeB implementation) and responses (LteMacUe implementation)
     */
    virtual void macHandleRac(cPacket *pkt)
    {
    }
 
    /*
     * Update UserTxParam stored in every lteMacPdu when an rtx changes this information
     */
    virtual void updateUserTxParam(cPacket *pkt) = 0;
    virtual void fromRlc(cPacket *pkt);
    virtual void fromPhy(cPacket *pkt);
    virtual LteHarqBufferRx *createRxHarqBuffer(MacNodeId src, const UserControlInfo *userInfo);
    virtual void recordBufferOverflow(Direction dir, double sample);
};
 
} //namespace
 
#endif