add to CSMA dox for trace sources
authorCraig Dowell <craigdo@ee.washington.edu>
Mon, 08 Dec 2008 21:09:29 -0800
changeset 3992cb912b415b7d
parent 3991 36052c1dd7ab
child 3993 cac6551f95eb
add to CSMA dox for trace sources
src/devices/csma/csma.h
     1.1 --- a/src/devices/csma/csma.h	Sat Dec 06 13:56:51 2008 -0800
     1.2 +++ b/src/devices/csma/csma.h	Mon Dec 08 21:09:29 2008 -0800
     1.3 @@ -1,8 +1,8 @@
     1.4  /**
     1.5   * \ingroup devices
     1.6 - * \defgroup CSMA CSMA Model
     1.7 + * \defgroup CsmaModel CSMA Model
     1.8   *
     1.9 - * \section CSMA Model
    1.10 + * \section CsmaModelOverview CSMA Model Overview
    1.11   *
    1.12   * The ns-3 CSMA device models a simple bus network in the spirit of Ethernet.
    1.13   * Although it does not model any real physical network you could ever build 
    1.14 @@ -18,7 +18,115 @@
    1.15   * so the ns-3 CSMA device does not model collision detection, nor will any
    1.16   * transmission in progress be "jammed."
    1.17   *
    1.18 - * \subsection CSMA Channel Model
    1.19 + * \section CsmaLayerModel CSMA Layer Model
    1.20 + *
    1.21 + * There are a number of conventions in use for describing layered 
    1.22 + * communications architectures in the literature and in textbooks.  The most
    1.23 + * common layering  model is the ISO seven layer reference model.  In this view
    1.24 + * the ns3::CsmaNetDevice and ns3::CsmaChannel pair occupies the lowest two 
    1.25 + * layers -- at the physical (layer one), and data link (layer two) positions.
    1.26 + * Another important reference model is that specified by RFC 1122, 
    1.27 + * "Requirements for Internet Hosts -- Communication Layers."  In this view the
    1.28 + * ns3::CsmaNetDevice and ns3::CsmaChannel pair occupies the lowest layer -- 
    1.29 + * the link layer.  There is also a seemingly endless litany of alternative 
    1.30 + * descriptions found in textbooks and in the literature.  We adopt the naming
    1.31 + * conventions used in the IEEE 802 standards which speak of LLC, MAC, MII
    1.32 + * and PHY layering.  These acronyms are defined as:
    1.33 + *
    1.34 + * - LLC:  Logical Link Control;
    1.35 + * - MAC:  Media Access Control;
    1.36 + * - MII:  Media Independent Interface;
    1.37 + * - PHY:  Physical Layer.
    1.38 + * 
    1.39 + * In this case the LLC and MAC are sublayers of the OSI data link layer and the 
    1.40 + * MII and PHY are sublayers of the OSI physical layer.
    1.41 + *
    1.42 + * The "top" of the CSMA device defines the transition from the network layer
    1.43 + * to the data link layer.  This transition is performed by higher layers by 
    1.44 + * calling either
    1.45 + *
    1.46 + * \code
    1.47 + *   bool 
    1.48 + *   CsmaNetDevice::Send (
    1.49 + *     Ptr<Packet> packet,
    1.50 + *     const Address& dest, 
    1.51 + *     uint16_t protocolNumber);
    1.52 + * \endcode
    1.53 + * 
    1.54 + * or
    1.55 + *
    1.56 + * \code
    1.57 + *  bool
    1.58 + *  CsmaNetDevice::SendFrom (
    1.59 + *    Ptr<Packet> packet, 
    1.60 + *    const Address& src, 
    1.61 + *   const Address& dest, 
    1.62 + *   uint16_t protocolNumber);
    1.63 + * \endcode
    1.64 + *
    1.65 + * In contrast to the IEEE 802.3 standards, there is no precisely specified
    1.66 + * PHY in the CSMA model in the sense of wire types, signals or pinouts.  The
    1.67 + * "bottom" interface of the ns3::CsmaNetDevice can be thought of as as a kind
    1.68 + * of Media Independent Interface (MII) as seen in the "Fast Ethernet" 
    1.69 + * (IEEE 802.3u) specifications.  This MII interface fits into a corresponding
    1.70 + * media independent interface on the ns3::CsmaChannel.  You will not find the
    1.71 + * equivalent of a 10BASE-T or a 1000BASE-LX PHY.
    1.72 + *
    1.73 + * The ns3::CsmaNetDevice calls the ns3::CsmaChannel through a media independent
    1.74 + * interface.  There is a method defined to tell the channel when to start 
    1.75 + * "wiggling the wires" using the method:
    1.76 + *
    1.77 + * \code
    1.78 + *   bool
    1.79 + *   CsmaChannel::TransmitStart (Ptr<Packet> p, uint32_t srcId);
    1.80 + * \endcode
    1.81 + *
    1.82 + * and a method to tell the channel when the transmission process is done and
    1.83 + * the channel should begin propagating the last bit across the "wire."
    1.84 + *
    1.85 + * \code
    1.86 + *   bool
    1.87 + *   CsmaChannel::TransmitEnd();
    1.88 + * \endcode
    1.89 + *
    1.90 + * When the transmit end method is executed, the channel will model a single 
    1.91 + * uniform signal propagation delay in the medium and then call the media
    1.92 + * independent interface at the bottom of each of the devices attached to the
    1.93 + * channel:
    1.94 + *
    1.95 + * \code
    1.96 + *   void
    1.97 + *   CsmaNetDevice::Receive (Ptr<Packet> packet, Ptr<CsmaNetDevice> senderDevice);
    1.98 + * \endcode
    1.99 + *
   1.100 + * There is a "pin" in the media independent interface corresponding to "COL"
   1.101 + * (collision).  The state of the channel may be sensed by calling,
   1.102 + *
   1.103 + * \code
   1.104 + *   WireState
   1.105 + *   CsmaChannel::GetState (void);
   1.106 + * \endcode
   1.107 + *
   1.108 + * The ns3::CsmaNetDevice will look at this "pin" before starting a send and 
   1.109 + * will perform appropriate backoff operations if required.
   1.110 + *
   1.111 + * Properly received packets are forwarded up to higher levels from the 
   1.112 + * ns3::CsmaNetDevice via a callback mechanism.  The callback function is
   1.113 + * initialized by the higher layer (when the net device is attached) using:
   1.114 + *
   1.115 + * \code
   1.116 + *   void 
   1.117 + *   CsmaNetDevice::SetReceiveCallback (NetDevice::ReceiveCallback cb);
   1.118 + * \endcode
   1.119 + *
   1.120 + * and is invoked upon proper reception of a packet by the net device from the
   1.121 + * channel in the following way:
   1.122 + *
   1.123 + * \code
   1.124 + *   m_rxCallback (this, packet, protocol, header.GetSource ());
   1.125 + * \endcode
   1.126 + *
   1.127 + * \section CsmaChannelModel CSMA Channel Model
   1.128   *
   1.129   * The class ns3::CsmaChannel models the actual transmission medium.
   1.130   * There is no fixed limit for the number of devices connected to the channel.
   1.131 @@ -29,7 +137,8 @@
   1.132   * channel.  There is no way to independently set data rates in the
   1.133   * devices.  Since the data rate is only used to calculate a delay time, there
   1.134   * is no limitation (other than by the data type holding the value) on the 
   1.135 - * speed at which CSMA channels and devices can operate.
   1.136 + * speed at which CSMA channels and devices can operate; and no restriction
   1.137 + * based on any kind of PHY characteristics.
   1.138   *
   1.139   * The ns3::CsmaChannel has three states, IDLE, TRANSMITTING and PROPAGATING.
   1.140   * These three states are "seen" instantaneously by all devices on the channel.
   1.141 @@ -76,7 +185,7 @@
   1.142   * - DataRate:      The bitrate for packet transmission on connected devices;
   1.143   * - Delay:       The speed of light transmission delay for the channel.
   1.144   *
   1.145 - * \subsection CSMA Net Device Model
   1.146 + * \section CsmaNetDeviceModel CSMA Net Device Model
   1.147   *
   1.148   * The CSMA network device appears somewhat like an Ethernet device.  The
   1.149   * ns3::CsmaNetDevice provides following Attributes:
   1.150 @@ -121,7 +230,177 @@
   1.151   * random delay of up to pow (2, retries) - 1 microseconds before a retry is
   1.152   * attempted.  The default maximum number of retries is 1000.
   1.153   *
   1.154 - * \subsection CSMA Model Summary
   1.155 + * \section CsmaTracingModel CSMA Tracing Model
   1.156 + *
   1.157 + * Like all ns-3 devices, the CSMA Model provides a number of trace sources.
   1.158 + * These trace sources can be hooked using your own custom trace code, or you
   1.159 + * can use our helper functions to arrange for tracing to be enabled on devices
   1.160 + * you specify.
   1.161 + *
   1.162 + * \subsection CsmaTracingModelUpperHooks Upper-Level Hooks
   1.163 + *
   1.164 + * From the point of view of tracing in the net device, there are several 
   1.165 + * interesting points to insert trace hooks.  A convention inherited from other
   1.166 + * simulators is that packets destined for transmission onto attached networks
   1.167 + * pass through a single"transmit queue" in the net device.  We provide trace 
   1.168 + * hooks at this point in packet flow, which corresponds (abstractly) only to a 
   1.169 + * transition from the network to data link layer.
   1.170 + *
   1.171 + * When a packet is sent to the CSMA net device for transmission it always 
   1.172 + * passed through the transmit queue.  The transmit queue in the 
   1.173 + * ns3::CsmaNetDevice inherits from ns3::Queue, and therefore inherits three 
   1.174 + * TraceSources:
   1.175 + *
   1.176 + * - An Enqueue operation source (see ns3::Queue::m_traceEnqueue);
   1.177 + * - A Dequeue operation source (see ns3::Queue::m_traceDequeue);
   1.178 + * - A Drop operation source (see ns3::Queue::m_traceDrop).
   1.179 + *
   1.180 + * The upper-level trace hooks for the ns3::CsmaNetDevice are, in fact, exactly
   1.181 + * these three trace sources on the single transmit queue of the device.  
   1.182 + *
   1.183 + * The m_traceEnqueue event is triggered when a packet is placed on the transmit
   1.184 + * queue.  This happens at the time that ns3::CsmaNetDevice::Send () or 
   1.185 + * ns3::CsmaNetDevice::SendFrom () is called.  
   1.186 + *
   1.187 + * The m_traceDequeue event is triggered when a packet is removed from the
   1.188 + * transmit queue.  Dequeues from the transmit queue can happen in three 
   1.189 + * situations:  1) If the underlying channel is idle when the 
   1.190 + * ns3::CsmaNetDevice::Send or ns3::CsmaNetDevice::SendFrom is called, a packet
   1.191 + * is dequeued from the transmit queue and immediately transmitted;  2) If the
   1.192 + * underlying channel is idle, a packet may be dequeued and immediately 
   1.193 + * transmitted in an internal ns3::TransmitCompleteEvent () that functions much 
   1.194 + * like a transmit complete interrupt service routine; or 3) from
   1.195 + * the random exponential backoff handler if a timeout is detected.
   1.196 + *
   1.197 + * To summarize, then, a packet is dequeued from the transmit queue, and a 
   1.198 + * Dequeue event is fired, immediately before it is transmitted down the channel.
   1.199 + * A packet is also dequeued from the transmit queue if it is unable to be 
   1.200 + * transmittted according to the backoff rules.  It is important to understand
   1.201 + * that this will appear in the ASCII traces as a Dequeued packet that will 
   1.202 + * appear as if it were transmitted.  The fact is that this packet is actually
   1.203 + * dropped by the net device.
   1.204 + *
   1.205 + * The reason for this behavior is due to the definition of the Drop event.  The
   1.206 + * m_traceDrop event is fired when a packet cannot be enqueued on the transmit
   1.207 + * queue becasue it is full.  This event only fires if the queue is full.
   1.208 + *
   1.209 + * A good usage example may be found in the ASCII trace functions of the 
   1.210 + * ns3::CsmaHelper.  In the ns3::CsmaHelper, you will find the following 
   1.211 + * methods:
   1.212 + *
   1.213 + * \code
   1.214 + *   void 
   1.215 + *   CsmaHelper::AsciiEnqueueEvent (
   1.216 + *     std::ostream *os, 
   1.217 + *     std::string path, 
   1.218 + *     Ptr<const Packet> packet)
   1.219 + * \endcode
   1.220 + *
   1.221 + * \code
   1.222 + *   void 
   1.223 + *   CsmaHelper::AsciiDequeueEvent (
   1.224 + *     std::ostream *os, 
   1.225 + *     std::string path, 
   1.226 + *     Ptr<const Packet> packet)
   1.227 + * \endcode
   1.228 + *
   1.229 + * \code
   1.230 + *   void 
   1.231 + *   CsmaHelper::AsciiDropEvent (
   1.232 + *     std::ostream *os, 
   1.233 + *     std::string path, 
   1.234 + *     Ptr<const Packet> packet)
   1.235 + * \endcode
   1.236 + *
   1.237 + * These events are hooked in the ns3::CsmaHelper::EnableAscii () method using
   1.238 + * a typical idiom:
   1.239 + *
   1.240 + * \code
   1.241 + *   std::ostringstream oss;
   1.242 + *   oss << "/NodeList/" << nodeid << "/DeviceList/" << deviceid << "/$ns3::CsmaNetDevice/TxQueue/Enqueue";
   1.243 + *   Config::Connect (oss.str (), MakeBoundCallback (&CsmaHelper::AsciiEnqueueEvent, &os));
   1.244 + * \endcode
   1.245 + *
   1.246 + * This particular snippet hooks the transmit queue (TxQueue) Enqueue operation
   1.247 + * trace source.  The source is identified by a string that may look something 
   1.248 + * like,
   1.249 + *
   1.250 + * \code
   1.251 + *   /NodeList/0/DeviceList/0/$ns3::CsmaNetDevice/TxQueue/Enqueue"
   1.252 + * \endcode
   1.253 + *
   1.254 + * This is the glue that connects the transmit queue enqueue trace source to 
   1.255 + * ns3::CsmaHelper AsciiEnqueueEvent.
   1.256 + *
   1.257 + * If you examine the handlers you will find that the AcsiiEnqueueEvent on the
   1.258 + * transmit queue ends up printing the well known '+' event int the ASCII trace
   1.259 + * files.   You will also find that AsciiDequeueEvent prints the '-' event and 
   1.260 + * AsciiDropEvent prints the 'd' event.
   1.261 + * 
   1.262 + * \subsection CsmaTracingModelUpperHooks Lower-Level Hooks
   1.263 + *
   1.264 + * Similar to the upper level trace hooks, there are trace hooks available at
   1.265 + * the lower levels of the net device.  In particular, these events fire from
   1.266 + * the ns3::CsmaNetDevice::Receive method which is the method called by the
   1.267 + * ns3::CsmaChannel to deliver a packet to the net device.
   1.268 +
   1.269 + * The trace source m_dropTrace is called to indicate a dropped packet if the
   1.270 + * receive side of the net device is not enabled (see 
   1.271 + * CsmaNetDevice::m_receiveEnable and the associated attribute "ReceiveEnable").
   1.272 + *
   1.273 + * The m_dropTrace is also used to indicate that a packet was discarded as 
   1.274 + * corrupt if the receive error model is used (see 
   1.275 + * ns3::CsmaNetDevice::m_receiveErrorModel and the associated attribute 
   1.276 + * "ReceiveErrorModel").
   1.277 + *
   1.278 + * The other low-level trace source fires on reception of an accepted packet
   1.279 + * (see ns3::CsmaNetDevice::m_rxTrace).  A packet is accepted if it is destined
   1.280 + * for the broadcast address, a multicast address, or to the MAC address 
   1.281 + * assigned to the net device.
   1.282 + *
   1.283 + * A good usage example may be found in the pcap trace functions of the 
   1.284 + * ns3::CsmaHelper.  In the ns3::CsmaHelper, you will find the following
   1.285 + * methods:
   1.286 + *
   1.287 + * \code
   1.288 + *   void 
   1.289 + *   CsmaHelper::EnqueueEvent (Ptr<PcapWriter> writer, Ptr<const Packet> packet)
   1.290 + * \endcode
   1.291 + *
   1.292 + * and
   1.293 + *
   1.294 + * \code
   1.295 + *   void 
   1.296 + *   CsmaHelper::RxEvent (Ptr<PcapWriter> writer, Ptr<const Packet> packet)
   1.297 + * \endcode
   1.298 + *
   1.299 + * These events are hooked in the ns3::CsmaHelper::EnablePcap () method using
   1.300 + * a typical idiom:
   1.301 + *
   1.302 + * \code
   1.303 + *   std::ostringstream oss;
   1.304 + *   oss << "/NodeList/" << nodeid << "/DeviceList/" << deviceid << "/$ns3::CsmaNetDevice/Rx";
   1.305 + *   Config::ConnectWithoutContext (oss.str (), MakeBoundCallback (&CsmaHelper::RxEvent, pcap));
   1.306 + * \endcode
   1.307 + *
   1.308 + * This particular snippet hooks the low level receive operation (m_rxTrace)
   1.309 + * trace source.  The source is identified by a string that may look something 
   1.310 + * like,
   1.311 + *
   1.312 + * \code
   1.313 + *   /NodeList/0/DeviceList/0/$ns3::CsmaNetDevice/Rx"
   1.314 + * \endcode
   1.315 + *
   1.316 + * This is the glue that connects the packet reception trace source to 
   1.317 + * ns3::CsmaHelper RxEvent.
   1.318 + *
   1.319 + * If you examine the handlers you will find that the RxEvent on the device 
   1.320 + * corresponds to the arrival of an accepted packet at the lowest levels of
   1.321 + * the device.  You will also find that the transmitted packet trace source
   1.322 + * acutally hooks to the transmit queue Enqueue event, which may be a quite
   1.323 + * unexpected behavior (a bug is currently filed -- #438).
   1.324 + *
   1.325 + * \section CsmaModelSummary CSMA Model Summary
   1.326   *
   1.327   * The ns3 CSMA model is a simplistic model of an Ethernet-like network.  It
   1.328   * supports a Carrier-Sense function and allows for Multiple Access to a 
   1.329 @@ -136,10 +415,12 @@
   1.330   *
   1.331   * Ns-3 Attributes provide a mechanism for setting various parameters in the 
   1.332   * device and channel such as addresses, encapsulation modes and error model
   1.333 - * selection.  Trace hooks are provided in the usual manner.
   1.334 + * selection.  Trace hooks are provided in the usual manner with a set of 
   1.335 + * upper level hooks corresponding to a transmit queue and used in ASCII 
   1.336 + * tracing; and also a set of lower level hooks used in pcap tracing.
   1.337   *
   1.338   * Although the ns-3 CsmaChannel and CsmaNetDevice does not model any kind of
   1.339   * network you could build or buy, it does provide us with some useful 
   1.340   * functionality.  You should, however, understand that it is explicitly not 
   1.341 - * Ethernet or IEEE 802.3 but an interesting subset.
   1.342 + * Ethernet or any flavor of IEEE 802.3 but an interesting subset.
   1.343   */