3  * \defgroup CSMA CSMA Model

     3  * \defgroup CsmaModel CSMA Model

     4  *

     4  *

     5  * \section CSMA Model

     5  * \section CsmaModelOverview CSMA Model Overview

    21  * \subsection CSMA Channel Model

    21  * \section CsmaLayerModel CSMA Layer Model

    22  *

    23  * There are a number of conventions in use for describing layered 

    24  * communications architectures in the literature and in textbooks.  The most

    25  * common layering  model is the ISO seven layer reference model.  In this view

    26  * the ns3::CsmaNetDevice and ns3::CsmaChannel pair occupies the lowest two 

    27  * layers -- at the physical (layer one), and data link (layer two) positions.

    28  * Another important reference model is that specified by RFC 1122, 

    29  * "Requirements for Internet Hosts -- Communication Layers."  In this view the

    30  * ns3::CsmaNetDevice and ns3::CsmaChannel pair occupies the lowest layer -- 

    31  * the link layer.  There is also a seemingly endless litany of alternative 

    32  * descriptions found in textbooks and in the literature.  We adopt the naming

    33  * conventions used in the IEEE 802 standards which speak of LLC, MAC, MII

    34  * and PHY layering.  These acronyms are defined as:

    35  *

    36  * - LLC:  Logical Link Control;

    37  * - MAC:  Media Access Control;

    38  * - MII:  Media Independent Interface;

    39  * - PHY:  Physical Layer.

    40  * 

    41  * In this case the LLC and MAC are sublayers of the OSI data link layer and the 

    42  * MII and PHY are sublayers of the OSI physical layer.

    43  *

    44  * The "top" of the CSMA device defines the transition from the network layer

    45  * to the data link layer.  This transition is performed by higher layers by 

    46  * calling either

    47  *

    48  * \code

    49  *   bool 

    50  *   CsmaNetDevice::Send (

    51  *     Ptr<Packet> packet,

    52  *     const Address& dest, 

    53  *     uint16_t protocolNumber);

    54  * \endcode

    55  * 

    56  * or

    57  *

    58  * \code

    59  *  bool

    60  *  CsmaNetDevice::SendFrom (

    61  *    Ptr<Packet> packet, 

    62  *    const Address& src, 

    63  *   const Address& dest, 

    64  *   uint16_t protocolNumber);

    65  * \endcode

    66  *

    67  * In contrast to the IEEE 802.3 standards, there is no precisely specified

    68  * PHY in the CSMA model in the sense of wire types, signals or pinouts.  The

    69  * "bottom" interface of the ns3::CsmaNetDevice can be thought of as as a kind

    70  * of Media Independent Interface (MII) as seen in the "Fast Ethernet" 

    71  * (IEEE 802.3u) specifications.  This MII interface fits into a corresponding

    72  * media independent interface on the ns3::CsmaChannel.  You will not find the

    73  * equivalent of a 10BASE-T or a 1000BASE-LX PHY.

    74  *

    75  * The ns3::CsmaNetDevice calls the ns3::CsmaChannel through a media independent

    76  * interface.  There is a method defined to tell the channel when to start 

    77  * "wiggling the wires" using the method:

    78  *

    79  * \code

    80  *   bool

    81  *   CsmaChannel::TransmitStart (Ptr<Packet> p, uint32_t srcId);

    82  * \endcode

    83  *

    84  * and a method to tell the channel when the transmission process is done and

    85  * the channel should begin propagating the last bit across the "wire."

    86  *

    87  * \code

    88  *   bool

    89  *   CsmaChannel::TransmitEnd();

    90  * \endcode

    91  *

    92  * When the transmit end method is executed, the channel will model a single 

    93  * uniform signal propagation delay in the medium and then call the media

    94  * independent interface at the bottom of each of the devices attached to the

    95  * channel:

    96  *

    97  * \code

    98  *   void

    99  *   CsmaNetDevice::Receive (Ptr<Packet> packet, Ptr<CsmaNetDevice> senderDevice);

   100  * \endcode

   101  *

   102  * There is a "pin" in the media independent interface corresponding to "COL"

   103  * (collision).  The state of the channel may be sensed by calling,

   104  *

   105  * \code

   106  *   WireState

   107  *   CsmaChannel::GetState (void);

   108  * \endcode

   109  *

   110  * The ns3::CsmaNetDevice will look at this "pin" before starting a send and 

   111  * will perform appropriate backoff operations if required.

   112  *

   113  * Properly received packets are forwarded up to higher levels from the 

   114  * ns3::CsmaNetDevice via a callback mechanism.  The callback function is

   115  * initialized by the higher layer (when the net device is attached) using:

   116  *

   117  * \code

   118  *   void 

   119  *   CsmaNetDevice::SetReceiveCallback (NetDevice::ReceiveCallback cb);

   120  * \endcode

   121  *

   122  * and is invoked upon proper reception of a packet by the net device from the

   123  * channel in the following way:

   124  *

   125  * \code

   126  *   m_rxCallback (this, packet, protocol, header.GetSource ());

   127  * \endcode

   128  *

   129  * \section CsmaChannelModel CSMA Channel Model

    32  * speed at which CSMA channels and devices can operate.

   140  * speed at which CSMA channels and devices can operate; and no restriction

   141  * based on any kind of PHY characteristics.

    79  * \subsection CSMA Net Device Model

   188  * \section CsmaNetDeviceModel CSMA Net Device Model

   124  * \subsection CSMA Model Summary

   233  * \section CsmaTracingModel CSMA Tracing Model

   234  *

   235  * Like all ns-3 devices, the CSMA Model provides a number of trace sources.

   236  * These trace sources can be hooked using your own custom trace code, or you

   237  * can use our helper functions to arrange for tracing to be enabled on devices

   238  * you specify.

   239  *

   240  * \subsection CsmaTracingModelUpperHooks Upper-Level Hooks

   241  *

   242  * From the point of view of tracing in the net device, there are several 

   243  * interesting points to insert trace hooks.  A convention inherited from other

   244  * simulators is that packets destined for transmission onto attached networks

   245  * pass through a single"transmit queue" in the net device.  We provide trace 

   246  * hooks at this point in packet flow, which corresponds (abstractly) only to a 

   247  * transition from the network to data link layer.

   248  *

   249  * When a packet is sent to the CSMA net device for transmission it always 

   250  * passed through the transmit queue.  The transmit queue in the 

   251  * ns3::CsmaNetDevice inherits from ns3::Queue, and therefore inherits three 

   252  * TraceSources:

   253  *

   254  * - An Enqueue operation source (see ns3::Queue::m_traceEnqueue);

   255  * - A Dequeue operation source (see ns3::Queue::m_traceDequeue);

   256  * - A Drop operation source (see ns3::Queue::m_traceDrop).

   257  *

   258  * The upper-level trace hooks for the ns3::CsmaNetDevice are, in fact, exactly

   259  * these three trace sources on the single transmit queue of the device.  

   260  *

   261  * The m_traceEnqueue event is triggered when a packet is placed on the transmit

   262  * queue.  This happens at the time that ns3::CsmaNetDevice::Send () or 

   263  * ns3::CsmaNetDevice::SendFrom () is called.  

   264  *

   265  * The m_traceDequeue event is triggered when a packet is removed from the

   266  * transmit queue.  Dequeues from the transmit queue can happen in three 

   267  * situations:  1) If the underlying channel is idle when the 

   268  * ns3::CsmaNetDevice::Send or ns3::CsmaNetDevice::SendFrom is called, a packet

   269  * is dequeued from the transmit queue and immediately transmitted;  2) If the

   270  * underlying channel is idle, a packet may be dequeued and immediately 

   271  * transmitted in an internal ns3::TransmitCompleteEvent () that functions much 

   272  * like a transmit complete interrupt service routine; or 3) from

   273  * the random exponential backoff handler if a timeout is detected.

   274  *

   275  * To summarize, then, a packet is dequeued from the transmit queue, and a 

   276  * Dequeue event is fired, immediately before it is transmitted down the channel.

   277  * A packet is also dequeued from the transmit queue if it is unable to be 

   278  * transmittted according to the backoff rules.  It is important to understand

   279  * that this will appear in the ASCII traces as a Dequeued packet that will 

   280  * appear as if it were transmitted.  The fact is that this packet is actually

   281  * dropped by the net device.

   282  *

   283  * The reason for this behavior is due to the definition of the Drop event.  The

   284  * m_traceDrop event is fired when a packet cannot be enqueued on the transmit

   285  * queue becasue it is full.  This event only fires if the queue is full.

   286  *

   287  * A good usage example may be found in the ASCII trace functions of the 

   288  * ns3::CsmaHelper.  In the ns3::CsmaHelper, you will find the following 

   289  * methods:

   290  *

   291  * \code

   292  *   void 

   293  *   CsmaHelper::AsciiEnqueueEvent (

   294  *     std::ostream *os, 

   295  *     std::string path, 

   296  *     Ptr<const Packet> packet)

   297  * \endcode

   298  *

   299  * \code

   300  *   void 

   301  *   CsmaHelper::AsciiDequeueEvent (

   302  *     std::ostream *os, 

   303  *     std::string path, 

   304  *     Ptr<const Packet> packet)

   305  * \endcode

   306  *

   307  * \code

   308  *   void 

   309  *   CsmaHelper::AsciiDropEvent (

   310  *     std::ostream *os, 

   311  *     std::string path, 

   312  *     Ptr<const Packet> packet)

   313  * \endcode

   314  *

   315  * These events are hooked in the ns3::CsmaHelper::EnableAscii () method using

   316  * a typical idiom:

   317  *

   318  * \code

   319  *   std::ostringstream oss;

   320  *   oss << "/NodeList/" << nodeid << "/DeviceList/" << deviceid << "/$ns3::CsmaNetDevice/TxQueue/Enqueue";

   321  *   Config::Connect (oss.str (), MakeBoundCallback (&CsmaHelper::AsciiEnqueueEvent, &os));

   322  * \endcode

   323  *

   324  * This particular snippet hooks the transmit queue (TxQueue) Enqueue operation

   325  * trace source.  The source is identified by a string that may look something 

   326  * like,

   327  *

   328  * \code

   329  *   /NodeList/0/DeviceList/0/$ns3::CsmaNetDevice/TxQueue/Enqueue"

   330  * \endcode

   331  *

   332  * This is the glue that connects the transmit queue enqueue trace source to 

   333  * ns3::CsmaHelper AsciiEnqueueEvent.

   334  *

   335  * If you examine the handlers you will find that the AcsiiEnqueueEvent on the

   336  * transmit queue ends up printing the well known '+' event int the ASCII trace

   337  * files.   You will also find that AsciiDequeueEvent prints the '-' event and 

   338  * AsciiDropEvent prints the 'd' event.

   339  * 

   340  * \subsection CsmaTracingModelUpperHooks Lower-Level Hooks

   341  *

   342  * Similar to the upper level trace hooks, there are trace hooks available at

   343  * the lower levels of the net device.  In particular, these events fire from

   344  * the ns3::CsmaNetDevice::Receive method which is the method called by the

   345  * ns3::CsmaChannel to deliver a packet to the net device.

   346 

   347  * The trace source m_dropTrace is called to indicate a dropped packet if the

   348  * receive side of the net device is not enabled (see 

   349  * CsmaNetDevice::m_receiveEnable and the associated attribute "ReceiveEnable").

   350  *

   351  * The m_dropTrace is also used to indicate that a packet was discarded as 

   352  * corrupt if the receive error model is used (see 

   353  * ns3::CsmaNetDevice::m_receiveErrorModel and the associated attribute 

   354  * "ReceiveErrorModel").

   355  *

   356  * The other low-level trace source fires on reception of an accepted packet

   357  * (see ns3::CsmaNetDevice::m_rxTrace).  A packet is accepted if it is destined

   358  * for the broadcast address, a multicast address, or to the MAC address 

   359  * assigned to the net device.

   360  *

   361  * A good usage example may be found in the pcap trace functions of the 

   362  * ns3::CsmaHelper.  In the ns3::CsmaHelper, you will find the following

   363  * methods:

   364  *

   365  * \code

   366  *   void 

   367  *   CsmaHelper::EnqueueEvent (Ptr<PcapWriter> writer, Ptr<const Packet> packet)

   368  * \endcode

   369  *

   370  * and

   371  *

   372  * \code

   373  *   void 

   374  *   CsmaHelper::RxEvent (Ptr<PcapWriter> writer, Ptr<const Packet> packet)

   375  * \endcode

   376  *

   377  * These events are hooked in the ns3::CsmaHelper::EnablePcap () method using

   378  * a typical idiom:

   379  *

   380  * \code

   381  *   std::ostringstream oss;

   382  *   oss << "/NodeList/" << nodeid << "/DeviceList/" << deviceid << "/$ns3::CsmaNetDevice/Rx";

   383  *   Config::ConnectWithoutContext (oss.str (), MakeBoundCallback (&CsmaHelper::RxEvent, pcap));

   384  * \endcode

   385  *

   386  * This particular snippet hooks the low level receive operation (m_rxTrace)

   387  * trace source.  The source is identified by a string that may look something 

   388  * like,

   389  *

   390  * \code

   391  *   /NodeList/0/DeviceList/0/$ns3::CsmaNetDevice/Rx"

   392  * \endcode

   393  *

   394  * This is the glue that connects the packet reception trace source to 

   395  * ns3::CsmaHelper RxEvent.

   396  *

   397  * If you examine the handlers you will find that the RxEvent on the device 

   398  * corresponds to the arrival of an accepted packet at the lowest levels of

   399  * the device.  You will also find that the transmitted packet trace source

   400  * acutally hooks to the transmit queue Enqueue event, which may be a quite

   401  * unexpected behavior (a bug is currently filed -- #438).

   402  *

   403  * \section CsmaModelSummary CSMA Model Summary

   139  * selection.  Trace hooks are provided in the usual manner.

   418  * selection.  Trace hooks are provided in the usual manner with a set of 

   419  * upper level hooks corresponding to a transmit queue and used in ASCII 

   420  * tracing; and also a set of lower level hooks used in pcap tracing.

   144  * Ethernet or IEEE 802.3 but an interesting subset.

   425  * Ethernet or any flavor of IEEE 802.3 but an interesting subset.