From 026fb79dbfd8efdc79307a09b3b6f75a50deee9d Mon Sep 17 00:00:00 2001 From: Craig Dowell Date: Wed, 10 Dec 2008 21:11:05 -0800 Subject: [PATCH] some device trace source documentation --- src/devices/csma/csma-net-device.cc | 4 +- src/devices/csma/csma.h | 30 +++--- src/devices/emu/emu.h | 58 ++++++++++- .../point-to-point-net-device.cc | 5 +- src/devices/point-to-point/point-to-point.h | 98 ++++++++++++++++--- src/devices/wifi/wifi.h | 59 ++++++++++- 6 files changed, 217 insertions(+), 37 deletions(-) diff --git a/src/devices/csma/csma-net-device.cc b/src/devices/csma/csma-net-device.cc index 11e9ee49d..ae8e518f1 100644 --- a/src/devices/csma/csma-net-device.cc +++ b/src/devices/csma/csma-net-device.cc @@ -83,10 +83,10 @@ CsmaNetDevice::GetTypeId (void) MakePointerAccessor (&CsmaNetDevice::m_queue), MakePointerChecker ()) .AddTraceSource ("Rx", - "The trace source to fire on reception of a MAC packet.", + "Trace source indicating reception of packet destined for broadcast, multicast or local address.", MakeTraceSourceAccessor (&CsmaNetDevice::m_rxTrace)) .AddTraceSource ("Drop", - "Trace source to fire on when a MAC packet is dropped.", + "Trace source indicating packet discarded due to receiver disabled or error model decision.", MakeTraceSourceAccessor (&CsmaNetDevice::m_dropTrace)) ; return tid; diff --git a/src/devices/csma/csma.h b/src/devices/csma/csma.h index 7ad787e35..3187d3441 100644 --- a/src/devices/csma/csma.h +++ b/src/devices/csma/csma.h @@ -23,7 +23,7 @@ * 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 CsmaNetDevice and CsmaChannel pair occupies the lowest two + * 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 @@ -43,7 +43,7 @@ * * 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 CsmaNetDevice::Send or CsmaNetDevice::SendFrom. + * calling either ns3::CsmaNetDevice::Send or ns3::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 @@ -55,25 +55,25 @@ * * 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 CsmaChannel::TransmitStart, and + * "wiggling the wires" using the method ns3::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. + * ns3::CsmaChannel::TransmitEnd. * * 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. + * ns3::CsmaNetDevice::Receive method. * * 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 + * ns3::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 * 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" + * ns3::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. * @@ -116,9 +116,9 @@ * the wire to the "far end." * * The transition to the TRANSMITTING state is driven by a call to - * CsmaChannel::TransmitStart which is called by the net device that + * ns3::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 CsmaChannel::TransmitEnd at the appropriate + * transmission with a call to ns3::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 @@ -199,7 +199,7 @@ * 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 + * passes through the transmit queue. The transmit queue in the * CsmaNetDevice inherits from Queue, and therefore inherits three * trace sources: * @@ -211,8 +211,8 @@ * 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 CsmaNetDevice::Send or - * CsmaNetDevice::SendFrom is called by a higher layer to queue a packet for + * queue. This happens at the time that ns3::CsmaNetDevice::Send or + * ns3::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 @@ -244,16 +244,16 @@ * 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 + * the net device is not enabled (see ns3::CsmaNetDevice::m_receiveEnable and the * associated attribute "ReceiveEnable"). * * The m_dropTrace is also used to indicate that a packet was discarded as * corrupt if a receive error model is used (see - * CsmaNetDevice::m_receiveErrorModel and the associated attribute + * ns3::CsmaNetDevice::m_receiveErrorModel and the associated attribute * "ReceiveErrorModel"). * * The other low-level trace source fires on reception of an accepted packet - * (see CsmaNetDevice::m_rxTrace). A packet is accepted if it is destined + * (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. * diff --git a/src/devices/emu/emu.h b/src/devices/emu/emu.h index ec25b241e..09d8e9dbb 100644 --- a/src/devices/emu/emu.h +++ b/src/devices/emu/emu.h @@ -1,8 +1,8 @@ /** * \ingroup devices - * \defgroup Emulated Emulated Net Device Model + * \defgroup EmuModel Emulated Net Device Model * - * \section Emulated Net Device Model + * \section EmuModelOverview Emulated Net Device Model Overview * * The emulated net device allows a simulation node to send and receive packets * a real network. @@ -57,4 +57,58 @@ * implication this has for static global routing. The global router module * attempts to walk the channels looking for adjacent networks. Since there * is no channel, the global router will be unable to do this. + * + * \section EmuTracingModel Emulated Net Device Tracing Model + * + * Like all ns-3 devices, the Emu 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 EmuTracingModelUpperHooks 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 + * hooks at this point in packet flow, which corresponds (abstractly) only to a + * transition from the network to data link layer, and call them collectively + * the device MAC hooks. + * + * When a packet is sent to the Emu net device for transmission it always + * passes through the transmit queue. The transmit queue in the EmuNetDevice + * inherits from Queue, and therefore inherits three trace sources: + * + * - 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 (MAC) trace hooks for the EmuNetDevice 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::EmuNetDevice::Send or + * ns3::EmuNetDevice::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 happen immediately after + * the packet was enqueued and only indicate that the packet is about to be + * sent to an underlying raw socket. The actual time at which the packet is + * sent out on the wire is not available. + * + * \subsection EmuTracingModelUpperHooks Lower-Level (PHY) Hooks + * + * Similar to the upper level trace hooks, there are trace hooks available at + * 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 underlying + * raw socket. + * + * The trace source m_dropTrace is not used in the Emu net device since that + * is really the business of the underlying "real" device driver. + * + * The other low-level trace source fires on reception of an accepted packet + * (see ns3::EmuNetDevice::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 Emu net device. */ diff --git a/src/devices/point-to-point/point-to-point-net-device.cc b/src/devices/point-to-point/point-to-point-net-device.cc index 60972851a..8a1b950a8 100644 --- a/src/devices/point-to-point/point-to-point-net-device.cc +++ b/src/devices/point-to-point/point-to-point-net-device.cc @@ -73,11 +73,10 @@ PointToPointNetDevice::GetTypeId (void) MakeTimeAccessor (&PointToPointNetDevice::m_tInterframeGap), MakeTimeChecker ()) .AddTraceSource ("Rx", - "Trace source to fire on reception of a MAC packet.", + "Trace source indicating reception of packet from the PointToPointChannel.", MakeTraceSourceAccessor (&PointToPointNetDevice::m_rxTrace)) .AddTraceSource ("Drop", - "Trace source to fire on when a MAC packet is dropped.", - + "Trace source indicating a packet was discarded due to a ReceiveErrorModel decision.", MakeTraceSourceAccessor (&PointToPointNetDevice::m_dropTrace)) ; diff --git a/src/devices/point-to-point/point-to-point.h b/src/devices/point-to-point/point-to-point.h index 3f9cf4178..8d8b1c3bd 100644 --- a/src/devices/point-to-point/point-to-point.h +++ b/src/devices/point-to-point/point-to-point.h @@ -1,8 +1,8 @@ /** * \ingroup devices - * \defgroup PointToPoint Point-to-Point Model + * \defgroup PointToPointModel Point-to-Point Model * - * \section Point-to-Point Model + * \section PointToPointPointOverview Point-to-Point Model Overview * * The ns-3 point-to-point model is of a very simple point to point data link * connecting exactly two ns3::PointToPointNetDevice devices over an @@ -21,17 +21,17 @@ * for IP Version 4 which is the sixteen-bit number 0x21 (see * http://www.iana.org/assignments/ppp-numbers). * - * The ns3::PointToPointNetDevice provides following Attributes: + * The PointToPointNetDevice provides following Attributes: * * - Address: The ns3::Mac48Address of the device (if desired); - * - DataRate: The data rate of the device; - * - TxQueue: The trasmit queue used by the device; - * - InterframeGap: The optional time to wait between "frames"; + * - DataRate: The data rate (ns3::DataRate) of the device; + * - TxQueue: The trasmit queue (ns3::Queue) used by the device; + * - InterframeGap: The optional ns3::Time to wait between "frames"; * - Rx: A trace source for received packets; * - Drop: A trace source for dropped packets. * - * The ns3::PointToPointNetDevice models a transmitter section that puts bits - * on a corresponding channel "wire." THe DataRate attribute specifies the + * The PointToPointNetDevice models a transmitter section that puts bits + * on a corresponding channel "wire." `The DataRate attribute specifies the * number of bits per second that the device will simulate sending over the * channel. In reality no bits are sent, but an event is scheduled for an * elapsed time consistent with the number of bits in each packet and the @@ -39,21 +39,95 @@ * models a receiver section that can receive any any data rate. Therefore * there is no need, nor way to set a receive data rate in this model. By * setting the DataRate on the transmitter of both devices connected to a - * given ns3::PointToPointChannel one can model a symmetric channel; or by + * given PointToPointChannel one can model a symmetric channel; or by * setting different DataRates one can model an asymmetric channel (e.g., * ADSL). * - * The ns3::PointToPointNetDevice supports the assignment of a "receive error + * The PointToPointNetDevice supports the assignment of a "receive error * model." This is an ns3::ErrorModel object that is used to simulate data * corruption on the link. * + * \section PointToPointChannelModel Point-to-Point Channel Model + * The point to point net devices are connected via an * ns3::PointToPointChannel. This channel models two wires transmitting bits * at the data rate specified by the source net device. There is no overhead * beyond the eight bits per byte of the packet sent. That is, we do not * model Flag Sequences, Frame Check Sequences nor do we "escape" any data. * - * The ns3::PointToPointNetChannel provides following Attributes: + * The PointToPointNetChannel provides following Attributes: * - * - Delay: The speed of light transmission delay for the channel. + * - Delay: An ns3::Time specifying the speed of light transmission delay for + * the channel. + * + * \section PointToPointTracingModel Point-to-Point Tracing Model + * + * Like all ns-3 devices, the Point-to-Point 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 PointToPointTracingModelUpperHooks 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 + * hooks at this point in packet flow, which corresponds (abstractly) only to a + * transition from the network to data link layer, and call them collectively + * the device MAC hooks. + * + * When a packet is sent to the Point-to-Point net device for transmission it + * always passes through the transmit queue. The transmit queue in the + * PoiintToPointNetDevice inherits from Queue, and therefore inherits three + * trace sources: + * + * - 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 (MAC) trace hooks for the PointToPointNetDevice 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::PointtoPointNetDevice::Send or + * ns3::PointToPointNetDevice::SendFrom is called by a higher layer to queue a + * packet for transmission. An Enqueue trace event firing should be interpreted + * as only indicating that a higher level protocol has sent a packet to the device. + * + * The m_traceDequeue event is triggered when a packet is removed from the + * transmit queue. Dequeues from the transmit queue can happen in two + * situations: 1) If the underlying channel is idle when + * PointToPointNetDevice::Send is called, a packet is dequeued from the transmit + * queue and immediately transmitted; 2) a packet may be dequeued and + * immediately transmitted in an internal TransmitCompleteEvent that functions + * much like a transmit complete interrupt service routine. An Dequeue trace + * event firing may be viewed as indicating that the PointToPointNetDevice has + * begun transmitting a packet. + * + * \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. We call these the PHY hooks. These + * events fire from the device methods that talk directly to the + * PointToPointChannel. + + * The trace source m_dropTrace is called to indicate a packet that is dropped + * by the device. This happens when a packet is discarded as corrupt due to a + * receive error model indication (see ns3::ErrorModel and the associated + * attribute "ReceiveErrorModel"). + * + * The other low-level trace source fires on reception of a packet (see + * ns3::PointToPointNetDevice::m_rxTrace) from the PointToPointChannel. + * + * \section PointToPointModelSummary Point-To-Point Model Summary + * + * The ns3 Point-to-Point model is a simplistic model of a point to point + * serial line link. + * + * Ns-3 Attributes provide a mechanism for setting various parameters in the + * device and channel such as data rates, speed-of-light delays and error model + * 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. */ diff --git a/src/devices/wifi/wifi.h b/src/devices/wifi/wifi.h index 1610dca90..3ced79bf5 100644 --- a/src/devices/wifi/wifi.h +++ b/src/devices/wifi/wifi.h @@ -2,7 +2,7 @@ * \ingroup devices * \defgroup Wifi Wifi Models * - * \section Wifi Models + * \section WifiModelOverview Wifi Models Overview * * The set of 802.11 models provided in ns-3 attempts to provide * an accurate MAC-level implementation of the 802.11 specification @@ -15,7 +15,6 @@ * - the so-called MAC high models: they implement the MAC-level * beacon generation, probing, and association state machines. * - a set of Rate control algorithms used by the MAC low models. - * * * We have today 3 MAC high models: * - a simple adhoc state machine which does not perform any @@ -49,7 +48,61 @@ * - ns3::OnoeMacStations * - ns3::AmrrMacStations * - * \section Wifi Tutorial + * \section WifiTracingModel Wifi Tracing Model * + * Like all ns-3 devices, the Wifi 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 WifiTracingModelUpperHooks Upper-Level (MAC) Hooks + * + * From the point of view of tracing in the net device, there are several + * interesting points to insert trace hooks. The first is at the interface + * between the device and higher layers. We provide trace hooks at this point + * in packet flow, which corresponds to a transition from the network to data + * link layer, and call them collectively the device MAC hooks. + * + * The first trace hook is called "Rx" and is fired using the + * ns3::WifiNetDevice::m_rxLogger trace hook. The perspective here is looking + * down into the WifiNetDevice so a receive indicates a packet being sent up + * from the channel to be forwarded up to higher layers. + * + * The second trace hook is called "Tx" and is fired using the + * ns3::WifiNetDevice::m_txLogger trace hook. This trace hook indicates a + * packet has been sent from higher layers down to the net device for + * transmission onto the network. + * + * \subsection WifiTracingModelLowerHooks Low-Level (PHY) Hooks + * + * Another interesting place to insert trace hooks is in the state machine + * that is driving the actual device transmission and reception logic. We + * provide the following hooks to instrument the lower levels of the device. + * + * First, we provide a trace hook to indicate state changes. This trace + * source is called "State" and is fired using the + * ns3::WifiPhyStateHelper::m_stateLogger trace source. + * + * We also provide a trace hook to indicate the successful reception of a + * packet from the channel. This trace source is called "RxOk" and is + * accessed using the ns3::WifiPhyStateHelper::m_rxOkTrace trace source. + * + * There also exists a trace hook to indicate an unsuccessful reception of a + * packet from the channel. This trace source is called "RxError" and is + * accessed using the ns3::WifiPhyStateHelper::m_rxErrorTrace trace source. + * + * There is a trace hook to indicate that transmission of a packet is + * starting onto the channel. This trace source is called "Tx" (don't + * confuse it with the higher layer "Tx" hook) and is + * fired using the ns3::WifiPhyStateHelper::m_txTrace trace source. + * + * \subsection WifiTracingModelRemoteHooks Remote Station Hooks + * + * We provide access to changes in the the per-remote-station RTS counter + * through the "Ssrc" trace source which is fired using the + * ns3::WifiRemoteStation::m_ssrc trace hook. + * + * Finally, we provide access to the per-remote-station SLRC couter that + * indications the number of retransmissions of data. Changes to this + * counter are traced using the ns3::WifiRemoteStation::m_slrc source. */