From fa8f4bf5283fbb1a5afb23b881c3b09c36ae55f3 Mon Sep 17 00:00:00 2001 From: Mathieu Lacage Date: Fri, 21 Mar 2008 12:33:35 -0700 Subject: [PATCH] improve doxygen --- src/devices/wifi/adhoc-wifi-mac.h | 2 + src/devices/wifi/nqap-wifi-mac.h | 7 ++ src/devices/wifi/nqsta-wifi-mac.h | 1 + src/devices/wifi/wifi-mac.cc | 19 +++++ src/devices/wifi/wifi-mac.h | 128 +++++++++++++++++++++++++++++- src/devices/wifi/wifi-phy.h | 40 +++++++--- 6 files changed, 185 insertions(+), 12 deletions(-) diff --git a/src/devices/wifi/adhoc-wifi-mac.h b/src/devices/wifi/adhoc-wifi-mac.h index f49e30497..c9324ef15 100644 --- a/src/devices/wifi/adhoc-wifi-mac.h +++ b/src/devices/wifi/adhoc-wifi-mac.h @@ -52,6 +52,7 @@ public: AdhocWifiMac (); ~AdhocWifiMac (); + // all inherited from WifiMac base class. virtual void SetSlot (Time slotTime); virtual void SetSifs (Time sifs); virtual void SetEifsNoDifs (Time eifsNoDifs); @@ -69,6 +70,7 @@ public: private: + // inherited from Object base class. virtual void DoDispose (void); /* invoked by the MacLows. */ void ForwardUp (Ptr packet, WifiMacHeader const*hdr); diff --git a/src/devices/wifi/nqap-wifi-mac.h b/src/devices/wifi/nqap-wifi-mac.h index 63d3a7bac..212d555fa 100644 --- a/src/devices/wifi/nqap-wifi-mac.h +++ b/src/devices/wifi/nqap-wifi-mac.h @@ -58,6 +58,7 @@ public: NqapWifiMac (); ~NqapWifiMac (); + // inherited from WifiMac. virtual void SetSlot (Time slotTime); virtual void SetSifs (Time sifs); virtual void SetEifsNoDifs (Time eifsNoDifs); @@ -74,7 +75,13 @@ public: virtual void SetSsid (Ssid ssid); + /** + * \param interval the interval between two beacon transmissions. + */ void SetBeaconInterval (Time interval); + /** + * \returns the interval between two beacon transmissions. + */ Time GetBeaconInterval (void) const; /** * Start beacon transmission immediately. diff --git a/src/devices/wifi/nqsta-wifi-mac.h b/src/devices/wifi/nqsta-wifi-mac.h index f3ec6af67..ea1a29378 100644 --- a/src/devices/wifi/nqsta-wifi-mac.h +++ b/src/devices/wifi/nqsta-wifi-mac.h @@ -58,6 +58,7 @@ public: NqstaWifiMac (); ~NqstaWifiMac (); + // inherited from WifiMac. virtual void SetSlot (Time slotTime); virtual void SetSifs (Time sifs); virtual void SetEifsNoDifs (Time eifsNoDifs); diff --git a/src/devices/wifi/wifi-mac.cc b/src/devices/wifi/wifi-mac.cc index a8bb73ae1..54d9df970 100644 --- a/src/devices/wifi/wifi-mac.cc +++ b/src/devices/wifi/wifi-mac.cc @@ -1,3 +1,22 @@ +/* -*- Mode: C++; c-file-style: "gnu"; indent-tabs-mode:nil; -*- */ +/* + * Copyright (c) 2008 INRIA + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License version 2 as + * published by the Free Software Foundation; + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + * + * Author: Mathieu Lacage + */ #include "wifi-mac.h" #include "ns3/uinteger.h" diff --git a/src/devices/wifi/wifi-mac.h b/src/devices/wifi/wifi-mac.h index fd2560d2f..a40f48119 100644 --- a/src/devices/wifi/wifi-mac.h +++ b/src/devices/wifi/wifi-mac.h @@ -1,3 +1,22 @@ +/* -*- Mode: C++; c-file-style: "gnu"; indent-tabs-mode:nil; -*- */ +/* + * Copyright (c) 2008 INRIA + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License version 2 as + * published by the Free Software Foundation; + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + * + * Author: Mathieu Lacage + */ #ifndef WIFI_MAC_H #define WIFI_MAC_H @@ -10,43 +29,149 @@ namespace ns3 { +/** + * \brief base class for all MAC-level wifi objects. + * + * This class encapsulates all the low-level MAC functionality + * DCA, EDCA, etc) and all the high-level MAC functionality + * (association/disassociation state machines). + * + */ class WifiMac : public Object { public: static TypeId GetTypeId (void); + /** + * \param slotTime the slot duration + */ virtual void SetSlot (Time slotTime); + /** + * \param sifs the sifs duration + */ virtual void SetSifs (Time sifs); + /** + * \param eifsNoDifs the duration of an EIFS minus DIFS. + * + * This value is used to calculate the EIFS depending + * on AIFSN. + */ virtual void SetEifsNoDifs (Time eifsNoDifs); + /** + * \param pifs the pifs duration. + */ void SetPifs (Time pifs); + /** + * \param ctsTimeout the duration of a CTS timeout. + */ void SetCtsTimeout (Time ctsTimeout); + /** + * \param ackTimeout the duration of an ACK timeout. + */ void SetAckTimeout (Time ackTimeout); + /** + * \param msduLifetime + * + * XXX: I cannot remmeber what this is used for. + */ void SetMsduLifetime (Time msduLifetime); + /** + * XXX: I cannot remember what this is used for. + */ void SetMaxPropagationDelay (Time delay); + /** + * \returns the current PIFS duration. + */ Time GetPifs (void) const; + /** + * \returns the current SIFS duration. + */ Time GetSifs (void) const; + /** + * \returns the current slot duration. + */ Time GetSlot (void) const; + /** + * \returns the current EIFS minus DIFS duration + */ Time GetEifsNoDifs (void) const; + /** + * \returns the current CTS timeout duration. + */ Time GetCtsTimeout (void) const; + /** + * \returns the current ACK timeout duration. + */ Time GetAckTimeout (void) const; + /** + * XXX: I cannot remember what this is used for. + */ Time GetMsduLifetime (void) const; + /** + * XXX: I cannot remember what this is used for. + */ Time GetMaxPropagationDelay (void) const; + /** + * \returns the maximum size of a MAC-level data payload. + */ uint32_t GetMaxMsduSize (void) const; + /** + * \returns the MAC address associated to this MAC layer. + */ virtual Mac48Address GetAddress (void) const = 0; + /** + * \returns the ssid which this MAC layer is going to try to stay in. + */ virtual Ssid GetSsid (void) const = 0; + /** + * \returns the BSSID associated to the current SSID. + * + * If we are an AP, this is the address of the AP itself. + * If are a STA, this is the address of the AP with which + * the STA is associated. + */ virtual Mac48Address GetBssid (void) const = 0; + /** + * \param address the current address of this MAC layer. + */ virtual void SetAddress (Mac48Address address) = 0; + /** + * \param ssid the current ssid of this MAC layer. + */ virtual void SetSsid (Ssid ssid) = 0; private: friend class WifiNetDevice; + /** + * \param packet the packet to send. + * \param to the address to which the packet should be sent. + * + * The packet should be enqueued in a tx queue, and should be + * dequeued as soon as the DCF function determines that + * access it granted to this MAC. + */ virtual void Enqueue (Ptr packet, Mac48Address to) = 0; + /** + * \param phy the physical layer attached to this MAC. + */ virtual void SetWifiPhy (Ptr phy) = 0; + /** + * \param stationManager the station manager attached to this MAC. + */ virtual void SetWifiRemoteStationManager (Ptr stationManager) = 0; + /** + * \param upCallback the callback to invoke when a packet must be forwarded up the stack. + */ virtual void SetForwardUpCallback (Callback, const Mac48Address &> upCallback) = 0; + /** + * \param linkUp the callback to invoke when the link becomes up. + */ virtual void SetLinkUpCallback (Callback linkUp) = 0; + /** + * \param linkDown the callback to invoke when the link becomes down. + */ virtual void SetLinkDownCallback (Callback linkDown) = 0; @@ -57,10 +182,7 @@ private: static Time GetDefaultCtsAckDelay (void); static Time GetDefaultCtsAckTimeout (void); - Time m_slot; Time m_pifs; - Time m_sifs; - Time m_eifsNoDifs; Time m_ctsTimeout; Time m_ackTimeout; Time m_maxPropagationDelay; diff --git a/src/devices/wifi/wifi-phy.h b/src/devices/wifi/wifi-phy.h index 68dabdfd2..d804f65a7 100644 --- a/src/devices/wifi/wifi-phy.h +++ b/src/devices/wifi/wifi-phy.h @@ -45,26 +45,47 @@ class TraceContainer; class WifiNetDevice; class WifiChannel; +/** + * \brief receive notifications about phy events. + */ class WifiPhyListener { public: virtual ~WifiPhyListener (); - /* we have received the first bit of a packet. We decided + /** + * \param duration the expected duration of the packet reception. + * + * we have received the first bit of a packet. We decided * that we could synchronize on this packet. It does not mean * we will be able to successfully receive completely the * whole packet. It means we will report a BUSY status. - * r.end will be invoked later to report whether or not - * the packet was successfully received. + * NotifyRxEndOk or NotifyRxEndError will be invoked later + * to report whether or not the packet was successfully received. */ virtual void NotifyRxStart (Time duration) = 0; - /* we have received the last bit of a packet for which - * rxStart was invoked first. + /** + * we have received the last bit of a packet for which + * NotifyRxStart was invoked first and, the packet has + * been successfully received. + */ + virtual void NotifyRxEndOk (void) = 0; + /** + * we have received the last bit of a packet for which + * NotifyRxStart was invoked first and, the packet has + * _not_ been successfully received. */ - virtual void NotifyRxEndOk (void) = 0; virtual void NotifyRxEndError (void) = 0; - /* we start the transmission of a packet. + /** + * \param duration the expected transmission duration. + * + * We are about to send the first bit of the packet. */ virtual void NotifyTxStart (Time duration) = 0; + /** + * \param duration the expected busy duration. + * + * We are going to be cca-busy for a while. + */ virtual void NotifyCcaBusyStart (Time duration) = 0; }; @@ -77,10 +98,11 @@ public: * in "Yet Another Network Simulator", * (http://cutebugs.net/files/wns2-yans.pdf). * + * * This PHY model depends on a channel loss and delay * model as provided by the ns3::PropagationLossModel - * and ns3::PropagationDelayModel classes. - * + * and ns3::PropagationDelayModel classes, both of which are + * members of the ns3::WifiChannel class. */ class WifiPhy : public Object {