nr-spectrum-phy.h

// Copyright (c) 2020 Centre Tecnologic de Telecomunicacions de Catalunya (CTTC)
//
// SPDX-License-Identifier: GPL-2.0-only
 
#ifndef NR_SPECTRUM_PHY_H
#define NR_SPECTRUM_PHY_H
 
#include "beam-manager.h"
#include "nr-chunk-processor.h"
#include "nr-control-messages.h"
#include "nr-harq-phy.h"
#include "nr-interference.h"
#include "nr-phy.h"
#include "nr-spectrum-signal-parameters.h"
 
#include "ns3/matrix-based-channel-model.h"
#include "ns3/net-device.h"
#include "ns3/random-variable-stream.h"
#include "ns3/spectrum-channel.h"
#include "ns3/traced-callback.h"
 
#include <functional>
 
namespace ns3
{
 
class UniformPlanarArray;
 
class NrSpectrumPhy : public SpectrumPhy
{
  public:
    static TypeId GetTypeId();
 
    NrSpectrumPhy();
 
    ~NrSpectrumPhy() override;
 
    enum State
    {
        IDLE = 0,   
        TX,         
        RX_DATA,    
        RX_DL_CTRL, 
        RX_UL_CTRL, 
        RX_UL_SRS,  
        CCA_BUSY    
    };
 
    // callbacks typedefs and setters
    typedef Callback<void, const Ptr<Packet>&> NrPhyRxDataEndOkCallback;
    typedef std::function<void(const std::list<Ptr<NrControlMessage>>&, uint8_t)>
        NrPhyRxCtrlEndOkCallback;
 
    typedef Callback<void, uint16_t, const Ptr<SpectrumValue>&> NrPhyRxPssCallback;
 
    typedef Callback<void, const DlHarqInfo&> NrPhyDlHarqFeedbackCallback;
    typedef Callback<void, const UlHarqInfo&> NrPhyUlHarqFeedbackCallback;
 
    void SetPhyRxDataEndOkCallback(const NrPhyRxDataEndOkCallback& c);
    void SetPhyRxCtrlEndOkCallback(const NrPhyRxCtrlEndOkCallback& c);
 
    void SetPhyRxPssCallback(const NrPhyRxPssCallback& c);
 
    void SetPhyDlHarqFeedbackCallback(const NrPhyDlHarqFeedbackCallback& c);
    void SetPhyUlHarqFeedbackCallback(const NrPhyUlHarqFeedbackCallback& c);
 
    // Methods inherited from spectrum phy
    void SetDevice(Ptr<NetDevice> d) override;
    Ptr<NetDevice> GetDevice() const override;
    void SetMobility(Ptr<MobilityModel> m) override;
    Ptr<MobilityModel> GetMobility() const override;
    void SetChannel(Ptr<SpectrumChannel> c) override;
    Ptr<const SpectrumModel> GetRxSpectrumModel() const override;
    /*
     * @brief Sets the beam manager of this spectrum phy, and that beam manager
     * is responsible for the antenna array of this spectrum phy
     */
    void SetBeamManager(Ptr<BeamManager> b);
 
    void AddBeamManager(Ptr<BeamManager> b);
 
    void ConfigPanelsBearingAngles();
 
    void ConfigPanelsBearingAngles(double firstPanelBearingAngleRad);
 
    double CircularBearingAnglesForPanels(double firstPanelBearingAngleRad,
                                          uint8_t panelIndex) const;
 
    /*
     * @brief Gets the beam manager of this spectrum phy.
     */
    Ptr<BeamManager> GetBeamManager();
 
    /*
     * @brief Sets the error model of this spectrum phy, overriding the default
     * that is created by the attribute NrSpectrumPhy::ErrorModelType
     *
     * @param em The error model
     */
    void SetErrorModel(Ptr<NrErrorModel> em);
 
    /*
     * @brief Gets a pointer to the error model (if instantiated)
     * @return Pointer to the error model
     */
    Ptr<NrErrorModel> GetErrorModel() const;
 
    /*
     * @brief Gets a pointer to the NrPhy instance
     * @return Pointer to the NrPhy instance
     */
    Ptr<NrPhy> GetNrPhy() const;
 
    /*
     * @brief Get the time of the most recent start of reception
     * @return The time value of the most recent start of reception
     */
    Time GetFirstRxStart() const;
 
    /*
     * @brief Set the time of the most recent start of reception
     * @param startTime The time value of the most recent start of reception
     */
    void SetFirstRxStart(Time startTime);
 
