--- a/src/lte/helper/lte-helper.h Thu Oct 02 21:17:48 2014 -0700 +++ a/src/lte/helper/lte-helper.h Sun Oct 05 23:25:08 2014 +0300 @@ -50,7 +50,47 @@ /** * \ingroup lte - * \brief Creation and configuration of LTE entities + * Creation and configuration of LTE entities. One LteHelper instance is + * typically enough for an LTE simulation. To create it: + * + * Ptr lteHelper = CreateObject (); + * + * The general responsibility of the helper is to create various LTE objects + * and arrange them together to make the whole LTE system. The overall + * arrangement would look like the following: + * - Downlink spectrum channel + * + Path loss model + * + Fading model + * - Uplink spectrum channel + * + Path loss model + * + Fading model + * - eNodeB node(s) + * + Mobility model + * + eNodeB device(s) + * * Antenna model + * * eNodeB PHY (includes spectrum PHY, interference model, HARQ model) + * * eNodeB MAC + * * eNodeB RRC (includes RRC protocol) + * * Scheduler + * * Handover algorithm + * * FFR (frequency reuse) algorithm + * * ANR (automatic neighbour relation) + * + EPC related models (EPC application, Internet stack, X2 interface) + * - UE node(s) + * + Mobility model + * + UE device(s) + * * Antenna model + * * UE PHY (includes spectrum PHY, interference model, HARQ model) + * * UE MAC + * * UE RRC (includes RRC protocol) + * * NAS + * - EPC helper + * - Various statistics calculator objects + * + * Spetrum channels are created automatically: one for DL, and one for UL. + * eNodeB devices are created by calling InstallEnbDevice(), while UE devices + * are created by calling InstallUeDevice(). EPC helper can be set by using + * SetEpcHelper(). */ class LteHelper : public Object { @@ -61,10 +101,9 @@ static TypeId GetTypeId (void); virtual void DoDispose (void); - /** * Set the EpcHelper to be used to setup the EPC network in - * conjunction with the setup of the LTE radio access network + * conjunction with the setup of the LTE radio access network. * * \note if no EpcHelper is ever set, then LteHelper will default * to creating an LTE-only simulation with no EPC, using LteRlcSm as @@ -78,14 +117,16 @@ void SetEpcHelper (Ptr h); /** + * Set the type of path loss model to be used for both DL and UL channels. * - * - * \param type the type of pathloss model to be used for the eNBs + * \param type type of path loss model, must be a type name of any class + * inheriting from ns3::PropagationLossModel, for example: + * "ns3::FriisPropagationLossModel" */ void SetPathlossModelType (std::string type); /** - * set an attribute for the pathloss model to be created + * Set an attribute for the path loss models to be created. * * \param n the name of the attribute * \param v the value of the attribute @@ -93,8 +134,13 @@ void SetPathlossModelAttribute (std::string n, const AttributeValue &v); /** + * Set the type of scheduler to be used by eNodeB devices. * - * \param type the type of scheduler to be used for the eNBs + * \param type type of scheduler, must be a type name of any class + * inheriting from ns3::FfMacScheduler, for example: + * "ns3::PfFfMacScheduler" + * + * Equivalent with setting the `Scheduler` attribute. */ void SetSchedulerType (std::string type); @@ -105,7 +151,7 @@ std::string GetSchedulerType () const; /** - * set an attribute for the scheduler to be created + * Set an attribute for the scheduler to be created. * * \param n the name of the attribute * \param v the value of the attribute @@ -113,8 +159,13 @@ void SetSchedulerAttribute (std::string n, const AttributeValue &v); /** + * Set the type of FFR algorithm to be used by eNodeB devices. * - * \param type the type of FFR algorithm to be used for the eNBs + * \param type type of FFR algorithm, must be a type name of any class + * inheriting from ns3::LteFfrAlgorithm, for example: + * "ns3::LteFrNoOpAlgorithm" + * + * Equivalent with setting the `FfrAlgorithm` attribute. */ void SetFfrAlgorithmType (std::string type); @@ -125,7 +176,7 @@ std::string GetFfrAlgorithmType () const; /** - * set an attribute for the FFR algorithm to be created + * Set an attribute for the FFR algorithm to be created. * * \param n the name of the attribute * \param v the value of the attribute @@ -133,8 +184,13 @@ void SetFfrAlgorithmAttribute (std::string n, const AttributeValue &v); /** + * Set the type of handover algorithm to be used by eNodeB devices. * - * \param type the type of handover algorithm to be used for the eNBs + * \param type type of handover algorithm, must be a type name of any class + * inheriting from ns3::LteHandoverAlgorithm, for example: + * "ns3::NoOpHandoverAlgorithm" + * + * Equivalent with setting the `HandoverAlgorithm` attribute. */ void SetHandoverAlgorithmType (std::string type); @@ -145,7 +201,7 @@ std::string GetHandoverAlgorithmType () const; /** - * set an attribute for the handover algorithm to be created + * Set an attribute for the handover algorithm to be created. * * \param n the name of the attribute * \param v the value of the attribute @@ -153,43 +209,49 @@ void SetHandoverAlgorithmAttribute (std::string n, const AttributeValue &v); /** - * set an attribute for the LteEnbNetDevice to be created + * Set an attribute for the eNodeB devices (LteEnbNetDevice) to be created. * - * \param n the name of the attribute + * \param n the name of the attribute. * \param v the value of the attribute */ void SetEnbDeviceAttribute (std::string n, const AttributeValue &v); /** + * Set the type of antenna model to be used by eNodeB devices. * - * \param type the type of AntennaModel to be used for the eNBs + * \param type type of antenna model, must be a type name of any class + * inheriting from ns3::AntennaModel, for example: + * "ns3::IsotropicAntennaModel" */ void SetEnbAntennaModelType (std::string type); /** - * set an attribute for the AntennaModel to be used for the eNBs + * Set an attribute for the eNodeB antenna model to be created. * - * \param n the name of the attribute + * \param n the name of the attribute. * \param v the value of the attribute */ void SetEnbAntennaModelAttribute (std::string n, const AttributeValue &v); /** - * set an attribute for the LteUeNetDevice to be created + * Set an attribute for the UE devices (LteUeNetDevice) to be created. * - * \param n the name of the attribute + * \param n the name of the attribute. * \param v the value of the attribute */ void SetUeDeviceAttribute (std::string n, const AttributeValue &v); /** + * Set the type of antenna model to be used by UE devices. * - * \param type the type of AntennaModel to be used for the UEs + * \param type type of antenna model, must be a type name of any class + * inheriting from ns3::AntennaModel, for example: + * "ns3::IsotropicAntennaModel" */ void SetUeAntennaModelType (std::string type); /** - * set an attribute for the AntennaModel to be used for the UEs + * Set an attribute for the UE antenna model to be created. * * \param n the name of the attribute * \param v the value of the attribute @@ -197,13 +259,16 @@ void SetUeAntennaModelAttribute (std::string n, const AttributeValue &v); /** - * - * \param type the type of SpectrumChannel to be used for the UEs + * Set the type of spectrum channel to be used in both DL and UL. + * + * \param type type of spectrum channel model, must be a type name of any + * class inheriting from ns3::SpectrumChannel, for example: + * "ns3::MultiModelSpectrumChannel" */ void SetSpectrumChannelType (std::string type); /** - * set an attribute for the SpectrumChannel to be used for the UEs + * Set an attribute for the spectrum channel to be created (both DL and UL). * * \param n the name of the attribute * \param v the value of the attribute @@ -211,19 +276,17 @@ void SetSpectrumChannelAttribute (std::string n, const AttributeValue &v); /** - * create a set of eNB devices + * Create a set of eNodeB devices. * * \param c the node container where the devices are to be installed - * * \return the NetDeviceContainer with the newly created devices */ NetDeviceContainer InstallEnbDevice (NodeContainer c); /** - * create a set of UE devices + * Create a set of UE devices. * * \param c the node container where the devices are to be installed - * * \return the NetDeviceContainer with the newly created devices */ NetDeviceContainer InstallUeDevice (NodeContainer c); @@ -328,7 +391,7 @@ void AttachToClosestEnb (Ptr ueDevice, NetDeviceContainer enbDevices); /** - * Activate a dedicated EPS bearer on a given set of UE devices + * Activate a dedicated EPS bearer on a given set of UE devices. * * \param ueDevices the set of UE devices * \param bearer the characteristics of the bearer to be activated @@ -337,24 +400,23 @@ void ActivateDedicatedEpsBearer (NetDeviceContainer ueDevices, EpsBearer bearer, Ptr tft); /** - * Activate a dedicated EPS bearer on a given UE device + * Activate a dedicated EPS bearer on a given UE device. * * \param ueDevice the UE device * \param bearer the characteristics of the bearer to be activated - * \param tft the Traffic Flow Template that identifies the traffic to go on this bearer + * \param tft the Traffic Flow Template that identifies the traffic to go on this bearer. */ void ActivateDedicatedEpsBearer (Ptr ueDevice, EpsBearer bearer, Ptr tft); - /** - * Create an X2 interface between all the eNBs in a given set + * Create an X2 interface between all the eNBs in a given set. * * \param enbNodes the set of eNB nodes */ void AddX2Interface (NodeContainer enbNodes); /** - * Create an X2 interface between two eNBs + * Create an X2 interface between two eNBs. * * \param enbNode1 one eNB of the X2 interface * \param enbNode2 the other eNB of the X2 interface @@ -362,50 +424,51 @@ void AddX2Interface (Ptr enbNode1, Ptr enbNode2); /** - * \brief Manually trigger an X2-based handover of a UE between two eNBs at a - * specific simulation time. - * \param hoTime when the Handover is initiated + * Manually trigger an X2-based handover. + * + * \param hoTime when the handover shall be initiated * \param ueDev the UE that hands off, must be of the type LteUeNetDevice * \param sourceEnbDev source eNB, must be of the type LteEnbNetDevice * (originally the UE is attached to this eNB) * \param targetEnbDev target eNB, must be of the type LteEnbNetDevice - * (the UE is finally connected to this eNB) + * (the UE would be connected to this eNB after the + * handover) * - * \warning Requires the use of EPC mode. See SetEpcHelper() method. + * \warning Requires the use of EPC mode. See SetEpcHelper() method */ void HandoverRequest (Time hoTime, Ptr ueDev, Ptr sourceEnbDev, Ptr targetEnbDev); /** - * Call ActivateDataRadioBearer (ueDevice, bearer) for each UE - * device in a given set + * Activate a Data Radio Bearer on a given UE devices (for LTE-only simulation). * * \param ueDevices the set of UE devices - * \param bearer + * \param bearer the characteristics of the bearer to be activated */ void ActivateDataRadioBearer (NetDeviceContainer ueDevices, EpsBearer bearer); /** - * Activate a Data Radio Bearer for a simplified LTE-only simulation - * without EPC. This method will schedule the actual activation of + * Activate a Data Radio Bearer on a UE device (for LTE-only simulation). + * This method will schedule the actual activation * the bearer so that it happens after the UE got connected. * - * \param ueDevice the device of the UE for which the radio bearer - * is to be activated + * \param ueDevice the UE device * \param bearer the characteristics of the bearer to be activated */ void ActivateDataRadioBearer (Ptr ueDevice, EpsBearer bearer); /** + * Set the type of fading model to be used in both DL and UL. * - * - * \param model the fading model to be used + * \param type type of fading model, must be a type name of any class + * inheriting from ns3::SpectrumPropagationLossModel, for + * example: "ns3::TraceFadingLossModel" */ - void SetFadingModel (std::string model); + void SetFadingModel (std::string type); /** - * set an attribute of the fading model + * Set an attribute for the fading model to be created (both DL and UL). * * \param n the name of the attribute * \param v the value of the attribute @@ -413,8 +476,7 @@ void SetFadingModelAttribute (std::string n, const AttributeValue &v); /** - * Enables logging for all components of the LENA architecture - * + * Enables full-blown logging for major components of the LENA architecture. */ void EnableLogComponents (void); @@ -426,59 +488,57 @@ void EnableTraces (void); /** - * Enable trace sinks for PHY layer + * Enable trace sinks for PHY layer. */ void EnablePhyTraces (void); - - /** - * Enable trace sinks for DL PHY layer + * Enable trace sinks for DL PHY layer. */ void EnableDlPhyTraces (void); /** - * Enable trace sinks for UL PHY layer + * Enable trace sinks for UL PHY layer. */ void EnableUlPhyTraces (void); /** - * Enable trace sinks for DL transmission PHY layer + * Enable trace sinks for DL transmission PHY layer. */ void EnableDlTxPhyTraces (void); /** - * Enable trace sinks for UL transmission PHY layer + * Enable trace sinks for UL transmission PHY layer. */ void EnableUlTxPhyTraces (void); /** - * Enable trace sinks for DL reception PHY layer + * Enable trace sinks for DL reception PHY layer. */ void EnableDlRxPhyTraces (void); /** - * Enable trace sinks for UL reception PHY layer + * Enable trace sinks for UL reception PHY layer. */ void EnableUlRxPhyTraces (void); /** - * Enable trace sinks for MAC layer + * Enable trace sinks for MAC layer. */ void EnableMacTraces (void); /** - * Enable trace sinks for DL MAC layer + * Enable trace sinks for DL MAC layer. */ void EnableDlMacTraces (void); /** - * Enable trace sinks for UL MAC layer + * Enable trace sinks for UL MAC layer. */ void EnableUlMacTraces (void); /** - * Enable trace sinks for RLC layer + * Enable trace sinks for RLC layer. */ void EnableRlcTraces (void); @@ -499,21 +559,19 @@ */ Ptr GetPdcpStats (void); - enum LteEpsBearerToRlcMapping_t {RLC_SM_ALWAYS = 1, - RLC_UM_ALWAYS = 2, - RLC_AM_ALWAYS = 3, - PER_BASED = 4}; - /** - * Assign a fixed random variable stream number to the random variables - * used by this model. Return the number of streams (possibly zero) that - * have been assigned. The Install() method should have previously been - * called by the user. - * - * \param c NetDeviceContainer of the set of net devices for which the - * LteNetDevice should be modified to use a fixed stream - * \param stream first stream index to use - * \return the number of stream indices assigned by this helper + * Assign a fixed random variable stream number to the random variables used. + * + * The InstallEnbDevice() or InstallUeDevice method should have previously + * been called by the user on the given devices. + * + * If TraceFadingLossModel has been set as the fading model type, this method + * will also assign a stream number to it, if none has been assigned before. + * + * \param c NetDeviceContainer of the set of net devices for which the + * LteNetDevice should be modified to use a fixed stream + * \param stream first stream index to use + * \return the number of stream indices (possibly zero) that have been assigned */ int64_t AssignStreams (NetDeviceContainer c, int64_t stream); @@ -523,26 +581,27 @@ private: /** - * \brief Create an eNodeB device (LteEnbNetDevice) on the given node. + * Create an eNodeB device (LteEnbNetDevice) on the given node. * \param n the node where the device is to be installed * \return pointer to the created device */ Ptr InstallSingleEnbDevice (Ptr n); /** - * \brief Create a UE device (LteUeNetDevice) on the given node. + * Create a UE device (LteUeNetDevice) on the given node * \param n the node where the device is to be installed * \return pointer to the created device */ Ptr InstallSingleUeDevice (Ptr n); /** - * \brief The actual function to trigger a manual handover. + * The actual function to trigger a manual handover. * \param ueDev the UE that hands off, must be of the type LteUeNetDevice * \param sourceEnbDev source eNB, must be of the type LteEnbNetDevice * (originally the UE is attached to this eNB) * \param targetEnbDev target eNB, must be of the type LteEnbNetDevice - * (the UE is finally connected to this eNB) + * (the UE would be connected to this eNB after the + * handover) * * This method is normally scheduled by HandoverRequest() to run at a specific * time where a manual handover is desired by the simulation user. @@ -551,49 +610,101 @@ Ptr sourceEnbDev, Ptr targetEnbDev); + /// The downlink LTE channel used in the simulation. Ptr m_downlinkChannel; + /// The uplink LTE channel used in the simulation. Ptr m_uplinkChannel; - + /// The path loss model used in the downlink channel. Ptr m_downlinkPathlossModel; + /// The path loss model used in the uplink channel. Ptr m_uplinkPathlossModel; + /// Factory of MAC scheduler object. ObjectFactory m_schedulerFactory; + /// Factory of FFR (frequency reuse) algorithm object. ObjectFactory m_ffrAlgorithmFactory; + /// Factory of handover algorithm object. ObjectFactory m_handoverAlgorithmFactory; - ObjectFactory m_propagationModelFactory; + /// Factory of LteEnbNetDevice objects. ObjectFactory m_enbNetDeviceFactory; + /// Factory of antenna object for eNodeB. ObjectFactory m_enbAntennaModelFactory; + /// Factory for LteUeNetDevice objects. ObjectFactory m_ueNetDeviceFactory; + /// Factory of antenna object for UE. ObjectFactory m_ueAntennaModelFactory; - + /// Factory of path loss model object for the downlink channel. ObjectFactory m_dlPathlossModelFactory; + /// Factory of path loss model object for the uplink channel. ObjectFactory m_ulPathlossModelFactory; - + /// Factory of both the downlink and uplink LTE channels. ObjectFactory m_channelFactory; + /// Name of fading model type, e.g., "ns3::TraceFadingLossModel". std::string m_fadingModelType; + /// Factory of fading model object for both the downlink and uplink channels. ObjectFactory m_fadingModelFactory; + /// The fading model used in both the downlink and uplink channels. Ptr m_fadingModule; + /** + * True if a random variable stream number has been assigned for the fading + * model. Used to prevent such assignment to be done more than once. + */ bool m_fadingStreamsAssigned; + /// Container of PHY layer statistics. Ptr m_phyStats; + /// Container of PHY layer statistics related to transmission. Ptr m_phyTxStats; + /// Container of PHY layer statistics related to reception. Ptr m_phyRxStats; + /// Container of MAC layer statistics. Ptr m_macStats; + /// Container of RLC layer statistics. Ptr m_rlcStats; + /// Container of PDCP layer statistics. Ptr m_pdcpStats; + /// RadioBearerStatsConnector m_radioBearerStatsConnector; + /** + * Helper which provides implementation of core network. Initially empty + * (i.e., LTE-only simulation without any core network) and then might be + * set using SetEpcHelper(). + */ Ptr m_epcHelper; + /** + * Keep track of the number of IMSI allocated. Increases by one every time a + * new UE is installed (by InstallSingleUeDevice()). The first UE will have + * an IMSI of 1. The maximum number of UE is 2^64 (~4.2e9). + */ uint64_t m_imsiCounter; + /** + * Keep track of the number of cell ID allocated. Increases by one every time + * a new eNodeB is installed (by InstallSingleEnbDevice()). The first eNodeB + * will have a cell ID of 1. The maximum number of eNodeB is 65535. + */ uint16_t m_cellIdCounter; + /** + * The `UseIdealRrc` attribute. If true, LteRrcProtocolIdeal will be used for + * RRC signaling. If false, LteRrcProtocolReal will be used. + */ bool m_useIdealRrc; + /** + * The `AnrEnabled` attribute. Activate or deactivate Automatic Neighbour + * Relation function. + */ bool m_isAnrEnabled; + /** + * The `UsePdschForCqiGeneration` attribute. If true, DL-CQI will be + * calculated from PDCCH as signal and PDSCH as interference. If false, + * DL-CQI will be calculated from PDCCH as signal and PDCCH as interference. + */ + bool m_usePdschForCqiGeneration; - bool m_usePdschForCqiGeneration; -}; +}; // end of `class LteHelper` } // namespace ns3 --- a/src/lte/helper/radio-environment-map-helper.h Thu Oct 02 21:17:48 2014 -0700 +++ a/src/lte/helper/radio-environment-map-helper.h Sun Oct 05 23:25:08 2014 +0300 @@ -37,8 +37,9 @@ class MobilityModel; /** - * Generates a 2D map of the SINR from the strongest transmitter in the downlink of an LTE FDD system. - * + * Generates a 2D map of the SINR from the strongest transmitter in the + * downlink of an LTE FDD system. For instructions on usage, please refer to + * the User Documentation. */ class RadioEnvironmentMapHelper : public Object { @@ -70,54 +71,84 @@ private: + /** + * Scheduled by Install() to perform the actual generation of map. + * + * If control channel is used for SINR calculation (the default), the delay + * is 2.6 milliseconds from the start of simulation. Otherwise, if data + * channel is used, the delay is 500.1 milliseconds from the start of + * simulation. + * + * The method will divide the whole map into parts (each contains at most a + * certain number of SINR listening points), and then call RunOneIteration() + * on each part, one by one. + */ void DelayedInstall (); + + /** + * Mobilize all the listeners to a specified area. Afterwards, schedule a + * call to PrintAndReset() in 0.5 milliseconds. + * + * \param xMin X coordinate of the first SINR listening point to deploy. + * \param xMax X coordinate of the last SINR listening point to deploy. + * \param yMin Y coordinate of the first SINR listening point to deploy. + * \param yMax Y coordinate of the last SINR listening point to deploy. + */ void RunOneIteration (double xMin, double xMax, double yMin, double yMax); + + /// Go through every listener, write the computed SINR, and then reset it. void PrintAndReset (); + + /// Called when the map generation procedure has been completed. void Finalize (); - + /// A complete Radio Environment Map is composed of many of this structure. struct RemPoint { + /// Simplified listener which compute SINR over the DL channel. Ptr phy; + /// Position of the listener in the environment. Ptr bmm; }; + /// List of listeners in the environment. std::list m_rem; - double m_xMin; - double m_xMax; - uint16_t m_xRes; - double m_xStep; + double m_xMin; ///< The `XMin` attribute. + double m_xMax; ///< The `XMax` attribute. + uint16_t m_xRes; ///< The `XRes` attribute. + double m_xStep; ///< Distance along X axis between adjacent listening points. - double m_yMin; - double m_yMax; - uint16_t m_yRes; - double m_yStep; + double m_yMin; ///< The `YMin` attribute. + double m_yMax; ///< The `YMax` attribute. + uint16_t m_yRes; ///< The `YRes` attribute. + double m_yStep; ///< Distance along Y axis between adjacent listening points. - uint32_t m_maxPointsPerIteration; + uint32_t m_maxPointsPerIteration; ///< The `MaxPointsPerIteration` attribute. - uint16_t m_earfcn; - uint16_t m_bandwidth; + uint16_t m_earfcn; ///< The `Earfcn` attribute. + uint16_t m_bandwidth; ///< The `Bandwidth` attribute. - double m_z; + double m_z; ///< The `Z` attribute. - std::string m_channelPath; - std::string m_outputFile; + std::string m_channelPath; ///< The `ChannelPath` attribute. + std::string m_outputFile; ///< The `OutputFile` attribute. - bool m_stopWhenDone; + bool m_stopWhenDone; ///< The `StopWhenDone` attribute. + /// The channel object taken from the `ChannelPath` attribute. Ptr m_channel; - double m_noisePower; + double m_noisePower; ///< The `NoisePower` attribute. - std::ofstream m_outFile; + std::ofstream m_outFile; ///< Stream the output to a file. - bool m_useDataChannel; - int32_t m_rbId; + bool m_useDataChannel; ///< The `UseDataChannel` attribute. + int32_t m_rbId; ///< The `RbId` attribute. -}; +}; // end of `class RadioEnvironmentMapHelper` -} +} // end of `namespace ns3` #endif /* RADIO_ENVIRONMENT_MAP_HELPER_H */ --- a/src/lte/model/a2-a4-rsrq-handover-algorithm.cc Thu Oct 02 21:17:48 2014 -0700 +++ a/src/lte/model/a2-a4-rsrq-handover-algorithm.cc Sun Oct 05 23:25:08 2014 +0300 @@ -66,13 +66,17 @@ .SetParent () .AddConstructor () .AddAttribute ("ServingCellThreshold", - "If the RSRQ of the serving cell is worse than this threshold, " - "neighbour cells are consider for handover", + "If the RSRQ of the serving cell is worse than this " + "threshold, neighbour cells are consider for handover. " + "Expressed in quantized range of [0..34] as per Section " + "9.1.7 of 3GPP TS 36.133.", UintegerValue (30), MakeUintegerAccessor (&A2A4RsrqHandoverAlgorithm::m_servingCellThreshold), - MakeUintegerChecker (0, 34)) // RSRQ range is [0..34] as per Section 9.1.7 of 3GPP TS 36.133 + MakeUintegerChecker (0, 34)) .AddAttribute ("NeighbourCellOffset", - "Minimum offset between serving and best neighbour cell to trigger the Handover", + "Minimum offset between the serving and the best neighbour " + "cell to trigger the handover. Expressed in quantized " + "range of [0..34] as per Section 9.1.7 of 3GPP TS 36.133.", UintegerValue (1), MakeUintegerAccessor (&A2A4RsrqHandoverAlgorithm::m_neighbourCellOffset), MakeUintegerChecker ()) --- a/src/lte/model/a2-a4-rsrq-handover-algorithm.h Thu Oct 02 21:17:48 2014 -0700 +++ a/src/lte/model/a2-a4-rsrq-handover-algorithm.h Sun Oct 05 23:25:08 2014 +0300 @@ -80,9 +80,7 @@ class A2A4RsrqHandoverAlgorithm : public LteHandoverAlgorithm { public: - /** - * \brief Creates an A2-A4-RSRQ handover algorithm instance. - */ + /// Creates an A2-A4-RSRQ handover algorithm instance. A2A4RsrqHandoverAlgorithm (); virtual ~A2A4RsrqHandoverAlgorithm (); @@ -106,41 +104,86 @@ void DoReportUeMeas (uint16_t rnti, LteRrcSap::MeasResults measResults); private: - // Internal methods + /** + * Called when Event A2 is detected, then trigger a handover if needed. + * + * \param rnti The RNTI of the UE who reported the event. + * \param servingCellRsrq The RSRQ of this cell as reported by the UE. + */ void EvaluateHandover (uint16_t rnti, uint8_t servingCellRsrq); + + /** + * Determines if a neighbour cell is a valid destination for handover. + * Currently always return true. + * + * \param cellId The cell ID of the neighbour cell. + * \return True if the cell is a valid destination for handover. + */ bool IsValidNeighbour (uint16_t cellId); + + /** + * Called when Event A4 is reported, then update the measurements table. + * If the RNTI and/or cell ID is not found in the table, a corresponding + * entry will be created. Only the latest measurements are stored in the + * table. + * + * \param rnti The RNTI of the UE who reported the event. + * \param cellId The cell ID of the measured cell. + * \param rsrq The RSRQ of the cell as measured by the UE. + */ void UpdateNeighbourMeasurements (uint16_t rnti, uint16_t cellId, uint8_t rsrq); - // The expected measurement identities + /// The expected measurement identity for A2 measurements. uint8_t m_a2MeasId; + /// The expected measurement identity for A4 measurements. uint8_t m_a4MeasId; /** - * \brief Measurements reported by a UE for a cell ID. - * - * The values are quantized according 3GPP TS 36.133 section 9.1.4 and 9.1.7. + * Measurements reported by a UE for a cell ID. The values are quantized + * according 3GPP TS 36.133 section 9.1.4 and 9.1.7. */ class UeMeasure : public SimpleRefCount { public: - uint16_t m_cellId; - uint8_t m_rsrp; - uint8_t m_rsrq; + uint16_t m_cellId; ///< Cell ID. + uint8_t m_rsrp; ///< RSRP in quantized format. \todo Can be removed? + uint8_t m_rsrq; ///< RSRQ in quantized format. }; - // cellId + /** + * Measurements reported by a UE for several cells. The structure is a map + * indexed by the cell ID. + */ typedef std::map > MeasurementRow_t; - // rnti + + /** + * Measurements reported by several UEs. The structure is a map indexed by + * the RNTI of the UE. + */ typedef std::map MeasurementTable_t; + + /// Table of measurement reports from all UEs. MeasurementTable_t m_neighbourCellMeasures; - // Class attributes + /** + * The `ServingCellThreshold` attribute. If the RSRQ of the serving cell is + * worse than this threshold, neighbour cells are consider for handover. + * Expressed in quantized range of [0..34] as per Section 9.1.7 of + * 3GPP TS 36.133. + */ uint8_t m_servingCellThreshold; + + /** + * The `NeighbourCellOffset` attribute. Minimum offset between the serving + * and the best neighbour cell to trigger the handover. Expressed in + * quantized range of [0..34] as per Section 9.1.7 of 3GPP TS 36.133. + */ uint8_t m_neighbourCellOffset; - // Handover Management SAPs + /// Interface to the eNodeB RRC instance. LteHandoverManagementSapUser* m_handoverManagementSapUser; + /// Receive API calls from the eNodeB RRC instance. LteHandoverManagementSapProvider* m_handoverManagementSapProvider; }; // end of class A2A4RsrqHandoverAlgorithm --- a/src/lte/model/a3-rsrp-handover-algorithm.h Thu Oct 02 21:17:48 2014 -0700 +++ a/src/lte/model/a3-rsrp-handover-algorithm.h Sun Oct 05 23:25:08 2014 +0300 @@ -65,9 +65,7 @@ class A3RsrpHandoverAlgorithm : public LteHandoverAlgorithm { public: - /** - * \brief Creates a strongest cell handover algorithm instance. - */ + /// Creates a strongest cell handover algorithm instance. A3RsrpHandoverAlgorithm (); virtual ~A3RsrpHandoverAlgorithm (); @@ -91,18 +89,32 @@ void DoReportUeMeas (uint16_t rnti, LteRrcSap::MeasResults measResults); private: - // Internal method + /** + * Determines if a neighbour cell is a valid destination for handover. + * Currently always return true. + * + * \param cellId The cell ID of the neighbour cell. + * \return True if the cell is a valid destination for handover. + */ bool IsValidNeighbour (uint16_t cellId); - // The expected measurement identity + /// The expected measurement identity for A3 measurements. uint8_t m_measId; - // Class attributes + /** + * The `Hysteresis` attribute. Handover margin (hysteresis) in dB (rounded to + * the nearest multiple of 0.5 dB). + */ double m_hysteresisDb; + /** + * The `TimeToTrigger` attribute. Time during which neighbour cell's RSRP + * must continuously higher than serving cell's RSRP " + */ Time m_timeToTrigger; - // Handover Management SAPs + /// Interface to the eNodeB RRC instance. LteHandoverManagementSapUser* m_handoverManagementSapUser; + /// Receive API calls from the eNodeB RRC instance. LteHandoverManagementSapProvider* m_handoverManagementSapProvider; }; // end of class A3RsrpHandoverAlgorithm --- a/src/lte/model/epc-ue-nas.cc Thu Oct 02 21:17:48 2014 -0700 +++ a/src/lte/model/epc-ue-nas.cc Sun Oct 05 23:25:08 2014 +0300 @@ -33,7 +33,7 @@ - +/// Map each of UE NAS states to its string representation. static const std::string g_ueNasStateName[EpcUeNas::NUM_STATES] = { "OFF", @@ -43,6 +43,10 @@ "ACTIVE" }; +/** + * \param s The UE NAS state. + * \return The string representation of the given state. + */ static inline const std::string & ToString (EpcUeNas::State s) { return g_ueNasStateName[s]; --- a/src/lte/model/epc-ue-nas.h Thu Oct 02 21:17:48 2014 -0700 +++ a/src/lte/model/epc-ue-nas.h Sun Oct 05 23:25:08 2014 +0300 @@ -179,16 +179,28 @@ // internal methods void DoActivateEpsBearer (EpsBearer bearer, Ptr tft); + /** + * Switch the UE RRC to the given state. + * \param s the destination state + */ void SwitchToState (State s); + /// The current UE NAS state. State m_state; + /** + * The `StateTransition` trace source. Fired upon every UE NAS state + * transition. Exporting old state and new state. + */ TracedCallback m_stateTransitionCallback; + /// The UE NetDevice. Ptr m_device; + /// The unique UE identifier. uint64_t m_imsi; + /// Closed Subscriber Group identity. uint32_t m_csgId; LteAsSapProvider* m_asSapProvider; --- a/src/lte/model/lte-amc.cc Thu Oct 02 21:17:48 2014 -0700 +++ a/src/lte/model/lte-amc.cc Sun Oct 05 23:25:08 2014 +0300 @@ -38,10 +38,13 @@ NS_OBJECT_ENSURE_REGISTERED (LteAmc); -// from 3GPP R1-081483 "Conveying MCS and TB size via PDCCH" -// file TBS_support.xls -// tab "MCS table" (rounded to 2 decimal digits) -// the index in the vector (0-15) identifies the CQI value +/** + * Table of CQI index and its spectral efficiency. Taken from 3GPP TSG-RAN WG1 + * [R1-081483 Conveying MCS and TB size via PDCCH] + * (http://www.3gpp.org/ftp/tsg_ran/WG1_RL1/TSGR1_52b/Docs/R1-081483.zip) + * file `TBS_support.xls` tab "MCS Table" (rounded to 2 decimal digits). + * The index of the vector (range 0-15) identifies the CQI value. + */ static const double SpectralEfficiencyForCqi[16] = { 0.0, // out of range 0.15, 0.23, 0.38, 0.6, 0.88, 1.18, @@ -49,13 +52,15 @@ 2.73, 3.32, 3.9, 4.52, 5.12, 5.55 }; - #if 0 // currently unused -// Table 7.1.7.1-1 of 3GPP TS 36.213 v8.8.0 -// the index in the vector (range 0-31; valid values 0-28) identifies the MCS index -// note that this is similar to the one in R1-081483 but: -// 1) a few values are different -// 2) in R1-081483, a valid MCS index is in the range 1-30 (not 0-28) +/** + * Table of MCS index (IMCS) and its TBS index (ITBS). Taken from 3GPP TS + * 36.213 v8.8.0 Table 7.1.7.1-1: _Modulation and TBS index table for PDSCH_. + * The index of the vector (range 0-31; valid values 0-28) identifies the MCS + * index. Note that this is similar to the one in R1-081483, but: + * - a few values are different; and + * - in R1-081483, a valid MCS index is in the range of 1-30 (not 0-28). + */ static const int ModulationSchemeForMcs[32] = { 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 4, 4, 4, 4, 4, 4, 4, @@ -66,12 +71,15 @@ }; #endif - -// from 3GPP R1-081483 "Conveying MCS and TB size via PDCCH" -// file TBS_support.xls -// tab "MCS table" (rounded to 2 decimal digits) -// the index in the table corresponds to the MCS index according to the convention in TS 36.213 -// (i.e., the MCS index reported in R1-081483 minus one) +/** + * Table of MCS index and its spectral efficiency. Taken from 3GPP TSG-RAN WG1 + * [R1-081483 Conveying MCS and TB size via PDCCH] + * (http://www.3gpp.org/ftp/tsg_ran/WG1_RL1/TSGR1_52b/Docs/R1-081483.zip) + * file `TBS_support.xls` tab "MCS Table" (rounded to 2 decimal digits). + * The index of the vector (range 0-31) corresponds to the MCS index according + * to the convention in TS 36.213 (i.e., the MCS index reported in R1-081483 + * minus one) + */ static const double SpectralEfficiencyForMcs[32] = { 0.15, 0.19, 0.23, 0.31, 0.38, 0.49, 0.6, 0.74, 0.88, 1.03, 1.18, 1.33, 1.48, 1.7, 1.91, 2.16, 2.41, 2.57, @@ -79,20 +87,26 @@ 0, 0, 0 }; -// Table 7.1.7.1-1 of 3GPP TS 36.213 v8.8.0 +/** + * Table of MCS index (IMCS) and its TBS index (ITBS). Taken from 3GPP TS + * 36.213 v8.8.0 Table 7.1.7.1-1: _Modulation and TBS index table for PDSCH_. + * The index of the vector (range 0-28) identifies the MCS index. + */ static const int McsToItbs[29] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 9, 10, 11, 12, 13, 14, 15, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26 }; - -// 3GPP TS 36.213 v8.8.0 Table 7.1.7.2.1-1: Transport block size table (dimension 27×110) -// for NPRB = 1 and Itbs = 6 the stadard returns 328, but it not consisent with the -// other values, therefore we used 88 obtained following the sequence of NPRB = 1 values +/** + * Table of number of physical resource blocks (NPRB), TBS index (ITBS), and + * their associated transport block size. Taken from 3GPP TS 36.213 v8.8.0 + * Table 7.1.7.2.1-1: _Transport block size table (dimension 27×110)_. + * \note For NPRB = 1 and ITBS = 6 the standard returns 328, but it is not + * consistent with the other values, therefore we use 88 obtained by + * following the sequence of NPRB = 1 values. + */ static const int TransportBlockSizeTable [110][27] = { - - /* NPRB 001*/ - { 16, 24, 32, 40, 56, 72, 88, 104, 120, 136, 144, 176, 208, 224, 256, 280, 328, 336, 376, 408, 440, 488, 520, 552, 584, 616, 712}, + /* NPRB 001*/ { 16, 24, 32, 40, 56, 72, 88, 104, 120, 136, 144, 176, 208, 224, 256, 280, 328, 336, 376, 408, 440, 488, 520, 552, 584, 616, 712}, /* NPRB 002*/ { 32, 56, 72, 104, 120, 144, 176, 224, 256, 296, 328, 376, 440, 488, 552, 600, 632, 696, 776, 840, 904, 1000, 1064, 1128, 1192, 1256, 1480}, /* NPRB 003*/ { 56, 88, 144, 176, 208, 224, 256, 328, 392, 456, 504, 584, 680, 744, 840, 904, 968, 1064, 1160, 1288, 1384, 1480, 1608, 1736, 1800, 1864, 2216}, /* NPRB 004*/ { 88, 144, 176, 208, 256, 328, 392, 472, 536, 616, 680, 776, 904, 1000, 1128, 1224, 1288, 1416, 1544, 1736, 1864, 1992, 2152, 2280, 2408, 2536, 2984}, --- a/src/lte/model/lte-amc.h Thu Oct 02 21:17:48 2014 -0700 +++ a/src/lte/model/lte-amc.h Sun Oct 05 23:25:08 2014 +0300 @@ -33,12 +33,12 @@ /** * \ingroup lte - * \brief The LteAmc class implements the Adaptive Modulation And Coding Scheme - * as proposed in 3GPP TSG-RAN WG1 - R1-081483 - * http://www.3gpp.org/ftp/tsg_ran/WG1_RL1/TSGR1_52b/Docs/R1-081483.zip + * Implements the Adaptive Modulation And Coding Scheme. As proposed in 3GPP + * TSG-RAN WG1 [R1-081483 Conveying MCS and TB size via PDCCH] + * (http://www.3gpp.org/ftp/tsg_ran/WG1_RL1/TSGR1_52b/Docs/R1-081483.zip). * * \note All the methods of this class are static, so you'll never - * need to create and manage instances of this class. + * need to create and manage instances of this class. */ class LteAmc : public Object { @@ -49,13 +49,21 @@ LteAmc (); virtual ~LteAmc(); + /// Types of AMC model. enum AmcModel { + /** + * \details + * An AMC model based on Piro, G.; Grieco, L.A; Boggia, G.; Camarda, P., + * "A two-level scheduling algorithm for QoS support in the downlink of + * LTE cellular networks," _Wireless Conference (EW), 2010 European_, + * pp.246,253, 12-15 April 2010. + */ PiroEW2010, - // model based on Piro, G.; Grieco, L.A.; Boggia, G.; Camarda, P.; - //A two-level scheduling algorithm for QoS support in the downlink of - //LTE cellular networks European Wireless Conference (EW), 2010 - MiErrorModel // model based on 10% of BER according to LteMiErrorModel + /** + * An AMC model based on 10% of BER according to LteMiErrorModel. + */ + MiErrorModel }; /** @@ -102,12 +110,21 @@ private: + /** + * The `Ber` attribute. + * + * The requested BER in assigning MCS (default is 0.00005). + */ double m_ber; + + /** + * The `AmcModel` attribute. + * + * AMC model used to assign CQI. + */ AmcModel m_amcModel; - - -}; +}; // end of `class LteAmc` } --- a/src/lte/model/lte-enb-phy.cc Thu Oct 02 21:17:48 2014 -0700 +++ a/src/lte/model/lte-enb-phy.cc Sun Oct 05 23:25:08 2014 +0300 @@ -51,19 +51,26 @@ NS_OBJECT_ENSURE_REGISTERED (LteEnbPhy); -// duration of the data part of a subframe in DL -// = 0.001 / 14 * 11 (fixed to 11 symbols) -1ns as margin to avoid overlapping simulator events +/** + * Duration of the data portion of a DL subframe. + * Equals to "TTI length * (11/14) - margin". + * Data portion is fixed to 11 symbols out of the available 14 symbols. + * 1 nanosecond margin is added to avoid overlapping simulator events. + */ static const Time DL_DATA_DURATION = NanoSeconds (785714 -1); -// delay from subframe start to transmission of the data in DL -// = 0.001 / 14 * 3 (ctrl fixed to 3 symbols) +/** + * Delay from the start of a DL subframe to transmission of the data portion. + * Equals to "TTI length * (3/14)". + * Control portion is fixed to 3 symbols out of the available 14 symbols. + */ static const Time DL_CTRL_DELAY_FROM_SUBFRAME_START = NanoSeconds (214286); //////////////////////////////////////// // member SAP forwarders //////////////////////////////////////// - +/// \todo SetBandwidth() and SetCellId() can be removed. class EnbMemberLteEnbPhySapProvider : public LteEnbPhySapProvider { public: @@ -173,7 +180,10 @@ &LteEnbPhy::GetNoiseFigure), MakeDoubleChecker ()) .AddAttribute ("MacToChannelDelay", - "The delay in TTI units that occurs between a scheduling decision in the MAC and the actual start of the transmission by the PHY. This is intended to be used to model the latency of real PHY and MAC implementations.", + "The delay in TTI units that occurs between a scheduling " + "decision in the MAC and the actual start of the " + "transmission by the PHY. This is intended to be used to " + "model the latency of real PHY and MAC implementations.", UintegerValue (2), MakeUintegerAccessor (&LteEnbPhy::SetMacChDelay, &LteEnbPhy::GetMacChDelay), @@ -183,6 +193,7 @@ MakeTraceSourceAccessor (&LteEnbPhy::m_reportUeSinr)) .AddAttribute ("UeSinrSamplePeriod", "The sampling period for reporting UEs' SINR stats (default value 1)", + /// \todo In what unit is this? UintegerValue (1), MakeUintegerAccessor (&LteEnbPhy::m_srsSamplePeriod), MakeUintegerChecker ()) @@ -191,6 +202,7 @@ MakeTraceSourceAccessor (&LteEnbPhy::m_reportInterferenceTrace)) .AddAttribute ("InterferenceSamplePeriod", "The sampling period for reporting interference stats (default value 1)", + /// \todo In what unit is this? UintegerValue (1), MakeUintegerAccessor (&LteEnbPhy::m_interferenceSamplePeriod), MakeUintegerChecker ()) --- a/src/lte/model/lte-enb-phy.h Thu Oct 02 21:17:48 2014 -0700 +++ a/src/lte/model/lte-enb-phy.h Sun Oct 05 23:25:08 2014 +0300 @@ -302,27 +302,46 @@ void DoSendLteControlMessage (Ptr msg); uint8_t DoGetMacChTtiDelay (); + /** + * Add the given RNTI to the list of attached UE #m_ueAttached. + * \param rnti RNTI of a UE + * \return true if the RNTI has _not_ existed before, or false otherwise. + */ bool AddUePhy (uint16_t rnti); - + /** + * Remove the given RNTI from the list of attached UE #m_ueAttached. + * \param rnti RNTI of a UE + * \return true if the RNTI has existed before, or false otherwise. + */ bool DeleteUePhy (uint16_t rnti); void CreateSrsReport (uint16_t rnti, double srs); - + /** + * List of RNTI of attached UEs. Used for quickly determining whether a UE is + * attached to this eNodeB or not. + */ std::set m_ueAttached; - // P_A per UE RNTI + /// P_A per UE RNTI. std::map m_paMap; - // DL power allocation map + /// DL power allocation map. std::map m_dlPowerAllocationMap; + /** + * A vector of integers, if the i-th value is j it means that the j-th + * resource block is used for transmission in the downlink. If there is + * no i such that the value of the i-th element is j, it means that RB j + * is not used. + */ std::vector m_listOfDownlinkSubchannel; std::vector m_dlDataRbMap; - std::vector< std::list > m_ulDciQueue; // for storing info on future receptions + /// For storing info on future receptions. + std::vector< std::list > m_ulDciQueue; LteEnbPhySapProvider* m_enbPhySapProvider; LteEnbPhySapUser* m_enbPhySapUser; @@ -330,7 +349,16 @@ LteEnbCphySapProvider* m_enbCphySapProvider; LteEnbCphySapUser* m_enbCphySapUser; + /** + * The frame number currently served. In ns-3, frame number starts from 1. + * In contrast, the 3GPP standard's frame number starts from 0. + */ uint32_t m_nrFrames; + /** + * The subframe number currently served. In ns-3, subframe number starts + * from 1. In contrast, the 3GPP standard's subframe number starts from 0. + * The number resets to the beginning again after 10 subframes. + */ uint32_t m_nrSubFrames; uint16_t m_srsPeriodicity; @@ -339,35 +367,54 @@ std::vector m_srsUeOffset; uint16_t m_currentSrsOffset; + /** + * The Master Information Block message to be broadcasted every frame. + * The message content is specified by the upper layer through the RRC SAP. + */ LteRrcSap::MasterInformationBlock m_mib; + /** + * The System Information Block Type 1 message to be broadcasted. SIB1 is + * broadcasted every 6th subframe of every odd-numbered radio frame. + * The message content is specified by the upper layer through the RRC SAP. + */ LteRrcSap::SystemInformationBlockType1 m_sib1; Ptr m_harqPhyModule; /** - * Trace reporting the linear average of SRS SINRs - * uint16_t cellId, uint16_t rnti, double sinrLinear + * The `ReportUeSinr` trace source. Reporting the linear average of SRS SINR. + * Exporting cell ID, RNTI, and SINR in linear unit. */ TracedCallback m_reportUeSinr; + /** + * The `UeSinrSamplePeriod` trace source. The sampling period for reporting + * UEs' SINR stats. + */ uint16_t m_srsSamplePeriod; std::map m_srsSampleCounterMap; /** - * Trace reporting the interference per PHY RB (TS 36.214 section 5.2.2, - * measured on DATA) - * uint16_t cellId, Ptr interference linear power per RB basis + * The `ReportInterference` trace source. Reporting the interference per PHY + * RB (TS 36.214 section 5.2.2, measured on DATA). Exporting cell ID and + * interference linear power per RB basis. */ TracedCallback > m_reportInterferenceTrace; + /** + * The `InterferenceSamplePeriod` attribute. The sampling period for + * reporting interference stats. + * \todo In what unit is this? + */ uint16_t m_interferenceSamplePeriod; uint16_t m_interferenceSampleCounter; /** - * Trace information regarding PHY stats from UL Tx perspective - * PhyTrasmissionStatParameters see lte-common.h + * The `DlPhyTransmission` trace source. Contains trace information regarding + * PHY stats from DL Tx perspective. Exporting a structure with type + * PhyTransmissionStatParameters. */ TracedCallback m_dlPhyTransmission; -}; +}; // end of `class LteEnbPhy` } --- a/src/lte/model/lte-enb-rrc.cc Thu Oct 02 21:17:48 2014 -0700 +++ a/src/lte/model/lte-enb-rrc.cc Sun Oct 05 23:25:08 2014 +0300 @@ -98,6 +98,7 @@ /////////////////////////////////////////// +/// Map each of UE Manager states to its string representation. static const std::string g_ueManagerStateName[UeManager::NUM_STATES] = { "INITIAL_RANDOM_ACCESS", @@ -112,6 +113,10 @@ "HANDOVER_LEAVING", }; +/** + * \param s The UE manager state. + * \return The string representation of the given state. + */ static const std::string & ToString (UeManager::State s) { return g_ueManagerStateName[s]; @@ -301,7 +306,8 @@ MakeUintegerAccessor (&UeManager::m_rnti), MakeUintegerChecker ()) .AddTraceSource ("StateTransition", - "fired upon every UE state transition seen by the UeManager at the eNB RRC", + "Fired upon every UE state transition seen by the " + "UeManager at the eNB RRC.", MakeTraceSourceAccessor (&UeManager::m_stateTransitionTrace)) ; return tid; @@ -1428,22 +1434,22 @@ // Trace sources .AddTraceSource ("NewUeContext", - "trace fired upon creation of a new UE context", + "Fired upon creation of a new UE context.", MakeTraceSourceAccessor (&LteEnbRrc::m_newUeContextTrace)) .AddTraceSource ("ConnectionEstablished", - "trace fired upon successful RRC connection establishment", + "Fired upon successful RRC connection establishment.", MakeTraceSourceAccessor (&LteEnbRrc::m_connectionEstablishedTrace)) .AddTraceSource ("ConnectionReconfiguration", - "trace fired upon RRC connection reconfiguration", + "Fired upon RRC connection reconfiguration.", MakeTraceSourceAccessor (&LteEnbRrc::m_connectionReconfigurationTrace)) .AddTraceSource ("HandoverStart", - "trace fired upon start of a handover procedure", + "Fired upon start of a handover procedure.", MakeTraceSourceAccessor (&LteEnbRrc::m_handoverStartTrace)) .AddTraceSource ("HandoverEndOk", - "trace fired upon successful termination of a handover procedure", + "Fired upon successful termination of a handover procedure.", MakeTraceSourceAccessor (&LteEnbRrc::m_handoverEndOkTrace)) .AddTraceSource ("RecvMeasurementReport", - "trace fired when measurement report is received", + "Fired when measurement report is received.", MakeTraceSourceAccessor (&LteEnbRrc::m_recvMeasurementReportTrace)) ; return tid; @@ -2305,10 +2311,24 @@ } -// from 3GPP TS 36.213 table 8.2-1 UE Specific SRS Periodicity +/// Number of distinct SRS periodicity plus one. static const uint8_t SRS_ENTRIES = 9; +/** + * Sounding Reference Symbol (SRS) periodicity (TSRS) in milliseconds. Taken + * from 3GPP TS 36.213 Table 8.2-1. Index starts from 1. + */ static const uint16_t g_srsPeriodicity[SRS_ENTRIES] = {0, 2, 5, 10, 20, 40, 80, 160, 320}; +/** + * The lower bound (inclusive) of the SRS configuration indices (ISRS) which + * use the corresponding SRS periodicity (TSRS). Taken from 3GPP TS 36.213 + * Table 8.2-1. Index starts from 1. + */ static const uint16_t g_srsCiLow[SRS_ENTRIES] = {0, 0, 2, 7, 17, 37, 77, 157, 317}; +/** + * The upper bound (inclusive) of the SRS configuration indices (ISRS) which + * use the corresponding SRS periodicity (TSRS). Taken from 3GPP TS 36.213 + * Table 8.2-1. Index starts from 1. + */ static const uint16_t g_srsCiHigh[SRS_ENTRIES] = {0, 1, 6, 16, 36, 76, 156, 316, 636}; void --- a/src/lte/model/lte-enb-rrc.h Thu Oct 02 21:17:48 2014 -0700 +++ a/src/lte/model/lte-enb-rrc.h Sun Oct 05 23:25:08 2014 +0300 @@ -55,8 +55,9 @@ /** - * Manages all the radio bearer information possessed by the ENB RRC for a single UE - * + * \ingroup lte + * Manages all the radio bearer information possessed by the ENB RRC for a + * single UE. */ class UeManager : public Object { @@ -397,34 +398,93 @@ */ void SwitchToState (State s); + uint8_t m_lastAllocatedDrbid; + /** + * The `DataRadioBearerMap` attribute. List of UE DataRadioBearerInfo by + * DRBID. + */ std::map > m_drbMap; + + /** + * The `Srb0` attribute. SignalingRadioBearerInfo for SRB0. + */ Ptr m_srb0; + /** + * The `Srb1` attribute. SignalingRadioBearerInfo for SRB1. + */ Ptr m_srb1; - uint8_t m_lastAllocatedDrbid; + + /** + * The `C-RNTI` attribute. Cell Radio Network Temporary Identifier. + */ uint16_t m_rnti; + /** + * International Mobile Subscriber Identity assigned to this UE. A globally + * unique UE identifier. + */ uint64_t m_imsi; + /// uint8_t m_lastRrcTransactionIdentifier; + /// LteRrcSap::PhysicalConfigDedicated m_physicalConfigDedicated; + /// Pointer to the parent eNodeB RRC. Ptr m_rrc; + /// The current UeManager state. State m_state; + /// LtePdcpSapUser* m_drbPdcpSapUser; + /// bool m_pendingRrcConnectionReconfiguration; - // imsi cellid rnti old new + + /** + * The `StateTransition` trace source. Fired upon every UE state transition + * seen by the UeManager at the eNB RRC. Exporting IMSI, cell ID, RNTI, old + * state, and new state. + */ TracedCallback m_stateTransitionTrace; + uint16_t m_sourceX2apId; uint16_t m_sourceCellId; uint16_t m_targetCellId; std::list m_drbsToBeStarted; bool m_needPhyMacConfiguration; + /** + * Time limit before a _connection request timeout_ occurs. Set after a new + * UE context is added after a successful Random Access. Calling + * LteEnbRrc::ConnectionRequestTimeout() when it expires. Cancelled when RRC + * CONNECTION REQUEST is received. + */ EventId m_connectionRequestTimeout; + /** + * Time limit before a _connection setup timeout_ occurs. Set after an RRC + * CONNECTION SETUP is sent. Calling LteEnbRrc::ConnectionSetupTimeout() when + * it expires. Cancelled when RRC CONNECTION SETUP COMPLETE is received. + */ EventId m_connectionSetupTimeout; + /** + * The delay before a _connection rejected timeout_ occurs. Set after an RRC + * CONNECTION REJECT is sent. Calling LteEnbRrc::ConnectionRejectedTimeout() + * when it expires. + */ EventId m_connectionRejectedTimeout; + /** + * Time limit before a _handover joining timeout_ occurs. Set after a new UE + * context is added after receiving a handover request. Calling + * LteEnbRrc::HandoverJoiningTimeout() when it expires. Cancelled when + * RRC CONNECTION RECONFIGURATION COMPLETE is received. + */ EventId m_handoverJoiningTimeout; + /** + * Time limit before a _handover leaving timeout_ occurs. Set after a + * handover command is sent. Calling LteEnbRrc::HandoverLeavingTimeout() + * when it expires. Cancelled when RRC CONNECTION RE-ESTABLISHMENT or X2 + * UE CONTEXT RELEASE is received. + */ EventId m_handoverLeavingTimeout; -}; +}; // end of `class UeManager` @@ -679,7 +739,7 @@ /** * Method triggered when a UE is expected to request for connection but does - * not do so in a reasonable time + * not do so in a reasonable time. The method will remove the UE context. * * \param rnti the T-C-RNTI whose timeout expired */ @@ -687,14 +747,16 @@ /** * Method triggered when a UE is expected to complete a connection setup - * procedure but does not do so in a reasonable time + * procedure but does not do so in a reasonable time. The method will remove + * the UE context. * * \param rnti the T-C-RNTI whose timeout expired */ void ConnectionSetupTimeout (uint16_t rnti); /** - * Method triggered a while after sending RRC Connection Rejected + * Method triggered a while after sending RRC Connection Rejected. The method + * will remove the UE context. * * \param rnti the T-C-RNTI whose timeout expired */ @@ -702,7 +764,8 @@ /** * Method triggered when a UE is expected to join the cell for a handover - * but does not do so in a reasonable time + * but does not do so in a reasonable time. The method will remove the UE + * context. * * \param rnti the C-RNTI whose timeout expired */ @@ -710,18 +773,17 @@ /** * Method triggered when a UE is expected to leave a cell for a handover - * but no feedback is received in a reasonable time + * but no feedback is received in a reasonable time. The method will remove + * the UE context. * * \param rnti the C-RNTI whose timeout expired */ void HandoverLeavingTimeout (uint16_t rnti); /** - * Send a HandoverRequest through the X2 SAP interface - * - * This method will trigger a handover which is started by the RRC - * by sending a handover request to the target eNB over the X2 - * interface + * Send a HandoverRequest through the X2 SAP interface. This method will + * trigger a handover which is started by the RRC by sending a handover + * request to the target eNB over the X2 interface * * \param rnti the ID of the UE to be handed over * \param cellId the ID of the target eNB @@ -918,53 +980,83 @@ Callback > m_forwardUpCallback; + /// Interface to receive messages from neighbour eNodeB over the X2 interface. EpcX2SapUser* m_x2SapUser; + /// Interface to send messages to neighbour eNodeB over the X2 interface. EpcX2SapProvider* m_x2SapProvider; + /// Receive API calls from the eNodeB MAC instance. LteEnbCmacSapUser* m_cmacSapUser; + /// Interface to the eNodeB MAC instance. LteEnbCmacSapProvider* m_cmacSapProvider; + /// Receive API calls from the handover algorithm instance. LteHandoverManagementSapUser* m_handoverManagementSapUser; + /// Interface to the handover algorithm instance. LteHandoverManagementSapProvider* m_handoverManagementSapProvider; + /// Receive API calls from the ANR instance. LteAnrSapUser* m_anrSapUser; + /// Interface to the ANR instance. LteAnrSapProvider* m_anrSapProvider; + /// Receive API calls from the FFR algorithm instance. LteFfrRrcSapUser* m_ffrRrcSapUser; + /// Interface to the FFR algorithm instance. LteFfrRrcSapProvider* m_ffrRrcSapProvider; + /// Interface to send messages to UE over the RRC protocol. LteEnbRrcSapUser* m_rrcSapUser; + /// Interface to receive messages from UE over the RRC protocol. LteEnbRrcSapProvider* m_rrcSapProvider; + /// Interface to the eNodeB MAC instance, to be used by RLC instances. LteMacSapProvider* m_macSapProvider; + /// Interface to send messages to core network over the S1 protocol. EpcEnbS1SapProvider* m_s1SapProvider; + /// Interface to receive messages from core network over the S1 protocol. EpcEnbS1SapUser* m_s1SapUser; + /// Receive API calls from the eNodeB PHY instance. LteEnbCphySapUser* m_cphySapUser; + /// Interface to the eNodeB PHY instance. LteEnbCphySapProvider* m_cphySapProvider; + /// True if ConfigureCell() has been completed. bool m_configured; + /// Cell identifier. Must be unique across the simulation. uint16_t m_cellId; + /// Downlink E-UTRA Absolute Radio Frequency Channel Number. uint16_t m_dlEarfcn; + /// Uplink E-UTRA Absolute Radio Frequency Channel Number. uint16_t m_ulEarfcn; + /// Downlink transmission bandwidth configuration in number of Resource Blocks. uint16_t m_dlBandwidth; + /// Uplink transmission bandwidth configuration in number of Resource Blocks. uint16_t m_ulBandwidth; + /// uint16_t m_lastAllocatedRnti; - /// the System Information Block Type 1 that is currently broadcasted over BCH + /// The System Information Block Type 1 that is currently broadcasted over BCH. LteRrcSap::SystemInformationBlockType1 m_sib1; + /** + * The `UeMap` attribute. List of UeManager by C-RNTI. + */ std::map > m_ueMap; /** - * \brief List of measurement configuration which are active in every UE - * attached to this eNodeB instance. + * List of measurement configuration which are active in every UE attached to + * this eNodeB instance. */ LteRrcSap::MeasConfig m_ueMeasConfig; + /// List of measurement identities which are intended for handover purpose. std::set m_handoverMeasIds; + /// List of measurement identities which are intended for ANR purpose. std::set m_anrMeasIds; + /// List of measurement identities which are intended for FFR purpose. std::set m_ffrMeasIds; struct X2uTeidInfo @@ -976,51 +1068,124 @@ // TEID RNTI, DRBID std::map m_x2uTeidInfoMap; + /** + * The `DefaultTransmissionMode` attribute. The default UEs' transmission + * mode (0: SISO). + */ uint8_t m_defaultTransmissionMode; - + /** + * The `EpsBearerToRlcMapping` attribute. Specify which type of RLC will be + * used for each type of EPS bearer. + */ enum LteEpsBearerToRlcMapping_t m_epsBearerToRlcMapping; - + /** + * The `SystemInformationPeriodicity` attribute. The interval for sending + * system information. + */ Time m_systemInformationPeriodicity; - - // SRS related attributes + /** + * The `SrsPeriodicity` attribute. The SRS periodicity in milliseconds. + */ uint16_t m_srsCurrentPeriodicityId; std::set m_ueSrsConfigurationIndexSet; uint16_t m_lastAllocatedConfigurationIndex; bool m_reconfigureUes; - // Cell selection related attribute + /** + * The `QRxLevMin` attribute. One of information transmitted within the SIB1 + * message, indicating the required minimum RSRP level that any UE must + * receive from this cell before it is allowed to camp to this cell. + */ int8_t m_qRxLevMin; - - // Handover related attributes + /** + * The `AdmitHandoverRequest` attribute. Whether to admit an X2 handover + * request from another eNB. + */ bool m_admitHandoverRequest; + /** + * The `AdmitRrcConnectionRequest` attribute. Whether to admit a connection + * request from a UE. + */ bool m_admitRrcConnectionRequest; - - // UE measurements related attributes + /** + * The `RsrpFilterCoefficient` attribute. Determines the strength of + * smoothing effect induced by layer 3 filtering of RSRP in all attached UE. + * If equals to 0, no layer 3 filtering is applicable. + */ uint8_t m_rsrpFilterCoefficient; + /** + * The `RsrqFilterCoefficient` attribute. Determines the strength of + * smoothing effect induced by layer 3 filtering of RSRQ in all attached UE. + * If equals to 0, no layer 3 filtering is applicable. + */ uint8_t m_rsrqFilterCoefficient; - - // timeouts + /** + * The `ConnectionRequestTimeoutDuration` attribute. After a RA attempt, if + * no RRC CONNECTION REQUEST is received before this time, the UE context is + * destroyed. Must account for reception of RAR and transmission of RRC + * CONNECTION REQUEST over UL GRANT. + */ Time m_connectionRequestTimeoutDuration; + /** + * The `ConnectionSetupTimeoutDuration` attribute. After accepting connection + * request, if no RRC CONNECTION SETUP COMPLETE is received before this time, + * the UE context is destroyed. Must account for the UE's reception of RRC + * CONNECTION SETUP and transmission of RRC CONNECTION SETUP COMPLETE. + */ Time m_connectionSetupTimeoutDuration; + /** + * The `ConnectionRejectedTimeoutDuration` attribute. Time to wait between + * sending a RRC CONNECTION REJECT and destroying the UE context. + */ Time m_connectionRejectedTimeoutDuration; + /** + * The `HandoverJoiningTimeoutDuration` attribute. After accepting a handover + * request, if no RRC CONNECTION RECONFIGURATION COMPLETE is received before + * this time, the UE context is destroyed. Must account for reception of X2 + * HO REQ ACK by source eNB, transmission of the Handover Command, + * non-contention-based random access and reception of the RRC CONNECTION + * RECONFIGURATION COMPLETE message. + */ Time m_handoverJoiningTimeoutDuration; + /** + * The `HandoverLeavingTimeoutDuration` attribute. After issuing a Handover + * Command, if neither RRC CONNECTION RE-ESTABLISHMENT nor X2 UE Context + * Release has been previously received, the UE context is destroyed. + */ Time m_handoverLeavingTimeoutDuration; - // cellid rnti + /** + * The `NewUeContext` trace source. Fired upon creation of a new UE context. + * Exporting cell ID and RNTI. + */ TracedCallback m_newUeContextTrace; - // imsi cellid rnti + /** + * The `ConnectionEstablished` trace source. Fired upon successful RRC + * connection establishment. Exporting IMSI, cell ID, and RNTI. + */ TracedCallback m_connectionEstablishedTrace; - // imsi cellid rnti + /** + * The `ConnectionReconfiguration` trace source. Fired upon RRC connection + * reconfiguration. Exporting IMSI, cell ID, and RNTI. + */ TracedCallback m_connectionReconfigurationTrace; - // imsi cellid rnti targetCellId + /** + * The `HandoverStart` trace source. Fired upon start of a handover + * procedure. Exporting IMSI, cell ID, RNTI, and target cell ID. + */ TracedCallback m_handoverStartTrace; - // imsi cellid rnti + /** + * The `HandoverEndOk` trace source. Fired upon successful termination of a + * handover procedure. Exporting IMSI, cell ID, and RNTI. + */ TracedCallback m_handoverEndOkTrace; - - // imsi cellid rnti + /** + * The `RecvMeasurementReport` trace source. Fired when measurement report is + * received. Exporting IMSI, cell ID, and RNTI. + */ TracedCallback m_recvMeasurementReportTrace; -}; +}; // end of `class LteEnbRrc` } // namespace ns3 --- a/src/lte/model/lte-phy.h Thu Oct 02 21:17:48 2014 -0700 +++ a/src/lte/model/lte-phy.h Sun Oct 05 23:25:08 2014 +0300 @@ -212,29 +212,86 @@ protected: + /// Pointer to the NetDevice where this PHY layer is attached. Ptr m_netDevice; + /** + * The downlink LteSpectrumPhy associated to this LtePhy. Also available as + * attribute `DlSpectrumPhy` in the child classes LteEnbPhy and LteUePhy. + */ Ptr m_downlinkSpectrumPhy; + /** + * The uplink LteSpectrumPhy associated to this LtePhy. Also available as + * attribute `UlSpectrumPhy` in the child classes LteEnbPhy and LteUePhy. + */ Ptr m_uplinkSpectrumPhy; + /** + * Transmission power in dBm. Also available as attribute `TxPower` in the + * child classes LteEnbPhy and LteUePhy. + */ double m_txPower; + /** + * Loss (dB) in the Signal-to-Noise-Ratio due to non-idealities in the + * receiver. Also available as attribute `NoiseFigure` in the child classes + * LteEnbPhy and LteUePhy. + * + * According to [Wikipedia](http://en.wikipedia.org/wiki/Noise_figure), this + * is "the difference in decibels (dB) between the noise output of the actual + * receiver to the noise output of an ideal receiver with the same overall + * gain and bandwidth when the receivers are connected to sources at the + * standard noise temperature T0." In this model, we consider T0 = 290K. + */ double m_noiseFigure; + /// Transmission time interval. double m_tti; + /** + * The UL bandwidth in number of PRBs. + * Specified by the upper layer through CPHY SAP. + */ uint8_t m_ulBandwidth; + /** + * The DL bandwidth in number of PRBs. + * Specified by the upper layer through CPHY SAP. + */ uint8_t m_dlBandwidth; + /// The RB gruop size according to the bandwidth. uint8_t m_rbgSize; - + /** + * The downlink carrier frequency. + * Specified by the upper layer through CPHY SAP. + */ uint16_t m_dlEarfcn; + /** + * The uplink carrier frequency. + * Specified by the upper layer through CPHY SAP. + */ uint16_t m_ulEarfcn; + /// A queue of packet bursts to be sent. std::vector< Ptr > m_packetBurstQueue; + /// A queue of control messages to be sent. std::vector< std::list > > m_controlMessagesQueue; - uint8_t m_macChTtiDelay; // delay between MAC and channel layer in terms of TTIs + /** + * Delay between MAC and channel layer in terms of TTIs. It is the delay that + * occurs between a scheduling decision in the MAC and the actual start of + * the transmission by the PHY. This is intended to be used to model the + * latency of real PHY and MAC implementations. + * + * In LteEnbPhy, it is 2 TTIs by default and can be configured through the + * `MacToChannelDelay` attribute. In LteUePhy, it is 4 TTIs. + */ + uint8_t m_macChTtiDelay; + /** + * Cell identifier. In LteEnbPhy, this corresponds to the ID of the cell + * which hosts this PHY layer. In LteUePhy, this corresponds to the ID of the + * eNodeB which this PHY layer is synchronized with. + */ uint16_t m_cellId; -}; +}; // end of `class LtePhy` } --- a/src/lte/model/lte-ue-phy.cc Thu Oct 02 21:17:48 2014 -0700 +++ a/src/lte/model/lte-ue-phy.cc Sun Oct 05 23:25:08 2014 +0300 @@ -47,14 +47,19 @@ -// duration of data portion of UL subframe -// = TTI - 1 symbol for SRS - 1ns as margin to avoid overlapping simulator events -// (symbol duration in nanoseconds = TTI / 14 (rounded)) -// in other words, duration of data portion of UL subframe = TTI*(13/14) -1ns +/** + * Duration of the data portion of a UL subframe. + * Equals to "TTI length - 1 symbol length for SRS - margin". + * The margin is 1 nanosecond and is intended to avoid overlapping simulator + * events. The duration of one symbol is TTI/14 (rounded). In other words, + * duration of data portion of UL subframe = 1 ms * (13/14) - 1 ns. + */ static const Time UL_DATA_DURATION = NanoSeconds (1e6 - 71429 - 1); -// delay from subframe start to transmission of SRS -// = TTI - 1 symbol for SRS +/** + * Delay from subframe start to transmission of SRS. + * Equals to "TTI length - 1 symbol for SRS". + */ static const Time UL_SRS_DELAY_FROM_SUBFRAME_START = NanoSeconds (1e6 - 71429); @@ -107,12 +112,17 @@ // LteUePhy methods //////////////////////////////////////// +/// Map each of UE PHY states to its string representation. static const std::string g_uePhyStateName[LteUePhy::NUM_STATES] = { "CELL_SEARCH", "SYNCHRONIZED" }; +/** + * \param s The UE PHY state. + * \return The string representation of the given state. + */ static inline const std::string & ToString (LteUePhy::State s) { return g_uePhyStateName[s]; @@ -243,7 +253,7 @@ MakeUintegerAccessor (&LteUePhy::m_rsrpSinrSamplePeriod), MakeUintegerChecker ()) .AddTraceSource ("UlPhyTransmission", - "DL transmission PHY layer statistics.", + "UL transmission PHY layer statistics.", MakeTraceSourceAccessor (&LteUePhy::m_ulPhyTransmission)) .AddAttribute ("DlSpectrumPhy", "The downlink LteSpectrumPhy associated to this LtePhy", @@ -263,7 +273,8 @@ MakeDoubleAccessor (&LteUePhy::m_pssReceptionThreshold), MakeDoubleChecker ()) .AddAttribute ("UeMeasurementsFilterPeriod", - "Time period for reporting UE measurements (default 200 ms.) ", + "Time period for reporting UE measurements, i.e., the" + "length of layer-1 filtering (default 200 ms).", TimeValue (MilliSeconds (200)), MakeTimeAccessor (&LteUePhy::m_ueMeasurementsFilterPeriod), MakeTimeChecker ()) @@ -271,10 +282,10 @@ "Report UE measurements RSRP (dBm) and RSRQ (dB).", MakeTraceSourceAccessor (&LteUePhy::m_reportUeMeasurements)) .AddTraceSource ("StateTransition", - "Trace fired upon every UE PHY state transition", + "Trace fired upon every UE PHY state transition.", MakeTraceSourceAccessor (&LteUePhy::m_stateTransitionTrace)) .AddAttribute ("EnableUplinkPowerControl", - "If true Uplink Power Control will be enabled", + "If true, Uplink Power Control will be enabled.", BooleanValue (true), MakeBooleanAccessor (&LteUePhy::m_enableUplinkPowerControl), MakeBooleanChecker ()) --- a/src/lte/model/lte-ue-phy.h Thu Oct 02 21:17:48 2014 -0700 +++ a/src/lte/model/lte-ue-phy.h Sun Oct 05 23:25:08 2014 +0300 @@ -260,6 +260,10 @@ */ void ReportUeMeasurements (); + /** + * Switch the UE PHY to the given state. + * \param s the destination state + */ void SwitchToState (State s); // UE CPHY SAP methods @@ -279,7 +283,9 @@ virtual void DoSendLteControlMessage (Ptr msg); virtual void DoSendRachPreamble (uint32_t prachId, uint32_t raRnti); + /// A list of sub channels to use in TX. std::vector m_subChannelsForTransmission; + /// A list of sub channels to use in RX. std::vector m_subChannelsForReception; std::vector< std::vector > m_subChannelsForTransmissionQueue; @@ -287,14 +293,23 @@ Ptr m_amc; + /** + * The `EnableUplinkPowerControl` attribute. If true, Uplink Power Control + * will be enabled. + */ bool m_enableUplinkPowerControl; + /// Pointer to UE Uplink Power Control entity. Ptr m_powerControl; - Time m_p10CqiPeriocity; /**< Wideband Periodic CQI: 2, 5, 10, 16, 20, 32, 40, 64, 80 or 160 ms */ + /// Wideband Periodic CQI. 2, 5, 10, 16, 20, 32, 40, 64, 80 or 160 ms. + Time m_p10CqiPeriocity; Time m_p10CqiLast; - /**< SubBand Aperiodic CQI: activated by DCI format 0 or Random Access Response Grant */ - // NOTE defines a periodicity for academic studies + /** + * SubBand Aperiodic CQI. Activated by DCI format 0 or Random Access Response + * Grant. + * \note Defines a periodicity for academic studies. + */ Time m_a30CqiPeriocity; Time m_a30CqiLast; @@ -317,10 +332,15 @@ bool m_dlConfigured; bool m_ulConfigured; + /// The current UE PHY state. State m_state; - // cellid rnti + /** + * The `StateTransition` trace source. Fired upon every UE PHY state + * transition. Exporting the serving cell ID, RNTI, old state, and new state. + */ TracedCallback m_stateTransitionTrace; + /// \todo Can be removed. uint8_t m_subframeNo; bool m_rsReceivedPowerUpdated; @@ -341,18 +361,32 @@ }; std::list m_pssList; - double m_pssReceptionThreshold; // on RSRQ [W] + /** + * The `RsrqUeMeasThreshold` attribute. Receive threshold for PSS on RSRQ + * in dB. + */ + double m_pssReceptionThreshold; + /// Summary results of measuring a specific cell. Used for layer-1 filtering. struct UeMeasurementsElement { - double rsrpSum; - uint8_t rsrpNum; - double rsrqSum; - uint8_t rsrqNum; + double rsrpSum; ///< Sum of RSRP sample values in linear unit. + uint8_t rsrpNum; ///< Number of RSRP samples. + double rsrqSum; ///< Sum of RSRQ sample values in linear unit. + uint8_t rsrqNum; ///< Number of RSRQ samples. }; + /** + * Store measurement results during the last layer-1 filtering period. + * Indexed by the cell ID where the measurements come from. + */ std::map m_ueMeasurementsMap; + /** + * The `UeMeasurementsFilterPeriod` attribute. Time period for reporting UE + * measurements, i.e., the length of layer-1 filtering (default 200 ms). + */ Time m_ueMeasurementsFilterPeriod; + /// \todo Can be removed. Time m_ueMeasurementsFilterLast; Ptr m_harqPhyModule; @@ -361,28 +395,36 @@ uint32_t m_raRnti; /** - * Trace information regarding RSRP and average SINR (see TS 36.214) - * uint16_t cellId, uint16_t rnti, double rsrp, double sinr + * The `ReportCurrentCellRsrpSinr` trace source. Trace information regarding + * RSRP and average SINR (see TS 36.214). Exporting cell ID, RNTI, RSRP, and + * SINR. */ TracedCallback m_reportCurrentCellRsrpSinrTrace; + /** + * The `RsrpSinrSamplePeriod` attribute. The sampling period for reporting + * RSRP-SINR stats. + */ uint16_t m_rsrpSinrSamplePeriod; uint16_t m_rsrpSinrSampleCounter; /** - * Trace information regarding RSRP and RSRQ (see TS 36.214) - * uint16_t rnti, uint16_t cellId, double rsrpDbm, double rsrqDb, bool isServingCell + * The `ReportUeMeasurements` trace source. Contains trace information + * regarding RSRP and RSRQ measured from a specific cell (see TS 36.214). + * Exporting RNTI, the ID of the measured cell, RSRP (in dBm), RSRQ (in dB), + * and whether the cell is the serving cell. */ TracedCallback m_reportUeMeasurements; EventId m_sendSrsEvent; /** - * Trace information regarding PHY stats from DL Tx perspective - * PhyTrasmissionStatParameters see lte-common.h + * The `UlPhyTransmission` trace source. Contains trace information regarding + * PHY stats from UL Tx perspective. Exporting a structure with type + * PhyTransmissionStatParameters. */ TracedCallback m_ulPhyTransmission; -}; +}; // end of `class LteUePhy` } --- a/src/lte/model/lte-ue-rrc.cc Thu Oct 02 21:17:48 2014 -0700 +++ a/src/lte/model/lte-ue-rrc.cc Sun Oct 05 23:25:08 2014 +0300 @@ -86,7 +86,7 @@ - +/// Map each of UE RRC states to its string representation. static const std::string g_ueRrcStateName[LteUeRrc::NUM_STATES] = { "IDLE_START", @@ -104,6 +104,10 @@ "CONNECTED_REESTABLISHING" }; +/** + * \param s The UE RRC state. + * \return The string representation of the given state. + */ static const std::string & ToString (LteUeRrc::State s) { return g_ueRrcStateName[s]; @@ -195,46 +199,46 @@ MakeTimeAccessor (&LteUeRrc::m_t300), MakeTimeChecker ()) .AddTraceSource ("MibReceived", - "trace fired upon reception of Master Information Block", + "Fired upon reception of Master Information Block.", MakeTraceSourceAccessor (&LteUeRrc::m_mibReceivedTrace)) .AddTraceSource ("Sib1Received", - "trace fired upon reception of System Information Block Type 1", + "Fired upon reception of System Information Block Type 1.", MakeTraceSourceAccessor (&LteUeRrc::m_sib1ReceivedTrace)) .AddTraceSource ("Sib2Received", - "trace fired upon reception of System Information Block Type 2", + "Fired upon reception of System Information Block Type 2.", MakeTraceSourceAccessor (&LteUeRrc::m_sib2ReceivedTrace)) .AddTraceSource ("StateTransition", - "trace fired upon every UE RRC state transition", + "Fired upon every UE RRC state transition.", MakeTraceSourceAccessor (&LteUeRrc::m_stateTransitionTrace)) .AddTraceSource ("InitialCellSelectionEndOk", - "trace fired upon successful initial cell selection procedure", + "Fired upon successful initial cell selection procedure.", MakeTraceSourceAccessor (&LteUeRrc::m_initialCellSelectionEndOkTrace)) .AddTraceSource ("InitialCellSelectionEndError", - "trace fired upon failed initial cell selection procedure", + "Fired upon failed initial cell selection procedure.", MakeTraceSourceAccessor (&LteUeRrc::m_initialCellSelectionEndErrorTrace)) .AddTraceSource ("RandomAccessSuccessful", - "trace fired upon successful completion of the random access procedure", + "Fired upon successful completion of the random access procedure.", MakeTraceSourceAccessor (&LteUeRrc::m_randomAccessSuccessfulTrace)) .AddTraceSource ("RandomAccessError", - "trace fired upon failure of the random access procedure", + "Fired upon failure of the random access procedure.", MakeTraceSourceAccessor (&LteUeRrc::m_randomAccessErrorTrace)) .AddTraceSource ("ConnectionEstablished", - "trace fired upon successful RRC connection establishment", + "Fired upon successful RRC connection establishment.", MakeTraceSourceAccessor (&LteUeRrc::m_connectionEstablishedTrace)) .AddTraceSource ("ConnectionTimeout", - "trace fired upon timeout RRC connection establishment because of T300", + "Fired upon timeout RRC connection establishment because of T300.", MakeTraceSourceAccessor (&LteUeRrc::m_connectionTimeoutTrace)) .AddTraceSource ("ConnectionReconfiguration", - "trace fired upon RRC connection reconfiguration", + "Fired upon RRC connection reconfiguration.", MakeTraceSourceAccessor (&LteUeRrc::m_connectionReconfigurationTrace)) .AddTraceSource ("HandoverStart", - "trace fired upon start of a handover procedure", + "Fired upon start of a handover procedure.", MakeTraceSourceAccessor (&LteUeRrc::m_handoverStartTrace)) .AddTraceSource ("HandoverEndOk", - "trace fired upon successful termination of a handover procedure", + "Fired upon successful termination of a handover procedure.", MakeTraceSourceAccessor (&LteUeRrc::m_handoverEndOkTrace)) .AddTraceSource ("HandoverEndError", - "trace fired upon failure of a handover procedure", + "Fired upon failure of a handover procedure.", MakeTraceSourceAccessor (&LteUeRrc::m_handoverEndErrorTrace)) ; return tid; --- a/src/lte/model/lte-ue-rrc.h Thu Oct 02 21:17:48 2014 -0700 +++ a/src/lte/model/lte-ue-rrc.h Sun Oct 05 23:25:08 2014 +0300 @@ -467,6 +467,10 @@ void LeaveConnectedMode (); void DisposeOldSrb1 (); uint8_t Bid2Drbid (uint8_t bid); + /** + * Switch the UE RRC to the given state. + * \param s the destination state + */ void SwitchToState (State s); std::map m_bid2DrbidMap; @@ -486,62 +490,137 @@ LteAsSapProvider* m_asSapProvider; LteAsSapUser* m_asSapUser; + /// The current UE RRC state. State m_state; + /// The unique UE identifier. uint64_t m_imsi; + /** + * The `C-RNTI` attribute. Cell Radio Network Temporary Identifier. + */ uint16_t m_rnti; + /** + * The `CellId` attribute. Serving cell identifier. + */ uint16_t m_cellId; + /** + * The `Srb0` attribute. SignalingRadioBearerInfo for SRB0. + */ Ptr m_srb0; + /** + * The `Srb1` attribute. SignalingRadioBearerInfo for SRB1. + */ Ptr m_srb1; + /** + * SRB1 configuration before RRC connection reconfiguration. To be deleted + * soon by DisposeOldSrb1(). + */ Ptr m_srb1Old; + /** + * The `DataRadioBearerMap` attribute. List of UE RadioBearerInfo for Data + * Radio Bearers by LCID. + */ std::map > m_drbMap; + /** + * True if RLC SM is to be used, false if RLC UM/AM are to be used. + * Can be modified using SetUseRlcSm(). + */ bool m_useRlcSm; uint8_t m_lastRrcTransactionIdentifier; LteRrcSap::PdschConfigDedicated m_pdschConfigDedicated; - uint8_t m_dlBandwidth; /**< downlink bandwidth in RBs */ - uint8_t m_ulBandwidth; /**< uplink bandwidth in RBs */ + uint8_t m_dlBandwidth; /**< Downlink bandwidth in RBs. */ + uint8_t m_ulBandwidth; /**< Uplink bandwidth in RBs. */ - uint16_t m_dlEarfcn; /**< downlink carrier frequency */ - uint16_t m_ulEarfcn; /**< uplink carrier frequency */ + uint16_t m_dlEarfcn; /**< Downlink carrier frequency. */ + uint16_t m_ulEarfcn; /**< Uplink carrier frequency. */ - // imsi cellId rnti, sourceCellId + /** + * The `MibReceived` trace source. Fired upon reception of Master Information + * Block. Exporting IMSI, the serving cell ID, RNTI, and the source cell ID. + */ TracedCallback m_mibReceivedTrace; - // imsi cellId rnti, sourceCellId + /** + * The `Sib1Received` trace source. Fired upon reception of System + * Information Block Type 1. Exporting IMSI, the serving cell ID, RNTI, and + * the source cell ID. + */ TracedCallback m_sib1ReceivedTrace; - // imsi cellId rnti + /** + * The `Sib2Received` trace source. Fired upon reception of System + * Information Block Type 2. Exporting IMSI, the serving cell ID, RNTI. + */ TracedCallback m_sib2ReceivedTrace; - // imsi cellId rnti + /** + * The `StateTransition` trace source. Fired upon every UE RRC state + * transition. Exporting IMSI, the serving cell ID, RNTI, old state, and new + * state. + */ TracedCallback m_stateTransitionTrace; - // imsi cellId + /** + * The `InitialCellSelectionEndOk` trace source. Fired upon successful + * initial cell selection procedure. Exporting IMSI and the selected cell ID. + */ TracedCallback m_initialCellSelectionEndOkTrace; - // imsi cellId + /** + * The `InitialCellSelectionEndError` trace source. Fired upon failed initial + * cell selection procedure. Exporting IMSI and the cell ID under evaluation. + */ TracedCallback m_initialCellSelectionEndErrorTrace; - // imsi cellId rnti + /** + * The `RandomAccessSuccessful` trace source. Fired upon successful + * completion of the random access procedure. Exporting IMSI, cell ID, and + * RNTI. + */ TracedCallback m_randomAccessSuccessfulTrace; - // imsi cellId rnti + /** + * The `RandomAccessError` trace source. Fired upon failure of the random + * access procedure. Exporting IMSI, cell ID, and RNTI. + */ TracedCallback m_randomAccessErrorTrace; - // imsi cellId rnti + /** + * The `ConnectionEstablished` trace source. Fired upon successful RRC + * connection establishment. Exporting IMSI, cell ID, and RNTI. + */ TracedCallback m_connectionEstablishedTrace; - // imsi cellId rnti + /** + * The `ConnectionTimeout` trace source. Fired upon timeout RRC connection + * establishment because of T300. Exporting IMSI, cell ID, and RNTI. + */ TracedCallback m_connectionTimeoutTrace; - // imsi cellId rnti + /** + * The `ConnectionReconfiguration` trace source. Fired upon RRC connection + * reconfiguration. Exporting IMSI, cell ID, and RNTI. + */ TracedCallback m_connectionReconfigurationTrace; - // imsi cellId rnti targetCellId + /** + * The `HandoverStart` trace source. Fired upon start of a handover + * procedure. Exporting IMSI, source cell ID, RNTI, and target cell ID. + */ TracedCallback m_handoverStartTrace; - // imsi cellId rnti + /** + * The `HandoverEndOk` trace source. Fired upon successful termination of a + * handover procedure. Exporting IMSI, cell ID, and RNTI. + */ TracedCallback m_handoverEndOkTrace; - // imsi cellId rnti + /** + * The `HandoverEndError` trace source. Fired upon failure of a handover + * procedure. Exporting IMSI, cell ID, and RNTI. + */ TracedCallback m_handoverEndErrorTrace; - bool m_connectionPending; /**< true if a connection request by upper layers is pending */ - bool m_hasReceivedMib; /**< true if MIB was received for the current cell */ - bool m_hasReceivedSib1; /**< true if SIB1 was received for the current cell */ - bool m_hasReceivedSib2; /**< true if SIB2 was received for the current cell */ + /// True if a connection request by upper layers is pending. + bool m_connectionPending; + /// True if MIB was received for the current cell. + bool m_hasReceivedMib; + /// True if SIB1 was received for the current cell. + bool m_hasReceivedSib1; + /// True if SIB2 was received for the current cell. + bool m_hasReceivedSib2; /// Stored content of the last SIB1 received. LteRrcSap::SystemInformationBlockType1 m_lastSib1; @@ -801,9 +880,9 @@ void CancelLeavingTrigger (uint8_t measId, uint16_t cellId); /** - * \brief Timer for RRC connection establishment procedure. - * - * Section 7.3 of 3GPP TS 36.331. + * The `T300` attribute. Timer for RRC connection establishment procedure + * (i.e., the procedure is deemed as failed if it takes longer than this). + * See Section 7.3 of 3GPP TS 36.331. */ Time m_t300; --- a/src/lte/model/no-op-handover-algorithm.h Thu Oct 02 21:17:48 2014 -0700 +++ a/src/lte/model/no-op-handover-algorithm.h Sun Oct 05 23:25:08 2014 +0300 @@ -41,9 +41,7 @@ class NoOpHandoverAlgorithm : public LteHandoverAlgorithm { public: - /** - * \brief Creates a No-op handover algorithm instance. - */ + /// Creates a No-op handover algorithm instance. NoOpHandoverAlgorithm (); virtual ~NoOpHandoverAlgorithm (); @@ -67,8 +65,9 @@ void DoReportUeMeas (uint16_t rnti, LteRrcSap::MeasResults measResults); private: - // Handover Management SAPs + /// Interface to the eNodeB RRC instance. LteHandoverManagementSapUser* m_handoverManagementSapUser; + /// Receive API calls from the eNodeB RRC instance. LteHandoverManagementSapProvider* m_handoverManagementSapProvider; }; // end of class NoOpHandoverAlgorithm