LteCommon.h Source File¶

Simu5G: LteCommon.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.
//
 
//
//  Description:
//  This file contains LTE typedefs and constants.
//  At the end of the file there are some utility functions.
//
 
#ifndef _LTE_LTECOMMON_H_
#define _LTE_LTECOMMON_H_
 
#include <algorithm>
#include <bitset>
#include <fstream>
#include <iostream>
#include <list>
#include <map>
#include <optional>
#include <queue>
#include <set>
#include <sstream>
#include <string>
#include <vector>
 
#include <inet/common/packet/Packet.h>
#include <inet/common/Protocol.h>
#include <inet/common/Units.h>
#include <inet/common/geometry/Geometry_m.h>
#include <inet/networklayer/common/L3Address.h>
#include <inet/networklayer/contract/ipv4/Ipv4Address.h>
 
#include "simu5g/common/LteDefs.h"
#include "simu5g/common/LteTypes.h"
#include "simu5g/common/LteCommonEnum_m.h"
 
namespace inet {
class PacketFilter;
}
 
using namespace omnetpp;
 
using inet::Hz;
using inet::GHz;
 
namespace simu5g {
 
class Binder;
class CellInfo;
class LteMacEnb;
class LteMacBase;
class PhyBase;
class StochasticChannelModel;
class LteControlInfo;
class FlowControlInfo;
class ExtCell;
class IBackgroundTrafficManager;
class BackgroundScheduler;
class TrafficGeneratorBase;
class LteProtocol
{
  public:
    static const inet::Protocol pdcp;    // Packet Data Convergence Protocol
    static const inet::Protocol rlc;     // Radio Link Control
    static const inet::Protocol ltemac;  // LTE Medium Access Control
    static const inet::Protocol gtp;     // GPRS Tunneling Protocol
    static const inet::Protocol x2ap;    // X2AP Protocol
    static const inet::Protocol sdap;    // Service Data Adaptation Protocol
    static const inet::Protocol unstructured;   // The payload of an Unstructured session: opaque data, carried as is
};
 
// Identity of one flow/bearer instance between two ends, as used to request bearer
// establishment. This is the identity half of FlowControlInfo as a plain value: the
// packet tag is constructed FROM it, not the other way around.
struct FlowId {
    MacNodeId sourceId = NODEID_NONE;
    MacNodeId destId = NODEID_NONE;
    Direction direction = DL;
    DrbId drbId = DRBID_NONE;
    MacNodeId d2dGroupId = NODEID_NONE;
    MacNodeId d2dTxPeerId = NODEID_NONE;
    MacNodeId d2dRxPeerId = NODEID_NONE;
 
    DrbKey txDrbKey() const;    // same logic as ctrlInfoToTxDrbKey (D2D groupcast keys by group)
    DrbKey rxDrbKey() const;    // same logic as ctrlInfoToRxDrbKey
    FlowId reversed() const;    // same swaps as Binder's (former) makeReverseFlowControlInfo
};
 
inline std::ostream& operator<<(std::ostream& os, const FlowId& e)
{
    os << "src=" << e.sourceId << " dst=" << e.destId << " dir=" << e.direction << " drb=" << e.drbId
       << " d2dGroup=" << e.d2dGroupId << " d2dTx=" << e.d2dTxPeerId << " d2dRx=" << e.d2dRxPeerId;
    return os;
}
 
// Identity of an IP flow as the packet classifier sees it: the fields the flow -> DRB
// bindings of ~Ip2Nic are keyed by. Not a packet filter (yet): the fields match exactly,
// except that the plain-LTE stack stores a wildcard direction to keep its key
// direction-agnostic.
struct FlowBindingKey {
    inet::L3Address srcAddr;
    inet::L3Address dstAddr;
    uint16_t typeOfService = 0;
    Direction direction = DL;
 
    bool operator==(const FlowBindingKey& other) const {
        return srcAddr == other.srcAddr && dstAddr == other.dstAddr &&
               typeOfService == other.typeOfService && direction == other.direction;
    }
 
