add device chapters to manual ns-3.3-RC4
authorTom Henderson <>
Mon, 15 Dec 2008 07:25:27 -0800
changeset 4024 dfd0bc16dc99
parent 4023 d320dea20aca
child 4025 e4b42930e37a
add device chapters to manual
--- a/doc/manual/Makefile	Sat Dec 13 23:44:20 2008 -0500
+++ b/doc/manual/Makefile	Mon Dec 15 07:25:27 2008 -0800
@@ -17,7 +17,8 @@
 	$(FIGURES)/buffer.eps \
 	$(FIGURES)/sockets-overview.eps \
 	$(FIGURES)/testbed.eps \
-	$(FIGURES)/emulated-channel.eps
+	$(FIGURES)/emulated-channel.eps \
+	$(FIGURES)/snir.eps
 IMAGES_PNG = ${IMAGES_EPS:.eps=.png}
 IMAGES_PDF = ${IMAGES_EPS:.eps=.pdf}
@@ -28,18 +29,21 @@
 	manual.texi \
 	attributes.texi \
 	callbacks.texi \
+	csma.texi \
 	emulation.texi \
 	node.texi \
 	objects.texi \
 	other.texi \
 	output.texi \
 	packets.texi \
+	point-to-point.texi \
 	random.texi \
 	realtime.texi \
 	routing.texi \
 	sockets.texi \
 	statistics.texi \
-	troubleshoot.texi
+	troubleshoot.texi \
+	wifi.texi
 %.eps : %.dia; $(DIA) -t eps $< -e $@
 %.png : %.dia; $(DIA) -t png $< -e $@
Binary file doc/manual/figures/snir.dia has changed
--- a/doc/manual/manual.texi	Sat Dec 13 23:44:20 2008 -0500
+++ b/doc/manual/manual.texi	Mon Dec 15 07:25:27 2008 -0800
@@ -89,6 +89,9 @@
 * Node and Internet Stack::
 * TCP::
 * Routing overview::
+* Wifi NetDevice::
+* CSMA NetDevice::
+* PointToPoint NetDevice::
 * Troubleshooting::
 @end menu
@@ -104,6 +107,9 @@
 @c @include output.texi
 @include tcp.texi
 @include routing.texi
+@include wifi.texi
+@include csma.texi
+@include point-to-point.texi
 @c @include other.texi
 @include troubleshoot.texi
--- a/doc/manual/point-to-point.texi	Sat Dec 13 23:44:20 2008 -0500
+++ b/doc/manual/point-to-point.texi	Mon Dec 15 07:25:27 2008 -0800
@@ -71,6 +71,7 @@
 @itemize @bullet
 @item Delay:  An ns3::Time specifying the speed of light transmission delay for
 the channel.
+@end itemize
 @node Using the PointToPointNetDevice
 @section Using the PointToPointNetDevice
@@ -132,14 +133,14 @@
 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 
+PointToPointNetDevice inherits from Queue, and therefore inherits three 
 trace sources:
-@itemize @bulleg
+@itemize @bullet
 @item An Enqueue operation source (see ns3::Queue::m_traceEnqueue);
 @item A Dequeue operation source (see ns3::Queue::m_traceDequeue);
 @item A Drop operation source (see ns3::Queue::m_traceDrop).
+@end itemize
 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.  
--- a/doc/manual/routing.texi	Sat Dec 13 23:44:20 2008 -0500
+++ b/doc/manual/routing.texi	Mon Dec 15 07:25:27 2008 -0800
@@ -313,7 +313,7 @@
 at time 5 seconds:
   Simulator::Schedule (Seconds (5),&GlobalRouteManager::RecomputeRoutingTables);
