--- a/src/devices/csma/csma.h Wed Dec 10 02:36:28 2008 -0800
+++ b/src/devices/csma/csma.h Wed Dec 10 16:47:44 2008 -0800
@@ -23,11 +23,11 @@
* 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
+ * the CsmaNetDevice and 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
- * ns3::CsmaNetDevice and ns3::CsmaChannel pair occupies the lowest layer --
+ * 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
@@ -43,94 +43,45 @@
*
* 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
- *
- * \code
- * bool
- * CsmaNetDevice::Send (
- * Ptr<Packet> packet,
- * const Address& dest,
- * uint16_t protocolNumber);
- * \endcode
- *
- * or
- *
- * \code
- * bool
- * CsmaNetDevice::SendFrom (
- * Ptr<Packet> packet,
- * const Address& src,
- * const Address& dest,
- * uint16_t protocolNumber);
- * \endcode
+ * calling either CsmaNetDevice::Send or 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 ns3::CsmaNetDevice can be thought of as as a kind
+ * "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 ns3::CsmaChannel. You will not find the
+ * media independent interface on the CsmaChannel. You will not find the
* equivalent of a 10BASE-T or a 1000BASE-LX PHY.
*
- * The ns3::CsmaNetDevice calls the ns3::CsmaChannel through a media independent
+ * 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:
- *
- * \code
- * bool
- * CsmaChannel::TransmitStart (Ptr<Packet> p, uint32_t srcId);
- * \endcode
- *
- * 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."
- *
- * \code
- * bool
- * CsmaChannel::TransmitEnd();
- * \endcode
+ * "wiggling the wires" using the method 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":
+ * CsmaChannel::TransmitEnd.
*
- * When the transmit end method is executed, the channel will model a single
- * uniform signal propagation delay in the medium and then call the media
- * independent interface at the bottom of each of the devices attached to the
- * channel:
- *
- * \code
- * void
- * CsmaNetDevice::Receive (Ptr<Packet> packet, Ptr<CsmaNetDevice> senderDevice);
- * \endcode
+ * 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
+ * CsmaNetDevice::Receive method.
*
- * There is a "pin" in the media independent interface corresponding to "COL"
- * (collision). The state of the channel may be sensed by calling,
- *
- * \code
- * WireState
- * CsmaChannel::GetState (void);
- * \endcode
- *
- * The ns3::CsmaNetDevice will look at this "pin" before starting a send and
- * will perform appropriate backoff operations if required.
+ * There is a "pin" in the device media independent interface corresponding to
+ * "COL" (collision). The state of the channel may be sensed by calling
+ * 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
- * ns3::CsmaNetDevice via a callback mechanism. The callback function is
- * initialized by the higher layer (when the net device is attached) using:
- *
- * \code
- * void
- * CsmaNetDevice::SetReceiveCallback (NetDevice::ReceiveCallback cb);
- * \endcode
- *
- * and is invoked upon proper reception of a packet by the net device from the
- * channel in the following way:
- *
- * \code
- * m_rxCallback (this, packet, protocol, header.GetSource ());
- * \endcode
+ * CsmaNetDevice via a callback mechanism. The callback function is
+ * initialized by the higher layer (when the net device is attached) using
+ * 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 ns3::CsmaChannel models the actual transmission medium.
+ * The class CsmaChannel models the actual transmission medium.
* There is no fixed limit for the number of devices connected to the channel.
- * The ns3::CsmaChannel models a data rate and a speed-of-light delay which can
+ * 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
@@ -140,14 +91,14 @@
* speed at which CSMA channels and devices can operate; and no restriction
* based on any kind of PHY characteristics.
*
- * The ns3::CsmaChannel has three states, IDLE, TRANSMITTING and PROPAGATING.
+ * 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 ns3::CsmaChannel model and it is
+ * 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.
@@ -165,9 +116,9 @@
* 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
+ * 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
+ * transmission with a call to 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
@@ -175,12 +126,12 @@
* 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 ns3::CsmaChannel models a broadcast medium so the packet is delivered
+ * 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 ns3::CsmaChannel provides following Attributes:
+ * The CsmaChannel provides following Attributes:
*
* - DataRate: The bitrate for packet transmission on connected devices;
* - Delay: The speed of light transmission delay for the channel.
@@ -188,9 +139,9 @@
* \section CsmaNetDeviceModel CSMA Net Device Model
*
* The CSMA network device appears somewhat like an Ethernet device. The
- * ns3::CsmaNetDevice provides following Attributes:
+ * CsmaNetDevice provides following Attributes:
*
- * - Address: The ns3::Mac48Address of the device;
+ * - 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;
@@ -200,19 +151,19 @@
* - Rx: A trace source for received packets;
* - Drop: A trace source for dropped packets.
*
- * The ns3::CsmaNetDevice supports the assignment of a "receive error model."
- * This is an ns3::ErrorModel object that is used to simulate data corruption
+ * 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 ns3::CsmaNetDevice are always routed through the
+ * 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. Every packet gets an ns3::EthernetHeader that includes the
+ * device. Every packet gets an EthernetHeader that includes the
* destination and source MAC addresses, and a length/type field. Every packet
- * also gets an ns3::EthernetTrailer which includes the FCS. Data in the
+ * also gets an EthernetTrailer which includes the FCS. Data in the
* packet may be encapsulated in different ways. By default, or by setting
* the "EncapsulationMode" attribute to "Llc", the encapsulation is by
* LLC SNAP. In this case, a SNAP header is added that contains the EtherType
@@ -224,7 +175,7 @@
* mode is defined but not implemented -- use of the RAW mode results in an
* assert firing.
*
- * The ns3::CsmaNetDevice implements a random exponential backoff algorithm
+ * 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
@@ -237,169 +188,75 @@
* can use our helper functions to arrange for tracing to be enabled on devices
* you specify.
*
- * \subsection CsmaTracingModelUpperHooks Upper-Level Hooks
+ * \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
+ * 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.
+ * 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
* passed through the transmit queue. The transmit queue in the
- * ns3::CsmaNetDevice inherits from ns3::Queue, and therefore inherits three
- * TraceSources:
+ * CsmaNetDevice inherits from Queue, and therefore inherits three
+ * trace sources:
*
- * - An Enqueue operation source (see ns3::Queue::m_traceEnqueue);
- * - A Dequeue operation source (see ns3::Queue::m_traceDequeue);
- * - A Drop operation source (see ns3::Queue::m_traceDrop).
+ * - 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 trace hooks for the ns3::CsmaNetDevice are, in fact, exactly
- * these three trace sources on the single transmit queue of the device.
+ * 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.
+ * queue. This happens at the time that CsmaNetDevice::Send or
+ * 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
- * ns3::CsmaNetDevice::Send or ns3::CsmaNetDevice::SendFrom is called, a packet
+ * 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 ns3::TransmitCompleteEvent () that functions much
+ * 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.
*
- * To summarize, then, a packet is dequeued from the transmit queue, and a
- * Dequeue event is fired, immediately before it is transmitted down the channel.
- * A packet is also dequeued from the transmit queue if it is unable to be
- * transmittted according to the backoff rules. It is important to understand
- * that this will appear in the ASCII traces as a Dequeued packet that will
- * appear as if it were transmitted. The fact is that this packet is actually
- * dropped by the net device.
- *
- * The reason for this behavior is due to the definition of the Drop event. The
- * m_traceDrop event is fired when a packet cannot be enqueued on the transmit
- * queue becasue it is full. This event only fires if the queue is full.
- *
- * A good usage example may be found in the ASCII trace functions of the
- * ns3::CsmaHelper. In the ns3::CsmaHelper, you will find the following
- * methods:
- *
- * \code
- * void
- * CsmaHelper::AsciiEnqueueEvent (
- * std::ostream *os,
- * std::string path,
- * Ptr<const Packet> packet)
- * \endcode
- *
- * \code
- * void
- * CsmaHelper::AsciiDequeueEvent (
- * std::ostream *os,
- * std::string path,
- * Ptr<const Packet> packet)
- * \endcode
+ * Case (3) implies that a packet is dequeued from the transmit queue if it is
+ * unable to be transmittted 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 becasue 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."
*
- * \code
- * void
- * CsmaHelper::AsciiDropEvent (
- * std::ostream *os,
- * std::string path,
- * Ptr<const Packet> packet)
- * \endcode
- *
- * These events are hooked in the ns3::CsmaHelper::EnableAscii () method using
- * a typical idiom:
- *
- * \code
- * std::ostringstream oss;
- * oss << "/NodeList/" << nodeid << "/DeviceList/" << deviceid << "/$ns3::CsmaNetDevice/TxQueue/Enqueue";
- * Config::Connect (oss.str (), MakeBoundCallback (&CsmaHelper::AsciiEnqueueEvent, &os));
- * \endcode
- *
- * This particular snippet hooks the transmit queue (TxQueue) Enqueue operation
- * trace source. The source is identified by a string that may look something
- * like,
- *
- * \code
- * /NodeList/0/DeviceList/0/$ns3::CsmaNetDevice/TxQueue/Enqueue"
- * \endcode
- *
- * This is the glue that connects the transmit queue enqueue trace source to
- * ns3::CsmaHelper AsciiEnqueueEvent.
- *
- * If you examine the handlers you will find that the AcsiiEnqueueEvent on the
- * transmit queue ends up printing the well known '+' event int the ASCII trace
- * files. You will also find that AsciiDequeueEvent prints the '-' event and
- * AsciiDropEvent prints the 'd' event.
- *
- * \subsection CsmaTracingModelUpperHooks Lower-Level Hooks
+ * \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. In particular, these events fire from
- * the ns3::CsmaNetDevice::Receive method which is the method called by the
- * ns3::CsmaChannel to deliver a packet to the net device.
+ * 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 dropped packet if the
- * receive side of the net device is not enabled (see
- * CsmaNetDevice::m_receiveEnable and the associated attribute "ReceiveEnable").
+ * 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 CsmaNetDevice::m_receiveEnable and the
+ * associated attribute "ReceiveEnable").
*
* The m_dropTrace is also used to indicate that a packet was discarded as
- * corrupt if the receive error model is used (see
- * ns3::CsmaNetDevice::m_receiveErrorModel and the associated attribute
+ * corrupt if a receive error model is used (see
+ * 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
+ * (see 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.
*
- * A good usage example may be found in the pcap trace functions of the
- * ns3::CsmaHelper. In the ns3::CsmaHelper, you will find the following
- * methods:
- *
- * \code
- * void
- * CsmaHelper::EnqueueEvent (Ptr<PcapWriter> writer, Ptr<const Packet> packet)
- * \endcode
- *
- * and
- *
- * \code
- * void
- * CsmaHelper::RxEvent (Ptr<PcapWriter> writer, Ptr<const Packet> packet)
- * \endcode
- *
- * These events are hooked in the ns3::CsmaHelper::EnablePcap () method using
- * a typical idiom:
- *
- * \code
- * std::ostringstream oss;
- * oss << "/NodeList/" << nodeid << "/DeviceList/" << deviceid << "/$ns3::CsmaNetDevice/Rx";
- * Config::ConnectWithoutContext (oss.str (), MakeBoundCallback (&CsmaHelper::RxEvent, pcap));
- * \endcode
- *
- * This particular snippet hooks the low level receive operation (m_rxTrace)
- * trace source. The source is identified by a string that may look something
- * like,
- *
- * \code
- * /NodeList/0/DeviceList/0/$ns3::CsmaNetDevice/Rx"
- * \endcode
- *
- * This is the glue that connects the packet reception trace source to
- * ns3::CsmaHelper RxEvent.
- *
- * If you examine the handlers you will find that the RxEvent on the device
- * corresponds to the arrival of an accepted packet at the lowest levels of
- * the device. You will also find that the transmitted packet trace source
- * acutally hooks to the transmit queue Enqueue event, which may be a quite
- * unexpected behavior (a bug is currently filed -- #438).
- *
* \section CsmaModelSummary CSMA Model Summary
*
* The ns3 CSMA model is a simplistic model of an Ethernet-like network. It