    // The same flow as seen from the other end: addresses swapped and direction
    // reversed (D2D and the wildcard direction map to themselves).
    FlowBindingKey reversed() const {
        Direction revDir = (direction == UL) ? DL : (direction == DL) ? UL : direction;
        return FlowBindingKey{dstAddr, srcAddr, typeOfService, revDir};
    }
};
 
inline std::ostream& operator<<(std::ostream& os, const FlowBindingKey& k)
{
    os << k.srcAddr << "->" << k.dstAddr << " tos=" << k.typeOfService << " dir=" << k.direction;
    return os;
}
 
struct FlowBindingKeyHash {
    static std::size_t hashAddress(const inet::L3Address& addr) {
        if (addr.getType() == inet::L3Address::IPv4)
            return std::hash<uint32_t>{}(addr.toIpv4().getInt());
        const uint32_t *w = addr.toIpv6().words();
        return std::hash<uint32_t>{}(w[0] ^ w[1] ^ w[2] ^ w[3]);
    }
    std::size_t operator()(const FlowBindingKey& key) const {
        std::size_t h1 = hashAddress(key.srcAddr);
        std::size_t h2 = hashAddress(key.dstAddr);
        std::size_t h3 = std::hash<uint16_t>{}(key.typeOfService);
        std::size_t h4 = std::hash<uint16_t>{}(uint16_t(key.direction));
        return h1 ^ (h2 << 1) ^ (h3 << 2) ^ (h4 << 3);
    }
};
 
// The configuration half of a bearer-establishment request: what the requester asks RRC
// to set the bearer up as. rlcMode = UNKNOWN_RLC_MODE means the requester states nothing;
// the bearer configurator then resolves the request from the bearer's definition entry
// before it reaches RRC. The D2D mode-switch path passes explicit values because it
// transports already-decided configuration.
struct BearerRequest {
    RlcMode rlcMode = UM;
    Lcg lcg = Lcg(0);   // logicalChannelGroup (mac-LogicalChannelConfig)
 
    // The flow whose classification triggered this establishment, if any: RRC binds it
    // to the bearer at both endpoints, so the reverse flow resolves to the same DRB
    // instead of establishing a second, parallel bearer. Absent when the requester
    // classifies by other means (SDAP maps QFIs) or establishes bearers up front
    // (the bearer configurator's static definitions).
    std::optional<FlowBindingKey> flowBindingKey;
};
 
inline std::ostream& operator<<(std::ostream& os, const BearerRequest& e)
{
    os << "rlcMode=" << e.rlcMode << " lcg=" << e.lcg << " hasFlowBindingKey=" << e.flowBindingKey.has_value();
    return os;
}
#define ELEM(x)            { x, #x }
#define TTI                0.001
#define NOW                simTime()
#define MAX_CODEWORDS      2
 
// Number of QCI classes
#define LTE_QCI_CLASSES    9
 
 
// specifies a list of bands that can be used by a user
typedef std::vector<Band> UsableBands;
 
// maps a user with a set of usable bands. If a UE is not in the list, the set of usable bands comprises the whole spectrum
typedef std::map<MacNodeId, UsableBands> UsableBandsList;
typedef unsigned short Codeword;
typedef unsigned short NumerologyIndex;
 
// Attenuation vector for analogue models
typedef std::vector<double> AttenuationVector;
 
 
/*************************
*   Transmission Modes  *
*************************/
const unsigned char DL_NUM_TXMODE = 6; //UNKNOWN_TX_MODE;
const unsigned char UL_NUM_TXMODE = 6; //UNKNOWN_TX_MODE;
 
 
const unsigned int txModeToIndex[2] = { 0, 1 };
 
const TxMode indexToTxMode[2] = {
    SINGLE_ANTENNA_PORT0,
    TRANSMIT_DIVERSITY
};
 
typedef std::map<MacNodeId, TxMode> TxModeMap;
 
const double cqiToByteTms[16] = { 0, 2, 3, 5, 11, 15, 20, 25, 36, 38, 49, 63, 72, 79, 89, 92 };
 
double dBmToLinear(double dbm);
double dBToLinear(double db);
double linearToDBm(double lin);
double linearToDb(double lin);
 
 
/*****************
* X2 Support
*****************/
 
class X2InformationElement;
typedef std::list<X2InformationElement *> X2InformationElementsList;
struct BandLimit
{
    Band band_;
    std::vector<int> limit_;
 
