--- a/src/devices/csma/csma-net-device.cc Wed Dec 10 13:28:51 2008 +0100
+++ b/src/devices/csma/csma-net-device.cc Wed Dec 10 21:11:05 2008 -0800
@@ -83,10 +83,10 @@
MakePointerAccessor (&CsmaNetDevice::m_queue),
MakePointerChecker<Queue> ())
.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;
--- a/src/devices/csma/csma.h Wed Dec 10 13:28:51 2008 +0100
+++ b/src/devices/csma/csma.h Wed Dec 10 21:11:05 2008 -0800
@@ -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.
*
--- a/src/devices/emu/emu.h Wed Dec 10 13:28:51 2008 +0100
+++ b/src/devices/emu/emu.h Wed Dec 10 21:11:05 2008 -0800
@@ -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.
*/
--- a/src/devices/point-to-point/point-to-point-net-device.cc Wed Dec 10 13:28:51 2008 +0100
+++ b/src/devices/point-to-point/point-to-point-net-device.cc Wed Dec 10 21:11:05 2008 -0800
@@ -73,11 +73,10 @@
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))
;
--- a/src/devices/point-to-point/point-to-point.h Wed Dec 10 13:28:51 2008 +0100
+++ b/src/devices/point-to-point/point-to-point.h Wed Dec 10 21:11:05 2008 -0800
@@ -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: 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.
*
- * - Delay: The speed of light transmission delay for the channel.
+ * 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.
*/
--- a/src/devices/wifi/wifi.h Wed Dec 10 13:28:51 2008 +0100
+++ b/src/devices/wifi/wifi.h Wed Dec 10 21:11:05 2008 -0800
@@ -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.
*/