    /*
     * @brief Get the duration of the most recent start of reception
     * @return The time value of the duration of the most recent start of reception
     */
    Time GetFirstRxDuration() const;
 
    /*
     * @brief Set the duration of the most recent start of reception
     * @param duration The time value of the duration of the most recent start of reception
     */
    void SetFirstRxDuration(Time duration);
 
    Ptr<Object> GetAntenna() const override;
 
    Ptr<Object> GetPanelByIndex(const uint8_t index) const;
 
    void SetNumPanels(const uint8_t numPanel);
 
    uint8_t GetNumPanels() const;
    /*
     * @brief Used to enable generation and triggering of DL DATA pathloss trace
     */
    void EnableDlDataPathlossTrace();
 
    /*
     * @brief Used to enable generation and triggering of DL CTRL pahtloss trace
     */
    void EnableDlCtrlPathlossTrace();
 
    void StartRx(Ptr<SpectrumSignalParameters> params) override;
 
    void SetRnti(uint16_t rnti);
 
    uint16_t GetRnti() const;
 
    // Attributes setters
    void SetCcaMode1Threshold(double thresholdDBm);
    double GetCcaMode1Threshold() const;
    void SetUnlicensedMode(bool unlicensedMode);
    void SetDataErrorModelEnabled(bool dataErrorModelEnabled);
    void SetErrorModelType(TypeId errorModelType);
 
    // other methods
    virtual void SetNoisePowerSpectralDensity(const Ptr<const SpectrumValue>& noisePsd);
    void SetTxPowerSpectralDensity(const Ptr<SpectrumValue>& txPsd);
    /*
     * @brief Returns a const pointer to the TX PSD
     * @return the TX PSD
     */
    Ptr<const SpectrumValue> GetTxPowerSpectralDensity();
    void StartTxDataFrames(const Ptr<PacketBurst>& pb,
                           const std::list<Ptr<NrControlMessage>>& ctrlMsgList,
                           const std::shared_ptr<DciInfoElementTdma> dci,
                           const Time& duration);
 
    bool IsTransmitting();
 
    void StartTxDlControlFrames(const std::list<Ptr<NrControlMessage>>& ctrlMsgList,
                                const Time& duration); // control frames from Gnb to ue
 
    void StartTxCsiRs(uint16_t rnti, uint16_t beamId);
 
    void StartTxUlControlFrames(const std::list<Ptr<NrControlMessage>>& ctrlMsgList,
                                const Time& duration);
    void AddDataPowerChunkProcessor(const Ptr<NrChunkProcessor>& p);
    void AddDataSinrChunkProcessor(const Ptr<NrChunkProcessor>& p);
 
    /*
     * @brief Adds the chunk processor that will process the interference for SRS signals at gNBs
     * @param p the chunk processor
     */
    void AddSrsSinrChunkProcessor(const Ptr<NrChunkProcessor>& p);
 
    void AddRsPowerChunkProcessor(const Ptr<NrChunkProcessor>& p);
 
    void AddDlCtrlSinrChunkProcessor(const Ptr<NrChunkProcessor>& p);
    void UpdateSinrPerceived(const SpectrumValue& sinr);
 
    void ReportDlCtrlSinr(const SpectrumValue& sinr);
 
    void UpdateSrsSinrPerceived(const SpectrumValue& srsSinr);
    void UpdateSrsSnrPerceived(const double srsSnr);
    void InstallPhy(const Ptr<NrPhy>& phyModel);
 
    Ptr<NrPhy> GetPhy() const;
    void SetAntenna(Ptr<Object> antenna);
 
    void AddPanel(const Ptr<Object> antenna);
 
    void SetActivePanel(const uint8_t panelIndex);
    Ptr<SpectrumChannel> GetSpectrumChannel() const;
    Ptr<NrInterference> GetNrInterference() const;
    void AddExpectedTb(ExpectedTb expectedTb);
 
    int64_t AssignStreams(int64_t stream);
 
    typedef void (*RxDataTracedCallback)(const SfnSf& sfnSf,
                                         Ptr<const SpectrumValue> v,
                                         const Time& t,
                                         uint16_t bwpId,
                                         uint16_t cellId);
 
    void AddExpectedSrsRnti(uint16_t rnti);
    void AddExpectedDlCtrlEnd(Time ctrlEndTime);
    /*
     * @brief SRS SINR callback whose input parameters are cellid, rnti, SRS SINR value
     */
    typedef Callback<void, uint16_t, uint16_t, double> SrsSinrReportCallback;
    typedef Callback<void, uint16_t, uint16_t, double> SrsSnrReportCallback;
 