    BandLimit() : band_(0)
    {
        limit_.resize(MAX_CODEWORDS, -1);
    }
 
    // default "from Band" constructor
    BandLimit(Band b) : band_(b)
    {
        limit_.resize(MAX_CODEWORDS, -1);
    }
 
    bool operator<(const BandLimit rhs) const
    {
        return limit_[0] > rhs.limit_[0];
    }
 
};
 
typedef std::vector<BandLimit> BandLimitVector;
 
/*****************
* LTE Constants
*****************/
 
const unsigned char MAXCW = 2;
const Cqi MAXCQI = 15;
const Cqi NOSIGNALCQI = 0;
const Rank NORANK = 1;
const Tbs CQI2ITBSSIZE = 29;
const unsigned int PDCP_HEADER_UM = 1;
const unsigned int PDCP_HEADER_AM = 2;
// Flat RLC header sizes used by the LTE TS 36.322 UM/AM path (and by the LTE AM STATUS
// PDU, see LteRlcAmRxEntity::sendStatusReportLte). These are fixed approximations: the LTE
// header/STATUS size does not vary with the SN field length, the segmentation state, or
// the NACK count. The NR TS 38.322 SO path instead sizes each PDU exactly via
// nrUmHeaderBytes()/nrAmHeaderBytes() below; making LTE AM equally faithful is future work.
const unsigned int RLC_HEADER_UM = 2;
const unsigned int RLC_HEADER_AM = 2;
 
// NR-SO RLC header size (bytes) by segment state, so the TX and the scheduler agree on the
// exact per-PDU header. snBits is the SN field length carried by this flow (UM 6/12, AM
// 12/18 per TS 38.322); the byte size is computed by octet-aligning the fixed fields + SN
// and adding the 16-bit SO on a non-first (continuation) segment.
enum NrUmSegState { NRUM_COMPLETE = 0, NRUM_FIRST = 1, NRUM_CONTINUATION = 2 };
 
// UM (TS 38.322 6.2.1.3): complete SDU = SI+R = 1B (no SN/SO); first segment = SI(2)+SN,
// byte-aligned (6-bit SN -> 1B, 12-bit -> 2B); continuation = that + SO(16b) (3B / 4B).
inline unsigned int nrUmHeaderBytes(NrUmSegState s, unsigned int snBits)
{
    if (s == NRUM_COMPLETE)
        return 1u;                          // SI + R, no SN
    unsigned int base = (2u + snBits + 7u) / 8u;            // SI(2) + SN, octet-aligned
    return (s == NRUM_CONTINUATION) ? base + 2u : base;     // + SO(16b) on a continuation
}
 
 
// AM (TS 38.322 6.2.1.4): an AMD PDU always carries the SN. complete/first = D/C+P+SI(4)+SN,
// byte-aligned (12-bit SN -> 2B, 18-bit -> 3B); continuation adds the SO(16b) (4B / 5B).
inline unsigned int nrAmHeaderBytes(NrUmSegState s, unsigned int snBits)
{
    unsigned int base = (4u + snBits + 7u) / 8u;            // D/C+P+SI(4) + SN, octet-aligned
    return (s == NRUM_CONTINUATION) ? base + 2u : base;     // + SO(16b) on a continuation
}
const unsigned int MAC_HEADER = 2;
const unsigned int MAXGRANT = 4294967295U;
 
/*****************
* MAC Support
*****************/
 
class LteMacBuffer;
class LteMacQueue;
class MacControlElement;
class LteMacPdu;
typedef std::map<std::pair<MacCid, Codeword>, unsigned int> LteMacScheduleList;
typedef std::map<std::pair<MacNodeId, Codeword>, inet::Packet *> MacPduList;
 
/*
 * Codeword list : for each node, it keeps track of allocated codewords (number)
 */
typedef std::map<MacNodeId, unsigned int> LteMacAllocatedCws;
typedef std::list<inet::Packet *> RlcSduList;
typedef std::list<size_t> RlcSduListSizes;
typedef cPacketQueue MacSduList;
typedef std::list<MacControlElement *> MacControlElementsList;
typedef std::set<MacNodeId> UeSet;
 
/*****************
* HARQ Support
*****************/
#define HARQ_NONE                255
#define HARQ_TX_INTERVAL         7 * TTI
 
// Codeword List - returned by Harq functions
typedef std::list<Codeword> CwList;
typedef std::pair<unsigned char, CwList> UnitList;
 
/*********************
* Incell Interference Support
*********************/
struct EnbInfo
{
    bool init;         // initialization flag
    bool isNr;        // eNodeB or gNodeB
    EnbType type;     // MICRO_ENB or MACRO_ENB
    double txPwr;
    TxDirectionType txDirection;
    double txAngle;
    MacNodeId id;
    PhyBase *phy = nullptr;
    LteMacEnb *mac = nullptr;
    StochasticChannelModel *realChan = nullptr;
    opp_component_ptr<cModule> eNodeB;
    int x2;
    std::string str() const;
};
 
struct UeInfo
{
    bool init;         // initialization flag
    double txPwr;
    MacNodeId id;
    MacNodeId cellId;
    StochasticChannelModel *realChan = nullptr;
    opp_component_ptr<cModule> ue;
    PhyBase *phy = nullptr;
    std::string str() const;
};
 
/**********************************
 * Background UEs avg CQI support *
 *********************************/
struct BgTrafficManagerInfo
{
    bool init;         // initialization flag
    IBackgroundTrafficManager *bgTrafficManager = nullptr;
    GHz carrierFrequency;
    double allocatedRbsDl;
    double allocatedRbsUl;
    std::vector<double> allocatedRbsUeUl;
    std::string str() const;
};
 
// uplink interference support
struct UeAllocationInfo {
    MacNodeId nodeId;
    MacCellId cellId;
    PhyBase *phy = nullptr;
    TrafficGeneratorBase *trafficGen = nullptr;
    Direction dir;
};
 
inline std::ostream& operator<<(std::ostream& os, const UeAllocationInfo& e)
{
    os << "node=" << e.nodeId << " cell=" << e.cellId << " dir=" << e.dir;
    return os;
}
 
typedef std::vector<ExtCell *> ExtCellList;
typedef std::vector<BackgroundScheduler *> BackgroundSchedulerList;
 
/*****************
*  PHY Support  *
*****************/
 
typedef std::vector<std::vector<std::vector<double>>> BlerCurves;
 
struct SlotFormat {
    bool tdd;
    unsigned int numDlSymbols;
    unsigned int numUlSymbols;
    unsigned int numFlexSymbols;
};
 
inline std::ostream& operator<<(std::ostream& os, const SlotFormat& e)
{
    os << "tdd=" << e.tdd << " dl=" << e.numDlSymbols << " ul=" << e.numUlSymbols << " flex=" << e.numFlexSymbols;
    return os;
}
 
struct CarrierInfo {
    GHz carrierFrequency;
    unsigned int numBands;
    unsigned int firstBand;
    unsigned int lastBand;
    BandLimitVector bandLimit;
    NumerologyIndex numerologyIndex;
    SlotFormat slotFormat;
};
 
inline std::ostream& operator<<(std::ostream& os, const CarrierInfo& e)
{
    os << "freq=" << e.carrierFrequency << " numBands=" << e.numBands
       << " bands=[" << e.firstBand << "," << e.lastBand << "] numerology=" << e.numerologyIndex
       << " slot={" << e.slotFormat << "} bandLimitEntries=" << e.bandLimit.size();
    return os;
}
 
typedef std::map<GHz, CarrierInfo> CarrierInfoMap;
 
/*************************************
* Shortcut for structures using STL
*************************************/
 
typedef std::vector<Cqi> CqiVector;
typedef std::set<Band> BandSet;
typedef std::set<Remote> RemoteSet;
typedef std::map<MacNodeId, bool> ConnectedUesMap;
typedef std::pair<int, simtime_t> PacketInfo;
typedef std::set<MacNodeId> ActiveUser;
typedef std::set<MacCid> ActiveSet;
typedef std::map<std::string, cMsgPar> ParameterMap;
 
/*********************
* Utility functions
*********************/
 
const std::string dirToA(Direction dir);
Direction directionFromBsrLcid(LogicalCid lcid, Direction fallback);
const std::string d2dModeToA(LteD2DMode mode);
const std::string allocationTypeToA(RbAllocationType type);
const std::string modToA(LteMod mod);
const std::string periodicityToA(FbPeriodicity per);
const std::string txModeToA(TxMode tx);
TxMode aToTxMode(std::string s);
const std::string schedDisciplineToA(SchedDiscipline discipline);
SchedDiscipline aToSchedDiscipline(std::string s);
Remote aToDas(std::string s);
const std::string dasToA(const Remote r);
const char *nodeTypeToA(RanNodeType t);
RanNodeType aToNodeType(std::string name);
RanNodeType getNodeTypeById(MacNodeId id);
bool isBaseStation(CoreNodeType nodeType);
void verifyControlInfo(const FlowControlInfo *info);
bool isNrUe(MacNodeId id);
FeedbackType getFeedbackType(std::string s);
RbAllocationType getRbAllocationType(std::string s);
const std::string phyFrameTypeToA(const LtePhyFrameType r);
LtePhyFrameType aToPhyFrameType(std::string s);
const std::string rlcModeToA(RlcMode type);
char *cStringToLower(char *str);
RlcMode aToRlcMode(std::string s);
const std::string sessionTypeToA(SessionType type);
SessionType aToSessionType(std::string s);
bool isIpSessionType(SessionType type);   // IPv4, IPv6 or IPv4v6
const std::string coreNetworkToA(CoreNetwork type);
CoreNetwork aToCoreNetwork(std::string s);
const std::string cellGroupToA(CellGroup group);
CellGroup aToCellGroup(std::string s);
 
// Configure an inet::PacketFilter from its string form: an expression written as
// "expr(...)", or a message-name pattern. Parse errors throw here, at setup time.
void configurePacketFilter(inet::PacketFilter& filter, const char *spec);
 
// Take the expr() value of a policy parameter as an evaluatable expression, bound to
// the given variable resolver (whose ownership passes to the expression). The returned
// expression is the caller's to delete. Parameters holding anything but an expr()
// throw here, at setup time.
omnetpp::cDynamicExpression *getExpressionFromPar(omnetpp::cPar& par, omnetpp::cDynamicExpression::IResolver *resolver);
const std::string planeToA(Plane p);
MacNodeId ctrlInfoToUeId(const FlowControlInfo *info);
DrbKey ctrlInfoToTxDrbKey(const FlowControlInfo *info); // DrbKey for TX context: key by dest (remote receiver)
DrbKey ctrlInfoToRxDrbKey(const FlowControlInfo *info); // DrbKey for RX context: key by source (remote sender)
const std::string DeploymentScenarioToA(DeploymentScenario type);
DeploymentScenario aToDeploymentScenario(std::string s);
inline bool isMulticastDestId(MacNodeId nodeId) {
    return num(nodeId) >= MULTICAST_DEST_MIN_ID;
}
void getParametersFromXML(cXMLElement *xmlData, ParameterMap& outputMap);
void parseStringToIntArray(std::string str, int *values, int dim, int pad);
void initializeAllChannels(cModule *mod);
 
void removeAllSimu5GTags(inet::Packet *pkt);
 
template<typename T>
bool checkIfHeaderType(const inet::Packet *pkt, bool checkFirst = false) {
 
    auto pktAux = pkt->dup();
 
    int index = 0;
    while (pktAux->getBitLength() > 0 && pktAux->peekAtFront<inet::Chunk>()) {
        auto chunk = pktAux->popAtFront<inet::Chunk>();
        if (inet::dynamicPtrCast<const T>(chunk)) {
            delete pktAux;
            if (index != 0 && checkFirst)
                throw cRuntimeError("The header is not the top");
            return true;
        }
        index++;
    }
    delete pktAux;
    return false;
}
 
} //namespace
 
#endif