add to CSMA dox for trace sources
authorCraig Dowell <craigdo@ee.washington.edu>
Mon, 08 Dec 2008 21:09:29 -0800
changeset 3992 cb912b415b7d
parent 3991 36052c1dd7ab
child 3993 cac6551f95eb
add to CSMA dox for trace sources
src/devices/csma/csma.h
--- a/src/devices/csma/csma.h	Sat Dec 06 13:56:51 2008 -0800
+++ b/src/devices/csma/csma.h	Mon Dec 08 21:09:29 2008 -0800
@@ -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.
  */