    void AddSrsSinrReportCallback(SrsSinrReportCallback callback);
    void AddSrsSnrReportCallback(SrsSnrReportCallback callback);
    void SetIsGnb(bool isGnb);
    uint16_t GetCellId() const;
    uint16_t GetBwpId() const;
    typedef void (*DataSnrTracedCallback)(const SfnSf& sfnSf,
                                          const uint16_t cellId,
                                          const uint8_t bwpId,
                                          const uint64_t imsi,
                                          const double snr);
    void ReportWbDlDataSnrPerceived(const double dlDataSnr);
 
    void AddDataMimoChunkProcessor(const Ptr<NrMimoChunkProcessor>& p);
 
    void AddCsiRsMimoChunkProcessor(const Ptr<NrMimoChunkProcessor>& p);
 
    void AddCsiImMimoChunkProcessor(const Ptr<NrMimoChunkProcessor>& p);
 
    void UpdateMimoSinrPerceived(const std::vector<MimoSinrChunk>& sinr);
    bool IsGnb() const;
 
  protected:
    void DoDispose() override;
 
    State GetState() const;
 
    Ptr<SpectrumChannel> GetChannel() const;
 
    Ptr<UniformRandomVariable> GetErrorModelRv() const;
 
    void ChangeState(State newState, Time duration);
 
    void EndTx();
 
    void IncrementActiveTransmissions();
 
    void NotifyRxDataTrace(const SfnSf& sfn,
                           Ptr<const SpectrumValue> spectrumValue,
                           const Time& duration,
                           uint16_t bwpId,
                           uint16_t cellId) const;
 
    void NotifyTxCtrlTrace(Time duration) const;
 
    void NotifyTxDataTrace(Time duration) const;
 
  private:
    std::vector<MimoSinrChunk>
        m_mimoSinrPerceived; 
 
    void StartRxData(const Ptr<NrSpectrumSignalParametersDataFrame>& params);
    void StartRxDlCtrl(const Ptr<NrSpectrumSignalParametersDlCtrlFrame>& params);
    void StartRxUlCtrl(const Ptr<NrSpectrumSignalParametersUlCtrlFrame>& params);
    void StartRxCsiRs(const Ptr<NrSpectrumSignalParametersCsiRs>& csiRsParams);
    void StartRxSrs(const Ptr<NrSpectrumSignalParametersUlCtrlFrame>& params);
    void CheckIfCsiImNeeded(const Ptr<NrSpectrumSignalParametersCsiRs>& csiRsParams);
 
    std::vector<MimoSinrChunk> GetMimoSinrForRnti(uint16_t rnti, uint8_t rank);
 
    void EndRxData();
    void ScheduleCsiIm(Ptr<SpectrumSignalParameters> csiRsParams) const;
    bool IsUeScheduled() const;
    void EndRxCtrl();
    void EndRxSrs();
    void MaybeCcaBusy();
    void CheckIfStillBusy();
    bool IsOnlySrs(const std::list<Ptr<NrControlMessage>>& ctrlMsgList);
 
    Ptr<MatrixBasedChannelModel::Complex3DVector> CreateSpectrumChannelMatrix(
        const Ptr<SpectrumSignalParameters> params) const;
 
    void CheckTransportBlockCorruptionStatus();
 
    void ProcessReceivedPacketBurst();
 
    void SendUlHarqFeedback(uint16_t rnti, TransportBlockInfo& tbInfo);
 
    DlHarqInfo SendDlHarqFeedback(uint16_t rnti, TransportBlockInfo& tbInfo);
 
    // attributes
    TypeId m_errorModelType{
        Object::GetTypeId()}; 
    bool m_dataErrorModelEnabled{
        true}; 
    double m_ccaMode1ThresholdW{0}; 
                                    //   CcaMode1Threshold and is configured in dBm
    bool m_unlicensedMode{
        false}; 
                //   Unlicensed mode additionally to licensed mode allows channel monitoring to
                //   discover if is busy before transmission.
 
    Ptr<SpectrumChannel> m_channel{
        nullptr}; 
    Ptr<const SpectrumModel> m_rxSpectrumModel{
        nullptr};                                 
    std::vector<Ptr<BeamManager>> m_beamManagers; 
    Ptr<MobilityModel> m_mobility{
        nullptr}; 
    Ptr<NetDevice> m_device{nullptr}; 
    Ptr<NrPhy> m_phy{nullptr}; 
    Ptr<NrErrorModel> m_errorModel{nullptr}; 
    std::vector<Ptr<Object>>
        m_antennaPanels; 
    Ptr<NrInterference> m_interferenceData{nullptr}; 
    Ptr<NrInterference> m_interferenceCtrl{nullptr}; 
    Ptr<NrInterference> m_interferenceSrs{
        nullptr}; 
    Ptr<NrInterference> m_interferenceCsiRs{
        nullptr}; 
    Ptr<NrInterference> m_interferenceCsiIm{
        nullptr}; 
 
