From c915a078d875e5bc4beb9bc1d50dfcc45e7a976a Mon Sep 17 00:00:00 2001 From: Craig Dowell Date: Wed, 10 Dec 2008 16:47:44 -0800 Subject: [PATCH] cleanup some trace dox --- src/devices/csma/csma.h | 293 ++++++++++------------------------------ 1 file changed, 75 insertions(+), 218 deletions(-) diff --git a/src/devices/csma/csma.h b/src/devices/csma/csma.h index 453ef4fde..7ad787e35 100644 --- a/src/devices/csma/csma.h +++ b/src/devices/csma/csma.h @@ -23,11 +23,11 @@ * 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 + * the CsmaNetDevice and 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 -- + * CsmaNetDevice and 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 @@ -43,94 +43,45 @@ * * 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 + * calling either CsmaNetDevice::Send or CsmaNetDevice::SendFrom. * * 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 + * "bottom" interface of the 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 + * media independent interface on the 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 + * The CsmaNetDevice calls the CsmaChannel through a media independent * interface. There is a method defined to tell the channel when to start - * "wiggling the wires" using the method: + * "wiggling the wires" using the method CsmaChannel::TransmitStart, 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": + * CsmaChannel::TransmitEnd. * - * \code - * bool - * CsmaChannel::TransmitStart (Ptr p, uint32_t srcId); - * \endcode + * When the TransmitEnd method is executed, the channel will model a single + * uniform signal propagation delay in the medium and deliver copes of the packet + * to each of the devices attached to the packet via the + * CsmaNetDevice::Receive method. * - * 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. + * There is a "pin" in the device media independent interface corresponding to + * "COL" (collision). The state of the channel may be sensed by calling + * CsmaChannel::GetState. Each device 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 + * CsmaNetDevice via a callback mechanism. The callback function is + * initialized by the higher layer (when the net device is attached) using + * CsmaNetDevice::SetReceiveCallback and is invoked upon "proper" + * reception of a packet by the net device in order to forward the packet up + * the protocol stack. * * \section CsmaChannelModel CSMA Channel Model * - * The class ns3::CsmaChannel models the actual transmission medium. + * The class CsmaChannel models the actual transmission medium. * There is no fixed limit for the number of devices connected to the channel. - * The ns3::CsmaChannel models a data rate and a speed-of-light delay which can + * The CsmaChannel models a data rate and a speed-of-light delay which can * be accessed via the attributes "DataRate" and "Delay" respectively. * The data rate provided to the channel is used to set the data rates * used by the transmitter sections of the CSMA devices connected to the @@ -140,14 +91,14 @@ * 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. + * The CsmaChannel has three states, IDLE, TRANSMITTING and PROPAGATING. * These three states are "seen" instantaneously by all devices on the channel. * By this we mean that if one device begins or ends a simulated transmission, * all devices on the channel are immediately aware of the change in state. * There is no time during which one device may see an IDLE channel while * another device physically further away in the collision domain may have * begun transmitting with the associated signals not propagated. Thus there - * is no need for collision detection in the ns3::CsmaChannel model and it is + * is no need for collision detection in the CsmaChannel model and it is * not implemented in any way. * * We do, as the name indicates, have a Carrier Sense aspect to the model. @@ -165,9 +116,9 @@ * the wire to the "far end." * * The transition to the TRANSMITTING state is driven by a call to - * ns3::CsmaChannel::TransmitStart which is called by the net device that + * CsmaChannel::TransmitStart which is called by the net device that * transmits the packet. It is the responsibility of that device to end the - * transmission with a call to ns3::CsmaChannel::TransmitEnd at the appropriate + * transmission with a call to CsmaChannel::TransmitEnd at the appropriate * simulation time that reflects the time elapsed to put all of the packet bits * on the wire. When TransmitEnd is called, the channel schedules an event * corresponding to a single speed-of-light delay. This delay applies to all @@ -175,12 +126,12 @@ * in which the packet bits propagate to a central location and then back out * equal length cables to the other devices on the channel. * - * The ns3::CsmaChannel models a broadcast medium so the packet is delivered + * The CsmaChannel models a broadcast medium so the packet is delivered * to all of the devices on the channel (including the source) at the end of * the propagation time. It is the responsibility of the sending device to * determine whether or not it receives a packet broadcast over the channel. * - * The ns3::CsmaChannel provides following Attributes: + * The CsmaChannel provides following Attributes: * * - DataRate: The bitrate for packet transmission on connected devices; * - Delay: The speed of light transmission delay for the channel. @@ -188,9 +139,9 @@ * \section CsmaNetDeviceModel CSMA Net Device Model * * The CSMA network device appears somewhat like an Ethernet device. The - * ns3::CsmaNetDevice provides following Attributes: + * CsmaNetDevice provides following Attributes: * - * - Address: The ns3::Mac48Address of the device; + * - Address: The Mac48Address of the device; * - SendEnable: Enable packet transmission if true; * - ReceiveEnable: Enable packet reception if true; * - EncapsulationMode: Type of link layer encapsulation to use; @@ -200,19 +151,19 @@ * - Rx: A trace source for received packets; * - Drop: A trace source for dropped packets. * - * The ns3::CsmaNetDevice supports the assignment of a "receive error model." - * This is an ns3::ErrorModel object that is used to simulate data corruption + * The CsmaNetDevice supports the assignment of a "receive error model." + * This is an ErrorModel object that is used to simulate data corruption * on the link. * - * Packets sent over the ns3::CsmaNetDevice are always routed through the + * Packets sent over the CsmaNetDevice are always routed through the * transmit queue to provide a trace hook for packets sent out over the * network. This transmit queue can be set (via attribute) to model different * queueing strategies. * * Also configurable by attribute is the encapsulation method used by the - * device. Every packet gets an ns3::EthernetHeader that includes the + * device. Every packet gets an EthernetHeader that includes the * destination and source MAC addresses, and a length/type field. Every packet - * also gets an ns3::EthernetTrailer which includes the FCS. Data in the + * also gets an EthernetTrailer which includes the FCS. Data in the * packet may be encapsulated in different ways. By default, or by setting * the "EncapsulationMode" attribute to "Llc", the encapsulation is by * LLC SNAP. In this case, a SNAP header is added that contains the EtherType @@ -224,7 +175,7 @@ * mode is defined but not implemented -- use of the RAW mode results in an * assert firing. * - * The ns3::CsmaNetDevice implements a random exponential backoff algorithm + * The CsmaNetDevice implements a random exponential backoff algorithm * that is executed if the channel is determined to be busy (TRANSMITTING or * PROPAGATING) when the device wants to start propagating. This results in a * random delay of up to pow (2, retries) - 1 microseconds before a retry is @@ -237,169 +188,75 @@ * can use our helper functions to arrange for tracing to be enabled on devices * you specify. * - * \subsection CsmaTracingModelUpperHooks Upper-Level Hooks + * \subsection CsmaTracingModelUpperHooks Upper-Level (MAC) 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 + * 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. + * transition from the network to data link layer, and call them collectively + * the device MAC hooks. * * 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: + * CsmaNetDevice inherits from Queue, and therefore inherits three + * trace sources: * - * - 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). + * - An Enqueue operation source (see Queue::m_traceEnqueue); + * - A Dequeue operation source (see Queue::m_traceDequeue); + * - A Drop operation source (see 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 upper-level (MAC) trace hooks for the 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. + * queue. This happens at the time that CsmaNetDevice::Send or + * CsmaNetDevice::SendFrom is called by a higher layer to queue a packet for + * transmission. * * 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 + * CsmaNetDevice::Send or 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 + * transmitted in an internal 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. + * Case (3) implies that a packet is 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 as a Dequeued packet and it is easy to + * incorrectly assume that the packet was transmitted since it passed through + * the transmit queue. In fact, a packet is actually dropped by the net device + * in this case. The reason for this behavior is due to the definition of the + * Queue Drop event. The m_traceDrop event is, by defintion, fired when a + * packet cannot be enqueued on the transmit queue becasue it is full. This + * event only fires if the queue is full and we do not overload this event + * to indicate that the CsmaChannel is "full." * - * 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 + * \subsection CsmaTracingModelUpperHooks Lower-Level (PHY) 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 lower levels of the net device. We call these the PHY hooks. These + * events fire from the device methods that talk directly to the CsmaChannel. - * 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 trace source m_dropTrace is called to indicate a packet that is dropped + * by the device. This happens in two cases: First, 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 + * corrupt if a receive error model is used (see + * 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 + * (see 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