From d3e7db87dd057c14df35fcadf23b08b7713af5a3 Mon Sep 17 00:00:00 2001 From: Tom Henderson Date: Mon, 15 Dec 2008 07:25:27 -0800 Subject: [PATCH] add device chapters to manual --- doc/manual/Makefile | 8 +- doc/manual/figures/snir.dia | Bin 0 -> 2529 bytes doc/manual/manual.texi | 6 + doc/manual/point-to-point.texi | 7 +- doc/manual/routing.texi | 2 +- doc/manual/wifi.texi | 359 +++++++++++++++++++++++++++++++++ 6 files changed, 376 insertions(+), 6 deletions(-) create mode 100644 doc/manual/figures/snir.dia create mode 100644 doc/manual/wifi.texi diff --git a/doc/manual/Makefile b/doc/manual/Makefile index cd7b36497..7dc11ceef 100644 --- a/doc/manual/Makefile +++ b/doc/manual/Makefile @@ -17,7 +17,8 @@ IMAGES_EPS = \ $(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 @@ CHAPTERS = \ 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 $@ diff --git a/doc/manual/figures/snir.dia b/doc/manual/figures/snir.dia new file mode 100644 index 0000000000000000000000000000000000000000..e3ab83fa1d81c69463553d7b7f66d36c2ea995a4 GIT binary patch literal 2529 zcmV<72_E(ziwFP!000001MQt{kE6C0$KUU#h%#@J3^oserZZKi>Z+Bh-s-mZb>sw3 zLYF`U%tPMvvtI-0COpLn*k@tak!H06j*sp0v;XECV7~w1edmu}X%u^5@GwR*Z9JmE zI&{5Y^DzG3UmvIT_=m?2-@6|9j{R&RvKz5)1abP?!+4t{`|s}W-`?J4{vjqw7|nd| zWfs%>e~9msdsgUv{Pljw!Ew-c|4&k(!Rtq#3-_L3yz zwEvm-@iiUD4}YF*x6a&6Vpu2PQvM66?%_ zPYyIXR{wO8>Cw@_#}(&n6vEZtbe$Z#_h&)^mqhMpI{M8E==iklV4DuleHi~oD~?aO zN31rs^i>9EAAY6?Pmo#eaCNz8s(ZC6R~@m|lVIc1BcwCOoFHRnF0e7v*niDgOLOZm z2$nQ(v$kK~qnh(Z>n;Z`yY;?ox^6<=QYq`xl0;GXR<4*bbH^s*j#V#x8f=nn)mi^8 zg<4y;oJ?d3ZWjyr!F&R=pAo3{Gs2uqEjAYxc$Uov?Tb$c)*dw2=mlq-b`{$RsIlhKb2 zL4ylB?WW7NFi7eQrpHImWas$@)-Dpn<58R((k&sIx%pRrq5dmPyfryry>D+pg{oTL z*jn*pbTe99Q|hMSJlz-KZdQty9v9+Mn%2z_yRhE`J6i9`lQ5wxt<+vvNR{IReFB2;k?11zK3r^1!Ks;8!d#XS^RPgma zR3IR7IF)|S#54_89D^3q^paM3oN9_VQH!>n?!^-52nbt9^?Dw+m>RHdFZHUvfH7RZ zV-XR`wgYgx-!uK2>M(vcIPr@?`yB}gV952mUhzA`d^fJ}`+(PZEFxAZcb(VI{z9Cx{(>;K4#u+%qmv- zwZl3C!m$Czu`vN!kc}%iR_k$JIJSgvY{GGDPJp(^<`o>P9dchdo(tjF zg5%hl00k|qD>zm$i@tDdi{jXT;MhnxHo!PGcpR%Ja$h)hL~*P`aIB{sn_wL4JdRDp zaX&aVG*KL52#)ch^5C{ijxmp8OL5#2j*%#i5d_C5<#-OpG2(GNR~+|*V=Rbc4FF?p zQF*6=M2a;Y#I}OCClKp`Ack0rv!&R9f|$D!I||~SKx_zt7-D0b?Te8HMKO0@j8r18 zFBqGGFouXzWMK+~pfKi!DUizJ^#x-~5XKN;<1A{7Fcikzs4-G$yuM&8Dvbw`#mka- z2rP@ozo|lH@%nUSBX4mBgC^U_4)x9#)f!@tljX%Hj0{ zV^dTP&z6p{GqGVYwl8DsD2)4qv8WWDBOPO;O&nN`oy#1v1}Ttx1G1{ zMHz7td1;dr%Y9*4SSn9`E-(Gdv!pw8>A);=QhRBW6w7^KSyXNh$xrSflUV^~nUmj3o1|D4&T@X_?5$Z< zv_Jac+j>i)gt7e;zSp7M`K6a=F86P*vFaCCpUh`1|MnC0>2A3Wqku+IdXd%7d1+&p zs<+hJY?J1?QQLu8g^^1m?)xU&RUU7{x8;hgKc##IZn^$d82Xe1xrrotp>5x@m%4Qs z5!ZW(FTFF<(2AdyF9O{Y*Y$#pg!g|Y^u6Nab+}_w&tqls*<32qH1h1%LK8oi%+EaD z{S_vxy+5;&+Z^ulMjlU{*WI+vHJE)4gQU)AdVKUucAkG=Z6iTE9%bucwgly0{e}9k zH1XD?BqKMrpfXWv{bQF%FuEBni+;^(ay7Pgp>9^zp&v$dcCr(>ox8k0-3$@m+XOpW z@5+;4UE7`f#Al8>zi9LdJ+lSq8J4SOIMp+K=1A5vJXAe%iZc``c~kOsgS`D7dNCb6 zvvqOL97L1RlM*=qk<(|$R4NCga*hC%o9c39ZmOp`H$^inS?Jn!L|wTlX&aWb{rUT^ r|5eHct!!)wbCj~(s%-i1J~`0n@k9O#``JWf_xR!eVBYtJ{Z?x literal 0 HcmV?d00001 diff --git a/doc/manual/manual.texi b/doc/manual/manual.texi index 6902e5865..ab6ac0fc1 100644 --- a/doc/manual/manual.texi +++ b/doc/manual/manual.texi @@ -89,6 +89,9 @@ see @uref{http://www.nsnam.org/docs/manual.pdf}. * Node and Internet Stack:: * TCP:: * Routing overview:: +* Wifi NetDevice:: +* CSMA NetDevice:: +* PointToPoint NetDevice:: * Troubleshooting:: @end menu @@ -104,6 +107,9 @@ see @uref{http://www.nsnam.org/docs/manual.pdf}. @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 diff --git a/doc/manual/point-to-point.texi b/doc/manual/point-to-point.texi index 32a704948..48faf05ae 100644 --- a/doc/manual/point-to-point.texi +++ b/doc/manual/point-to-point.texi @@ -71,6 +71,7 @@ The PointToPointChannel provides following Attributes: @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 @@ 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 +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). -@item +@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. diff --git a/doc/manual/routing.texi b/doc/manual/routing.texi index 2e313319e..275a76fef 100644 --- a/doc/manual/routing.texi +++ b/doc/manual/routing.texi @@ -313,7 +313,7 @@ For instance, this scheduling call will cause the tables to be rebuilt at time 5 seconds: @verbatim Simulator::Schedule (Seconds (5),&GlobalRouteManager::RecomputeRoutingTables); -@end verbatimT +@end verbatim @node Global Routing Implementation @section Global Routing Implementation diff --git a/doc/manual/wifi.texi b/doc/manual/wifi.texi new file mode 100644 index 000000000..cd200f4d1 --- /dev/null +++ b/doc/manual/wifi.texi @@ -0,0 +1,359 @@ +@node Wifi NetDevice +@chapter Wifi NetDevice +@anchor{chap:wifi} + +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. + +@menu +* 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 +specification. + +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}: +@enumerate +@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: +@enumerate +@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{http://cutebugs.net/files/wns2-yans.pdf,,"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 +@code{src/devices/wifi}. + +@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{http://cutebugs.net/files/wns2-yans.pdf,,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: +@verbatim + YansWifiChannelHelper wifiChannelHelper = YansWifiChannelHelper::Default (); + Ptr 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 +typically: +@verbatim + 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: +@verbatim + 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": +@verbatim + 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{http://cutebugs.net/files/wns2-yans.pdf,,"Yet Another Network Simulator"} for more details. + +The PHY layer can be in one of three states: +@enumerate +@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} +@image{figures/snir,,3in} +@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.