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.