satellite-phy-rx-carrier.h

Go to the documentation of this file.

/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
 * Copyright (c) 2013 Magister Solutions Ltd.
 * Copyright (c) 2018 CNES
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License version 2 as
 * published by the Free Software Foundation;
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 * Author: Jani Puttonen <jani.puttonen@magister.fi>
 * Author: Mathias Ettinger <mettinger@toulouse.viveris.fr>
 */
 
#ifndef SATELLITE_PHY_RX_CARRIER_H
#define SATELLITE_PHY_RX_CARRIER_H
 
#include "satellite-enums.h"
#include "satellite-interference-elimination.h"
#include "satellite-interference.h"
#include "satellite-phy-rx-carrier-conf.h"
#include "satellite-phy-rx.h"
#include "satellite-phy.h"
#include "satellite-utils.h"
#include "satellite-wave-form-conf.h"
 
#include "ns3/mac48-address.h"
#include "ns3/object.h"
#include "ns3/ptr.h"
#include "ns3/traced-callback.h"
 
#include <deque>
#include <list>
#include <map>
#include <stdint.h>
#include <utility>
#include <vector>
 
namespace ns3
{
 
class Address;
class SatPhy;
class SatSignalParameters;
class SatLinkResults;
class SatChannelEstimationErrorContainer;
class SatNodeInfo;

class SatPhyRxCarrier : public Object
{
  public:
    typedef struct
    {
        Ptr<SatSignalParameters> rxParams;
        Mac48Address destAddress;
        Mac48Address sourceAddress;
        Mac48Address finalDestAddress;
        Mac48Address finalSourceAddress;
        Ptr<SatInterference::InterferenceChangeEvent> interferenceEvent;
    } rxParams_s;

    typedef void (*LinkBudgetTraceCallback)(Ptr<SatSignalParameters> rxParams,
                                            Mac48Address receiverAddress,
                                            Mac48Address destinationAddress,
                                            double interference,
                                            double sinr);

    typedef void (*RxPowerTraceCallback)(double rxPower, const Address& utAddress);

    typedef void (*LinkSinrTraceCallback)(double sinr, const Address& utAddress);

    typedef void (*PhyRxErrorCallback)(uint32_t nPackets, const Address& utAddress, bool isError);

    typedef void (*PhyRxCollisionCallback)(uint32_t nPackets,
                                           const Address& utAddress,
                                           bool isCollided);

    SatPhyRxCarrier(uint32_t carrierId,
                    Ptr<SatPhyRxCarrierConf> carrierConf,
                    Ptr<SatWaveformConf> waveformConf,
                    bool isRandomAccessEnabled);

    virtual ~SatPhyRxCarrier();

    enum State
    {
        IDLE,
        RX
    };

    enum CarrierType
    {
        BASE,
        DEDICATED_ACCESS,
        RA_SLOTTED_ALOHA,
        RA_CRDSA,
        RA_ESSA
    };

    static TypeId GetTypeId(void);

    void SetPhy(Ptr<SatPhy> phy);

    inline void SetSatId(uint32_t satId)
    {
        m_satId = satId;
    }

    inline uint32_t GetSatId()
    {
        return m_satId;
    }

    inline void SetBeamId(uint32_t beamId)
    {
        m_beamId = beamId;
    }

    inline uint32_t GetBeamId()
    {
        return m_beamId;
    }

    void SetNodeInfo(const Ptr<SatNodeInfo> nodeInfo);

    virtual bool StartRx(Ptr<SatSignalParameters> rxParams);

    inline virtual CarrierType GetCarrierType()
    {
        return BASE;
    }

    virtual void BeginEndScheduling();


    void SetReceiveCb(SatPhyRx::ReceiveCallback cb);

    void SetCnoCb(SatPhyRx::CnoCallback cb);

    void SetAverageNormalizedOfferedLoadCallback(
        SatPhyRx::AverageNormalizedOfferedLoadCallback callback);

    double GetRxTemperatureK()
    {
        return m_rxTemperatureK;
    }
 
  protected:
    inline virtual const bool GetDefaultReceiveMode()
    {
        return false;
    }

    inline bool IsReceivingDedicatedAccess()
    {
        return m_receivingDedicatedAccess;
    }

    inline Ptr<SatInterference> GetInterferenceModel()
    {
        return m_satInterference;
    }

    inline Ptr<SatInterferenceElimination> GetInterferenceEliminationModel()
    {
        return m_satInterferenceElimination;
    }

    virtual Ptr<SatInterference::InterferenceChangeEvent> CreateInterference(
        Ptr<SatSignalParameters> rxParams,
        Address rxAddress) = 0;


    std::pair<bool, SatPhyRxCarrier::rxParams_s> GetReceiveParams(
        Ptr<SatSignalParameters> rxParams);

    inline rxParams_s GetStoredRxParams(uint32_t key)
    {
        return m_rxParamsMap[key];
    }

    inline void StoreRxParams(uint32_t key, rxParams_s rxParams)
    {
        m_rxParamsMap[key] = rxParams;
    }

    inline void RemoveStoredRxParams(uint32_t key)
    {
        m_rxParamsMap.erase(key);
    }

    inline Mac48Address GetOwnAddress()
    {
        return m_ownAddress;
    }

    inline Ptr<SatNodeInfo> GetNodeInfo()
    {
        return m_nodeInfo;
    }

    void DoCompositeSinrOutputTrace(double cSinr);

