diff --git a/src/devices/mesh/dot11s/hwmp-protocol-mac.h b/src/devices/mesh/dot11s/hwmp-protocol-mac.h index 0c77f3719..f12d9c77d 100644 --- a/src/devices/mesh/dot11s/hwmp-protocol-mac.h +++ b/src/devices/mesh/dot11s/hwmp-protocol-mac.h @@ -72,6 +72,7 @@ private: /** \brief Request a destination. If can not send preq immediately - * add a destination to exisying PREQ generated by me and stored in * PREQ queue + * \param dest is the destination to be resolved * \param originator_seqno is a sequence number that shall be preq originator sequenece number * \param dst_seqno is a sequence number taken from routing table */ diff --git a/src/devices/mesh/dot11s/hwmp-protocol.h b/src/devices/mesh/dot11s/hwmp-protocol.h index 73367d424..ced82fe38 100644 --- a/src/devices/mesh/dot11s/hwmp-protocol.h +++ b/src/devices/mesh/dot11s/hwmp-protocol.h @@ -66,9 +66,8 @@ public: */ bool Install (Ptr); void PeerLinkStatus (Mac48Address meshPontAddress, Mac48Address peerAddress, uint32_t interface,bool status); - ///\brief This callback is used to obtain active neighbours on a - //given interface - ///\param interface is the interface ID + ///\brief This callback is used to obtain active neighbours on a given interface + ///\param cb is a callback, which returns a list of addresses on given interface (uint32_t) void SetNeighboursCallback (Callback, uint32_t> cb); ///\name Proactive PREQ mechanism: ///\{ @@ -127,13 +126,13 @@ private: //retransmitted std::vector GetBroadcastReceivers (uint32_t interface); /** - * \brief MAC-plugin asks wether the frame can be dropeed. Protocol automatically updates seqno. + * \brief MAC-plugin asks whether the frame can be dropped. Protocol automatically updates seqno. * * \return true if frame can be dropped - * \param uint32_t is the seqno - * \param Mac48Address is the mesh source addrress of the frame + * \param seqno is the sequence number of source + * \param source is the source address */ - bool DropDataFrame (uint32_t, Mac48Address); + bool DropDataFrame (uint32_t seqno, Mac48Address source); //\} private: /// Packet waiting its routing information @@ -168,7 +167,7 @@ private: /** * \brief Generates PREQ retry when retry timeout has expired and route is still unresolved. * - * When PREQ retry has achieved the maximum level - retry mechanish should be cancelled + * When PREQ retry has achieved the maximum level - retry mechanism should be canceled */ void RetryPathDiscovery (Mac48Address dst, uint8_t numOfRetry); ///\} @@ -222,7 +221,7 @@ private: ///\{ std::map m_preqTimeouts; EventId m_proactivePreqTimer; - //Random start in Proactive PREQ propagation + /// Random start in Proactive PREQ propagation Time m_randomStart; ///\} diff --git a/src/devices/mesh/dot11s/peer-link.h b/src/devices/mesh/dot11s/peer-link.h index 125e50d9b..8cc35b83d 100644 --- a/src/devices/mesh/dot11s/peer-link.h +++ b/src/devices/mesh/dot11s/peer-link.h @@ -51,13 +51,14 @@ public: /// Process beacon received from peer void SetBeaconInformation (Time lastBeacon, Time BeaconInterval); /** - * \brief Method used to detecet peer link changes + * \brief Method used to detect peer link changes * - * \param bool if true - opened new link, if false - link closed + * \param cb is a callback, which notifyes, that on interface (uint32_t), peer link + * with address (Mac48Address) was opened (bool is true) or closed (bool is false) */ void SetLinkStatusCallback (Callback cb); /** - * \name Peer link geeters/setters + * \name Peer link getters/setters * \{ */ void SetPeerAddress (Mac48Address macaddr); @@ -203,7 +204,7 @@ private: private: ///The number of interface I am associated with uint32_t m_interface; - /// pointer to mac plugin, which is responsible for peer management + /// pointer to MAC plugin, which is responsible for peer management Ptr m_macPlugin; /// Peer address Mac48Address m_peerAddress; @@ -230,9 +231,7 @@ private: PeerState m_state; /// Mesh interface configuration IeConfiguration m_configuration; - - // State is a bitfield as defined as follows: - // This are states for a given + /// Beacon timing element received from the peer. Needed by BCA IeBeaconTiming m_beaconTiming; /** diff --git a/src/devices/mesh/dot11s/peer-management-protocol.h b/src/devices/mesh/dot11s/peer-management-protocol.h index 182c7e491..b86959b1a 100644 --- a/src/devices/mesh/dot11s/peer-management-protocol.h +++ b/src/devices/mesh/dot11s/peer-management-protocol.h @@ -63,14 +63,13 @@ public: /** * \brief Methods that handle beacon sending/receiving procedure. * - * This methods interact with MAC_layer plug-in + * \name This methods interact with MAC_layer plug-in * \{ */ /** * \brief When we are sending a beacon - we fill beacon timing * element - * \param IeBeaconTiming is a beacon timing element that - * should be present in beacon + * \return IeBeaconTiming is a beacon timing element that should be present in beacon * \param interface is a interface sending a beacon */ Ptr GetBeaconTimingElement (uint32_t interface); @@ -80,7 +79,11 @@ public: * and remember beacon timers - last beacon and beacon interval to * detect beacon loss and cancel links * \param interface is a interface on which beacon was received + * \param meshBeacon indicates whether the beacon is mesh beacon or not. * \param timingElement is a timing element of remote beacon + * \param peerAddress is an address where a beacon was received from + * \param receivingTime is a time when beacon was received + * \param beaconInterval is a beacon interval of received beacon */ void UpdatePeerBeaconTiming ( uint32_t interface, @@ -98,18 +101,15 @@ public: */ /** * Deliver Peer link management information to the protocol-part - * \param void is returning value - we pass a frame and forget - * about it - * \param uint32_t - is a interface ID of a given MAC (interfaceID rather - * than MAC address, beacause many interfaces may have the same MAC) - * \param Mac48Address is address of peer - * \param Mac48Address is address of peer mesh point device (equal + * \param interface is a interface ID of a given MAC (interfaceID rather + * than MAC address, because many interfaces may have the same MAC) + * \param peerAddress is address of peer + * \param peerMeshPointAddress is address of peer mesh point device (equal * to peer address when only one interface) - * \param uint16_t is association ID, which peer has assigned to - * us - * \param IeConfiguration is mesh configuration element - * taken from the peer management frame - * \param IePeerManagement is peer link management element + * \param aid is association ID, which peer has assigned to us + * \param peerManagementElement is peer link management element + * \param meshConfig is mesh configuration element taken from the peer + * management frame */ void ReceivePeerLinkFrame ( uint32_t interface, @@ -120,17 +120,20 @@ public: IeConfiguration meshConfig ); /** - * Cancell peer link due to broken configuration (SSID or Supported + * \brief Cancels peer link due to broken configuration (Mesh ID or Supported * rates) */ void ConfigurationMismatch (uint32_t interface, Mac48Address peerAddress); /** - * Cancel peer link due to successive transmission failures + * \brief Cancels peer link due to successive transmission failures */ void TransmissionFailure (uint32_t interface, const Mac48Address peerAddress); + /** + * \brief resets transmission failure statistics + */ void TransmissionSuccess (uint32_t interface, const Mac48Address peerAddress); /** - * Checks if there is established link + * \brief Checks if there is established link */ bool IsActiveLink (uint32_t interface, Mac48Address peerAddress); //\} @@ -140,7 +143,7 @@ public: std::vector GetActiveLinks (uint32_t interface); ///\brief needed by plugins to set global source address Mac48Address GetAddress (); - ///\Needed to fill mesh configuration + ///\brief Needed to fill mesh configuration uint8_t GetNumberOfLinks (); void SetMeshId (std::string s); Ptr GetMeshId () const; @@ -162,10 +165,8 @@ private: /// keeps all peer links at a given interface. typedef std::vector > PeerLinksOnInterface; /// This map keeps all peer links. - ///\param uint32_t is interface ID typedef std::map PeerLinksMap; - ///\brief This map keeps relationship between peer address and its - /// beacon information + /// This map keeps relationship between peer address and its beacon information typedef std::map BeaconsOnInterface; ///\brief This map keeps beacon information on all intefaces typedef std::map BeaconInfoMap; @@ -174,7 +175,7 @@ private: ///\} private: /** - * Return a position in beacon-storage for a given remote station + * \brief Fills information of received beacon. Needed to form own beacon timing element */ void FillBeaconInfo (uint32_t interface, Mac48Address peerAddress, Time receivingTime, Time beaconInterval); Ptr InitiateLink ( @@ -219,19 +220,20 @@ private: uint8_t m_maxNumberOfPeerLinks; uint8_t m_maxBeaconLostForBeaconTiming; /** - * Peer Links + * \name Peer Links * \{ */ PeerLinksMap m_peerLinks; /** * \} */ - ///\brief Callback to notify about peer link changes: - ///\param Mac48Address is peer address of mesh point - ///\param Mac48Address is peer address of interface - ///\param uint32_t - interface ID - ///\param bool is staus - true when new link has appeared, false - - //when link was closed + /** + * \brief Callback to notify about peer link changes: + * Mac48Address is peer address of mesh point, + * Mac48Address is peer address of interface, + * uint32_t - interface ID, + * bool is status - true when new link has appeared, false - when link was closed, + */ Callback m_peerStatusCallback; ///\} //Keeps statistics diff --git a/src/devices/mesh/mesh-l2-routing-protocol.h b/src/devices/mesh/mesh-l2-routing-protocol.h index fc98c4b46..a265b3349 100644 --- a/src/devices/mesh/mesh-l2-routing-protocol.h +++ b/src/devices/mesh/mesh-l2-routing-protocol.h @@ -102,7 +102,7 @@ public: * MeshPointDevice must call this method when passing a packet to * upper layer. * \returns true if packet shall not be dropeed, false otherwise. - * \param sourceIface the incoming interface of the packet + * \param fromIface the incoming interface of the packet * \param source source address * \param destination destination address * \param packet the packet to be handled diff --git a/src/devices/mesh/mesh-point-device.h b/src/devices/mesh/mesh-point-device.h index f2e78d929..0f560da1d 100644 --- a/src/devices/mesh/mesh-point-device.h +++ b/src/devices/mesh/mesh-point-device.h @@ -133,14 +133,14 @@ private: uint16_t protocol, const Mac48Address src, const Mac48Address dst); /** - * Response callback for L2 routing protocol. This will be executed when routing information is ready. + * \brief Response callback for L2 routing protocol. This will be executed when routing information is ready. * * \param success True is route found. TODO: diagnose routing errors * \param packet Packet to send * \param src Source MAC address * \param dst Destination MAC address * \param protocol Protocol ID - * \param outIface Interface to use (ID) for send (decided by routing protocol). All interfaces will be used if outIface = 0xffffffff + * \param iface Interface to use (ID) for send (decided by routing protocol). All interfaces will be used if outIface = 0xffffffff */ void DoSend (bool success, Ptr packet, Mac48Address src, Mac48Address dst, uint16_t protocol, diff --git a/src/devices/mesh/mesh.h b/src/devices/mesh/mesh.h index 1f0aacb33..673318ee4 100644 --- a/src/devices/mesh/mesh.h +++ b/src/devices/mesh/mesh.h @@ -24,7 +24,84 @@ * \ingroup devices * \defgroup mesh Mesh * - * \brief Layer 2 mobile ad hoc wireless (aka mesh) networking - * - * see http://www.nsnam.org/wiki/index.php/Mesh for module architectural description. + * \brief MAC-layer mobile mesh networking. + * \section MeshOverview Overview of Layer-2 Mesh networking protocols. + * The main goal of this module is to provide an NS-3 model of MAC-layer routing + * protocols, which can be interfaced as plain network device by upper layer protocols. + * Also our model supports stations with multiple network devices handled by a single + * MAC-layer routing protocol, and this devices (called 'interfaces') are hidden from upper-layer protocols. + * + * Current implementation provides 2 layers of MAC-layer routing stack. + * The upper layer is Mesh point device layer - it is an interface to upper-layer protocols and it implements + * routing itself. The main task of this layer is to aggregate multiple network devices working under the same MAC-layer + * routing protocol, to send, receive, and forward packets. + * The lower layer implements interaction with MAC-layer itself, because some routing protocols (like HWMP in IEEE802.11s) + * require their own management frames and some of this management frames may be MAC-specific. So, the main task + * of this layer is to handle MAC-specific management frames needed by routing protocols. + * + * At the moment two routing protocols are implemented in this module: + * - HWMP (default routing protocol for IEEE802.11s standard) + Peer management protocol (also described in 802.11s + * draft standard), which is required by HWMP to manage peer links (works like association in IEEE802.11). + * - FLAME (Forwarding LAyer for MEshing). + * The former protocol works only with 802.11-MAC, the latter protocol works with all network devices, which support + * 48-bit MAC_addressing scheme. + * \subsection Architecture Architecture of MAC-layer routing stack. + * According to said above, MAC-layer routing stack consists of two layers: + * The upper is a ns3::MeshPointDevice, which forwards packets using ns3::MeshL2RoutingProtocol, attached to it. + * Interface between MeshPointDevice and upper layers inherited from ns3::NetDevice class. Interface between MeshPointDevice + * and MeshL2RoutingProtocol is the following: MeshPointDevice gives a packet with source and destination addresses, + * number of network device, from which it was received and callback to be executed when route is found. + * All routing queues are implemented inside a protocol. After the routing discovery procedure is done, protocol returns a + * packet back to mesh point device and gives an index of network device, where packet shall be sent to. All additional + * routing information is stored inside a packet using a tags. After all this routine packet goes to the lower layer. + * The lower layer is responsible for filling MAC-specific headers. At the moment we have implemented only lower layer + * for WifiNetDevice - ns::MeshWifiInterfaceMac, and ns3::MeshWifiInterfaceMacPlugin. The former is a new kind of WifiMac, which + * implements IEEE802.11S mesh interface, when beaconing is turned on, and a simple ad hoc, when the beaconing is turned off. + * Also MeshWfifiInterfaceMac supports beacon shifting, yo avoid collisions in mesh network. + * The latter is a lower part of L2Routing protocol. It handles all outgoing and all incoming frames, fills needed headers and + * decides, whether to drop a frame or not and it can add needed information elements to a beacon. + * See http://www.nsnam.org/wiki/index.php/Mesh for module architectural description. + * \subsection NewProtocol Adding a new protocol. + * This model requires, that all network devices shall operate with ns3::Mac48Address type of addresses. + * To add a new protocol you need to define the following things: + * - Write a upper part of the protocol. + * - If Your protocol works only with 802.11 MAC - write a lower part, inherited from ns3::MeshWifiInterfaceMacPlugin + * - If Your protocol works with other type of Network devices - write your own lower part of protocol (interface of + * communication with other types of network devices is not implemented) if needed. + * + * When you implement a protocol, you must remember, that when you are at MeshPointDevice level, you work with a packet + * without LLC header, and when you are at plugin-level using ns3::MeshWifiInterfaceMacPlugun, the LLC header is already attached (by WifiNetDevice) + * \attention Note, when you work with ns3::MeshWifiInterfaceMac, you have an ability to install multiple number of plugins. + * \subsection Dot11s Overview of 802.11s + * Implementation of 802.11s draft standard consists of two main parts: Peer management protocol and HWMP - Hybrid Wireless Mesh Protocol. + * The task of peer management protocol is to open links, detecting beacons, and close peer links due to transmission failures or beacon loss. + * If peer link between sender and receiver does not exist, the packet shall be dropped. + * \subsubsection IE Implementation of Information elements + * To make a model of 802.11 stack, we need to implement a big quantity of information elements and have an ability to add them in a beacon. + * Also we have to parse beacon and extract a proper information elements from it. So, two classes ns3::WifiInformationElement and ns3::WifiInformationElementVector + * implement this functionality. The former keeps all information of information element and its elementId and has methods SerializeInformation and Deserialize information + * ns3::WifiInformationElementVector works as a header and adds all stored information elements to a packet. + * \subsubsection PMP Peer management protocol + * Peer management protocol consists of three main parts: + * - Protocol itself ns3::dot11s::PeerManagementProtocol, which keeps all active peer links and handles all changes of their states + * and notifies a routing protocol about link failures. + * - its MAC plugin ns3::dot11s::PeerManagementProtocolMac which drops packet, if there is no peer link, + * and peek all needed information from management frames and information lements from beacons. + * - peer link instance ns3::dot11s::PeerLink which keeps finite state machine for each peer link, keeps beacon loss counter and counter of failed packets + * to be transmitted. + * + * Procedure of closing peer link is not described detailed in 802.11s draft standard, so the link may be closed by: + * - Beacon loss (see a proper attribute of ns3::dot11s::PeerLink class) + * - by transmission failure - when a proper number of successive packets have failed to transmit, the link shall be closed. + * Also Peer management protocol is responsible for beacon collision avoidance, because it keeps beacon timing elements from all neighbours. + * Note, that PeerManagementProtocol is not attached to MeshPointDevice as a routing protocol, but the structure is the similar: the upper layer of protocol, and its plugins. + * + * \subsubsection HWMP Hybrid Wireless Mesh Protocol + * HWMP is implemented in both modes - reactive and proactive. Also we have implemented an ability to transmit broadcast data and management frames as unicasts (see proper attributes). + * This feature turns on when you need to transmit a broadcast and the number of neighbours of the transmitting station is is more than threshold. + * \subsection overview of FLAME + * + * \subsection Statistics + * Each routing protocol has a statistic structure, Report and ResetStats methods. This gives an opportunity to write statistic to an *.xml file periodically. As soon as you can reset statistics, + * the period of report you can ajust as you need. */ diff --git a/src/devices/mesh/wifi-information-element-vector.h b/src/devices/mesh/wifi-information-element-vector.h index 0ca447b92..f7825946e 100644 --- a/src/devices/mesh/wifi-information-element-vector.h +++ b/src/devices/mesh/wifi-information-element-vector.h @@ -120,6 +120,12 @@ public: TypeId GetInstanceTypeId () const; virtual uint32_t GetSerializedSize () const; virtual void Serialize (Buffer::Iterator start) const; + /** + * \attention When you use RemoveHeader, WifiInformationElementVector supposes, that + * all buffer consists of information elements + * @param start + * @return + */ virtual uint32_t Deserialize (Buffer::Iterator start); virtual void Print (std::ostream &os) const; //\} @@ -129,6 +135,7 @@ public: * \return deserialized bytes */ virtual uint32_t DeserializeSingleIe (Buffer::Iterator start); + ///Set maximum size to control overflow of the max packet length void SetMaxSize (uint16_t size); typedef std::vector >::iterator Iterator; Iterator Begin (); diff --git a/src/helper/mesh-helper.h b/src/helper/mesh-helper.h index 1c69793cf..0a1d0e79a 100644 --- a/src/helper/mesh-helper.h +++ b/src/helper/mesh-helper.h @@ -42,9 +42,22 @@ public: static MeshHelper Default (); /** - * \param type the type of ns3::WifiMac to create. - * \param n%d the name of the attribute to set - * \param v%d the value of the attribute to set + * \param n0 the name of the attribute to set + * \param v0 the value of the attribute to set + * \param n1 the name of the attribute to set + * \param v1 the value of the attribute to set + * \param n2 the name of the attribute to set + * \param v2 the value of the attribute to set + * \param n3 the name of the attribute to set + * \param v3 the value of the attribute to set + * \param n4 the name of the attribute to set + * \param v4 the value of the attribute to set + * \param n5 the name of the attribute to set + * \param v5 the value of the attribute to set + * \param n6 the name of the attribute to set + * \param v6 the value of the attribute to set + * \param n7 the name of the attribute to set + * \param v7 the value of the attribute to set * * All the attributes specified in this method should exist * in the requested mac. @@ -59,8 +72,22 @@ public: std::string n7 = "", const AttributeValue &v7 = EmptyAttributeValue ()); /** * \param type the type of ns3::WifiRemoteStationManager to create. - * \param n%d the name of the attribute to set - * \param v%d the value of the attribute to set + * \param n0 the name of the attribute to set + * \param v0 the value of the attribute to set + * \param n1 the name of the attribute to set + * \param v1 the value of the attribute to set + * \param n2 the name of the attribute to set + * \param v2 the value of the attribute to set + * \param n3 the name of the attribute to set + * \param v3 the value of the attribute to set + * \param n4 the name of the attribute to set + * \param v4 the value of the attribute to set + * \param n5 the name of the attribute to set + * \param v5 the value of the attribute to set + * \param n6 the name of the attribute to set + * \param v6 the value of the attribute to set + * \param n7 the name of the attribute to set + * \param v7 the value of the attribute to set * * All the attributes specified in this method should exist * in the requested station manager. @@ -101,10 +128,8 @@ public: /** * \brief Install 802.11s mesh device & protocols on given node list * - * \param phy Wifi PHY helper - * \param nodes List of nodes to install - * \param roots List of root mesh points - * \param nInterfaces Number of mesh point radio interfaces (= WiFi NICs) + * \param phyHelper Wifi PHY helper + * \param c List of nodes to install * * \return list of created mesh point devices, see MeshPointDevice */ @@ -112,9 +137,22 @@ public: Install (const WifiPhyHelper &phyHelper, NodeContainer c) const; /** * \param type the type of ns3::MeshStack. - * - * All the attributes specified in this method should exist - * in the requested station manager. + * \param n0 the name of the attribute to set + * \param v0 the value of the attribute to set + * \param n1 the name of the attribute to set + * \param v1 the value of the attribute to set + * \param n2 the name of the attribute to set + * \param v2 the value of the attribute to set + * \param n3 the name of the attribute to set + * \param v3 the value of the attribute to set + * \param n4 the name of the attribute to set + * \param v4 the value of the attribute to set + * \param n5 the name of the attribute to set + * \param v5 the value of the attribute to set + * \param n6 the name of the attribute to set + * \param v6 the value of the attribute to set + * \param n7 the name of the attribute to set + * \param v7 the value of the attribute to set */ void SetStackInstaller (std::string type, std::string n0 = "", const AttributeValue &v0 = EmptyAttributeValue (),