--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/csma/doc/csma.h Sat Mar 05 01:00:13 2011 +0000
@@ -0,0 +1,331 @@
+/**
+ * \ingroup devices
+ * \defgroup CsmaModel CSMA Model
+ *
+ * \section CsmaModelOverview CSMA Model Overview
+ *
+ * The ns-3 CSMA device models a simple bus network in the spirit of Ethernet.
+ * Although it does not model any real physical network you could ever build
+ * or buy, it does provide some very useful functionality.
+ *
+ * Typically when one thinks of a bus network Ethernet or IEEE 802.3 comes to
+ * mind. Ethernet uses CSMA/CD (Carrier Sense Multiple Access with Collision
+ * Detection with exponentially increasing backoff to contend for the shared
+ * transmission medium. The ns-3 CSMA device models only a portion of this
+ * process, using the nature of the globally available channel to provide
+ * instantaneous (faster than light) carrier sense and priority-based
+ * collision "avoidance." Collisions in the sense of Ethernet never happen and
+ * so the ns-3 CSMA device does not model collision detection, nor will any
+ * transmission in progress be "jammed."
+ *
+ * \section CsmaLayerModel CSMA Layer Model
+ *
+ * There are a number of conventions in use for describing layered
+ * communications architectures in the literature and in textbooks. The most
+ * common layering model is the ISO seven layer reference model. In this view
+ * the ns3::CsmaNetDevice and ns3::CsmaChannel pair occupies the lowest two
+ * layers -- at the physical (layer one), and data link (layer two) positions.
+ * Another important reference model is that specified by RFC 1122,
+ * "Requirements for Internet Hosts -- Communication Layers." In this view the
+ * CsmaNetDevice and CsmaChannel pair occupies the lowest layer --
+ * the link layer. There is also a seemingly endless litany of alternative
+ * descriptions found in textbooks and in the literature. We adopt the naming
+ * conventions used in the IEEE 802 standards which speak of LLC, MAC, MII
+ * and PHY layering. These acronyms are defined as:
+ *
+ * - LLC: Logical Link Control;
+ * - MAC: Media Access Control;
+ * - MII: Media Independent Interface;
+ * - PHY: Physical Layer.
+ *
+ * In this case the LLC and MAC are sublayers of the OSI data link layer and the
+ * MII and PHY are sublayers of the OSI physical layer.
+ *
+ * The "top" of the CSMA device defines the transition from the network layer
+ * to the data link layer. This transition is performed by higher layers by
+ * calling either ns3::CsmaNetDevice::Send or ns3::CsmaNetDevice::SendFrom.
+ *
+ * In contrast to the IEEE 802.3 standards, there is no precisely specified
+ * PHY in the CSMA model in the sense of wire types, signals or pinouts. The
+ * "bottom" interface of the CsmaNetDevice can be thought of as as a kind
+ * of Media Independent Interface (MII) as seen in the "Fast Ethernet"
+ * (IEEE 802.3u) specifications. This MII interface fits into a corresponding
+ * media independent interface on the CsmaChannel. You will not find the
+ * equivalent of a 10BASE-T or a 1000BASE-LX PHY.
+ *
+ * The CsmaNetDevice calls the CsmaChannel through a media independent
+ * interface. There is a method defined to tell the channel when to start
+ * "wiggling the wires" using the method ns3::CsmaChannel::TransmitStart, and
+ * a method to tell the channel when the transmission process is done and
+ * the channel should begin propagating the last bit across the "wire":
+ * ns3::CsmaChannel::TransmitEnd.
+ *
+ * When the TransmitEnd method is executed, the channel will model a single
+ * uniform signal propagation delay in the medium and deliver copes of the packet
+ * to each of the devices attached to the packet via the
+ * ns3::CsmaNetDevice::Receive method.
+ *
+ * There is a "pin" in the device media independent interface corresponding to
+ * "COL" (collision). The state of the channel may be sensed by calling
+ * ns3::CsmaChannel::GetState. Each device will look at this "pin" before
+ * starting a send and will perform appropriate backoff operations if required.
+ *
+ * Properly received packets are forwarded up to higher levels from the
+ * CsmaNetDevice via a callback mechanism. The callback function is
+ * initialized by the higher layer (when the net device is attached) using
+ * ns3::CsmaNetDevice::SetReceiveCallback and is invoked upon "proper"
+ * reception of a packet by the net device in order to forward the packet up
+ * the protocol stack.
+ *
+ * \section CsmaChannelModel CSMA Channel Model
+ *
+ * The class CsmaChannel models the actual transmission medium.
+ * There is no fixed limit for the number of devices connected to the channel.
+ * The CsmaChannel models a data rate and a speed-of-light delay which can
+ * be accessed via the attributes "DataRate" and "Delay" respectively.
+ * The data rate provided to the channel is used to set the data rates
+ * used by the transmitter sections of the CSMA devices connected to the
+ * channel. There is no way to independently set data rates in the
+ * devices. Since the data rate is only used to calculate a delay time, there
+ * is no limitation (other than by the data type holding the value) on the
+ * speed at which CSMA channels and devices can operate; and no restriction
+ * based on any kind of PHY characteristics.
+ *
+ * The CsmaChannel has three states, IDLE, TRANSMITTING and PROPAGATING.
+ * These three states are "seen" instantaneously by all devices on the channel.
+ * By this we mean that if one device begins or ends a simulated transmission,
+ * all devices on the channel are immediately aware of the change in state.
+ * There is no time during which one device may see an IDLE channel while
+ * another device physically further away in the collision domain may have
+ * begun transmitting with the associated signals not propagated. Thus there
+ * is no need for collision detection in the CsmaChannel model and it is
+ * not implemented in any way.
+ *
+ * We do, as the name indicates, have a Carrier Sense aspect to the model.
+ * Since the simulator is single threaded, access to the common channel will
+ * be serialized by the simulator. This provides a deterministic mechanism
+ * for contending for the channel. The channel is allocated (transitioned from
+ * state IDLE to state TRANSMITTING) on a first-come first-served basis. The
+ * channel always goes through a three state process:
+ *
+ * IDLE -> TRANSMITTING -> PROPAGATING -> IDLE
+ *
+ * The TRANSMITTING state models the time during which the source net device
+ * is actually wiggling the signals on the wire. The PROPAGATING state models
+ * the time after the last bit was sent, when the signal is propagating down
+ * the wire to the "far end."
+ *
+ * The transition to the TRANSMITTING state is driven by a call to
+ * ns3::CsmaChannel::TransmitStart which is called by the net device that
+ * transmits the packet. It is the responsibility of that device to end the
+ * transmission with a call to ns3::CsmaChannel::TransmitEnd at the appropriate
+ * simulation time that reflects the time elapsed to put all of the packet bits
+ * on the wire. When TransmitEnd is called, the channel schedules an event
+ * corresponding to a single speed-of-light delay. This delay applies to all
+ * net devices on the channel identically. You can think of a symmetrical hub
+ * in which the packet bits propagate to a central location and then back out
+ * equal length cables to the other devices on the channel.
+ *
+ * The CsmaChannel models a broadcast medium so the packet is delivered
+ * to all of the devices on the channel (including the source) at the end of
+ * the propagation time. It is the responsibility of the sending device to
+ * determine whether or not it receives a packet broadcast over the channel.
+ *
+ * The CsmaChannel provides following Attributes:
+ *
+ * - DataRate: The bitrate for packet transmission on connected devices;
+ * - Delay: The speed of light transmission delay for the channel.
+ *
+ * \section CsmaNetDeviceModel CSMA Net Device Model
+ *
+ * The CSMA network device appears somewhat like an Ethernet device, but it
+ * is important to understand that it does not model an Ethernet device. As
+ * mentioned above, it does not model collisions. The CSMA model also provides
+ * users with the ability to configure the device into other states that are
+ * not compatible with strictly Ethernet or IEEE 802.3 devices.
+ *
+ * The CsmaNetDevice provides following Attributes:
+ *
+ * - Address: The Mac48Address of the device;
+ * - SendEnable: Enable packet transmission if true;
+ * - ReceiveEnable: Enable packet reception if true;
+ * - EncapsulationMode: Type of link layer encapsulation to use;
+ * - RxErrorModel: The receive error model;
+ * - TxQueue: The transmit queue used by the device;
+ * - InterframeGap: The optional time to wait between "frames";
+ * - Rx: A trace source for received packets;
+ * - Drop: A trace source for dropped packets.
+ *
+ * We recommend thinking carefully about changing these Attributes, since
+ * it can result in behavior that surprises users. We allow this because
+ * we believe flexibility is important. As an example of a possibly
+ * surprising effect of changing Attributes, consider the following:
+ *
+ * The Mtu Attribute indicates the Maximum Transmission Unit to the device.
+ * This is the size of the largest Protocol Data Unit (PDU) that the
+ * device can send. This Attribute defaults to 1500 bytes and corresponds
+ * to a number found in RFC 894, "A Standard for the Transmission of IP
+ * Datagrams over Ethernet Networks." The number is actually derived
+ * from the maximum packet size for 10Base5 (full-spec Ethernet) networks --
+ * 1518 bytes. If you subtract DIX encapsulation overhead for Ethernet
+ * packets (18 bytes) you will end up with a maximum possible data size (MTU)
+ * of 1500 bytes. One can also find that the MTU for IEEE 802.3 networks
+ * is 1492 bytes. This is because LLC/SNAP encapsulation adds an extra eight
+ * bytes of overhead to the packet. In both cases, the underlying network
+ * hardware is limited to 1518 bytes, but the MTU is different because the
+ * encapsulation is different.
+ *
+ * If one leaves the Mtu Attribute at 1500 bytes and changes the encapsulation
+ * mode Attribute to Llc, the result will be a network that encapsulates 1500
+ * byte PDUs with LLC/SNAP framing resulting in packets of 1526 bytes. This
+ * would be illegal in many networks, but we allow you do do this. This
+ * results in a simulation that quite subtly does not reflect what you might
+ * be expecting since a real device would balk at sending a 1526 byte packet.
+ *
+ * There also exist jumbo frames (1500 < MTU <= 9000 bytes) and super-jumbo
+ * (MTU > 9000 bytes) frames that are not officially sanctioned by IEEE but
+ * are available in some high-speed (Gigabit) networks and NICs. In the
+ * CSMA model, one could leave the encapsulation mode set to Dix, and set the
+ * Mtu to 64000 bytes -- even though an associated CsmaChannel DataRate was
+ * left at 10 megabits per second (certainly not Gigabit Ethernet). This
+ * would essentially model an Ethernet switch made out of vampire-tapped
+ * 1980s-style 10Base5 networks that support super-jumbo datagrams, which is
+ * certainly not something that was ever made, nor is likely to ever be made;
+ * however it is quite easy for you to configure.
+ *
+ * Be careful about assumptions regarding what CSMA is actually modelling and
+ * how configuration (Attributes) may allow you to swerve considerably away
+ * from reality.
+ *
+ * The CsmaNetDevice supports the assignment of a "receive error model."
+ * This is an ErrorModel object that is used to simulate data corruption
+ * on the link.
+ *
+ * Packets sent over the CsmaNetDevice are always routed through the
+ * transmit queue to provide a trace hook for packets sent out over the
+ * network. This transmit queue can be set (via attribute) to model different
+ * queueing strategies.
+ *
+ * Also configurable by attribute is the encapsulation method used by the
+ * device. By default, or by setting the "EncapsulationMode" attribute to
+ * "Dix", the encapsulation is according to the DEC, Intel, Xerox standard.
+ * This is sometimes called EthernetII framing and is the familiar destination
+ * MAC, source MAC, EtherType, Data, CRC format.
+ *
+ * If the "EncapsulationMode" attribute is set to "Llc", the encapsulation is by
+ * LLC SNAP. In this case, a SNAP header is added that contains the EtherType
+ * (IP or ARP).
+ *
+ * The other implemented encapsulation modes are IP_ARP (set "EncapsulationMode"
+ * to "IpArp") in which the length type of the Ethernet header receives the
+ * protocol number of the packet; or ETHERNET_V1 (set "EncapsulationMode" to
+ * "EthernetV1") in which the length type of the Ethernet header receives the
+ * length of the packet. A "Raw" encapsulation mode is defined but not
+ * implemented -- use of the RAW mode results in an assertion.
+ *
+ * The CsmaNetDevice implements a random exponential backoff algorithm
+ * that is executed if the channel is determined to be busy (TRANSMITTING or
+ * PROPAGATING) when the device wants to start propagating. This results in a
+ * random delay of up to pow (2, retries) - 1 microseconds before a retry is
+ * attempted. The default maximum number of retries is 1000.
+ *
+ * \section CsmaTracingModel CSMA Tracing Model
+ *
+ * Like all ns-3 devices, the CSMA Model provides a number of trace sources.
+ * These trace sources can be hooked using your own custom trace code, or you
+ * can use our helper functions to arrange for tracing to be enabled on devices
+ * you specify.
+ *
+ * \subsection CsmaTracingModelUpperHooks Upper-Level (MAC) Hooks
+ *
+ * From the point of view of tracing in the net device, there are several
+ * interesting points to insert trace hooks. A convention inherited from other
+ * simulators is that packets destined for transmission onto attached networks
+ * pass through a single "transmit queue" in the net device. We provide trace
+ * hooks at this point in packet flow, which corresponds (abstractly) only to a
+ * transition from the network to data link layer, and call them collectively
+ * the device MAC hooks.
+ *
+ * When a packet is sent to the CSMA net device for transmission it always
+ * passes through the transmit queue. The transmit queue in the
+ * CsmaNetDevice inherits from Queue, and therefore inherits three
+ * trace sources:
+ *
+ * - An Enqueue operation source (see Queue::m_traceEnqueue);
+ * - A Dequeue operation source (see Queue::m_traceDequeue);
+ * - A Drop operation source (see Queue::m_traceDrop).
+ *
+ * The upper-level (MAC) trace hooks for the CsmaNetDevice are, in fact,
+ * exactly these three trace sources on the single transmit queue of the device.
+ *
+ * The m_traceEnqueue event is triggered when a packet is placed on the transmit
+ * queue. This happens at the time that ns3::CsmaNetDevice::Send or
+ * ns3::CsmaNetDevice::SendFrom is called by a higher layer to queue a packet for
+ * transmission.
+ *
+ * The m_traceDequeue event is triggered when a packet is removed from the
+ * transmit queue. Dequeues from the transmit queue can happen in three
+ * situations: 1) If the underlying channel is idle when the
+ * CsmaNetDevice::Send or CsmaNetDevice::SendFrom is called, a packet
+ * is dequeued from the transmit queue and immediately transmitted; 2) If the
+ * underlying channel is idle, a packet may be dequeued and immediately
+ * transmitted in an internal TransmitCompleteEvent that functions much
+ * like a transmit complete interrupt service routine; or 3) from
+ * the random exponential backoff handler if a timeout is detected.
+ *
+ * Case (3) implies that a packet is dequeued from the transmit queue if it is
+ * unable to be transmitted according to the backoff rules. It is important
+ * to understand that this will appear as a Dequeued packet and it is easy to
+ * incorrectly assume that the packet was transmitted since it passed through
+ * the transmit queue. In fact, a packet is actually dropped by the net device
+ * in this case. The reason for this behavior is due to the definition of the
+ * Queue Drop event. The m_traceDrop event is, by defintion, fired when a
+ * packet cannot be enqueued on the transmit queue because it is full. This
+ * event only fires if the queue is full and we do not overload this event
+ * to indicate that the CsmaChannel is "full."
+ *
+ * \subsection CsmaTracingModelUpperHooks Lower-Level (PHY) Hooks
+ *
+ * Similar to the upper level trace hooks, there are trace hooks available at
+ * the lower levels of the net device. We call these the PHY hooks. These
+ * events fire from the device methods that talk directly to the CsmaChannel.
+ *
+ * The trace source m_dropTrace is called to indicate a packet that is dropped
+ * by the device. This happens in two cases: First, if the receive side of
+ * the net device is not enabled (see ns3::CsmaNetDevice::m_receiveEnable and the
+ * associated attribute "ReceiveEnable").
+ *
+ * The m_dropTrace is also used to indicate that a packet was discarded as
+ * corrupt if a receive error model is used (see
+ * ns3::CsmaNetDevice::m_receiveErrorModel and the associated attribute
+ * "ReceiveErrorModel").
+ *
+ * The other low-level trace source fires on reception of an accepted packet
+ * (see ns3::CsmaNetDevice::m_rxTrace). A packet is accepted if it is destined
+ * for the broadcast address, a multicast address, or to the MAC address
+ * assigned to the net device.
+ *
+ * \section CsmaModelSummary CSMA Model Summary
+ *
+ * The ns3 CSMA model is a simplistic model of an Ethernet-like network. It
+ * supports a Carrier-Sense function and allows for Multiple Access to a
+ * shared medium. It is not physical in the sense that the state of the
+ * medium is instantaneously shared among all devices. This means that there
+ * is no collision detection required in this model and none is implemented.
+ * There will never be a "jam" of a packet already on the medium. Access to
+ * the shared channel is on a first-come first-served basis as determined by
+ * the simulator scheduler. If the channel is determined to be busy by looking
+ * at the global state, a random exponential backoff is performed and a retry
+ * is attempted.
+ *
+ * Ns-3 Attributes provide a mechanism for setting various parameters in the
+ * device and channel such as addresses, encapsulation modes and error model
+ * selection. Trace hooks are provided in the usual manner with a set of
+ * upper level hooks corresponding to a transmit queue and used in ASCII
+ * tracing; and also a set of lower level hooks used in pcap tracing.
+ *
+ * Although the ns-3 CsmaChannel and CsmaNetDevice does not model any kind of
+ * network you could build or buy, it does provide us with some useful
+ * functionality. You should, however, understand that it is explicitly not
+ * Ethernet or any flavor of IEEE 802.3 but an interesting subset.
+ */
--- a/src/csma/model/csma.h Sat Mar 05 00:55:35 2011 +0000
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,331 +0,0 @@
-/**
- * \ingroup devices
- * \defgroup CsmaModel CSMA Model
- *
- * \section CsmaModelOverview CSMA Model Overview
- *
- * The ns-3 CSMA device models a simple bus network in the spirit of Ethernet.
- * Although it does not model any real physical network you could ever build
- * or buy, it does provide some very useful functionality.
- *
- * Typically when one thinks of a bus network Ethernet or IEEE 802.3 comes to
- * mind. Ethernet uses CSMA/CD (Carrier Sense Multiple Access with Collision
- * Detection with exponentially increasing backoff to contend for the shared
- * transmission medium. The ns-3 CSMA device models only a portion of this
- * process, using the nature of the globally available channel to provide
- * instantaneous (faster than light) carrier sense and priority-based
- * collision "avoidance." Collisions in the sense of Ethernet never happen and
- * so the ns-3 CSMA device does not model collision detection, nor will any
- * transmission in progress be "jammed."
- *
- * \section CsmaLayerModel CSMA Layer Model
- *
- * There are a number of conventions in use for describing layered
- * communications architectures in the literature and in textbooks. The most
- * common layering model is the ISO seven layer reference model. In this view
- * the ns3::CsmaNetDevice and ns3::CsmaChannel pair occupies the lowest two
- * layers -- at the physical (layer one), and data link (layer two) positions.
- * Another important reference model is that specified by RFC 1122,
- * "Requirements for Internet Hosts -- Communication Layers." In this view the
- * CsmaNetDevice and CsmaChannel pair occupies the lowest layer --
- * the link layer. There is also a seemingly endless litany of alternative
- * descriptions found in textbooks and in the literature. We adopt the naming
- * conventions used in the IEEE 802 standards which speak of LLC, MAC, MII
- * and PHY layering. These acronyms are defined as:
- *
- * - LLC: Logical Link Control;
- * - MAC: Media Access Control;
- * - MII: Media Independent Interface;
- * - PHY: Physical Layer.
- *
- * In this case the LLC and MAC are sublayers of the OSI data link layer and the
- * MII and PHY are sublayers of the OSI physical layer.
- *
- * The "top" of the CSMA device defines the transition from the network layer
- * to the data link layer. This transition is performed by higher layers by
- * calling either ns3::CsmaNetDevice::Send or ns3::CsmaNetDevice::SendFrom.
- *
- * In contrast to the IEEE 802.3 standards, there is no precisely specified
- * PHY in the CSMA model in the sense of wire types, signals or pinouts. The
- * "bottom" interface of the CsmaNetDevice can be thought of as as a kind
- * of Media Independent Interface (MII) as seen in the "Fast Ethernet"
- * (IEEE 802.3u) specifications. This MII interface fits into a corresponding
- * media independent interface on the CsmaChannel. You will not find the
- * equivalent of a 10BASE-T or a 1000BASE-LX PHY.
- *
- * The CsmaNetDevice calls the CsmaChannel through a media independent
- * interface. There is a method defined to tell the channel when to start
- * "wiggling the wires" using the method ns3::CsmaChannel::TransmitStart, and
- * a method to tell the channel when the transmission process is done and
- * the channel should begin propagating the last bit across the "wire":
- * ns3::CsmaChannel::TransmitEnd.
- *
- * When the TransmitEnd method is executed, the channel will model a single
- * uniform signal propagation delay in the medium and deliver copes of the packet
- * to each of the devices attached to the packet via the
- * ns3::CsmaNetDevice::Receive method.
- *
- * There is a "pin" in the device media independent interface corresponding to
- * "COL" (collision). The state of the channel may be sensed by calling
- * ns3::CsmaChannel::GetState. Each device will look at this "pin" before
- * starting a send and will perform appropriate backoff operations if required.
- *
- * Properly received packets are forwarded up to higher levels from the
- * CsmaNetDevice via a callback mechanism. The callback function is
- * initialized by the higher layer (when the net device is attached) using
- * ns3::CsmaNetDevice::SetReceiveCallback and is invoked upon "proper"
- * reception of a packet by the net device in order to forward the packet up
- * the protocol stack.
- *
- * \section CsmaChannelModel CSMA Channel Model
- *
- * The class CsmaChannel models the actual transmission medium.
- * There is no fixed limit for the number of devices connected to the channel.
- * The CsmaChannel models a data rate and a speed-of-light delay which can
- * be accessed via the attributes "DataRate" and "Delay" respectively.
- * The data rate provided to the channel is used to set the data rates
- * used by the transmitter sections of the CSMA devices connected to the
- * channel. There is no way to independently set data rates in the
- * devices. Since the data rate is only used to calculate a delay time, there
- * is no limitation (other than by the data type holding the value) on the
- * speed at which CSMA channels and devices can operate; and no restriction
- * based on any kind of PHY characteristics.
- *
- * The CsmaChannel has three states, IDLE, TRANSMITTING and PROPAGATING.
- * These three states are "seen" instantaneously by all devices on the channel.
- * By this we mean that if one device begins or ends a simulated transmission,
- * all devices on the channel are immediately aware of the change in state.
- * There is no time during which one device may see an IDLE channel while
- * another device physically further away in the collision domain may have
- * begun transmitting with the associated signals not propagated. Thus there
- * is no need for collision detection in the CsmaChannel model and it is
- * not implemented in any way.
- *
- * We do, as the name indicates, have a Carrier Sense aspect to the model.
- * Since the simulator is single threaded, access to the common channel will
- * be serialized by the simulator. This provides a deterministic mechanism
- * for contending for the channel. The channel is allocated (transitioned from
- * state IDLE to state TRANSMITTING) on a first-come first-served basis. The
- * channel always goes through a three state process:
- *
- * IDLE -> TRANSMITTING -> PROPAGATING -> IDLE
- *
- * The TRANSMITTING state models the time during which the source net device
- * is actually wiggling the signals on the wire. The PROPAGATING state models
- * the time after the last bit was sent, when the signal is propagating down
- * the wire to the "far end."
- *
- * The transition to the TRANSMITTING state is driven by a call to
- * ns3::CsmaChannel::TransmitStart which is called by the net device that
- * transmits the packet. It is the responsibility of that device to end the
- * transmission with a call to ns3::CsmaChannel::TransmitEnd at the appropriate
- * simulation time that reflects the time elapsed to put all of the packet bits
- * on the wire. When TransmitEnd is called, the channel schedules an event
- * corresponding to a single speed-of-light delay. This delay applies to all
- * net devices on the channel identically. You can think of a symmetrical hub
- * in which the packet bits propagate to a central location and then back out
- * equal length cables to the other devices on the channel.
- *
- * The CsmaChannel models a broadcast medium so the packet is delivered
- * to all of the devices on the channel (including the source) at the end of
- * the propagation time. It is the responsibility of the sending device to
- * determine whether or not it receives a packet broadcast over the channel.
- *
- * The CsmaChannel provides following Attributes:
- *
- * - DataRate: The bitrate for packet transmission on connected devices;
- * - Delay: The speed of light transmission delay for the channel.
- *
- * \section CsmaNetDeviceModel CSMA Net Device Model
- *
- * The CSMA network device appears somewhat like an Ethernet device, but it
- * is important to understand that it does not model an Ethernet device. As
- * mentioned above, it does not model collisions. The CSMA model also provides
- * users with the ability to configure the device into other states that are
- * not compatible with strictly Ethernet or IEEE 802.3 devices.
- *
- * The CsmaNetDevice provides following Attributes:
- *
- * - Address: The Mac48Address of the device;
- * - SendEnable: Enable packet transmission if true;
- * - ReceiveEnable: Enable packet reception if true;
- * - EncapsulationMode: Type of link layer encapsulation to use;
- * - RxErrorModel: The receive error model;
- * - TxQueue: The transmit queue used by the device;
- * - InterframeGap: The optional time to wait between "frames";
- * - Rx: A trace source for received packets;
- * - Drop: A trace source for dropped packets.
- *
- * We recommend thinking carefully about changing these Attributes, since
- * it can result in behavior that surprises users. We allow this because
- * we believe flexibility is important. As an example of a possibly
- * surprising effect of changing Attributes, consider the following:
- *
- * The Mtu Attribute indicates the Maximum Transmission Unit to the device.
- * This is the size of the largest Protocol Data Unit (PDU) that the
- * device can send. This Attribute defaults to 1500 bytes and corresponds
- * to a number found in RFC 894, "A Standard for the Transmission of IP
- * Datagrams over Ethernet Networks." The number is actually derived
- * from the maximum packet size for 10Base5 (full-spec Ethernet) networks --
- * 1518 bytes. If you subtract DIX encapsulation overhead for Ethernet
- * packets (18 bytes) you will end up with a maximum possible data size (MTU)
- * of 1500 bytes. One can also find that the MTU for IEEE 802.3 networks
- * is 1492 bytes. This is because LLC/SNAP encapsulation adds an extra eight
- * bytes of overhead to the packet. In both cases, the underlying network
- * hardware is limited to 1518 bytes, but the MTU is different because the
- * encapsulation is different.
- *
- * If one leaves the Mtu Attribute at 1500 bytes and changes the encapsulation
- * mode Attribute to Llc, the result will be a network that encapsulates 1500
- * byte PDUs with LLC/SNAP framing resulting in packets of 1526 bytes. This
- * would be illegal in many networks, but we allow you do do this. This
- * results in a simulation that quite subtly does not reflect what you might
- * be expecting since a real device would balk at sending a 1526 byte packet.
- *
- * There also exist jumbo frames (1500 < MTU <= 9000 bytes) and super-jumbo
- * (MTU > 9000 bytes) frames that are not officially sanctioned by IEEE but
- * are available in some high-speed (Gigabit) networks and NICs. In the
- * CSMA model, one could leave the encapsulation mode set to Dix, and set the
- * Mtu to 64000 bytes -- even though an associated CsmaChannel DataRate was
- * left at 10 megabits per second (certainly not Gigabit Ethernet). This
- * would essentially model an Ethernet switch made out of vampire-tapped
- * 1980s-style 10Base5 networks that support super-jumbo datagrams, which is
- * certainly not something that was ever made, nor is likely to ever be made;
- * however it is quite easy for you to configure.
- *
- * Be careful about assumptions regarding what CSMA is actually modelling and
- * how configuration (Attributes) may allow you to swerve considerably away
- * from reality.
- *
- * The CsmaNetDevice supports the assignment of a "receive error model."
- * This is an ErrorModel object that is used to simulate data corruption
- * on the link.
- *
- * Packets sent over the CsmaNetDevice are always routed through the
- * transmit queue to provide a trace hook for packets sent out over the
- * network. This transmit queue can be set (via attribute) to model different
- * queueing strategies.
- *
- * Also configurable by attribute is the encapsulation method used by the
- * device. By default, or by setting the "EncapsulationMode" attribute to
- * "Dix", the encapsulation is according to the DEC, Intel, Xerox standard.
- * This is sometimes called EthernetII framing and is the familiar destination
- * MAC, source MAC, EtherType, Data, CRC format.
- *
- * If the "EncapsulationMode" attribute is set to "Llc", the encapsulation is by
- * LLC SNAP. In this case, a SNAP header is added that contains the EtherType
- * (IP or ARP).
- *
- * The other implemented encapsulation modes are IP_ARP (set "EncapsulationMode"
- * to "IpArp") in which the length type of the Ethernet header receives the
- * protocol number of the packet; or ETHERNET_V1 (set "EncapsulationMode" to
- * "EthernetV1") in which the length type of the Ethernet header receives the
- * length of the packet. A "Raw" encapsulation mode is defined but not
- * implemented -- use of the RAW mode results in an assertion.
- *
- * The CsmaNetDevice implements a random exponential backoff algorithm
- * that is executed if the channel is determined to be busy (TRANSMITTING or
- * PROPAGATING) when the device wants to start propagating. This results in a
- * random delay of up to pow (2, retries) - 1 microseconds before a retry is
- * attempted. The default maximum number of retries is 1000.
- *
- * \section CsmaTracingModel CSMA Tracing Model
- *
- * Like all ns-3 devices, the CSMA Model provides a number of trace sources.
- * These trace sources can be hooked using your own custom trace code, or you
- * can use our helper functions to arrange for tracing to be enabled on devices
- * you specify.
- *
- * \subsection CsmaTracingModelUpperHooks Upper-Level (MAC) Hooks
- *
- * From the point of view of tracing in the net device, there are several
- * interesting points to insert trace hooks. A convention inherited from other
- * simulators is that packets destined for transmission onto attached networks
- * pass through a single "transmit queue" in the net device. We provide trace
- * hooks at this point in packet flow, which corresponds (abstractly) only to a
- * transition from the network to data link layer, and call them collectively
- * the device MAC hooks.
- *
- * When a packet is sent to the CSMA net device for transmission it always
- * passes through the transmit queue. The transmit queue in the
- * CsmaNetDevice inherits from Queue, and therefore inherits three
- * trace sources:
- *
- * - An Enqueue operation source (see Queue::m_traceEnqueue);
- * - A Dequeue operation source (see Queue::m_traceDequeue);
- * - A Drop operation source (see Queue::m_traceDrop).
- *
- * The upper-level (MAC) trace hooks for the CsmaNetDevice are, in fact,
- * exactly these three trace sources on the single transmit queue of the device.
- *
- * The m_traceEnqueue event is triggered when a packet is placed on the transmit
- * queue. This happens at the time that ns3::CsmaNetDevice::Send or
- * ns3::CsmaNetDevice::SendFrom is called by a higher layer to queue a packet for
- * transmission.
- *
- * The m_traceDequeue event is triggered when a packet is removed from the
- * transmit queue. Dequeues from the transmit queue can happen in three
- * situations: 1) If the underlying channel is idle when the
- * CsmaNetDevice::Send or CsmaNetDevice::SendFrom is called, a packet
- * is dequeued from the transmit queue and immediately transmitted; 2) If the
- * underlying channel is idle, a packet may be dequeued and immediately
- * transmitted in an internal TransmitCompleteEvent that functions much
- * like a transmit complete interrupt service routine; or 3) from
- * the random exponential backoff handler if a timeout is detected.
- *
- * Case (3) implies that a packet is dequeued from the transmit queue if it is
- * unable to be transmitted according to the backoff rules. It is important
- * to understand that this will appear as a Dequeued packet and it is easy to
- * incorrectly assume that the packet was transmitted since it passed through
- * the transmit queue. In fact, a packet is actually dropped by the net device
- * in this case. The reason for this behavior is due to the definition of the
- * Queue Drop event. The m_traceDrop event is, by defintion, fired when a
- * packet cannot be enqueued on the transmit queue because it is full. This
- * event only fires if the queue is full and we do not overload this event
- * to indicate that the CsmaChannel is "full."
- *
- * \subsection CsmaTracingModelUpperHooks Lower-Level (PHY) Hooks
- *
- * Similar to the upper level trace hooks, there are trace hooks available at
- * the lower levels of the net device. We call these the PHY hooks. These
- * events fire from the device methods that talk directly to the CsmaChannel.
- *
- * The trace source m_dropTrace is called to indicate a packet that is dropped
- * by the device. This happens in two cases: First, if the receive side of
- * the net device is not enabled (see ns3::CsmaNetDevice::m_receiveEnable and the
- * associated attribute "ReceiveEnable").
- *
- * The m_dropTrace is also used to indicate that a packet was discarded as
- * corrupt if a receive error model is used (see
- * ns3::CsmaNetDevice::m_receiveErrorModel and the associated attribute
- * "ReceiveErrorModel").
- *
- * The other low-level trace source fires on reception of an accepted packet
- * (see ns3::CsmaNetDevice::m_rxTrace). A packet is accepted if it is destined
- * for the broadcast address, a multicast address, or to the MAC address
- * assigned to the net device.
- *
- * \section CsmaModelSummary CSMA Model Summary
- *
- * The ns3 CSMA model is a simplistic model of an Ethernet-like network. It
- * supports a Carrier-Sense function and allows for Multiple Access to a
- * shared medium. It is not physical in the sense that the state of the
- * medium is instantaneously shared among all devices. This means that there
- * is no collision detection required in this model and none is implemented.
- * There will never be a "jam" of a packet already on the medium. Access to
- * the shared channel is on a first-come first-served basis as determined by
- * the simulator scheduler. If the channel is determined to be busy by looking
- * at the global state, a random exponential backoff is performed and a retry
- * is attempted.
- *
- * Ns-3 Attributes provide a mechanism for setting various parameters in the
- * device and channel such as addresses, encapsulation modes and error model
- * selection. Trace hooks are provided in the usual manner with a set of
- * upper level hooks corresponding to a transmit queue and used in ASCII
- * tracing; and also a set of lower level hooks used in pcap tracing.
- *
- * Although the ns-3 CsmaChannel and CsmaNetDevice does not model any kind of
- * network you could build or buy, it does provide us with some useful
- * functionality. You should, however, understand that it is explicitly not
- * Ethernet or any flavor of IEEE 802.3 but an interesting subset.
- */
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/mesh/doc/mesh.h Sat Mar 05 01:00:13 2011 +0000
@@ -0,0 +1,104 @@
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+/*
+ * Copyright (c) 2009 IITP RAS
+ *
+ * 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
+ *
+ * Authors: Kirill Andreev <[email protected]>
+ * Aleksander Safonov <[email protected]>
+ * Pavel Boyko <[email protected]>
+ *
+ * This is top level mesh module description
+ */
+
+/**
+ * \ingroup devices
+ * \defgroup mesh Mesh
+ *
+ * \brief MAC-layer mobile mesh networking.
+ * \section MeshOverview Overview of Layer-2 Mesh networking protocols
+ *
+ * The main goal of this module is to provide MAC-layer routing functionality.
+
+ * The main part of MAC-layer routing model is specific 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.
+ *
+ * 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-tier 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 types 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
+ * (it works like association mechanism in IEEE802.11).
+ * - FLAME (Forwarding LAyer for MEshing).
+
+ * 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
+ * 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 beacons 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 operate 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 L2Routing protocol has a structure to capture statistics, Report and ResetStats methods.
+ * This gives an opportunity to collect statistic to an *.xml file periodically.
+ */
--- a/src/mesh/model/mesh.h Sat Mar 05 00:55:35 2011 +0000
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,104 +0,0 @@
-/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
-/*
- * Copyright (c) 2009 IITP RAS
- *
- * 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
- *
- * Authors: Kirill Andreev <[email protected]>
- * Aleksander Safonov <[email protected]>
- * Pavel Boyko <[email protected]>
- *
- * This is top level mesh module description
- */
-
-/**
- * \ingroup devices
- * \defgroup mesh Mesh
- *
- * \brief MAC-layer mobile mesh networking.
- * \section MeshOverview Overview of Layer-2 Mesh networking protocols
- *
- * The main goal of this module is to provide MAC-layer routing functionality.
-
- * The main part of MAC-layer routing model is specific 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.
- *
- * 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-tier 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 types 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
- * (it works like association mechanism in IEEE802.11).
- * - FLAME (Forwarding LAyer for MEshing).
-
- * 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
- * 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 beacons 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 operate 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 L2Routing protocol has a structure to capture statistics, Report and ResetStats methods.
- * This gives an opportunity to collect statistic to an *.xml file periodically.
- */