diff --git a/src/devices/csma/csma.h b/src/devices/csma/csma.h index 3aa899198..453ef4fde 100644 --- a/src/devices/csma/csma.h +++ b/src/devices/csma/csma.h @@ -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, + * const Address& dest, + * uint16_t protocolNumber); + * \endcode + * + * or + * + * \code + * bool + * CsmaNetDevice::SendFrom ( + * Ptr 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 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, Ptr 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 packet) + * \endcode + * + * \code + * void + * CsmaHelper::AsciiDequeueEvent ( + * std::ostream *os, + * std::string path, + * Ptr packet) + * \endcode + * + * \code + * void + * CsmaHelper::AsciiDropEvent ( + * std::ostream *os, + * std::string path, + * Ptr 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 writer, Ptr packet) + * \endcode + * + * and + * + * \code + * void + * CsmaHelper::RxEvent (Ptr writer, Ptr 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. */