F5/unison
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

some device trace source documentation

Browse Source
This commit is contained in:
Craig Dowell
2008-12-10 21:11:05 -08:00
parent 1bf5ac4f09
commit 026fb79dbf
6 changed files with 217 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
src/devices/csma/csma-net-device.cc
View File

@@ -83,10 +83,10 @@ CsmaNetDevice::GetTypeId (void)
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;

30
src/devices/csma/csma.h
View File

@@ -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.
*

58
src/devices/emu/emu.h
View File

@@ -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.
*/

5
src/devices/point-to-point/point-to-point-net-device.cc
View File

@@ -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))
;

98
src/devices/point-to-point/point-to-point.h
View File

@@ -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.
*/

59
src/devices/wifi/wifi.h
View File

@@ -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.
*/