From 55bf5fc2e7c22c1ec50bd29e88e488c30a9660e4 Mon Sep 17 00:00:00 2001
From: Ramon Bauza <unknown>
Date: Tue, 15 Sep 2009 14:33:04 +0200
Subject: [PATCH] Doxy doc for Wifi channel switching

---
 src/devices/wifi/dca-txop.h          | 3 +++
 src/devices/wifi/dcf-manager.h       | 2 ++
 src/devices/wifi/edca-txop-n.h       | 3 +++
 src/devices/wifi/mac-low.h           | 3 ++-
 src/devices/wifi/yans-wifi-channel.h | 4 +++-
 src/devices/wifi/yans-wifi-phy.h     | 7 +++++++
 6 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/src/devices/wifi/dca-txop.h b/src/devices/wifi/dca-txop.h
index 5406ac2fc..69b8a050f 100644
--- a/src/devices/wifi/dca-txop.h
+++ b/src/devices/wifi/dca-txop.h
@@ -127,6 +127,9 @@ private:
   void NotifyAccessGranted (void);
   void NotifyInternalCollision (void);
   void NotifyCollision (void);
+  /**
+  * When a channel switching occurs, enqueued packets are removed.
+  */
   void NotifyChannelSwitching (void); 
   /* event handlers */
   void GotCts (double snr, WifiMode txMode);
diff --git a/src/devices/wifi/dcf-manager.h b/src/devices/wifi/dcf-manager.h
index e19bfcbcc..dcd2393f9 100644
--- a/src/devices/wifi/dcf-manager.h
+++ b/src/devices/wifi/dcf-manager.h
@@ -260,6 +260,8 @@ public:
    * \param duration expected duration of channel switching period
    *
    * Notify the DCF that a channel switching period has just started.
+   * During swtiching state, new packets can be enqueued in DcaTxop/EdcaTxop
+   * but they won't access to the medium until the end of the channel switching.
    */
   void NotifySwitchingStartNow (Time duration); 
   /**
diff --git a/src/devices/wifi/edca-txop-n.h b/src/devices/wifi/edca-txop-n.h
index 37f43e52e..eb80a4fc9 100644
--- a/src/devices/wifi/edca-txop-n.h
+++ b/src/devices/wifi/edca-txop-n.h
@@ -101,6 +101,9 @@ public:
   void NotifyAccessGranted (void);
   void NotifyInternalCollision (void);
   void NotifyCollision (void);
+  /**
+  * When a channel switching occurs, enqueued packets are removed.
+  */
   void NotifyChannelSwitching (void);
 
   /*event handlers*/
diff --git a/src/devices/wifi/mac-low.h b/src/devices/wifi/mac-low.h
index 2a1ee4002..7b090fbd9 100644
--- a/src/devices/wifi/mac-low.h
+++ b/src/devices/wifi/mac-low.h
@@ -360,7 +360,8 @@ public:
    * \param duration switching delay duration.
    *
    * This method is typically invoked by the PhyMacLowListener to notify
-   * the MAC layer that a channel switching occured.
+   * the MAC layer that a channel switching occured. When a channel switching
+   * occurs, pending MAC transmissions (RTS, CTS, DATA and ACK) are cancelled.
    */
   void NotifySwitchingStartNow (Time duration); 
 private:
diff --git a/src/devices/wifi/yans-wifi-channel.h b/src/devices/wifi/yans-wifi-channel.h
index 6bd05c4e0..ab6a4d526 100644
--- a/src/devices/wifi/yans-wifi-channel.h
+++ b/src/devices/wifi/yans-wifi-channel.h
@@ -76,7 +76,9 @@ public:
    * \param preamble the preamble associated to the packet
    *
    * This method should not be invoked by normal users. It is 
-   * currently invoked only from WifiPhy::Send.
+   * currently invoked only from WifiPhy::Send. YansWifiChannel 
+   * delivers packets only between PHYs with the same m_channelNumber,
+   * e.g. PHYs that are operating on the same channel.
    */
   void Send (Ptr<YansWifiPhy> sender, Ptr<const Packet> packet, double txPowerDbm,
              WifiMode wifiMode, WifiPreamble preamble) const;
diff --git a/src/devices/wifi/yans-wifi-phy.h b/src/devices/wifi/yans-wifi-phy.h
index c39be9f25..948d97bfb 100644
--- a/src/devices/wifi/yans-wifi-phy.h
+++ b/src/devices/wifi/yans-wifi-phy.h
@@ -77,6 +77,13 @@ public:
    *
    * where Starting channel frequency is standard-dependent, see SetStandard()
    * as defined in IEEE 802.11-2007 17.3.8.3.2.
+   *
+   * YansWifiPhy can switch among different channels. Basically, YansWifiPhy 
+   * has a private attribute m_channelNumber that identifies the channel the 
+   * PHY operates on. Channel switching cannot interrupt an ongoing transmission.
+   * When PHY is in TX state, the channel switching is postponed until the end
+   * of the current transmission. When the PHY is in SYNC state, the channel 
+   * switching causes the drop of the sync packet. 
    */ 
   void SetChannelNumber (uint16_t id);
   /// Return current channel number, see SetChannelNumber()