-@end verbatimT
+@end verbatim
 @node Global Routing Implementation
 @section Global Routing Implementation
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/wifi.texi	Mon Dec 15 07:25:27 2008 -0800
@@ -0,0 +1,359 @@
+@node Wifi NetDevice
+@chapter Wifi NetDevice
+ns-3 nodes can contain a collection of NetDevice objects, much like an actual 
+computer contains separate interface cards for Ethernet, Wifi, Bluetooth, etc.  This chapter describes the ns-3 WifiNetDevice and related models.  By
+adding WifiNetDevice objects to ns-3 nodes, one can create models of
+802.11-based infrastructure and ad hoc networks.
+* Overview of the model::
+* Using the WifiNetDevice::
+* The WifiChannel and WifiPhy models::
+* The MAC model::
+* Wifi Attributes::
+* Wifi Tracing::
+@end menu
+@node Overview of the model
+@section Overview of the model
+@strong{Note:}  This overview is taken largely from the Doxygen for the
+WifiNetDevice module.
+The set of 802.11 models provided in ns-3 attempts to provide
+an accurate MAC-level implementation of the 802.11 specification
+and to provide a not-so-slow PHY-level model of the 802.11a
+The current implementation provides roughly four levels of models:
+@itemize @bullet
+@item the @strong{PHY layer models}
+@item the so-called @strong{MAC low models}: they implement DCF
+@item the so-called @strong{MAC high models}: they implement the MAC-level
+beacon generation, probing, and association state machines, and
+@item a set of @strong{Rate control algorithms} used by the MAC low models
+@end itemize
+There are presently three @strong{MAC high models}:
+@item a simple adhoc state machine that does not perform any
+kind of beacon generation, probing, or association. This
+state machine is implemented by the @code{ns3::AdhocWifiNetDevice}
+and @code{ns3::MacHighAdhoc} classes.
+@item  an active probing and association state machine that handles
+automatic re-association whenever too many beacons are missed
+is implemented by the @code{ns3::NqstaWifiNetDevice} and
+@code{ns3::MacHighNqsta} classes.
+@item an access point that generates periodic beacons, and that
+accepts every attempt to associate. This AP state machine
+is implemented by the @code{ns3::NqapWifiNetDevice} and
+@code{ns3::MacHighNqap} classes.
+@end enumerate 
+The @strong{MAC low layer} is split into three components:
+@item @code{ns3::MacLow} which takes care of RTS/CTS/DATA/ACK transactions.
+@item @code{ns3::DcfManager} and @code{ns3::DcfState} which implements the DCF function.
+@item @code{ns3::DcaTxop} which handles the packet queue, packet fragmentation,
+and packet retransmissions if they are needed.
+@end enumerate
+There are also several @strong{rate control algorithms} that can be used by the Mac low layer:
+@itemize @bullet
+@item @code{ns3::ArfMacStations}
+@item @code{ns3::AArfMacStations}
+@item @code{ns3::IdealMacStations}
+@item @code{ns3::CrMacStations}
+@item @code{ns3::OnoeMacStations}
+@item @code{ns3::AmrrMacStations}
+@end itemize
+The PHY layer implements a single model in the 
+@code{ns3::WifiPhy class}: the
+physical layer model implemented there is described fully in a paper 
+entitled @uref{,,"Yet Another Network Simulator"}. 
+In ns-3, nodes can have multiple WifiNetDevices on separate channels,
+and the WifiNetDevice can coexist with other device types; this removes
+an architectural limitation found in ns-2.  Presently, however, there
+is no model for cross-channel interference or coupling.
+The source code for the Wifi NetDevice lives in the directory
+@node Using the WifiNetDevice
+@section Using the WifiNetDevice
+Users who use the low-level ns-3 API and who wish to add a WifiNetDevice
+to their node must create an instance of a WifiNetDevice, plus 
+a number of consitutent objects, and bind them together appropriately
+(the WifiNetDevice is very modular in this regard, for future
+extensibility).  At the low-level API, this can be done
+with about 20 lines of code (see @code{ns3::WifiHelper::Install} and
+@code{ns3::YansWifiPhyHelper::Create}).  They also must create,
+at some point, a WifiChannel, which also contains a number of
+constituent objects (see @code{ns3::YansWifiChannelHelper::Create}).
+However, a few helpers are available for users to add these devices
+and channels with only a few lines of code, if they are willing to
+use defaults, and the helpers provide additional API to allow the
+passing of attribute values to change default values.  The scripts
+in @code{src/examples} can be browsed to see how this is done.
+@subsection YansWifiChannelHelper
+The YansWifiChannelHelper has an unusual name.  Readers may wonder why
+it is named this way.  The reference is to the 
+@uref{,,yans simulator},
+from which this model is taken.  The helper can be used to create
+a WifiChannel with a default PropagationLoss and PropagationDelay model.  
+Specifically, the default is a channel model
+with a propagation delay equal to a constant, the speed of light,
+and a propagation loss based on a log distance model with a reference 
+loss of 46.6777 dB at reference distance of 1m.
+Users will typically type code such as:
+  YansWifiChannelHelper wifiChannelHelper = YansWifiChannelHelper::Default ();
+  Ptr<WifiChannel> wifiChannel = wifiChannelHelper.Create ();
+@end verbatim
+to get the defaults.  Note the distinction above in creating a helper
+object vs. an actual simulation object.
+In ns-3, helper objects (used at the helper API only) are created on the
+stack (they could also be created with operator new and later deleted).
+However, the actual ns-3 objects typically inherit from 
+@code{class ns3::Object} and are assigned to a smart pointer.  See the
+chapter on 
+@uref{Object model} for a discussion of the ns-3 object model, if you
+are not familiar with it.
+@emph{Todo:  Add notes about how to configure attributes with this helper API}
+@subsection YansWifiPhyHelper
+Physical devices (base class @code{ns3::Phy}) connect to 
+@code{ns3::Channel} models in ns-3.  We need to create Phy objects appropriate
+for the YansWifiChannel; here the @code{YansWifiPhyHelper} will
+do the work.
+The YansWifiPhyHelper class configures an object factory to create instances
+of a @code{YansWifiPhy} and
+adds some other objects to it, including possibly a supplemental 
+ErrorRateModel and a pointer to a MobilityModel.  The user code is
+  YansWifiPhyHelper wifiPhyHelper = YansWifiPhyHelper::Default ();
+  wifiPhyHelper.SetChannel (wifiChannel);
+@end verbatim
+Note that we haven't actually created any WifiPhy objects yet; we've 
+just prepared the YansWifiPhyHelper by telling it which channel it is 
+connected to.  The phy objects are created in the next step.
+@subsection WifiHelper
+We're now ready to create WifiNetDevices.  First, let's create
+a WifiHelper with default settings:
+  WifiHelper wifiHelper = WifiHelper::Default ();
+@end verbatim
+What does this do?  It sets the RemoteStationManager to
+@code{ns3::ArfWifiManager} and the upper MAC to @code{ns3::AdhocWifiMac}
+by default (which can be overridden by other arguments).
+Now, let's use the wifiPhyHelper created above to install WifiNetDevices
+on a set of nodes in a NodeContainer "c":
+  NetDeviceContainer wifiContainer = WifiHelper::Install (wifiPhyHelper, c);
+@end verbatim
+This creates the WifiNetDevice which includes also a WifiRemoteStationManager,
+a WifiMac, and a WifiPhy (connected to the matching WifiChannel).
+There are many ns-3 @uref{Attributes} that can be set on the above
+helpers to deviate from the default behavior; the example scripts
+show how to do some of this reconfiguration.
+@subsection AdHoc WifiNetDevice configuration 
+This is a typical example of how a user might configure an adhoc network.
+@emph{Write me}
+@subsection Infrastructure (Access Point and clients) WifiNetDevice configuration 
+This is a typical example of how a user might configure an access point and a set of clients. 
+@emph{Write me}
+@node The WifiChannel and WifiPhy models
+@section The WifiChannel and WifiPhy models
+The WifiChannel subclass can be used to connect together a set of
+@code{ns3::WifiNetDevice} network interfaces. The class @code{ns3::WifiPhy}
+is the
+object within the WifiNetDevice that receives bits from the channel.
+A WifiChannel contains
+a @code{ns3::PropagationLossModel} and a @code{ns3::PropagationDelayModel} 
+which can
+be overridden by the WifiChannel::SetPropagationLossModel
+and the WifiChannel::SetPropagationDelayModel methods. By default,
+no propagation models are set.
+The WifiPhy models an 802.11a channel, in terms of frequency, modulation,
+and bit rates, and interacts with the PropagationLossModel and 
+PropagationDelayModel found in the channel.  
+This section summarizes
+the description of the BER calculations found in the yans paper
+taking into account the
+Forward Error Correction present in 802.11a and describes
+the algorithm we implemented to decide whether or not a 
+packet can be successfully received.  See @uref{,,"Yet Another Network Simulator"} for more details.
+The PHY layer can be in one of three states:
+@item TX: the PHY is currently transmitting a signal
+on behalf of its associated MAC
+@item RX: the PHY is synchronized on a signal and
+is waiting until it has received its last bit to forward
+it to the MAC.
+@item IDLE: the PHY is not in the TX or RX states.
+@end enumerate
+When the first bit of a new packet is received while
+the PHY is not IDLE (that is, it is already synchronized
+on the reception of another earlier packet or it is
+sending data itself), the received packet is dropped. 
+Otherwise, if the PHY is IDLE, we calculate the received
+energy of the first bit of this new signal and compare it 
+against our Energy Detection threshold (as defined 
+by the Clear Channel Assessment function mode 1). 
+If the energy of the packet k is higher, then the PHY moves 
+to RX state and schedules an event when the last bit of 
+the packet is expected to be received. Otherwise, the 
+PHY stays in IDLE state and drops the packet.
+The energy of the received signal is assumed
+to be zero outside of the reception interval of packet k and
+is calculated from the transmission power with a path-loss 
+propagation model in the reception interval.
+where the path loss exponent, @math{n}, is chosen equal to 3, 
+the reference distance, @math{d_0} is choosen equal to 
+@math{1.0m} and 
+the reference energy is based based on a Friis
+propagation model.
+When the last bit of the packet upon which the PHY is 
+synchronized is received, we need to calculate the 
+probability that the packet is received with any error
+to decide whether or not 
+the packet on which we were synchronized could
+be successfully received or not: a random number 
+is drawn from a uniform distribution and is compared against
+the probability of error.
+To evaluate the probability of error, we start from the piecewise linear 
+functions shown in Figure @ref{fig:snir} and calculate the 
+SNIR function. 
+@float Figure,fig:snir
+@caption{SNIR function over time}
+@end float 
+From the SNIR function we can derive bit error rates for BPSK and QAM
+modulations.  Then, for each interval l where BER is
+constant, we define the upper bound of a probability that an error is
+present in the chunk of bits located in the interval l for packet k.
+If we assume an AWGN channel, 
+binary convolutional coding (which is the case in 802.11a)
+and hard-decision Viterbi decoding, the error rate is thus derived,
+and the packet error probability for packet k can be computed.. 
+@subsection WifiChannel configuration
+WifiChannel models include both a PropagationDelayModel and a 
+PropagationLossModel.  The following PropagationDelayModels are available:
+@itemize @bullet
+@item ConstantSpeedPropagationDelayModel
+@item RandomPropagationDelayModel
+@end itemize
+The following PropagationLossModels are available:
+@itemize @bullet
+@item RandomPropagationLossModel
+@item FriisPropagationLossModel
+@item LogDistancePropagationLossModel
+@item JakesPropagationLossModel
+@item CompositePropagationLossModel
+@end itemize
+@node The MAC model
+@section The MAC model
+The 802.11 Distributed Coordination Function is used to
+calculate when to grant access to the transmission medium. While
+implementing the DCF would have been particularly easy if we
+had used a recurring timer that expired every slot, we
+chose to use the method described in @emph{(missing reference here from
+Yans paper)}
+where the backoff timer duration is lazily calculated whenever
+needed since it is claimed to have much better performance than
+the simpler recurring timer solution.
+The higher-level MAC functions are implemented in a set of other
+C++ classes and deal with:
+@itemize @bullet
+@item packet fragmentation and defragmentation,
+@item use of the rts/cts protocol,
+@item rate control algorithm,
+@item connection and disconnection to and from an Access Point,
+@item the MAC transmission queue,
+@item beacon generation,
+@item etc.
+@end itemize
+@node Wifi Attributes
+@section Wifi Attributes
+The WifiNetDevice makes heavy use of the ns-3 @ref{Attributes} subsystem for
+configuration and default value management.  Presently, approximately
+100 values are stored in this system.
+For instance, class @code{ns-3::WifiMac} exports these attributes:
+@itemize @bullet
+@item CtsTimeout: When this timeout expires, the RTS/CTS handshake has failed.
+@item AckTimeout: When this timeout expires, the DATA/ACK handshake has failed.
+@item Sifs: The value of the SIFS constant.
+@item EifsNoDifs: The value of EIFS-DIFS
+@item Slot: The duration of a Slot.
+@item Pifs: The value of the PIFS constant.
+@item MaxPropagationDelay: The maximum propagation delay. Unused for now.
+@item MaxMsduSize: The maximum size of an MSDU accepted by the MAC layer.This value conforms to the specification.
+@item Ssid: The ssid we want to belong to.
+@end itemize
+@node Wifi Tracing
+@section Wifi Tracing
+@emph{This needs revised/updating based on the latest Doxygen}
+ns-3 has a sophisticated tracing infrastructure that allows users to hook
+into existing trace sources, or to define and export new ones.  
+Wifi-related trace sources that are available by default include:
+@itemize @bullet
+@item @code{ns3::WifiNetDevice}
+@itemize @bullet
+@item Rx: Received payload from the MAC layer.
+@item Tx: Send payload to the MAC layer.
+@end itemize
+@item @code{ns3::WifiPhy}
+@itemize @bullet
+@item State: The WifiPhy state
+@item RxOk: A packet has been received successfully.
+@item RxError: A packet has been received unsuccessfully.
+@item Tx: Packet transmission is starting.
+@end itemize
+@end itemize
+Briefly, this means, for example, that a user can hook a processing 
+function to the "State" tracing hook above and be notified whenever the
+WifiPhy model changes state.