add device chapters to manual ns-3.3-RC4
authorTom Henderson <tomh@tomh.org>
Mon, 15 Dec 2008 07:25:27 -0800
changeset 4024dfd0bc16dc99
parent 4023 d320dea20aca
child 4025 e4b42930e37a
add device chapters to manual
doc/manual/Makefile
doc/manual/figures/snir.dia
doc/manual/manual.texi
doc/manual/point-to-point.texi
doc/manual/routing.texi
doc/manual/wifi.texi
     1.1 --- a/doc/manual/Makefile	Sat Dec 13 23:44:20 2008 -0500
     1.2 +++ b/doc/manual/Makefile	Mon Dec 15 07:25:27 2008 -0800
     1.3 @@ -17,7 +17,8 @@
     1.4  	$(FIGURES)/buffer.eps \
     1.5  	$(FIGURES)/sockets-overview.eps \
     1.6  	$(FIGURES)/testbed.eps \
     1.7 -	$(FIGURES)/emulated-channel.eps
     1.8 +	$(FIGURES)/emulated-channel.eps \
     1.9 +	$(FIGURES)/snir.eps
    1.10  
    1.11  IMAGES_PNG = ${IMAGES_EPS:.eps=.png}
    1.12  IMAGES_PDF = ${IMAGES_EPS:.eps=.pdf}
    1.13 @@ -28,18 +29,21 @@
    1.14  	manual.texi \
    1.15  	attributes.texi \
    1.16  	callbacks.texi \
    1.17 +	csma.texi \
    1.18  	emulation.texi \
    1.19  	node.texi \
    1.20  	objects.texi \
    1.21  	other.texi \
    1.22  	output.texi \
    1.23  	packets.texi \
    1.24 +	point-to-point.texi \
    1.25  	random.texi \
    1.26  	realtime.texi \
    1.27  	routing.texi \
    1.28  	sockets.texi \
    1.29  	statistics.texi \
    1.30 -	troubleshoot.texi
    1.31 +	troubleshoot.texi \
    1.32 +	wifi.texi
    1.33  
    1.34  %.eps : %.dia; $(DIA) -t eps $< -e $@
    1.35  %.png : %.dia; $(DIA) -t png $< -e $@
     2.1 Binary file doc/manual/figures/snir.dia has changed
     3.1 --- a/doc/manual/manual.texi	Sat Dec 13 23:44:20 2008 -0500
     3.2 +++ b/doc/manual/manual.texi	Mon Dec 15 07:25:27 2008 -0800
     3.3 @@ -89,6 +89,9 @@
     3.4  * Node and Internet Stack::
     3.5  * TCP::
     3.6  * Routing overview::
     3.7 +* Wifi NetDevice::
     3.8 +* CSMA NetDevice::
     3.9 +* PointToPoint NetDevice::
    3.10  * Troubleshooting::
    3.11  @end menu
    3.12  
    3.13 @@ -104,6 +107,9 @@
    3.14  @c @include output.texi
    3.15  @include tcp.texi
    3.16  @include routing.texi
    3.17 +@include wifi.texi
    3.18 +@include csma.texi
    3.19 +@include point-to-point.texi
    3.20  @c @include other.texi
    3.21  @include troubleshoot.texi
    3.22  
     4.1 --- a/doc/manual/point-to-point.texi	Sat Dec 13 23:44:20 2008 -0500
     4.2 +++ b/doc/manual/point-to-point.texi	Mon Dec 15 07:25:27 2008 -0800
     4.3 @@ -71,6 +71,7 @@
     4.4  @itemize @bullet
     4.5  @item Delay:  An ns3::Time specifying the speed of light transmission delay for
     4.6  the channel.
     4.7 +@end itemize
     4.8  
     4.9  @node Using the PointToPointNetDevice
    4.10  @section Using the PointToPointNetDevice
    4.11 @@ -132,14 +133,14 @@
    4.12  
    4.13  When a packet is sent to the Point-to-Point net device for transmission it 
    4.14  always passes through the transmit queue.  The transmit queue in the 
    4.15 -PoiintToPointNetDevice inherits from Queue, and therefore inherits three 
    4.16 +PointToPointNetDevice inherits from Queue, and therefore inherits three 
    4.17  trace sources:
    4.18  
    4.19 -@itemize @bulleg
    4.20 +@itemize @bullet
    4.21  @item An Enqueue operation source (see ns3::Queue::m_traceEnqueue);
    4.22  @item A Dequeue operation source (see ns3::Queue::m_traceDequeue);
    4.23  @item A Drop operation source (see ns3::Queue::m_traceDrop).
    4.24 -@item
    4.25 +@end itemize
    4.26  
    4.27  The upper-level (MAC) trace hooks for the PointToPointNetDevice are, in fact, 
    4.28  exactly these three trace sources on the single transmit queue of the device.  
     5.1 --- a/doc/manual/routing.texi	Sat Dec 13 23:44:20 2008 -0500
     5.2 +++ b/doc/manual/routing.texi	Mon Dec 15 07:25:27 2008 -0800
     5.3 @@ -313,7 +313,7 @@
     5.4  at time 5 seconds:
     5.5  @verbatim
     5.6    Simulator::Schedule (Seconds (5),&GlobalRouteManager::RecomputeRoutingTables);
     5.7 -@end verbatimT
     5.8 +@end verbatim
     5.9  
    5.10  @node Global Routing Implementation
    5.11  @section Global Routing Implementation
     6.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.2 +++ b/doc/manual/wifi.texi	Mon Dec 15 07:25:27 2008 -0800
     6.3 @@ -0,0 +1,359 @@
     6.4 +@node Wifi NetDevice
     6.5 +@chapter Wifi NetDevice
     6.6 +@anchor{chap:wifi}
     6.7 +
     6.8 +ns-3 nodes can contain a collection of NetDevice objects, much like an actual 
     6.9 +computer contains separate interface cards for Ethernet, Wifi, Bluetooth, etc.  This chapter describes the ns-3 WifiNetDevice and related models.  By
    6.10 +adding WifiNetDevice objects to ns-3 nodes, one can create models of
    6.11 +802.11-based infrastructure and ad hoc networks.
    6.12 +
    6.13 +@menu
    6.14 +* Overview of the model::
    6.15 +* Using the WifiNetDevice::
    6.16 +* The WifiChannel and WifiPhy models::
    6.17 +* The MAC model::
    6.18 +* Wifi Attributes::
    6.19 +* Wifi Tracing::
    6.20 +@end menu
    6.21 +
    6.22 +@node Overview of the model
    6.23 +@section Overview of the model
    6.24 +
    6.25 +@strong{Note:}  This overview is taken largely from the Doxygen for the
    6.26 +WifiNetDevice module.
    6.27 +
    6.28 +The set of 802.11 models provided in ns-3 attempts to provide
    6.29 +an accurate MAC-level implementation of the 802.11 specification
    6.30 +and to provide a not-so-slow PHY-level model of the 802.11a
    6.31 +specification.
    6.32 +
    6.33 +The current implementation provides roughly four levels of models:
    6.34 +@itemize @bullet
    6.35 +@item the @strong{PHY layer models}
    6.36 +@item the so-called @strong{MAC low models}: they implement DCF
    6.37 +@item the so-called @strong{MAC high models}: they implement the MAC-level
    6.38 +beacon generation, probing, and association state machines, and
    6.39 +@item a set of @strong{Rate control algorithms} used by the MAC low models
    6.40 +@end itemize
    6.41 +
    6.42 +There are presently three @strong{MAC high models}:
    6.43 +@enumerate
    6.44 +@item a simple adhoc state machine that does not perform any
    6.45 +kind of beacon generation, probing, or association. This
    6.46 +state machine is implemented by the @code{ns3::AdhocWifiNetDevice}
    6.47 +and @code{ns3::MacHighAdhoc} classes.
    6.48 +@item  an active probing and association state machine that handles
    6.49 +automatic re-association whenever too many beacons are missed
    6.50 +is implemented by the @code{ns3::NqstaWifiNetDevice} and
    6.51 +@code{ns3::MacHighNqsta} classes.
    6.52 +@item an access point that generates periodic beacons, and that
    6.53 +accepts every attempt to associate. This AP state machine
    6.54 +is implemented by the @code{ns3::NqapWifiNetDevice} and
    6.55 +@code{ns3::MacHighNqap} classes.
    6.56 +@end enumerate 
    6.57 +
    6.58 +The @strong{MAC low layer} is split into three components:
    6.59 +@enumerate
    6.60 +@item @code{ns3::MacLow} which takes care of RTS/CTS/DATA/ACK transactions.
    6.61 +@item @code{ns3::DcfManager} and @code{ns3::DcfState} which implements the DCF function.
    6.62 +@item @code{ns3::DcaTxop} which handles the packet queue, packet fragmentation,
    6.63 +and packet retransmissions if they are needed.
    6.64 +@end enumerate
    6.65 +
    6.66 +There are also several @strong{rate control algorithms} that can be used by the Mac low layer:
    6.67 +@itemize @bullet
    6.68 +@item @code{ns3::ArfMacStations}
    6.69 +@item @code{ns3::AArfMacStations}
    6.70 +@item @code{ns3::IdealMacStations}
    6.71 +@item @code{ns3::CrMacStations}
    6.72 +@item @code{ns3::OnoeMacStations}
    6.73 +@item @code{ns3::AmrrMacStations}
    6.74 +@end itemize
    6.75 +
    6.76 +The PHY layer implements a single model in the 
    6.77 +@code{ns3::WifiPhy class}: the
    6.78 +physical layer model implemented there is described fully in a paper 
    6.79 +entitled @uref{http://cutebugs.net/files/wns2-yans.pdf,,"Yet Another Network Simulator"}. 
    6.80 +
    6.81 +In ns-3, nodes can have multiple WifiNetDevices on separate channels,
    6.82 +and the WifiNetDevice can coexist with other device types; this removes
    6.83 +an architectural limitation found in ns-2.  Presently, however, there
    6.84 +is no model for cross-channel interference or coupling.
    6.85 +
    6.86 +The source code for the Wifi NetDevice lives in the directory
    6.87 +@code{src/devices/wifi}.
    6.88 +
    6.89 +@node Using the WifiNetDevice
    6.90 +@section Using the WifiNetDevice
    6.91 +
    6.92 +Users who use the low-level ns-3 API and who wish to add a WifiNetDevice
    6.93 +to their node must create an instance of a WifiNetDevice, plus 
    6.94 +a number of consitutent objects, and bind them together appropriately
    6.95 +(the WifiNetDevice is very modular in this regard, for future
    6.96 +extensibility).  At the low-level API, this can be done
    6.97 +with about 20 lines of code (see @code{ns3::WifiHelper::Install} and
    6.98 +@code{ns3::YansWifiPhyHelper::Create}).  They also must create,
    6.99 +at some point, a WifiChannel, which also contains a number of
   6.100 +constituent objects (see @code{ns3::YansWifiChannelHelper::Create}).
   6.101 +
   6.102 +However, a few helpers are available for users to add these devices
   6.103 +and channels with only a few lines of code, if they are willing to
   6.104 +use defaults, and the helpers provide additional API to allow the
   6.105 +passing of attribute values to change default values.  The scripts
   6.106 +in @code{src/examples} can be browsed to see how this is done.
   6.107 +
   6.108 +@subsection YansWifiChannelHelper
   6.109 +
   6.110 +The YansWifiChannelHelper has an unusual name.  Readers may wonder why
   6.111 +it is named this way.  The reference is to the 
   6.112 +@uref{http://cutebugs.net/files/wns2-yans.pdf,,yans simulator},
   6.113 +from which this model is taken.  The helper can be used to create
   6.114 +a WifiChannel with a default PropagationLoss and PropagationDelay model.  
   6.115 +Specifically, the default is a channel model
   6.116 +with a propagation delay equal to a constant, the speed of light,
   6.117 +and a propagation loss based on a log distance model with a reference 
   6.118 +loss of 46.6777 dB at reference distance of 1m.
   6.119 +
   6.120 +Users will typically type code such as:
   6.121 +@verbatim
   6.122 +  YansWifiChannelHelper wifiChannelHelper = YansWifiChannelHelper::Default ();
   6.123 +  Ptr<WifiChannel> wifiChannel = wifiChannelHelper.Create ();
   6.124 +@end verbatim
   6.125 +to get the defaults.  Note the distinction above in creating a helper
   6.126 +object vs. an actual simulation object.
   6.127 +In ns-3, helper objects (used at the helper API only) are created on the
   6.128 +stack (they could also be created with operator new and later deleted).
   6.129 +However, the actual ns-3 objects typically inherit from 
   6.130 +@code{class ns3::Object} and are assigned to a smart pointer.  See the
   6.131 +chapter on 
   6.132 +@uref{Object model} for a discussion of the ns-3 object model, if you
   6.133 +are not familiar with it.
   6.134 +
   6.135 +@emph{Todo:  Add notes about how to configure attributes with this helper API}
   6.136 +
   6.137 +@subsection YansWifiPhyHelper
   6.138 +
   6.139 +Physical devices (base class @code{ns3::Phy}) connect to 
   6.140 +@code{ns3::Channel} models in ns-3.  We need to create Phy objects appropriate
   6.141 +for the YansWifiChannel; here the @code{YansWifiPhyHelper} will
   6.142 +do the work.
   6.143 +
   6.144 +The YansWifiPhyHelper class configures an object factory to create instances
   6.145 +of a @code{YansWifiPhy} and
   6.146 +adds some other objects to it, including possibly a supplemental 
   6.147 +ErrorRateModel and a pointer to a MobilityModel.  The user code is
   6.148 +typically:
   6.149 +@verbatim
   6.150 +  YansWifiPhyHelper wifiPhyHelper = YansWifiPhyHelper::Default ();
   6.151 +  wifiPhyHelper.SetChannel (wifiChannel);
   6.152 +@end verbatim
   6.153 +Note that we haven't actually created any WifiPhy objects yet; we've 
   6.154 +just prepared the YansWifiPhyHelper by telling it which channel it is 
   6.155 +connected to.  The phy objects are created in the next step.
   6.156 +
   6.157 +@subsection WifiHelper
   6.158 +
   6.159 +We're now ready to create WifiNetDevices.  First, let's create
   6.160 +a WifiHelper with default settings:
   6.161 +@verbatim
   6.162 +  WifiHelper wifiHelper = WifiHelper::Default ();
   6.163 +@end verbatim
   6.164 +What does this do?  It sets the RemoteStationManager to
   6.165 +@code{ns3::ArfWifiManager} and the upper MAC to @code{ns3::AdhocWifiMac}
   6.166 +by default (which can be overridden by other arguments).
   6.167 +Now, let's use the wifiPhyHelper created above to install WifiNetDevices
   6.168 +on a set of nodes in a NodeContainer "c":
   6.169 +@verbatim
   6.170 +  NetDeviceContainer wifiContainer = WifiHelper::Install (wifiPhyHelper, c);
   6.171 +@end verbatim
   6.172 +This creates the WifiNetDevice which includes also a WifiRemoteStationManager,
   6.173 +a WifiMac, and a WifiPhy (connected to the matching WifiChannel).
   6.174 +
   6.175 +There are many ns-3 @uref{Attributes} that can be set on the above
   6.176 +helpers to deviate from the default behavior; the example scripts
   6.177 +show how to do some of this reconfiguration.
   6.178 +
   6.179 +@subsection AdHoc WifiNetDevice configuration 
   6.180 +This is a typical example of how a user might configure an adhoc network.
   6.181 +
   6.182 +@emph{Write me}
   6.183 +
   6.184 +@subsection Infrastructure (Access Point and clients) WifiNetDevice configuration 
   6.185 +This is a typical example of how a user might configure an access point and a set of clients. 
   6.186 +
   6.187 +@emph{Write me}
   6.188 +
   6.189 +@node The WifiChannel and WifiPhy models
   6.190 +@section The WifiChannel and WifiPhy models
   6.191 +
   6.192 +The WifiChannel subclass can be used to connect together a set of
   6.193 +@code{ns3::WifiNetDevice} network interfaces. The class @code{ns3::WifiPhy}
   6.194 +is the
   6.195 +object within the WifiNetDevice that receives bits from the channel.
   6.196 +A WifiChannel contains
   6.197 +a @code{ns3::PropagationLossModel} and a @code{ns3::PropagationDelayModel} 
   6.198 +which can
   6.199 +be overridden by the WifiChannel::SetPropagationLossModel
   6.200 +and the WifiChannel::SetPropagationDelayModel methods. By default,
   6.201 +no propagation models are set.
   6.202 +
   6.203 +The WifiPhy models an 802.11a channel, in terms of frequency, modulation,
   6.204 +and bit rates, and interacts with the PropagationLossModel and 
   6.205 +PropagationDelayModel found in the channel.  
   6.206 +
   6.207 +This section summarizes
   6.208 +the description of the BER calculations found in the yans paper
   6.209 +taking into account the
   6.210 +Forward Error Correction present in 802.11a and describes
   6.211 +the algorithm we implemented to decide whether or not a 
   6.212 +packet can be successfully received.  See @uref{http://cutebugs.net/files/wns2-yans.pdf,,"Yet Another Network Simulator"} for more details.
   6.213 +
   6.214 +The PHY layer can be in one of three states:
   6.215 +@enumerate
   6.216 +@item TX: the PHY is currently transmitting a signal
   6.217 +on behalf of its associated MAC
   6.218 +@item RX: the PHY is synchronized on a signal and
   6.219 +is waiting until it has received its last bit to forward
   6.220 +it to the MAC.
   6.221 +@item IDLE: the PHY is not in the TX or RX states.
   6.222 +@end enumerate
   6.223 +
   6.224 +When the first bit of a new packet is received while
   6.225 +the PHY is not IDLE (that is, it is already synchronized
   6.226 +on the reception of another earlier packet or it is
   6.227 +sending data itself), the received packet is dropped. 
   6.228 +Otherwise, if the PHY is IDLE, we calculate the received
   6.229 +energy of the first bit of this new signal and compare it 
   6.230 +against our Energy Detection threshold (as defined 
   6.231 +by the Clear Channel Assessment function mode 1). 
   6.232 +If the energy of the packet k is higher, then the PHY moves 
   6.233 +to RX state and schedules an event when the last bit of 
   6.234 +the packet is expected to be received. Otherwise, the 
   6.235 +PHY stays in IDLE state and drops the packet.
   6.236 +
   6.237 +The energy of the received signal is assumed
   6.238 +to be zero outside of the reception interval of packet k and
   6.239 +is calculated from the transmission power with a path-loss 
   6.240 +propagation model in the reception interval.
   6.241 +where the path loss exponent, @math{n}, is chosen equal to 3, 
   6.242 +the reference distance, @math{d_0} is choosen equal to 
   6.243 +@math{1.0m} and 
   6.244 +the reference energy is based based on a Friis
   6.245 +propagation model.
   6.246 +
   6.247 +When the last bit of the packet upon which the PHY is 
   6.248 +synchronized is received, we need to calculate the 
   6.249 +probability that the packet is received with any error
   6.250 +to decide whether or not 
   6.251 +the packet on which we were synchronized could
   6.252 +be successfully received or not: a random number 
   6.253 +is drawn from a uniform distribution and is compared against
   6.254 +the probability of error.
   6.255 +
   6.256 +To evaluate the probability of error, we start from the piecewise linear 
   6.257 +functions shown in Figure @ref{fig:snir} and calculate the 
   6.258 +SNIR function. 
   6.259 +
   6.260 +@float Figure,fig:snir
   6.261 +@caption{SNIR function over time}
   6.262 +@image{figures/snir,,3in} 
   6.263 +@end float 
   6.264 +
   6.265 +From the SNIR function we can derive bit error rates for BPSK and QAM
   6.266 +modulations.  Then, for each interval l where BER is
   6.267 +constant, we define the upper bound of a probability that an error is
   6.268 +present in the chunk of bits located in the interval l for packet k.
   6.269 +If we assume an AWGN channel, 
   6.270 +binary convolutional coding (which is the case in 802.11a)
   6.271 +and hard-decision Viterbi decoding, the error rate is thus derived,
   6.272 +and the packet error probability for packet k can be computed.. 
   6.273 +
   6.274 +@subsection WifiChannel configuration
   6.275 +
   6.276 +WifiChannel models include both a PropagationDelayModel and a 
   6.277 +PropagationLossModel.  The following PropagationDelayModels are available:
   6.278 +@itemize @bullet
   6.279 +@item ConstantSpeedPropagationDelayModel
   6.280 +@item RandomPropagationDelayModel
   6.281 +@end itemize
   6.282 +
   6.283 +The following PropagationLossModels are available:
   6.284 +@itemize @bullet
   6.285 +@item RandomPropagationLossModel
   6.286 +@item FriisPropagationLossModel
   6.287 +@item LogDistancePropagationLossModel
   6.288 +@item JakesPropagationLossModel
   6.289 +@item CompositePropagationLossModel
   6.290 +@end itemize
   6.291 +
   6.292 +@node The MAC model
   6.293 +@section The MAC model
   6.294 +
   6.295 +The 802.11 Distributed Coordination Function is used to
   6.296 +calculate when to grant access to the transmission medium. While
   6.297 +implementing the DCF would have been particularly easy if we
   6.298 +had used a recurring timer that expired every slot, we
   6.299 +chose to use the method described in @emph{(missing reference here from
   6.300 +Yans paper)}
   6.301 +where the backoff timer duration is lazily calculated whenever
   6.302 +needed since it is claimed to have much better performance than
   6.303 +the simpler recurring timer solution.
   6.304 +
   6.305 +The higher-level MAC functions are implemented in a set of other
   6.306 +C++ classes and deal with:
   6.307 +@itemize @bullet
   6.308 +@item packet fragmentation and defragmentation,
   6.309 +@item use of the rts/cts protocol,
   6.310 +@item rate control algorithm,
   6.311 +@item connection and disconnection to and from an Access Point,
   6.312 +@item the MAC transmission queue,
   6.313 +@item beacon generation,
   6.314 +@item etc.
   6.315 +@end itemize
   6.316 +
   6.317 +@node Wifi Attributes
   6.318 +@section Wifi Attributes
   6.319 +
   6.320 +The WifiNetDevice makes heavy use of the ns-3 @ref{Attributes} subsystem for
   6.321 +configuration and default value management.  Presently, approximately
   6.322 +100 values are stored in this system.
   6.323 +
   6.324 +For instance, class @code{ns-3::WifiMac} exports these attributes:
   6.325 +@itemize @bullet
   6.326 +@item CtsTimeout: When this timeout expires, the RTS/CTS handshake has failed.
   6.327 +@item AckTimeout: When this timeout expires, the DATA/ACK handshake has failed.
   6.328 +@item Sifs: The value of the SIFS constant.
   6.329 +@item EifsNoDifs: The value of EIFS-DIFS
   6.330 +@item Slot: The duration of a Slot.
   6.331 +@item Pifs: The value of the PIFS constant.
   6.332 +@item MaxPropagationDelay: The maximum propagation delay. Unused for now.
   6.333 +@item MaxMsduSize: The maximum size of an MSDU accepted by the MAC layer.This value conforms to the specification.
   6.334 +@item Ssid: The ssid we want to belong to.
   6.335 +@end itemize
   6.336 +
   6.337 +@node Wifi Tracing
   6.338 +@section Wifi Tracing
   6.339 +
   6.340 +@emph{This needs revised/updating based on the latest Doxygen}
   6.341 +
   6.342 +ns-3 has a sophisticated tracing infrastructure that allows users to hook
   6.343 +into existing trace sources, or to define and export new ones.  
   6.344 +
   6.345 +Wifi-related trace sources that are available by default include:
   6.346 +@itemize @bullet
   6.347 +@item @code{ns3::WifiNetDevice}
   6.348 +@itemize @bullet
   6.349 +@item Rx: Received payload from the MAC layer.
   6.350 +@item Tx: Send payload to the MAC layer.
   6.351 +@end itemize
   6.352 +@item @code{ns3::WifiPhy}
   6.353 +@itemize @bullet
   6.354 +@item State: The WifiPhy state
   6.355 +@item RxOk: A packet has been received successfully.
   6.356 +@item RxError: A packet has been received unsuccessfully.
   6.357 +@item Tx: Packet transmission is starting.
   6.358 +@end itemize
   6.359 +@end itemize
   6.360 +Briefly, this means, for example, that a user can hook a processing 
   6.361 +function to the "State" tracing hook above and be notified whenever the
   6.362 +WifiPhy model changes state.