F5/unison
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

add to CSMA dox for trace sources

Browse Source
This commit is contained in:
Craig Dowell
2008-12-08 21:09:29 -08:00
parent 32de22509c
commit 99c1403d6e
1 changed files with 289 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

297
src/devices/csma/csma.h
View File

@@ -1,8 +1,8 @@
/**
* \ingroup devices
* \defgroup CSMA CSMA Model
* \defgroup CsmaModel CSMA Model
*
* \section 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
@@ -18,7 +18,115 @@
* so the ns-3 CSMA device does not model collision detection, nor will any
* transmission in progress be "jammed."
*
* \subsection CSMA Channel Model
* \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
* ns3::CsmaNetDevice and ns3::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
*
* \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
*
* 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
* 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
* equivalent of a 10BASE-T or a 1000BASE-LX PHY.
*
* The ns3::CsmaNetDevice calls the ns3::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
*
* 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
*
* 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.
*
* 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
*
* \section CsmaChannelModel CSMA Channel Model
*
* The class ns3::CsmaChannel models the actual transmission medium.
* There is no fixed limit for the number of devices connected to the channel.
@@ -29,7 +137,8 @@
* 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.
* 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.
* These three states are "seen" instantaneously by all devices on the channel.
@@ -76,7 +185,7 @@
* - DataRate: The bitrate for packet transmission on connected devices;
* - Delay: The speed of light transmission delay for the channel.
*
* \subsection CSMA Net Device Model
* \section CsmaNetDeviceModel CSMA Net Device Model
*
* The CSMA network device appears somewhat like an Ethernet device. The
* ns3::CsmaNetDevice provides following Attributes:
@@ -121,7 +230,177 @@
* random delay of up to pow (2, retries) - 1 microseconds before a retry is
* attempted. The default maximum number of retries is 1000.
*
* \subsection CSMA Model Summary
* \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 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.
*
* 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:
*
* - 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).
*
* 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 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.
*
* 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
* 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
* 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
*
* \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
*
* 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 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 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
* "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.
*
* 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
* supports a Carrier-Sense function and allows for Multiple Access to a
@@ -136,10 +415,12 @@
*
* 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.
* 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 IEEE 802.3 but an interesting subset.
* Ethernet or any flavor of IEEE 802.3 but an interesting subset.
*/