# HG changeset patch # User Tommaso Pecorella # Date 1440239527 -7200 # Parent 624b6f905b54c479053ce3aa17342a914571bd5a [Doxygen] spectrum module fixes diff --git a/src/spectrum/examples/adhoc-aloha-ideal-phy-matrix-propagation-loss-model.cc b/src/spectrum/examples/adhoc-aloha-ideal-phy-matrix-propagation-loss-model.cc --- a/src/spectrum/examples/adhoc-aloha-ideal-phy-matrix-propagation-loss-model.cc +++ b/src/spectrum/examples/adhoc-aloha-ideal-phy-matrix-propagation-loss-model.cc @@ -61,6 +61,8 @@ /** + * \ingroup spectrum + * * Store the last pathloss value for each TX-RX pair. This is an * example of how the PathlossTrace (provided by some SpectrumChannel * implementations) work. @@ -87,7 +89,7 @@ void Print (); private: - std::map > m_pathlossMap; + std::map > m_pathlossMap; //!< Path loss map }; void diff --git a/src/spectrum/helper/adhoc-aloha-noack-ideal-phy-helper.h b/src/spectrum/helper/adhoc-aloha-noack-ideal-phy-helper.h --- a/src/spectrum/helper/adhoc-aloha-noack-ideal-phy-helper.h +++ b/src/spectrum/helper/adhoc-aloha-noack-ideal-phy-helper.h @@ -138,13 +138,13 @@ protected: - ObjectFactory m_phy; - ObjectFactory m_device; - ObjectFactory m_queue; - ObjectFactory m_antenna; - Ptr m_channel; - Ptr m_txPsd; - Ptr m_noisePsd; + ObjectFactory m_phy; //!< Object factory for the phy objects + ObjectFactory m_device; //!< Object factory for the NetDevice objects + ObjectFactory m_queue; //!< Object factory for the Queue objects + ObjectFactory m_antenna; //!< Object factory for the Antenna objects + Ptr m_channel; //!< Channel + Ptr m_txPsd; //!< Tx power spectral density + Ptr m_noisePsd; //!< Noise power spectral density }; diff --git a/src/spectrum/helper/spectrum-analyzer-helper.cc b/src/spectrum/helper/spectrum-analyzer-helper.cc --- a/src/spectrum/helper/spectrum-analyzer-helper.cc +++ b/src/spectrum/helper/spectrum-analyzer-helper.cc @@ -39,6 +39,12 @@ NS_LOG_COMPONENT_DEFINE ("SpectrumAnalyzerHelper"); +/** + * \ingroup spectrum + * \brief Writes a report of the Average Power Spectral Density + * \param streamWrapper the wrapper to the output stream + * \param avgPowerSpectralDensity Average Power Spectral Density + */ static void WriteAveragePowerSpectralDensityReport (Ptr streamWrapper, Ptr avgPowerSpectralDensity) diff --git a/src/spectrum/helper/spectrum-analyzer-helper.h b/src/spectrum/helper/spectrum-analyzer-helper.h --- a/src/spectrum/helper/spectrum-analyzer-helper.h +++ b/src/spectrum/helper/spectrum-analyzer-helper.h @@ -39,7 +39,7 @@ /** * \ingroup spectrum - * + * \brief Class to allow the Spectrum Analysis */ class SpectrumAnalyzerHelper { @@ -48,14 +48,14 @@ ~SpectrumAnalyzerHelper (); /** - * set the SpectrumChannel that will be used by SpectrumPhy instances created by this helper + * Set the SpectrumChannel that will be used by SpectrumPhy instances created by this helper * * @param channel */ void SetChannel (Ptr channel); /** - * set the SpectrumChannel that will be used by SpectrumPhy instances created by this helper + * Set the SpectrumChannel that will be used by SpectrumPhy instances created by this helper * * @param channelName */ @@ -141,13 +141,13 @@ private: - ObjectFactory m_phy; - ObjectFactory m_device; - ObjectFactory m_antenna; + ObjectFactory m_phy; //!< Object factory for the phy objects + ObjectFactory m_device; //!< Object factory for the NetDevice objects + ObjectFactory m_antenna; //!< Object factory for the Antenna objects - Ptr m_channel; - Ptr m_rxSpectrumModel; - std::string m_prefix; + Ptr m_channel; //!< Channel + Ptr m_rxSpectrumModel; //!< Spectrum model + std::string m_prefix; //!< Prefix for the output files }; diff --git a/src/spectrum/helper/spectrum-helper.h b/src/spectrum/helper/spectrum-helper.h --- a/src/spectrum/helper/spectrum-helper.h +++ b/src/spectrum/helper/spectrum-helper.h @@ -39,11 +39,19 @@ /** * \ingroup spectrum - * + * \brief Setup a SpectrumChannel */ class SpectrumChannelHelper { public: + /** + * \brief Setup a default SpectrumChannel. The Default mode is: + * Channel: "ns3::SingleModelSpectrumChannel", + * PropagationDelay: "ns3::ConstantSpeedPropagationDelayModel", and + * SpectrumPropagationLoss: "ns3::FriisSpectrumPropagationLossModel". + * + * \returns a Default-configured SpectrumChannelHelper + */ static SpectrumChannelHelper Default (); /** @@ -190,10 +198,10 @@ Ptr Create (void) const; private: - Ptr m_spectrumPropagationLossModel; - Ptr m_propagationLossModel; - ObjectFactory m_propagationDelay; - ObjectFactory m_channel; + Ptr m_spectrumPropagationLossModel; //!< Spectrum propagation loss model + Ptr m_propagationLossModel; //!< Propagation loss model + ObjectFactory m_propagationDelay; //!< Propagation delay + ObjectFactory m_channel; //!< Channel }; @@ -201,7 +209,7 @@ /** * \ingroup spectrum * - * create and configure several SpectrumPhy instances and connect them to a channel. + * Create and configure several SpectrumPhy instances and connect them to a channel. */ class SpectrumPhyHelper { @@ -269,8 +277,8 @@ private: - ObjectFactory m_phy; - Ptr m_channel; + ObjectFactory m_phy; //!< Object factory for the phy objects + Ptr m_channel; //!< Channel }; diff --git a/src/spectrum/helper/tv-spectrum-transmitter-helper.cc b/src/spectrum/helper/tv-spectrum-transmitter-helper.cc --- a/src/spectrum/helper/tv-spectrum-transmitter-helper.cc +++ b/src/spectrum/helper/tv-spectrum-transmitter-helper.cc @@ -34,8 +34,9 @@ NS_LOG_COMPONENT_DEFINE ("TvSpectrumTransmitterHelper"); -// NORTH AMERICA: 84 elements (index 0 - 83); valid channels = 2 - 83 +/// NORTH AMERICA: 84 elements (index 0 - 83); valid channels = 2 - 83 const int northAmericaArrayLength = 84; +/// NORTH AMERICA start frequencies const double northAmericaStartFrequencies[84] = {0, 0, 54e6, 60e6, 66e6, 76e6, 82e6, 174e6, 180e6, 186e6, 192e6, 198e6, 204e6, 210e6, 470e6, 476e6, 482e6, 488e6, 494e6, 500e6, 506e6, 512e6, 518e6, 524e6, 530e6, 536e6, 542e6, 548e6, @@ -45,6 +46,7 @@ 752e6, 758e6, 764e6, 770e6, 776e6, 782e6, 788e6, 794e6, 800e6, 806e6, 812e6, 818e6, 824e6, 830e6, 836e6, 842e6, 848e6, 854e6, 860e6, 866e6, 872e6, 878e6, 884e6}; +/// NORTH AMERICA end frequencies const double northAmericaEndFrequencies[84] = {0, 0, 60e6, 66e6, 72e6, 82e6, 88e6, 180e6, 186e6, 192e6, 198e6, 204e6, 210e6, 216e6, 476e6, 482e6, 488e6, 494e6, 500e6, 506e6, 512e6, 518e6, 524e6, 530e6, 536e6, 542e6, 548e6, 554e6, @@ -55,8 +57,9 @@ 824e6, 830e6, 836e6, 842e6, 848e6, 854e6, 860e6, 866e6, 872e6, 878e6, 884e6, 890e6}; -// EUROPE: 70 elements (index 0 - 69); valid channels = 5 - 12, 21 - 69 +/// EUROPE: 70 elements (index 0 - 69); valid channels = 5 - 12, 21 - 69 const int europeArrayLength = 70; +/// EUROPE start frequencies const double europeStartFrequencies[70] = {0, 0, 0, 0, 0, 174e6, 181e6, 188e6, 195e6, 202e6, 209e6, 216e6, 223e6, 0, 0, 0, 0, 0, 0, 0, 0, 470e6, 478e6, 486e6, 494e6, 502e6, 510e6, 518e6, 526e6, 534e6, 542e6, 550e6, 558e6, 566e6, @@ -64,6 +67,7 @@ 662e6, 670e6, 678e6, 686e6, 694e6, 702e6, 710e6, 718e6, 726e6, 734e6, 742e6, 750e6, 758e6, 766e6, 774e6, 782e6, 790e6, 798e6, 806e6, 814e6, 822e6, 830e6, 838e6, 846e6, 854e6}; +/// EUROPE end frequencies const double europeEndFrequencies[70] = {0, 0, 0, 0, 0, 181e6, 188e6, 195e6, 202e6, 209e6, 216e6, 223e6, 230e6, 0, 0, 0, 0, 0, 0, 0, 0, 478e6, 486e6, 494e6, 502e6, 510e6, 518e6, 526e6, 534e6, 542e6, 550e6, 558e6, 566e6, 574e6, @@ -72,8 +76,9 @@ 758e6, 766e6, 774e6, 782e6, 790e6, 798e6, 806e6, 814e6, 822e6, 830e6, 838e6, 846e6, 854e6, 862e6}; -// JAPAN: 63 elements (index 0 - 62); valid channels = 1 - 62 +/// JAPAN: 63 elements (index 0 - 62); valid channels = 1 - 62 const int japanArrayLength = 63; +/// JAPAN start frequencies const double japanStartFrequencies[63] = {0, 90e6, 96e6, 102e6, 170e6, 176e6, 182e6, 188e6, 192e6, 198e6, 204e6, 210e6, 216e6, 470e6, 476e6, 482e6, 488e6, 494e6, 500e6, 506e6, 512e6, 518e6, 524e6, 530e6, 536e6, 542e6, 548e6, 554e6, @@ -81,6 +86,7 @@ 626e6, 632e6, 638e6, 644e6, 650e6, 656e6, 662e6, 668e6, 674e6, 680e6, 686e6, 692e6, 698e6, 704e6, 710e6, 716e6, 722e6, 728e6, 734e6, 740e6, 746e6, 752e6, 758e6, 764e6}; +/// JAPAN end frequencies const double japanEndFrequencies[63] = {0, 96e6, 102e6, 108e6, 176e6, 182e6, 188e6, 194e6, 198e6, 204e6, 210e6, 216e6, 222e6, 476e6, 482e6, 488e6, 494e6, 500e6, 506e6, 512e6, 518e6, 524e6, 530e6, 536e6, 542e6, 548e6, 554e6, 560e6, diff --git a/src/spectrum/helper/tv-spectrum-transmitter-helper.h b/src/spectrum/helper/tv-spectrum-transmitter-helper.h --- a/src/spectrum/helper/tv-spectrum-transmitter-helper.h +++ b/src/spectrum/helper/tv-spectrum-transmitter-helper.h @@ -49,17 +49,18 @@ * and location. * * Here is an example of how to use this class: - * - * TvSpectrumTransmitterHelper tvTransHelper; - * tvTransHelper.SetChannel (channel); // provided that user has a Ptr ready. - * tvTransHelper.SetAttribute ("StartFrequency", DoubleValue (524e6)); - * tvTransHelper.SetAttribute ("ChannelBandwidth", DoubleValue (6e6)); - * tvTransHelper.SetAttribute ("StartingTime", TimeValue (Seconds (0))); - * tvTransHelper.SetAttribute ("TransmitDuration", TimeValue (Seconds (0.2))); - * tvTransHelper.SetAttribute ("BasePsd", DoubleValue (22.22)); - * tvTransHelper.SetAttribute ("TvType", EnumValue (TvSpectrumTransmitter::TVTYPE_8VSB)); - * tvTransHelper.SetAttribute ("Antenna", StringValue ("ns3::IsotropicAntennaModel")); - * tvTransHelper.Install (tvTransmitterNode); //provided that user has a NodeContainer ready. + * \code + TvSpectrumTransmitterHelper tvTransHelper; + tvTransHelper.SetChannel (channel); // provided that user has a Ptr ready. + tvTransHelper.SetAttribute ("StartFrequency", DoubleValue (524e6)); + tvTransHelper.SetAttribute ("ChannelBandwidth", DoubleValue (6e6)); + tvTransHelper.SetAttribute ("StartingTime", TimeValue (Seconds (0))); + tvTransHelper.SetAttribute ("TransmitDuration", TimeValue (Seconds (0.2))); + tvTransHelper.SetAttribute ("BasePsd", DoubleValue (22.22)); + tvTransHelper.SetAttribute ("TvType", EnumValue (TvSpectrumTransmitter::TVTYPE_8VSB)); + tvTransHelper.SetAttribute ("Antenna", StringValue ("ns3::IsotropicAntennaModel")); + tvTransHelper.Install (tvTransmitterNode); // provided that user has a NodeContainer ready. + \endcode */ class TvSpectrumTransmitterHelper { @@ -204,7 +205,7 @@ /** * Assigns the stream number for the uniform random number generator to use * - * @param stream first stream index to use + * @param streamNum first stream index to use * @return the number of stream indices assigned by this helper */ int64_t AssignStreams (int64_t streamNum); diff --git a/src/spectrum/helper/waveform-generator-helper.h b/src/spectrum/helper/waveform-generator-helper.h --- a/src/spectrum/helper/waveform-generator-helper.h +++ b/src/spectrum/helper/waveform-generator-helper.h @@ -40,6 +40,7 @@ /** * \ingroup spectrum * + * Create a Waveform generator, which can be used to inject specific noise in the channel. */ class WaveformGeneratorHelper { @@ -134,11 +135,11 @@ protected: - ObjectFactory m_phy; - ObjectFactory m_device; - ObjectFactory m_antenna; - Ptr m_channel; - Ptr m_txPsd; + ObjectFactory m_phy; //!< Object factory for the phy objects + ObjectFactory m_device; //!< Object factory for the NetDevice objects + ObjectFactory m_antenna; //!< Object factory for the Antenna objects + Ptr m_channel; //!< Channel + Ptr m_txPsd; //!< Tx power spectral density }; diff --git a/src/spectrum/model/aloha-noack-mac-header.h b/src/spectrum/model/aloha-noack-mac-header.h --- a/src/spectrum/model/aloha-noack-mac-header.h +++ b/src/spectrum/model/aloha-noack-mac-header.h @@ -30,11 +30,16 @@ /** * \ingroup spectrum + * Header for the AlohaNoack NetDevice * */ class AlohaNoackMacHeader : public Header { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); virtual TypeId GetInstanceTypeId (void) const; virtual uint32_t GetSerializedSize (void) const; @@ -42,14 +47,31 @@ virtual uint32_t Deserialize (Buffer::Iterator start); virtual void Print (std::ostream &os) const; + /** + * Set the source address + * \param source the source address + */ void SetSource (Mac48Address source); + /** + * Set the destination address + * \param destination the destination address + */ void SetDestination (Mac48Address destination); + + /** + * Get the source address + * \returns the source address + */ Mac48Address GetSource () const; + /** + * Get the destination address + * \returns the destination address + */ Mac48Address GetDestination () const; private: - Mac48Address m_source; - Mac48Address m_destination; + Mac48Address m_source; //!< source address + Mac48Address m_destination; //!< destination address }; diff --git a/src/spectrum/model/aloha-noack-net-device.cc b/src/spectrum/model/aloha-noack-net-device.cc --- a/src/spectrum/model/aloha-noack-net-device.cc +++ b/src/spectrum/model/aloha-noack-net-device.cc @@ -35,6 +35,12 @@ NS_LOG_COMPONENT_DEFINE ("AlohaNoackNetDevice"); +/** + * \brief Output stream operator + * \param os output stream + * \param state the state to print + * \return an output stream + */ std::ostream& operator<< (std::ostream& os, AlohaNoackNetDevice::State state) { switch (state) diff --git a/src/spectrum/model/aloha-noack-net-device.h b/src/spectrum/model/aloha-noack-net-device.h --- a/src/spectrum/model/aloha-noack-net-device.h +++ b/src/spectrum/model/aloha-noack-net-device.h @@ -59,11 +59,20 @@ class AlohaNoackNetDevice : public NetDevice { public: + /** + * State of the NetDevice + */ enum State { - IDLE, TX, RX + IDLE, //!< Idle state + TX, //!< Transmitting state + RX //!< Receiving state }; + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); AlohaNoackNetDevice (); @@ -174,37 +183,35 @@ virtual void SetPromiscReceiveCallback (PromiscReceiveCallback cb); virtual bool SupportsSendFrom (void) const; - - - - private: + /** + * Notification of Guard Interval end. + */ void NotifyGuardIntervalEnd (); virtual void DoDispose (void); /** * start the transmission of a packet by contacting the PHY layer - * */ void StartTransmission (); - Ptr m_queue; + Ptr m_queue; //!< packet queue - TracedCallback > m_macTxTrace; - TracedCallback > m_macTxDropTrace; - TracedCallback > m_macPromiscRxTrace; - TracedCallback > m_macRxTrace; + TracedCallback > m_macTxTrace; //!< Tx trace + TracedCallback > m_macTxDropTrace; //!< Tx Drop trace + TracedCallback > m_macPromiscRxTrace; //!< Promiscuous Rx trace + TracedCallback > m_macRxTrace; //!< Rx trace - Ptr m_node; - Ptr m_channel; + Ptr m_node; //!< Node owning this NetDevice + Ptr m_channel; //!< Channel - Mac48Address m_address; + Mac48Address m_address; //!< MAC address - NetDevice::ReceiveCallback m_rxCallback; - NetDevice::PromiscReceiveCallback m_promiscRxCallback; + NetDevice::ReceiveCallback m_rxCallback; //!< Rx callback + NetDevice::PromiscReceiveCallback m_promiscRxCallback; //!< Promiscuous Rx callback - GenericPhyTxStartCallback m_phyMacTxStartCallback; + GenericPhyTxStartCallback m_phyMacTxStartCallback; //!< Tx Start callback /** * List of callbacks to fire if the link changes state (up or down). @@ -212,16 +219,13 @@ TracedCallback<> m_linkChangeCallbacks; - uint32_t m_ifIndex; - mutable uint32_t m_mtu; - bool m_linkUp; + uint32_t m_ifIndex; //!< Interface index + mutable uint32_t m_mtu; //!< NetDevice MTU + bool m_linkUp; //!< true if the link is up - - State m_state; - - Ptr m_currentPkt; - - Ptr m_phy; + State m_state; //!< State of the NetDevice + Ptr m_currentPkt; //!< Current packet + Ptr m_phy; //!< PHY object }; diff --git a/src/spectrum/model/constant-spectrum-propagation-loss.h b/src/spectrum/model/constant-spectrum-propagation-loss.h --- a/src/spectrum/model/constant-spectrum-propagation-loss.h +++ b/src/spectrum/model/constant-spectrum-propagation-loss.h @@ -25,25 +25,40 @@ namespace ns3 { - +/** + * \ingroup spectrum + * + * A Constant (fixed) propagation loss. The loss is not dependent on the distance. + */ class ConstantSpectrumPropagationLossModel : public SpectrumPropagationLossModel { public: ConstantSpectrumPropagationLossModel (); ~ConstantSpectrumPropagationLossModel (); + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (); virtual Ptr DoCalcRxPowerSpectralDensity (Ptr txPsd, Ptr a, Ptr b) const; - + /** + * Set the propagation loss + * \param lossDb the propagation loss [dB] + */ void SetLossDb (double lossDb); + /** + * Get the propagation loss + * \returns the propagation loss [dB] + */ double GetLossDb () const; protected: - double m_lossDb; - double m_lossLinear; + double m_lossDb; //!< Propagation loss [dB] + double m_lossLinear; //!< Propagation loss (linear) private: }; diff --git a/src/spectrum/model/friis-spectrum-propagation-loss.h b/src/spectrum/model/friis-spectrum-propagation-loss.h --- a/src/spectrum/model/friis-spectrum-propagation-loss.h +++ b/src/spectrum/model/friis-spectrum-propagation-loss.h @@ -32,7 +32,15 @@ /** * \ingroup spectrum + * \brief Friis spectrum propagation loss model * + * The propagation loss is calculated according to a simplified version of Friis' + * formula in which antenna gains are unitary: + * + * \f$ L = \frac{4 \pi * d * f}{C^2}\f$ + * + * where C = 3e8 m/s is the light speed in the vacuum. The intended + * use is to calculate Prx = Ptx * G */ class FriisSpectrumPropagationLossModel : public SpectrumPropagationLossModel { @@ -41,6 +49,10 @@ FriisSpectrumPropagationLossModel (); ~FriisSpectrumPropagationLossModel (); + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (); @@ -51,14 +63,7 @@ /** * Return the propagation loss L according to a simplified version of Friis' - * formula in which antenna gains are unitary: - * - * (4 * pi * d * f) ^ 2 - * L = ---------------------- - * C^2 - * - * where C = 3e8 m/s is the light speed in the vacuum. The intended - * use is to calculate Prx = Ptx * G + * formula in which antenna gains are unitary * * @param f frequency in Hz * @param d distance in m @@ -66,10 +71,6 @@ * @return if Prx < Ptx then return Prx; else return Ptx */ double CalculateLoss (double f, double d) const; - -protected: - double m_propagationSpeed; - }; diff --git a/src/spectrum/model/half-duplex-ideal-phy.cc b/src/spectrum/model/half-duplex-ideal-phy.cc --- a/src/spectrum/model/half-duplex-ideal-phy.cc +++ b/src/spectrum/model/half-duplex-ideal-phy.cc @@ -71,6 +71,12 @@ SpectrumPhy::DoDispose (); } +/** + * \brief Output stream operator + * \param os output stream + * \param s the state to print + * \return an output stream + */ std::ostream& operator<< (std::ostream& os, HalfDuplexIdealPhy::State s) { switch (s) diff --git a/src/spectrum/model/half-duplex-ideal-phy.h b/src/spectrum/model/half-duplex-ideal-phy.h --- a/src/spectrum/model/half-duplex-ideal-phy.h +++ b/src/spectrum/model/half-duplex-ideal-phy.h @@ -84,13 +84,18 @@ /** * PHY states - * */ enum State { - IDLE, TX, RX + IDLE, //!< Idle state + TX, //!< Transmitting state + RX //!< Receiving state }; + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); // inherited from SpectrumPhy @@ -105,17 +110,17 @@ /** - * set the Power Spectral Density of outgoing signals in power units + * \brief Set the Power Spectral Density of outgoing signals in power units * (Watt, Pascal...) per Hz. * - * @param txPsd + * @param txPsd Tx Power Spectral Density */ void SetTxPowerSpectralDensity (Ptr txPsd); /** - * - * @param noisePsd the Noise Power Spectral Density in power units + * \brief Set the Noise Power Spectral Density in power units * (Watt, Pascal...) per Hz. + * @param noisePsd the Noise Power Spectral Density */ void SetNoisePowerSpectralDensity (Ptr noisePsd); @@ -132,29 +137,30 @@ bool StartTx (Ptr p); /** - * set the PHY rate to be used by this PHY. + * Set the PHY rate to be used by this PHY. * - * @param rate + * @param rate DataRate */ void SetRate (DataRate rate); /** + * Get the PHY rate to be used by this PHY. * * @return the PHY rate used by this PHY. */ DataRate GetRate () const; /** - * set the callback for the end of a TX, as part of the - * interconnections betweenthe PHY and the MAC + * Set the callback for the end of a TX, as part of the + * interconnections between the PHY and the MAC * * @param c the callback */ void SetGenericPhyTxEndCallback (GenericPhyTxEndCallback c); /** - * set the callback for the start of RX, as part of the - * interconnections betweenthe PHY and the MAC + * Set the callback for the start of RX, as part of the + * interconnections between the PHY and the MAC * * @param c the callback */ @@ -162,7 +168,7 @@ /** * set the callback for the end of a RX in error, as part of the - * interconnections betweenthe PHY and the MAC + * interconnections between the PHY and the MAC * * @param c the callback */ @@ -170,7 +176,7 @@ /** * set the callback for the successful end of a RX, as part of the - * interconnections betweenthe PHY and the MAC + * interconnections between the PHY and the MAC * * @param c the callback */ @@ -186,52 +192,56 @@ private: virtual void DoDispose (void); + /** + * Change the PHY state + * \param newState new state + */ void ChangeState (State newState); + /** + * End the current Tx + */ void EndTx (); + /** + * About current Rx + */ void AbortRx (); + /** + * End current Rx + */ void EndRx (); - EventId m_endRxEventId; + EventId m_endRxEventId; //!< End Rx event - Ptr m_mobility; - Ptr m_antenna; - Ptr m_netDevice; - Ptr m_channel; + Ptr m_mobility; //!< Mobility model + Ptr m_antenna; //!< Antenna model + Ptr m_netDevice; //!< NetDevice connected to theis phy + Ptr m_channel; //!< Channel - Ptr m_txPsd; - Ptr m_rxPsd; - Ptr m_txPacket; - Ptr m_rxPacket; + Ptr m_txPsd; //!< Tx power spectral density + Ptr m_rxPsd; //!< Rx power spectral density + Ptr m_txPacket; //!< Tx packet + Ptr m_rxPacket; //!< Rx packet - DataRate m_rate; + DataRate m_rate; //!< Datarate + State m_state; //!< PHY state - State m_state; + TracedCallback > m_phyTxStartTrace; //!< Trace - Tx start + TracedCallback > m_phyTxEndTrace; //!< Trace - Tx end + TracedCallback > m_phyRxStartTrace; //!< Trace - Rx start + TracedCallback > m_phyRxAbortTrace; //!< Trace - Rx abort + TracedCallback > m_phyRxEndOkTrace; //!< Trace - Tx end (ok) + TracedCallback > m_phyRxEndErrorTrace; //!< Trace - Rx end (error) - TracedCallback > m_phyTxStartTrace; - TracedCallback > m_phyTxEndTrace; - TracedCallback > m_phyRxStartTrace; - TracedCallback > m_phyRxAbortTrace; - TracedCallback > m_phyRxEndOkTrace; - TracedCallback > m_phyRxEndErrorTrace; + GenericPhyTxEndCallback m_phyMacTxEndCallback; //!< Callback - Tx end + GenericPhyRxStartCallback m_phyMacRxStartCallback; //!< Callback - Rx start + GenericPhyRxEndErrorCallback m_phyMacRxEndErrorCallback; //!< Callback - Rx error + GenericPhyRxEndOkCallback m_phyMacRxEndOkCallback; //!< Callback - Rx end - GenericPhyTxEndCallback m_phyMacTxEndCallback; - GenericPhyRxStartCallback m_phyMacRxStartCallback; - GenericPhyRxEndErrorCallback m_phyMacRxEndErrorCallback; - GenericPhyRxEndOkCallback m_phyMacRxEndOkCallback; - - SpectrumInterference m_interference; + SpectrumInterference m_interference; //!< Received interference }; - - - - - } - - - #endif /* HALF_DUPLEX_IDEAL_PHY_H */ diff --git a/src/spectrum/model/microwave-oven-spectrum-value-helper.cc b/src/spectrum/model/microwave-oven-spectrum-value-helper.cc --- a/src/spectrum/model/microwave-oven-spectrum-value-helper.cc +++ b/src/spectrum/model/microwave-oven-spectrum-value-helper.cc @@ -25,10 +25,15 @@ NS_LOG_COMPONENT_DEFINE ("MicrowaveOvenSpectrumValue"); +/// Spectrum model for the 5MHz model (model #2) static Ptr g_MicrowaveOvenSpectrumModel5Mhz; +/// Spectrum model for the 6MHz model (model #1) static Ptr g_MicrowaveOvenSpectrumModel6Mhz; - +/** + * \ingroup spectrum + * Init a static class containing the MWO #2 model (5Mhz) + */ static class MicrowaveOvenSpectrumModel5MhzInitializer { public: @@ -47,10 +52,14 @@ NS_LOG_LOGIC ("bands.size () :" << bands.size ()); g_MicrowaveOvenSpectrumModel5Mhz = Create (bands); } -} g_MicrowaveOvenSpectrumModel5MhzInitializerInstance; +} g_MicrowaveOvenSpectrumModel5MhzInitializerInstance; //!< MWO model #2 +/** + * \ingroup spectrum + * Init a static class containing the MWO #1 model (6Mhz) + */ static class MicrowaveOvenSpectrumModel6MhzInitializer { public: @@ -69,7 +78,7 @@ NS_LOG_LOGIC ("bands.size () :" << bands.size ()); g_MicrowaveOvenSpectrumModel6Mhz = Create (bands); } -} g_MicrowaveOvenSpectrumModel6MhzInitializerInstance; +} g_MicrowaveOvenSpectrumModel6MhzInitializerInstance; //!< MWO model #1 diff --git a/src/spectrum/model/multi-model-spectrum-channel.cc b/src/spectrum/model/multi-model-spectrum-channel.cc --- a/src/spectrum/model/multi-model-spectrum-channel.cc +++ b/src/spectrum/model/multi-model-spectrum-channel.cc @@ -46,6 +46,12 @@ NS_OBJECT_ENSURE_REGISTERED (MultiModelSpectrumChannel); +/** + * \brief Output stream operator + * \param lhs output stream + * \param rhs the TxSpectrumModelInfoMap to print + * \return an output stream + */ std::ostream& operator<< (std::ostream& lhs, TxSpectrumModelInfoMap_t& rhs) { for (TxSpectrumModelInfoMap_t::iterator it = rhs.begin (); diff --git a/src/spectrum/model/multi-model-spectrum-channel.h b/src/spectrum/model/multi-model-spectrum-channel.h --- a/src/spectrum/model/multi-model-spectrum-channel.h +++ b/src/spectrum/model/multi-model-spectrum-channel.h @@ -33,43 +33,63 @@ namespace ns3 { +/** + * \ingroup spectrum + * Container: SpectrumModelUid_t, SpectrumConverter + */ typedef std::map SpectrumConverterMap_t; - /** * \ingroup spectrum - * + * The Tx spectrum model information. This class is used to convert + * one spectrum model into another one. */ class TxSpectrumModelInfo { public: + /** + * Constructor. + * \param txSpectrumModel the Tx Spectrum model. + */ TxSpectrumModelInfo (Ptr txSpectrumModel); - Ptr m_txSpectrumModel; - SpectrumConverterMap_t m_spectrumConverterMap; + Ptr m_txSpectrumModel; //!< Tx Spectrum model. + SpectrumConverterMap_t m_spectrumConverterMap; //!< Spectrum converter. }; -typedef std::map TxSpectrumModelInfoMap_t; - /** * \ingroup spectrum - * + * Container: SpectrumModelUid_t, TxSpectrumModelInfo + */ +typedef std::map TxSpectrumModelInfoMap_t; + + +/** + * \ingroup spectrum + * The Rx spectrum model information. This class is used to convert + * one spectrum model into another one. */ class RxSpectrumModelInfo { public: + /** + * Constructor. + * \param rxSpectrumModel the Rx Spectrum model. + */ RxSpectrumModelInfo (Ptr rxSpectrumModel); - Ptr m_rxSpectrumModel; - std::set > m_rxPhySet; + Ptr m_rxSpectrumModel; //!< Rx Spectrum model. + std::set > m_rxPhySet; //!< Container of the Rx Spectrum phy objects. }; +/** + * \ingroup spectrum + * Container: SpectrumModelUid_t, RxSpectrumModelInfo + */ typedef std::map RxSpectrumModelInfoMap_t; - - /** * \ingroup spectrum * @@ -89,6 +109,10 @@ public: MultiModelSpectrumChannel (); + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); // inherited from SpectrumChannel @@ -103,58 +127,55 @@ virtual uint32_t GetNDevices (void) const; virtual Ptr GetDevice (uint32_t i) const; + /** + * Get the frequency-dependent propagation loss model. + * \returns a pointer to the propagation loss model. + */ virtual Ptr GetSpectrumPropagationLossModel (void); protected: void DoDispose (); - - private: /** - * this method checks if m_rxSpectrumModelInfoMap contains an entry + * This method checks if m_rxSpectrumModelInfoMap contains an entry * for the given TX SpectrumModel. If such entry exists, it returns * an interator pointing to it. If not, it creates a new entry in * m_txSpectrumMpodelInfoMap, and returns an iterator to it. * - * @param txSpectrumModel the TX SpectrumModel being considered + * @param txSpectrumModel The TX SpectrumModel being considered * - * @return an iterator pointing to the corresponding entry in m_txSpectrumModelInfoMap + * @return An iterator pointing to the corresponding entry in m_txSpectrumModelInfoMap */ TxSpectrumModelInfoMap_t::const_iterator FindAndEventuallyAddTxSpectrumModel (Ptr txSpectrumModel); /** - * used internally to reschedule transmission after the propagation delay + * Used internally to reschedule transmission after the propagation delay. * - * @param params - * @param receiver + * @param params The signal paramters. + * @param receiver A pointer to the receiver SpectrumPhy. */ virtual void StartRx (Ptr params, Ptr receiver); - - /** - * propagation delay model to be used with this channel - * + * Propagation delay model to be used with this channel. */ Ptr m_propagationDelay; /** - * single-frequency propagation loss model to be used with this channel - * - */ + * Single-frequency propagation loss model to be used with this channel. + */ Ptr m_propagationLoss; /** - * frequency-dependent propagation loss model to be used with this channel - * + * Frequency-dependent propagation loss model to be used with this channel. */ Ptr m_spectrumPropagationLoss; /** - * data structure holding, for each TX SpectrumModel, all the + * Data structure holding, for each TX SpectrumModel, all the * converters to any RX SpectrumModel, and all the corresponding * SpectrumPhy instances. * @@ -163,14 +184,21 @@ /** - * data structure holding, for each RX spectrum model, all the + * Data structure holding, for each RX spectrum model, all the * corresponding SpectrumPhy instances. - * */ RxSpectrumModelInfoMap_t m_rxSpectrumModelInfoMap; + /** + * Number of devices connected to the channel. + */ uint32_t m_numDevices; + /** + * Maximum loss [dB]. + * + * Any device above this loss is considered out of range. + */ double m_maxLossDb; /** diff --git a/src/spectrum/model/non-communicating-net-device.h b/src/spectrum/model/non-communicating-net-device.h --- a/src/spectrum/model/non-communicating-net-device.h +++ b/src/spectrum/model/non-communicating-net-device.h @@ -54,6 +54,10 @@ class NonCommunicatingNetDevice : public NetDevice { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); NonCommunicatingNetDevice (); @@ -123,12 +127,10 @@ private: virtual void DoDispose (void); - Ptr m_node; - Ptr m_channel; - - uint32_t m_ifIndex; - - Ptr m_phy; + Ptr m_node; //!< node this NetDevice is associated to + Ptr m_channel; //!< Channel used by the NetDevice + uint32_t m_ifIndex; //!< Interface index + Ptr m_phy; //!< Phy object }; diff --git a/src/spectrum/model/single-model-spectrum-channel.h b/src/spectrum/model/single-model-spectrum-channel.h --- a/src/spectrum/model/single-model-spectrum-channel.h +++ b/src/spectrum/model/single-model-spectrum-channel.h @@ -43,9 +43,12 @@ public: SingleModelSpectrumChannel (); + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); - // inherited from SpectrumChannel virtual void AddPropagationLossModel (Ptr loss); virtual void AddSpectrumPropagationLossModel (Ptr loss); @@ -58,16 +61,20 @@ virtual uint32_t GetNDevices (void) const; virtual Ptr GetDevice (uint32_t i) const; - + /// Container: SpectrumPhy objects typedef std::vector > PhyList; + /** + * Get the frequency-dependent propagation loss model. + * \returns a pointer to the propagation loss model. + */ virtual Ptr GetSpectrumPropagationLossModel (void); private: virtual void DoDispose (); /** - * used internally to reschedule transmission after the propagation delay + * Used internally to reschedule transmission after the propagation delay. * * @param params * @param receiver @@ -75,38 +82,38 @@ void StartRx (Ptr params, Ptr receiver); /** - * list of SpectrumPhy instances attached to - * the channel + * List of SpectrumPhy instances attached to the channel. */ PhyList m_phyList; /** - * SpectrumModel that this channel instance - * is supporting + * SpectrumModel that this channel instance is supporting. */ Ptr m_spectrumModel; /** - * propagation delay model to be used with this channel - * + * Propagation delay model to be used with this channel. */ Ptr m_propagationDelay; /** - * single-frequency propagation loss model to be used with this channel - * - */ + * Single-frequency propagation loss model to be used with this channel. + */ Ptr m_propagationLoss; /** - * frequency-dependent propagation loss model to be used with this channel - * + * Frequency-dependent propagation loss model to be used with this channel. */ Ptr m_spectrumPropagationLoss; + /** + * Maximum loss [dB]. + * + * Any device above this loss is considered out of range. + */ double m_maxLossDb; /** diff --git a/src/spectrum/model/spectrum-analyzer.cc b/src/spectrum/model/spectrum-analyzer.cc --- a/src/spectrum/model/spectrum-analyzer.cc +++ b/src/spectrum/model/spectrum-analyzer.cc @@ -74,7 +74,7 @@ .SetGroupName ("Spectrum") .AddConstructor () .AddAttribute ("Resolution", - "The lengh of the time interval over which the " + "The length of the time interval over which the " "power spectral density of incoming signals is averaged", TimeValue (MilliSeconds (1)), MakeTimeAccessor (&SpectrumAnalyzer::m_resolution), diff --git a/src/spectrum/model/spectrum-analyzer.h b/src/spectrum/model/spectrum-analyzer.h --- a/src/spectrum/model/spectrum-analyzer.h +++ b/src/spectrum/model/spectrum-analyzer.h @@ -38,7 +38,7 @@ /** * \ingroup spectrum * - * Simple SpectrumPhy implemetation that averages the spectrum power + * Simple SpectrumPhy implementation that averages the spectrum power * density of incoming transmissions to produce a spectrogram. * * @@ -52,9 +52,13 @@ SpectrumAnalyzer (); virtual ~SpectrumAnalyzer (); + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); -// inherited from SpectrumPhy + // inherited from SpectrumPhy void SetChannel (Ptr c); void SetMobility (Ptr m); void SetDevice (Ptr d); @@ -68,12 +72,12 @@ /** * Set the spectrum model used by the SpectrumAnalyzer to represent incoming signals * - * @param m + * @param m the Rx Spectrum model */ void SetRxSpectrumModel (Ptr m); /** - * set the AntennaModel to be used + * Set the AntennaModel to be used * * \param a the Antenna Model */ @@ -96,25 +100,40 @@ void DoDispose (); private: - Ptr m_mobility; - Ptr m_antenna; - Ptr m_netDevice; - Ptr m_channel; + Ptr m_mobility; //!< Pointer to the mobility model + Ptr m_antenna; //!< Pointer to the Antenna model + Ptr m_netDevice; //!< Pointer to the NetDevice using this object + Ptr m_channel; //!< Pointer to the channel to be analyzed + /** + * Generates a report of the data collected so far. + * + * This function is called periodically. + */ virtual void GenerateReport (); + /** + * Adds a signal to the data collected. + */ void AddSignal (Ptr psd); + /** + * Removes a signal to the data collected. + */ void SubtractSignal (Ptr psd); + /** + * Updates the data about the received Energy + */ void UpdateEnergyReceivedSoFar (); - Ptr m_spectrumModel; - Ptr m_sumPowerSpectralDensity; - Ptr m_energySpectralDensity; - double m_noisePowerSpectralDensity; - Time m_resolution; - Time m_lastChangeTime; - bool m_active; + Ptr m_spectrumModel; //!< Spectrum model + Ptr m_sumPowerSpectralDensity; //!< Sum of the received PSD + Ptr m_energySpectralDensity; //!< Energy spectral density + double m_noisePowerSpectralDensity; //!< Noise power spectral density + Time m_resolution; //!< Time resolution + Time m_lastChangeTime; //!< When the last update happened + bool m_active; //!< True if the analyzer is active + /// TracedCallback - average power spectral density report. TracedCallback > m_averagePowerSpectralDensityReportTrace; }; diff --git a/src/spectrum/model/spectrum-channel.h b/src/spectrum/model/spectrum-channel.h --- a/src/spectrum/model/spectrum-channel.h +++ b/src/spectrum/model/spectrum-channel.h @@ -47,11 +47,15 @@ { public: virtual ~SpectrumChannel (); + + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); - /** - * set the single-frequency propagation loss model to be used + * Set the single-frequency propagation loss model to be used * \warning only models that do not depend on the TX power should be used. * * \param loss a pointer to the propagation loss model to be used. @@ -59,13 +63,13 @@ virtual void AddPropagationLossModel (Ptr loss) = 0; /** - * set the frequency-dependent propagation loss model to be used + * Set the frequency-dependent propagation loss model to be used * \param loss a pointer to the propagation loss model to be used. */ virtual void AddSpectrumPropagationLossModel (Ptr loss) = 0; /** - * set the propagation delay model to be used + * Set the propagation delay model to be used * \param delay Ptr to the propagation delay model to be used. */ virtual void SetPropagationDelayModel (Ptr delay) = 0; @@ -79,7 +83,7 @@ virtual void StartTx (Ptr params) = 0; /** - * @brief add a SpectrumPhy to a channel, so it can receive packets + * @brief Add a SpectrumPhy to a channel, so it can receive packets * * This method is used to attach a SpectrumPhy instance to a * SpectrumChannel instance, so that the SpectrumPhy can receive diff --git a/src/spectrum/model/spectrum-converter.h b/src/spectrum/model/spectrum-converter.h --- a/src/spectrum/model/spectrum-converter.h +++ b/src/spectrum/model/spectrum-converter.h @@ -78,9 +78,9 @@ */ double GetCoefficient (const BandInfo& from, const BandInfo& to) const; - std::vector > m_conversionMatrix; // /< matrix of conversion coefficients - Ptr m_fromSpectrumModel; // /< the SpectrumModel this SpectrumConverter instance can convert from - Ptr m_toSpectrumModel; // /< the SpectrumModel this SpectrumConverter instance can convert to + std::vector > m_conversionMatrix; //!< matrix of conversion coefficients + Ptr m_fromSpectrumModel; //!< the SpectrumModel this SpectrumConverter instance can convert from + Ptr m_toSpectrumModel; //!< the SpectrumModel this SpectrumConverter instance can convert to }; diff --git a/src/spectrum/model/spectrum-error-model.cc b/src/spectrum/model/spectrum-error-model.cc --- a/src/spectrum/model/spectrum-error-model.cc +++ b/src/spectrum/model/spectrum-error-model.cc @@ -44,6 +44,9 @@ { } + +NS_OBJECT_ENSURE_REGISTERED (ShannonSpectrumErrorModel); + /* static */ TypeId ShannonSpectrumErrorModel::GetTypeId () @@ -55,6 +58,7 @@ ; return tid; } + void ShannonSpectrumErrorModel::DoDispose () { diff --git a/src/spectrum/model/spectrum-error-model.h b/src/spectrum/model/spectrum-error-model.h --- a/src/spectrum/model/spectrum-error-model.h +++ b/src/spectrum/model/spectrum-error-model.h @@ -46,8 +46,24 @@ */ static TypeId GetTypeId (); virtual ~SpectrumErrorModel (); + + /** + * Start a packet reception + * \param p the packet + */ virtual void StartRx (Ptr p) = 0; + + /** + * Evaluates a chunk + * \param sinr the SpectrumValue experienced by the Chunk + * \param duration the Chunk length + */ virtual void EvaluateChunk (const SpectrumValue& sinr, Time duration) = 0; + + /** + * Checks if the packet being received is correct + * \returns true if the packet is correct. + */ virtual bool IsRxCorrect () = 0; }; @@ -77,8 +93,8 @@ bool IsRxCorrect (); private: - uint32_t m_bytes; - uint32_t m_deliverableBytes; + uint32_t m_bytes; //!< Length of the packet being received + uint32_t m_deliverableBytes; //!< Bytes that can be received according to the Shnanon's formula }; diff --git a/src/spectrum/model/spectrum-interference.h b/src/spectrum/model/spectrum-interference.h --- a/src/spectrum/model/spectrum-interference.h +++ b/src/spectrum/model/spectrum-interference.h @@ -56,14 +56,14 @@ static TypeId GetTypeId (void); /** - * set the SpectrumErrorModel to be used. + * Set the SpectrumErrorModel to be used. * - * @param e + * @param e the error model */ void SetErrorModel (Ptr e); /** - * notify that the PHY is starting a RX attempt + * Notify that the PHY is starting a RX attempt * * @param p the packet corresponding to the signal being RX * @param rxPsd the power spectral density of the signal being RX @@ -71,12 +71,12 @@ void StartRx (Ptr p, Ptr rxPsd); /** - * notify that the PHY has aborted RX + * Notify that the PHY has aborted RX */ void AbortRx (); /** - * notify that the RX attempt has ended. The receiving PHY must call + * Notify that the RX attempt has ended. The receiving PHY must call * this method upon RX end in order to: * 1) know if RX was successful or not * 2) free up resources that might eventually be used for the @@ -90,17 +90,17 @@ /** - * notify that a new signal is being perceived in the medium. This + * Notify that a new signal is being perceived in the medium. This * method is to be called for all incoming signal, regardless of - * wether they're useful signals or interferers. + * whether they're useful signals or interferers. * * @param spd the power spectral density of the new signal * @param duration the duration of the new signal */ void AddSignal (Ptr spd, const Time duration); - /** + * Set the Noise Power Spectral Density * * @param noisePsd the Noise Power Spectral Density in power units * (Watt, Pascal...) per Hz. @@ -112,30 +112,40 @@ void DoDispose (); private: + + /** + * Evaluate a Chunk, depending on the Rx status and the last update time + */ void ConditionallyEvaluateChunk (); + /** + * Adds a signal perceived in the medium. + * @param spd the power spectral density of the new signal + */ void DoAddSignal (Ptr spd); + /** + * Removes a signal perceived in the medium. + * @param spd the power spectral density of the new signal + */ void DoSubtractSignal (Ptr spd); + bool m_receiving; //!< True if in Rx status + /** + * Stores the power spectral density of the signal whose RX is being attempted + */ + Ptr m_rxSignal; - bool m_receiving; + /** + * Stores the spectral power density of the sum of incoming signals; + * does not include noise, includes the SPD of the signal being RX + */ + Ptr m_allSignals; - Ptr m_rxSignal; /**< stores the power spectral density of - * the signal whose RX is being - * attempted - */ + Ptr m_noise; //!< Noise spectral power density - Ptr m_allSignals; /**< stores the spectral - * power density of the sum of incoming signals; - * does not include noise, includes the SPD of the signal being RX - */ + Time m_lastChangeTime; //!< the time of the last change in m_TotalPower - Ptr m_noise; - - Time m_lastChangeTime; /**< the time of the last change in - m_TotalPower */ - - Ptr m_errorModel; + Ptr m_errorModel; //!< Error model diff --git a/src/spectrum/model/spectrum-model.h b/src/spectrum/model/spectrum-model.h --- a/src/spectrum/model/spectrum-model.h +++ b/src/spectrum/model/spectrum-model.h @@ -44,13 +44,16 @@ */ struct BandInfo { - double fl; ///< lower limit of subband - double fc; ///< center frequency - double fh; ///< upper limit of subband + double fl; //!< lower limit of subband + double fc; //!< center frequency + double fh; //!< upper limit of subband }; +/// Container of BandInfo typedef std::vector Bands; + +/// Uid for SpectrumModels typedef uint32_t SpectrumModelUid_t; /** @@ -63,6 +66,12 @@ class SpectrumModel : public SimpleRefCount { public: + /** + * Comparison operator. Returns true if the two SpectumModels are identical + * \param lhs left operand + * \param rhs right operand + * \returns true if the two operands are identical + */ friend bool operator== (const SpectrumModel& lhs, const SpectrumModel& rhs); /** @@ -102,15 +111,19 @@ */ SpectrumModelUid_t GetUid () const; - + /** + * Const Iterator to the model Bands container start. + */ Bands::const_iterator Begin () const; + /** + * Const Iterator to the model Bands container end. + */ Bands::const_iterator End () const; private: - Bands m_bands; ///< actual definition of frequency bands - /// within this SpectrumModel - SpectrumModelUid_t m_uid; ///< unique id for a given set of frequencies - static SpectrumModelUid_t m_uidCount; ///< counter to assign m_uids + Bands m_bands; //!< Actual definition of frequency bands within this SpectrumModel + SpectrumModelUid_t m_uid; //!< unique id for a given set of frequencies + static SpectrumModelUid_t m_uidCount; //!< counter to assign m_uids }; diff --git a/src/spectrum/model/spectrum-phy.h b/src/spectrum/model/spectrum-phy.h --- a/src/spectrum/model/spectrum-phy.h +++ b/src/spectrum/model/spectrum-phy.h @@ -49,17 +49,21 @@ SpectrumPhy (); virtual ~SpectrumPhy (); + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); /** - * set the associated NetDevice instance + * Set the associated NetDevice instance * * @param d the NetDevice instance */ virtual void SetDevice (Ptr d) = 0; /** - * get the associated NetDevice instance + * Get the associated NetDevice instance * * @return a Ptr to the associated NetDevice instance */ @@ -73,7 +77,7 @@ virtual void SetMobility (Ptr m) = 0; /** - * get the associated MobilityModel instance + * Get the associated MobilityModel instance * * @return a Ptr to the associated MobilityModel instance */ @@ -95,7 +99,7 @@ virtual Ptr GetRxSpectrumModel () const = 0; /** - * get the AntennaModel used by the NetDevice for reception + * Get the AntennaModel used by the NetDevice for reception * * @return a Ptr to the AntennaModel used by the NetDevice for reception */ @@ -109,7 +113,18 @@ virtual void StartRx (Ptr params) = 0; private: + /** + * \brief Copy constructor + * + * Defined and unimplemented to avoid misuse + */ SpectrumPhy (SpectrumPhy const &); + /** + * \brief Copy constructor + * + * Defined and unimplemented to avoid misuse + * \returns + */ SpectrumPhy& operator= (SpectrumPhy const &); }; diff --git a/src/spectrum/model/spectrum-propagation-loss-model.h b/src/spectrum/model/spectrum-propagation-loss-model.h --- a/src/spectrum/model/spectrum-propagation-loss-model.h +++ b/src/spectrum/model/spectrum-propagation-loss-model.h @@ -47,11 +47,14 @@ SpectrumPropagationLossModel (); virtual ~SpectrumPropagationLossModel (); + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (); - /** - * used to chain various instances of SpectrumPropagationLossModel + * Used to chain various instances of SpectrumPropagationLossModel * * @param next */ @@ -63,12 +66,12 @@ * @param txPsd the SpectrumValue representing the power spectral * density of the transmission. Watt units are to be used for radio * communications, and Pascal units for acoustic communications - * (e.g. underwater). + * (e.g., underwater). * * @param a sender mobility * @param b receiver mobility * - * @return set of values vs frequency representing the received + * @return set of values Vs frequency representing the received * power in the same units used for the txPower parameter. */ Ptr CalcRxPowerSpectralDensity (Ptr txPsd, @@ -82,20 +85,19 @@ private: /** * - * - * @param txPsd set of values vs frequency representing the + * @param txPsd set of values Vs frequency representing the * transmission power. See SpectrumChannel for details. * @param a sender mobility * @param b receiver mobility * - * @return set of values vs frequency representing the received + * @return set of values Vs frequency representing the received * power in the same units used for the txPower parameter. */ virtual Ptr DoCalcRxPowerSpectralDensity (Ptr txPsd, Ptr a, Ptr b) const = 0; - Ptr m_next; + Ptr m_next; //!< SpectrumPropagationLossModel chained to this one. }; diff --git a/src/spectrum/model/spectrum-signal-parameters.h b/src/spectrum/model/spectrum-signal-parameters.h --- a/src/spectrum/model/spectrum-signal-parameters.h +++ b/src/spectrum/model/spectrum-signal-parameters.h @@ -35,6 +35,8 @@ class AntennaModel; /** + * \ingroup spectrum + * * This struct provides the generic signal representation to be used by * all wireless technologies. Any specific wireless technology is * allowed to define additional signal parameters by inheriting from this diff --git a/src/spectrum/model/spectrum-value.cc b/src/spectrum/model/spectrum-value.cc --- a/src/spectrum/model/spectrum-value.cc +++ b/src/spectrum/model/spectrum-value.cc @@ -416,6 +416,12 @@ } +/** + * \brief Output stream operator + * \param os output stream + * \param pvf the SpectrumValue to print + * \return an output stream + */ std::ostream& operator << (std::ostream& os, const SpectrumValue& pvf) { diff --git a/src/spectrum/model/spectrum-value.h b/src/spectrum/model/spectrum-value.h --- a/src/spectrum/model/spectrum-value.h +++ b/src/spectrum/model/spectrum-value.h @@ -30,6 +30,7 @@ namespace ns3 { +/// Container for element values typedef std::vector Values; /** @@ -283,7 +284,7 @@ /** * unary plus operator * - * + * @param rhs Right Hand Side of the operator * @return the value of *this */ friend SpectrumValue operator+ (const SpectrumValue& rhs); @@ -291,7 +292,7 @@ /** * unary minus operator * - * + * @param rhs Right Hand Side of the operator * @return the value of - *this */ friend SpectrumValue operator- (const SpectrumValue& rhs); @@ -452,7 +453,6 @@ /** * - * * @param lhs the base * @param rhs the exponent * @@ -515,33 +515,94 @@ private: + /** + * Add a SpectrumValue (element to element addition) + * \param x SpectrumValue + */ void Add (const SpectrumValue& x); + /** + * Add a flat value to all the current elements + * \param s flat value + */ void Add (double s); + /** + * Subtracts a SpectrumValue (element by element subtraction) + * \param x SpectrumValue + */ void Subtract (const SpectrumValue& x); + /** + * Subtracts a flat value to all the current elements + * \param s flat value + */ void Subtract (double s); + /** + * Multiplies for a SpectrumValue (element to element multiplication) + * \param x SpectrumValue + */ void Multiply (const SpectrumValue& x); + /** + * Multiplies for a flat value to all the current elements + * \param s flat value + */ void Multiply (double s); + /** + * Divides by a SpectrumValue (element to element division) + * \param x SpectrumValue + */ void Divide (const SpectrumValue& x); + /** + * Divides by a flat value to all the current elements + * \param s flat value + */ void Divide (double s); + /** + * Change the values sign + */ void ChangeSign (); + /** + * Shift the values to the left + */ void ShiftLeft (int n); + /** + * Shift the values to the right + */ void ShiftRight (int n); + /** + * Modifies each element so that it each element is raised to the exponent + * + * \param exp the exponent + */ void Pow (double exp); + /** + * Modifies each element so that it is + * the base raised to each element value + * + * \param base the base + */ void Exp (double base); + /** + * Applies a Log10 to each the elements + */ void Log10 (); + /** + * Applies a Log2 to each the elements + */ void Log2 (); + /** + * Applies a Log to each the elements + */ void Log (); - Ptr m_spectrumModel; + Ptr m_spectrumModel; //!< The spectrum model -/** - * Set of values which implement the codomain of the functions in - * the Function Space defined by SpectrumValue. There is no restriction - * on what these values represent (a transmission power density, a - * propagation loss, etc.). - * - */ + /** + * Set of values which implement the codomain of the functions in + * the Function Space defined by SpectrumValue. There is no restriction + * on what these values represent (a transmission power density, a + * propagation loss, etc.). + * + */ Values m_values; diff --git a/src/spectrum/model/tv-spectrum-transmitter.cc b/src/spectrum/model/tv-spectrum-transmitter.cc --- a/src/spectrum/model/tv-spectrum-transmitter.cc +++ b/src/spectrum/model/tv-spectrum-transmitter.cc @@ -185,12 +185,17 @@ return m_channel; } -// Used as key for map containing created spectrum models +/// Used as key for map containing created spectrum models struct TvSpectrumModelId { + /** + * Constructor + * \param stFreq Start frequency [Hz] + * \param bwidth Bandwidth [Hz] + */ TvSpectrumModelId (double stFreq, double bwidth); - double startFrequency; - double bandwidth; + double startFrequency; //!< Start frequency [Hz] + double bandwidth; //!< Bandwidth [Hz] }; TvSpectrumModelId::TvSpectrumModelId (double stFreq, double bwidth) @@ -199,6 +204,13 @@ { } +/** + * Minus-than operator + * \param a left operand + * \param b right operand + * \returns true if the left operand has a lower starting frequency + * or a smaller bandwidth (if both have the same starting freq.) + */ bool operator < (const TvSpectrumModelId& a, const TvSpectrumModelId& b) { @@ -206,7 +218,7 @@ ( (a.startFrequency == b.startFrequency) && (a.bandwidth < b.bandwidth) ) ); } -// Stores created spectrum models +/// Stores created spectrum models static std::map > g_tvSpectrumModelMap; /** diff --git a/src/spectrum/model/tv-spectrum-transmitter.h b/src/spectrum/model/tv-spectrum-transmitter.h --- a/src/spectrum/model/tv-spectrum-transmitter.h +++ b/src/spectrum/model/tv-spectrum-transmitter.h @@ -57,8 +57,8 @@ TVTYPE_COFDM }; - TvSpectrumTransmitter (); //!< Default constructor - virtual ~TvSpectrumTransmitter (); //!< Destructor + TvSpectrumTransmitter (); + virtual ~TvSpectrumTransmitter (); /** * Register this type. diff --git a/src/spectrum/model/waveform-generator.h b/src/spectrum/model/waveform-generator.h --- a/src/spectrum/model/waveform-generator.h +++ b/src/spectrum/model/waveform-generator.h @@ -57,6 +57,10 @@ WaveformGenerator (); virtual ~WaveformGenerator (); + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); // inherited from SpectrumPhy @@ -129,21 +133,24 @@ private: virtual void DoDispose (void); - Ptr m_mobility; - Ptr m_antenna; - Ptr m_netDevice; - Ptr m_channel; + Ptr m_mobility; //!< Mobility model + Ptr m_antenna; //!< Antenna model + Ptr m_netDevice; //!< Owning NetDevice + Ptr m_channel; //!< Channel + /** + * Generates a waveform + */ virtual void GenerateWaveform (); - Ptr m_txPowerSpectralDensity; - Time m_period; - double m_dutyCycle; - Time m_startTime; - EventId m_nextWave; + Ptr m_txPowerSpectralDensity; //!< Tx PSD + Time m_period; //!< Period + double m_dutyCycle; //!< Duty Cycle (should be in [0,1]) + Time m_startTime; //!< Start time + EventId m_nextWave; //!< Next waveform generation event - TracedCallback > m_phyTxStartTrace; - TracedCallback > m_phyTxEndTrace; + TracedCallback > m_phyTxStartTrace; //!< TracedCallback: Tx start + TracedCallback > m_phyTxEndTrace; //!< TracedCallback: Tx end }; diff --git a/src/spectrum/model/wifi-spectrum-value-helper.cc b/src/spectrum/model/wifi-spectrum-value-helper.cc --- a/src/spectrum/model/wifi-spectrum-value-helper.cc +++ b/src/spectrum/model/wifi-spectrum-value-helper.cc @@ -23,7 +23,7 @@ namespace ns3 { - +/// The Wi-Fi spectrum model static Ptr g_WifiSpectrumModel5Mhz; WifiSpectrumValueHelper::~WifiSpectrumValueHelper () @@ -34,6 +34,9 @@ { } +/** + * Static class to initialize the values for the Wi-Fi spectrum model + */ static class WifiSpectrumModel5MhzInitializer { public: @@ -50,7 +53,7 @@ } g_WifiSpectrumModel5Mhz = Create (bands); } -} g_WifiSpectrumModel5MhzInitializerInstance; +} g_WifiSpectrumModel5MhzInitializerInstance; //!< initialization instance for WifiSpectrumModel5Mhz diff --git a/src/spectrum/model/wifi-spectrum-value-helper.h b/src/spectrum/model/wifi-spectrum-value-helper.h --- a/src/spectrum/model/wifi-spectrum-value-helper.h +++ b/src/spectrum/model/wifi-spectrum-value-helper.h @@ -31,40 +31,43 @@ /** * \ingroup spectrum * - * this abstract class defines the interface for interacting with all WifiSpectrumValue implementations. + * This abstract class defines the interface for interacting with all WifiSpectrumValue implementations. * */ class WifiSpectrumValueHelper { public: virtual ~WifiSpectrumValueHelper (); - /* + /** + * Creates a SpectrumValue instance which + * has a constant value for all frequencies * - * @param value the constant value + * @param psd the constant value * - * @return a Ptr to a newly created SpectrumValue instance which - * has a constant value for all frequencies + * @return a Ptr to a newly created SpectrumValue */ virtual Ptr CreateConstant (double psd) = 0; - /* + /** + * Creates a SpectrumValue instance which + * represents the TX Power Spectral Density of a wifi device + * corresponding to the provided parameters * * @param txPower the total TX power in W * @param channel the number of the channel * - * @return a Ptr to a newly created SpectrumValue instance which - * represents the TX Power Spectral Density of a wifi device - * corresponding to the provided parameters + * @return a Ptr to a newly created SpectrumValue */ virtual Ptr CreateTxPowerSpectralDensity (double txPower, uint32_t channel) = 0; - /* + /** + * Creates a pectrumValue instance which + * represents the frequency response of the RF filter which is used + * by a wifi device to receive signals when tuned to a particular channel * * @param channel the number of the channel * - * @return a Ptr to a newly created SpectrumValue instance which - * represents the frequency response of the RF filter which is used - * by a wifi device to receive signals when tuned to a particular channel + * @return a Ptr to a newly created SpectrumValue */ virtual Ptr CreateRfFilter (uint32_t channel) = 0; @@ -79,11 +82,11 @@ * 5 MHz spectrum resolution. * */ -class WifiSpectrumValue5MhzFactory +class WifiSpectrumValue5MhzFactory : public WifiSpectrumValueHelper { public: virtual ~WifiSpectrumValue5MhzFactory (); - // inherited from WifiSpectrumValue + // inherited from WifiSpectrumValueHelper virtual Ptr CreateConstant (double psd); virtual Ptr CreateTxPowerSpectralDensity (double txPower, uint32_t channel); virtual Ptr CreateRfFilter (uint32_t channel);