    virtual void DoCreateInterferenceModel(Ptr<SatPhyRxCarrierConf> carrierConf,
                                           uint32_t carrierId,
                                           double rxBandwidthHz);

    virtual void DoCreateInterferenceEliminationModel(Ptr<SatPhyRxCarrierConf> carrierConf,
                                                      uint32_t carrierId,
                                                      Ptr<SatWaveformConf> waveformConf);

    inline virtual SatEnums::ChannelType_t GetChannelType()
    {
        return m_channelType;
    }

    inline void SetChannelType(SatEnums::ChannelType_t channelType)
    {
        m_channelType = channelType;
    }

    inline virtual SatEnums::RegenerationMode_t GetLinkRegenerationMode()
    {
        return m_linkRegenerationMode;
    }

    inline void SetLinkRegenerationMode(SatEnums::RegenerationMode_t linkRegenerationMode)
    {
        m_linkRegenerationMode = linkRegenerationMode;
    }

    void ChangeState(State newState);

    inline State GetState()
    {
        return m_state;
    }

    bool CheckAgainstLinkResults(double cSinr, Ptr<SatSignalParameters> rxParams);

    virtual void EndRxData(uint32_t key) = 0;

    const bool m_randomAccessEnabled;

    virtual void DoDispose();

    double CalculateSinr(double rxPowerW,
                         double ifPowerW,
                         double rxNoisePowerW,
                         double rxAciIfPowerW,
                         double rxExtNoisePowerW,
                         double otherInterference);

    double CalculateSinr(double sinr, double otherInterference);

    double CalculateCompositeSinr(double sinr1, double sinr2);

    double GetWorstSinr(double sinr1, double sinr2);

    void IncreaseNumOfRxState(SatEnums::PacketType_t packetType);

    void DecreaseNumOfRxState(SatEnums::PacketType_t packetType);

    void CheckRxStateSanity();

    inline uint32_t GetCarrierId() const
    {
        return m_carrierId;
    }

    inline Ptr<SatLinkResults> GetLinkResults()
    {
        return m_linkResults;
    }

    inline Ptr<SatWaveformConf> GetWaveformConf()
    {
        return m_waveformConf;
    }

    inline Ptr<SatChannelEstimationErrorContainer> GetChannelEstimationErrorContainer()
    {
        return m_channelEstimationError;
    }

    inline bool IsCompositeSinrOutputTraceEnabled() const
    {
        return m_enableCompositeSinrOutputTrace;
    }

    inline double GetUniformRandomValue(double min, double max)
    {
        return m_uniformVariable->GetValue(min, max);
    }


    double m_rxTemperatureK;

    double m_rxBandwidthHz;

    double m_rxExtNoisePowerW;

    double m_rxNoisePowerW;

    double m_rxAciIfPowerW;

    SatEnums::RegenerationMode_t m_linkRegenerationMode;


    TracedCallback<Ptr<SatSignalParameters>, // RX signalling parameters
                   Mac48Address,             // receiver address
                   Mac48Address,             // packet destination address
                   double,                   // interference power
                   double                    // composite SINR
                   >
        m_linkBudgetTrace;

    TracedCallback<double, const Address&> m_rxPowerTrace;

    TracedCallback<double, const Address&> m_sinrTrace;

    TracedCallback<double, const Address&> m_linkSinrTrace;


    TracedCallback<uint32_t, const Address&, bool> m_daRxTrace;
 
    TracedCallback<uint32_t, const Address&> m_daRxCarrierIdTrace;

    SatPhyRxCarrierConf::AdditionalInterferenceCallback m_additionalInterferenceCallback;

    SatPhyRx::ReceiveCallback m_rxCallback;

    SatPhy::CnoCallback m_cnoCallback;

    SatPhy::AverageNormalizedOfferedLoadCallback m_avgNormalizedOfferedLoadCallback;
 
  private:
    bool CheckAgainstLinkResultsErrorModelAvi(double cSinr, Ptr<SatSignalParameters> rxParams);
 
    State m_state;                          //< Current state of the carrier
    uint32_t m_satId;                       //< Satellite ID
    uint32_t m_beamId;                      //< Beam ID
    uint32_t m_carrierId;                   //< Carrier ID
    bool m_receivingDedicatedAccess;        //< Is the carrier receiving a dedicated access packet
    Ptr<SatInterference> m_satInterference; //< Interference model
    Ptr<SatInterferenceElimination> m_satInterferenceElimination; //< Interference model
    bool m_enableCompositeSinrOutputTrace; //< Enable composite SINR output tracing

    uint32_t m_numOfOngoingRx;

    uint32_t m_rxPacketCounter;
 
    std::map<uint32_t, rxParams_s> m_rxParamsMap; //< Storage for Rx parameters by ID
    Mac48Address m_ownAddress;                    //< Carrier address
    Ptr<SatNodeInfo> m_nodeInfo;                  //< NodeInfo of the node where carrier is attached
    SatEnums::ChannelType_t m_channelType;        //< Channel type
    Ptr<SatLinkResults> m_linkResults;            //< Link results from the carrier configuration
    Ptr<SatWaveformConf> m_waveformConf;          //< Waveform configuration
    Ptr<UniformRandomVariable> m_uniformVariable; //< Uniform helper random variable
    SatPhyRxCarrierConf::ErrorModel m_errorModel; //< Error model
    double m_constantErrorRate;                   //< Error rate for constant error model

    Ptr<SatChannelEstimationErrorContainer> m_channelEstimationError;
};
 
} // namespace ns3
 
#endif /* SATELLITE_PHY_RX_CARRIER_H */