diff --git a/doc/MeshArchitecture.png b/doc/MeshArchitecture.png new file mode 100644 index 000000000..4be05d980 Binary files /dev/null and b/doc/MeshArchitecture.png differ diff --git a/src/devices/mesh/dot11s/dot11s.h b/src/devices/mesh/dot11s/dot11s.h index c939fad57..d3087b666 100644 --- a/src/devices/mesh/dot11s/dot11s.h +++ b/src/devices/mesh/dot11s/dot11s.h @@ -28,34 +28,40 @@ * Current model conforms IEEE 802.11s D3.0 draft version and includes * Peer Management Protocol and HWMP (routing) Protocol implementations. * - * The multi-interface (aka multi radio) mesh points are supported as an + * The multi-interface mesh points are supported as an * extension of IEEE draft version 3.0. Note that corresponding helper * creates single interface station by default. * \section Dot11s Overview of IEEE 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, detect beacons, - * and close peer links due to transmission failures or beacon loss. + * + * The task of peer management protocol is the following: + * -open links detecting beacons and starting peer link finite + * state machine. + * -close peer links due to transmission failures or beacon loss. + * * If peer link between sender and receiver does not exist, the packet will be dropped. - * \subsubsection IE Implementation of Information elements - * To make a model of 802.11 stack, we need to implement large quantity of information - * elements and have an ability to add them in a beacon. - * Also we have to parse beacon and extract 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 ns3::WifiInformationElement::SerializeInformation and - * ns3::WifiInformationElement::DeserializeInformation. - * ns3::WifiInformationElementVector adds all stored information elements to a packet. - * \subsubsection PMP Peer management protocol + * So, the plug-in to peer management protocol is the first in the list of + * ns3::MeshWifiInterfaceMacPlugin + * \subsection IE Implementation of Information elements + * To make a model of 802.11s stack, we need to implement large quantity of information + * elements and have an ability to add them in a beacon. Also we have to parse beacon + * and extract proper information elements from it. So, two classes ns3::WifiInformationElement + * and ns3::WifiInformationElementVector support this functionality. The former keeps all + * internal structure of information element and its elementId. It has methods + * ns3::WifiInformationElement::SerializeInformation and ns3::WifiInformationElement::DeserializeInformation. + * The latter is ns3::WifiInformationElementVector adds all stored information elements to a packet. + * \subsection 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, + * - Protocol itself ns3::dot11s::PeerManagementProtocol, which keeps all active peer links on interfaces, + * handles all changes of their states and notifies a routing protocol about link failures. + * - MAC plug-in ns3::dot11s::PeerManagementProtocolMac which drops packet, if there is no peer link, * and peek all needed information from management frames and information elements 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. + * - Peer link ns3::dot11s::PeerLink which keeps finite state machine of each peer link, keeps + * beacon loss counter and counter of successive transmission failures. * - * Procedure of closing peer link is not described detailed in 802.11s draft standard, so the link may be closed by: + * Procedure of closing peer link is not described detailed in 802.11s draft standard, so in our model + * the link may be closed by: * - beacon loss (see an appropriate attribute of ns3::dot11s::PeerLink class) * - transmission failure -- when a predefined number of successive packets have failed to transmit, * the link will be closed. @@ -63,10 +69,10 @@ * 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 similar: the upper layer of protocol ns3::dot11s::PeerManagementProtocol - * and its plugins ns3::dot11s::PeerManagementProtocolMac. + * but the structure is similar: the upper tier of protocol ns3::dot11s::PeerManagementProtocol + * and its plug-in is ns3::dot11s::PeerManagementProtocolMac. * - * \subsubsection HWMP Hybrid Wireless Mesh Protocol + * \subsection 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 appropriate attributes). * This feature turns off at a station when the number of neighbours of the station is more than a threshold. diff --git a/src/devices/mesh/mesh.h b/src/devices/mesh/mesh.h index b1df00bbe..4ab0f651b 100644 --- a/src/devices/mesh/mesh.h +++ b/src/devices/mesh/mesh.h @@ -15,9 +15,11 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA * - * Author: Pavel Boyko + * Authors: Kirill Andreev + * Aleksander Safonov + * Pavel Boyko * - * This is toplevel mesh module description + * This is top level mesh module description */ /** @@ -26,52 +28,77 @@ * * \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, 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. + * The main goal of this module is to provide a MAC-layer routing functionality. + + * The main part of MAC-layer routing model is a special type of a network device -- + * ns3::MeshPointDevice. Being an interface to upper-layer protocols, it provides routing functionality, + * hidden from upper-layer protocols, by means of ns3::MeshL2RoutingProtocol. * - * 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 mechanism in IEEE802.11). + * Our model supports stations with multiple network devices handled by a single + * MAC-layer routing protocol. So, ns3::MeshPointDevice serves as an umbrella to multiple + * network devices ("interfaces") working under the same MAC-layer routing protocol. + * + * Network devices may be of different types, each with a specific medium access method. + * So ns3::MeshL2RoutingProtocol consists of two parts: the one independent from the network device type, + * which we refer to as a routing protocol, and the other one depended on the network device type. which + * we refer to as a plug-in to the routing protocol. + * + * One can imagine a MAC-layer routing as a two-tiers model. ns3::MeshL2RoutingProtocol and ns3::MeshPointDevice + * belong to the upper tier. The task of ns3::MeshPointDevice is to send, receive, and forward frames, + * while the task of ns3::MeshL2RoutingProtocol is to resolve routes and keep frames waiting for route resolution. + * This functionality is independent from the type of underlying network devices ("interfaces"). + * + * The lower tier implements the part of MAC-layer routing, specific for underlying network devices + * and their medium access control methods. For example, HWMP routing protocol in IEEE802.11s + * uses its own specific management frames. + * + * At present, two routing protocols are implemented in this module: + * - HWMP (default routing protocol for IEEE802.11s standard) + Peer management protocol + * (also described in 802.11s standard draft) which is required by HWMP to manage peer links + * (works like association mechanism in IEEE802.11). * - FLAME (Forwarding LAyer for MEshing). - * While the former protocol works only with 802.11-MAC, the latter protocol works with all network devices, which support + + * While HWMP only works with 802.11-MAC, FLAME works with all types of 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 is inherited from ns3::NetDevice class. Interface between ns3::MeshPointDevice - * and ns3::MeshL2RoutingProtocol is the following: ns3::MeshPointDevice gives a packet with source and destination addresses, - * number of network device, from which it was received and a callback to be executed when the route is found. - * All routing queues are implemented inside a protocol. After the routing discovery procedure is done, protocol returns a - * packet back to ns3::MeshPointDevice and gives an index of network device, which the packet shall be sent to. All additional - * routing information is stored inside a packet using tags. After all this routine is done the 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 ns3::WifiNetDevice -- ns3::MeshWifiInterfaceMac, and ns3::MeshWifiInterfaceMacPlugin. The former is a new kind of WifiMac, which - * implements IEEE802.11s mesh interface or a simple ad hoc depending on whether beaconing is enabled or not. - * Also ns3::MeshWifiInterfaceMac supports beacon shifting (Beacon Collision Avoidance). - * The ns3::MeshWifiInterfaceMacPlugin 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 for - * 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::MeshWifiInterfaceMacPlugin, the LLC header is already attached (by WifiNetDevice) - * \attention Note, when you work with ns3::MeshWifiInterfaceMac, you have an ability to install multiple plugins. + * \subsection Architecture Architecture of MAC-layer routing stack + * As already mentioned, MAC-layer routing consists of two tiers. + * An ns3::MeshPointDevice which forwards frames by using an attached ns3::MeshL2RoutingProtocol forms + * the upper tier. The interface between ns3::MeshPointDevice and the upper-layer protocols is inherited + * from ns3::NetDevice class. The ns3::MeshPointDevice interacts with ns3::MeshL2RoutingProtocol as follows: + * ns3::MeshPointDevice gives to ns3::MeshL2RoutingProtocol a frame with the source and destination addresses, + * the network device index which the frame is received from, and a callback to be executed when the route is found. + * The callback is needed because all routing queues are implemented inside ns3::MeshL2RoutingProtocol. + * When the route is resolved, ns3::MeshL2RoutingProtocol returns the frame back to ns3::MeshPointDevice with the + * network device index which the packet shall be sent to. All additional routing information is stored inside + * the frame by means of tags. In the end, when all these routines are done, the frame goes to the lower tier. + + * The lower tier is responsible for filling MAC-specific headers. At present, we have only implemented the + * lower tier which is specific for ns3::WifiNetDevice. This tier is implemented as two base classes: + * ns3::MeshWifiInterfaceMac and ns3::MeshWifiInterfaceMacPlugin. The former is a new kind of WifiMac. If beacon + * generation is enabled or disabled, it implements IEEE802.11s mesh functionality or a simple ad hoc functionality + * of the MAC-high part of the WiFi model, respectively. The latter is a plug-in to L2Routing protocol. + * It handles all outgoing and incoming frames, fills headers and make decisions to drop a frame or not. Also, it + * adds information elements to a beacon specific to given L2Routing protocol, if needed. + * \image html MeshArchitecture.png "Overview of the Mesh MAC-layer routing system" + * + * \subsection NewProtocol Adding a new protocol + * This module requires all the network devices operates with ns3::Mac48Address addressing scheme. + * + * To add a new L2Routing protocol, one needs to define the following: + * - Write an upper part of the protocol inherited from ns3::MeshL2Routing. + * - If the protocol works only with 802.11 MAC -- write a plug-in inherited from ns3::MeshWifiInterfaceMacPlugin + * - If the protocol works with other types of network devices -- write your own plug-in (interface for + * communication with other types of network devices is not implemented). + * + * When you implement a L2Routing protocol, remember that when you are at L2Routing tier, + * you work with a frame without an LLC header, and when you are at plug-in tier using + * ns3::MeshWifiInterfaceMacPlugin, an LLC header is already attached (by WifiNetDevice) + * + * \attention Note, when you use ns3::MeshWifiInterfaceMac, multiple plug-ins may be installed. + * * \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. Because you can reset statistics, you can adjust a period of report. + * Each L2Routing protocol has a structure to capture statistics, Report and ResetStats methods. + * This gives an opportunity to collect statistic to an *.xml file periodically. */