    Ptr<SpectrumValue> m_txPsd{nullptr};          
    Ptr<UniformRandomVariable> m_random{nullptr}; 
 
    NrHarqPhy m_harqPhyModule; 
 
    std::unordered_map<uint16_t, TransportBlockInfo>
        m_transportBlocks; 
    std::list<Ptr<PacketBurst>> m_rxPacketBurstList; 
    std::list<Ptr<NrControlMessage>>
        m_rxControlMessageList; 
 
    Time m_firstRxStart{
        Seconds(0)}; 
    Time m_firstRxDuration{Seconds(0)}; 
    State m_state{IDLE};                
    SpectrumValue m_sinrPerceived; 
 
    uint16_t m_rnti{0};    
    bool m_hasRnti{false}; 
    uint16_t m_activeTransmissions{0}; 
 
    std::list<SrsSinrReportCallback> m_srsSinrReportCallback; 
    std::list<SrsSnrReportCallback> m_srsSnrReportCallback;   
    uint16_t m_currentSrsRnti{0};
    Time m_ctrlEndTime;           
    EventId m_checkIfIsIdleEvent; 
    Time m_busyTimeEnds{
        Seconds(0)}; 
 
    // callbacks for CTRL and DATA, and UL/DL HARQ
    NrPhyRxCtrlEndOkCallback
        m_phyRxCtrlEndOkCallback; 
    NrPhyRxDataEndOkCallback
        m_phyRxDataEndOkCallback;          
    NrPhyRxPssCallback m_phyRxPssCallback; 
    NrPhyDlHarqFeedbackCallback
        m_phyDlHarqFeedbackCallback; 
    NrPhyUlHarqFeedbackCallback
        m_phyUlHarqFeedbackCallback; 
    // traces
    TracedCallback<Time>
        m_channelOccupied; 
    TracedCallback<Time> m_txDataTrace; 
    TracedCallback<Time> m_txCtrlTrace; 
    TracedCallback<RxPacketTraceParams>
        m_rxPacketTraceGnb; 
    TracedCallback<RxPacketTraceParams>
        m_rxPacketTraceUe; 
    TracedCallback<GnbPhyPacketCountParameter>
        m_txPacketTraceGnb; 
    TracedCallback<const SfnSf&, Ptr<const SpectrumValue>, const Time&, uint16_t, uint16_t>
        m_rxDataTrace;
    TracedCallback<const SfnSf,
                   const uint16_t,
                   const uint8_t,
                   const uint64_t,
                   const double>
        m_dlDataSnrTrace; 
 
    /*
     * @brief Trace source that reports the following: Cell ID, Bwp ID, UE node ID, DL
     * CTRL pathloss
     */
    typedef TracedCallback<uint16_t, uint8_t, uint32_t, double> DlPathlossTrace;
    DlPathlossTrace m_dlCtrlPathlossTrace; 
    bool m_enableDlCtrlPathlossTrace =
        false; 
    /*
     * @brief Trace source that reports the following: Cell ID, Bwp ID, UE node ID, DL
     * CTRL pathloss, CQI that corresponds to the current SINR considering single port(rank 1).
     * This CQI value is added to the data pathloss trace to allow results filtering for the
     * calibration purposes, to compensate for the lack of RSSI based initial access and handover
     * features at the time this trace was added to 5G-LENA. Once these both features are part of
     * 5G-LENA, the CQI value should be removed from this trace. Also, notice that for MIMO
     * simulations this CQI value is based on the approximation of SINR, such as if it was used
     * a single port (rank 1), so this CQI value does not correspond to the CQI value that will
     * later be determined by PM search algorithm.
     */
    typedef TracedCallback<uint16_t, uint8_t, uint32_t, double, uint8_t> DlDataPathlossTrace;
    DlDataPathlossTrace m_dlDataPathlossTrace; 
    bool m_enableDlDataPathlossTrace =
        false;                   
    double m_dlDataPathloss = 0; // DL data pathloss calculated in StartRx, and used in trace in
                                 // EndRxData, i.e., when ProcessReceivedPacketBurst is called
    bool m_isGnb = false;
    uint8_t m_numPanels{1};        
    uint8_t m_activePanelIndex{0}; 
};
 
} // namespace ns3
 
#endif /* NR_SPECTRUM_PHY_H */