diff --git a/doc/tutorial/building-topologies.texi b/doc/tutorial/building-topologies.texi index b50b7608b..62ab61d42 100644 --- a/doc/tutorial/building-topologies.texi +++ b/doc/tutorial/building-topologies.texi @@ -158,9 +158,9 @@ point-to-point and CSMA net device, the number of ``extra'' nodes means the number nodes you desire in the CSMA section minus one. The next bit of code should be quite familiar by now. We instantiate a -@code{PointToPointHelper} and set the associated default attributes so that -we create a five megabit per second transmitter on devices created using the -helper and a two millisecond delay on channels created by the helper. +@code{PointToPointHelper} and set the associated default @code{Attributes} so +that we create a five megabit per second transmitter on devices created using +the helper and a two millisecond delay on channels created by the helper. @verbatim PointToPointHelper pointToPoint; @@ -179,13 +179,13 @@ We mentioned above that you were going to see a helper for CSMA devices and channels, and the next lines introduce them. The @code{CsmaHelper} works just like a @code{PointToPointHelper}, but it creates and connects CSMA devices and channels. In the case of a CSMA device and channel pair, notice that the data -rate is specified by a @emph{channel} attribute instead of a device attribute. -This is because a real CSMA network does not allow one to mix, for example, -10Base-T and 100Base-T devices on a given channel. We first set the data rate -to 100 megabits per second, and then set the speed-of-light delay of the channel -to 6560 nano-seconds (arbitrarily chosen as 1 nanosecond per foot over a 100 -meter segment). Notice that you can set an attribute using its native data -type. +rate is specified by a @emph{channel} @code{Attribute} instead of a device +@code{Attribute}. This is because a real CSMA network does not allow one to mix, +for example, 10Base-T and 100Base-T devices on a given channel. We first set +the data rate to 100 megabits per second, and then set the speed-of-light delay +of the channel to 6560 nano-seconds (arbitrarily chosen as 1 nanosecond per foot +over a 100 meter segment). Notice that you can set an @code{Attribute} using +its native data type. @verbatim CsmaHelper csma; @@ -252,8 +252,8 @@ nodes that has a CSMA node and the client on the node having only a point-to-point device. First, we set up the echo server. We create a @code{UdpEchoServerHelper} and -provide a required attribute value to the constructor which is the server port -number. Recall that this port can be changed later using the +provide a required @code{Attribute} value to the constructor which is the server +port number. Recall that this port can be changed later using the @code{SetAttribute} method if desired, but we require it to be provided to the constructor. @@ -276,7 +276,7 @@ if we create @code{nCsma} ``extra'' nodes the last one will be at index code. The client application is set up exactly as we did in the @code{first.cc} -example script. Again, we provide required attributes to the +example script. Again, we provide required @code{Attributes} to the @code{UdpEchoClientHelper} in the constructor (in this case the remote address and port). We tell the client to send packets to the server we just installed on the last of the ``extra'' CSMA nodes. We install the client on the @@ -780,8 +780,8 @@ that we will connect via the point-to-point link. @end verbatim Next, we see an old friend. We instantiate a @code{PointToPointHelper} and -set the associated default attributes so that we create a five megabit per -second transmitter on devices created using the helper and a two millisecond +set the associated default @code{Attributes} so that we create a five megabit +per second transmitter on devices created using the helper and a two millisecond delay on channels created by the helper. We then @code{Intall} the devices on the nodes and the channel between them. @@ -809,8 +809,8 @@ that will get CSMA devices. The node in question is going to end up with a point-to-point device and a CSMA device. We then create a number of ``extra'' nodes that compose the remainder of the CSMA network. -We then instantiate a @code{CsmaHelper} and set its attributes as we did in -the previous example. We create a @code{NetDeviceContainer} to keep track of +We then instantiate a @code{CsmaHelper} and set its @code{Attributes} as we did +in the previous example. We create a @code{NetDeviceContainer} to keep track of the created CSMA net devices and then we @code{Install} CSMA devices on the selected nodes. @@ -882,8 +882,8 @@ will be used to set the value of the ``Ssid'' @code{Attribute} of the MAC layer implementation. The particular kind of MAC layer is specified by @code{Attribute} as being of the "ns3::NqstaWifiMac" type. This means that the MAC will use a ``non-QoS station'' (nqsta) state machine. Finally, the -``ActiveProbing'' attribute is set to false. This means that probe requests -will not be sent by MACs created by this helper. +``ActiveProbing'' @code{Attribute} is set to false. This means that probe +requests will not be sent by MACs created by this helper. Once all the station-specific parameters are fully configured, both at the MAC and PHY layers, we can invoke our now-familiar @code{Install} method to @@ -908,11 +908,11 @@ requirements of the AP. In this case, the @code{WifiHelper} is going to create MAC layers of the ``ns3::NqapWifiMac'' (Non-Qos Access Point) type. We set the -``BeaconGeneration'' attribute to true and also set an interval between +``BeaconGeneration'' @code{Attribute} to true and also set an interval between beacons of 2.5 seconds. The next lines create the single AP which shares the same set of PHY-level -attributes (and channel) as the stations: +@code{Attributes} (and channel) as the stations: @verbatim NetDeviceContainer apDevices; @@ -922,8 +922,8 @@ attributes (and channel) as the stations: Now, we are going to add mobility models. We want the STA nodes to be mobile, wandering around inside a bounding box, and we want to make the AP node stationary. We use the @code{MobilityHelper} to make this easy for us. -First, we instantiate a @code{MobilityHelper} object and set some attributes -controlling the ``position allocator'' functionality. +First, we instantiate a @code{MobilityHelper} object and set some +@code{Attributes} controlling the ``position allocator'' functionality. @verbatim MobilityHelper mobility; @@ -1329,7 +1329,8 @@ Under the ``core'' section, you will find a link to ``The list of all trace sources.'' You may find it interesting to try and hook some of these traces yourself. Additionally in the ``Modules'' documentation, there is a link to ``The list of all attributes.'' You can set the default value of -any of these attributes via the command line as we have previously discussed. +any of these @code{Attributes} via the command line as we have previously +discussed. We have just scratched the surface of @command{ns-3} in this tutorial, but we hope we have covered enough to get you started doing useful work. diff --git a/doc/tutorial/conceptual-overview.texi b/doc/tutorial/conceptual-overview.texi index bae4f2290..cb38386bb 100644 --- a/doc/tutorial/conceptual-overview.texi +++ b/doc/tutorial/conceptual-overview.texi @@ -446,12 +446,12 @@ to what we call an @code{Attribute} of the @code{PointToPointNetDevice}. If you look at the Doxygen for class @code{ns3::PointToPointNetDevice} and find the documentation for the @code{GetTypeId} method, you will find a list of @code{Attributes} defined for the device. Among these is the ``DataRate'' -attribute. Most user-visible @command{ns-3} objects have similar lists of -attributes. We use this mechanism to easily configure simulations without +@code{Attribute}. Most user-visible @command{ns-3} objects have similar lists of +@code{Attributes}. We use this mechanism to easily configure simulations without recompiling as you will see in a following section. Similar to the ``DataRate'' on the @code{PointToPointNetDevice} you will find a -``Delay'' attribute associated with the @code{PointToPointChannel}. The +``Delay'' @code{Attribute} associated with the @code{PointToPointChannel}. The final line, @verbatim @@ -487,8 +487,9 @@ is created. For each node in the @code{NodeContainer} (there must be exactly two for a point-to-point link) a @code{PointToPointNetDevice} is created and saved in the device container. A @code{PointToPointChannel} is created and the two @code{PointToPointNetDevices} are attached. When objects are created -by the @code{PointToPointHelper}, the attributes previously set in the helper -are used to initialize the corresponding attributes in the created objects. +by the @code{PointToPointHelper}, the @code{Attributes} previously set in the +helper are used to initialize the corresponding @code{Attributes} in the +created objects. After executing the @code{pointToPoint.Install (nodes)} call we will have two nodes, each with an installed point-to-point net device and a @@ -575,13 +576,13 @@ created. The first line of code in the above snippet declares the @code{UdpEchoServerHelper}. As usual, this isn't the application itself, it is an object used to help us create the actual applications. One of our -conventions is to place required attributes in the helper constructor. In this -case, the helper can't do anything useful unless it is provided with a port -number that the client also knows about. Rather than just picking one and -hoping it all works out, we require the port number as a parameter to the +conventions is to place required @code{Attributes} in the helper constructor. +In this case, the helper can't do anything useful unless it is provided with +a port number that the client also knows about. Rather than just picking one +and hoping it all works out, we require the port number as a parameter to the constructor. The constructor, in turn, simply does a @code{SetAttribute} -with the passed value. You can, if desired, set the ``Port'' attribute to -another value later. +with the passed value. You can, if desired, set the ``Port'' @code{Attribute} +to another value later. Similar to many other helper objects, the @code{UdpEchoServerHelper} object has an @code{Install} method. It is the execution of this method that actually @@ -634,12 +635,12 @@ that is managed by an @code{UdpEchoClientHelper}. clientApps.Stop (Seconds (10.0)); @end verbatim -For the echo client, however, we need to set five different attributes. The -first two attributes are set during construction of the +For the echo client, however, we need to set five different @code{Attributes}. +The first two @code{Attributes} are set during construction of the @code{UdpEchoClientHelper}. We pass parameters that are used (internally to -the helper) to set the ``RemoteAddress'' and ``RemotePort'' attributes in -accordance with our convention to make required attributes parameters in the -helper constructors. +the helper) to set the ``RemoteAddress'' and ``RemotePort'' @code{Attributes} +in accordance with our convention to make required @code{Attributes} parameters +in the helper constructors. Recall that we used an @code{Ipv4InterfaceContainer} to keep track of the IP addresses we assigned to our devices. The zeroth interface in the @@ -651,12 +652,12 @@ are creating the helper and telling it so set the remote address of the client to be the IP address assigned to the node on which the server resides. We also tell it to arrange to send packets to port nine. -The ``MaxPackets'' attribute tells the client the maximum number of packets -we allow it to send during the simulation. The ``Interval'' attribute tells -the client how long to wait between packets, and the ``PacketSize'' attribute -tells the client how large its packet payloads should be. With this -particular combination of attributes, we are telling the client to send one -1024-byte packet. +The ``MaxPackets'' @code{Attribute} tells the client the maximum number of +packets we allow it to send during the simulation. The ``Interval'' +@code{Attribute} tells the client how long to wait between packets, and the +``PacketSize'' @code{Attribute} tells the client how large its packet payloads +should be. With this particular combination of @code{Attributes}, we are +telling the client to send one 1024-byte packet. Just as in the case of the echo server, we tell the echo client to @code{Start} and @code{Stop}, but here we start the client one second after the server is diff --git a/doc/tutorial/getting-started.texi b/doc/tutorial/getting-started.texi index ef06acbb4..d0b18cd94 100644 --- a/doc/tutorial/getting-started.texi +++ b/doc/tutorial/getting-started.texi @@ -411,7 +411,7 @@ system. in the example above, this library was not found and the corresponding feature was not enabled. There is a feature to use sudo to set the suid bit of certain programs. This was not enabled by default. -Now go ahead and switch back to the debug build: +Now go ahead and switch back to the debug build. @verbatim ./waf -d debug configure @@ -424,6 +424,26 @@ the @command{ns-3} programs by simply typing, ./waf @end verbatim +Some waf commands are meaningful during the build phase and some commands are valid +in the configuration phase. For example, if you wanted to use the emulation +features of @command{ns-3} you might want to enable setting the suid bit using +sudo. This is a configuration command, and so you could have run the following +command + +@verbatim + ./waf -d debug --enable-sudo configure +@end verbatim + +If you had done this, waf would have run sudo to change the socket creator +programs to run as root. There are many other configure- and build-time options +available in waf. To explore these options, type: + +@verbatim + ./waf -- help +@end verbatim + +We'll use some of the testing-related commands in the next section. + Okay, sorry, I made you build the @command{ns-3} part of the system twice, but now you know how to change the configuration and build optimized code. @@ -518,7 +538,7 @@ a regression test, you can do the following: @verbatim cd build/debug/regression/traces/second.ref - tcpdump -nn -tt -r second-1-1.pcap + tcpdump -nn -tt -r second-2-0.pcap @end verbatim The output should be clear to anyone who is familiar with tcpdump or net diff --git a/doc/tutorial/tweaking.texi b/doc/tutorial/tweaking.texi index ff1f70125..8a7ebcbf5 100644 --- a/doc/tutorial/tweaking.texi +++ b/doc/tutorial/tweaking.texi @@ -93,7 +93,7 @@ to get our bearings, go ahead and run the script just as you did previously, @verbatim ./waf --run scratch/myfirst -@end verbtim +@end verbatim You should see the now familiar output of the first @command{ns-3} example program @@ -438,10 +438,10 @@ in the following code, @end verbatim This simple two line snippet is actually very useful by itself. It opens the -door to the @command{ns-3} global variable and attribute systems. Go ahead -and add that two lines of code to the @code{scratch/first.cc} script at the -start of @code{main}. Go ahead and build the script and run it, but ask the script -for help in the following way, +door to the @command{ns-3} global variable and @code{Attribute} systems. Go +ahead and add that two lines of code to the @code{scratch/first.cc} script at +the start of @code{main}. Go ahead and build the script and run it, but ask +the script for help in the following way, @verbatim ./waf --run "scratch/myfirst --PrintHelp" @@ -464,7 +464,7 @@ now see the @code{--PrintHelp} argument and respond with, @end verbatim Let's focus on the @code{--PrintAttributes} option. We have already hinted -at the @command{ns-3} attribute system while walking through the +at the @command{ns-3} @code{Attribute} system while walking through the @code{first.cc} script. We looked at the following lines of code, @verbatim @@ -475,17 +475,17 @@ at the @command{ns-3} attribute system while walking through the and mentioned that @code{DataRate} was actually an @code{Attribute} of the @code{PointToPointNetDevice}. Let's use the command line argument parser -to take a look at the attributes of the PointToPointNetDevice. The help +to take a look at the @code{Attributes} of the PointToPointNetDevice. The help listing says that we should provide a @code{TypeId}. This corresponds to the -class name of the class to which the attributes belong. In this case it will -be @code{ns3::PointToPointNetDevice}. Let's go ahead and type in, +class name of the class to which the @code{Attributes} belong. In this case it +will be @code{ns3::PointToPointNetDevice}. Let's go ahead and type in, @verbatim ./waf --run "scratch/myfirst --PrintAttributes=ns3::PointToPointNetDevice" @end verbatim -The system will print out all of the attributes of this kind of net device. -Among the attributes you will see listed is, +The system will print out all of the @code{Attributes} of this kind of net device. +Among the @code{Attributes} you will see listed is, @verbatim --ns3::PointToPointNetDevice::DataRate=[32768bps]: @@ -493,7 +493,7 @@ Among the attributes you will see listed is, @end verbatim This is the default value that will be used when a @code{PointToPointNetDevice} -is created in the system. We overrode this default with the attribute +is created in the system. We overrode this default with the @code{Attribute} setting in the @code{PointToPointHelper} above. Let's use the default values for the point-to-point devices and channels by deleting the @code{SetDeviceAttribute} call and the @code{SetChannelAttribute} call from @@ -558,7 +558,7 @@ the formula implied by the help item: ./waf --run "scratch/myfirst --ns3::PointToPointNetDevice::DataRate=5Mbps" @end verbatim -This will set the default value of the @code{DataRate} attribute back to +This will set the default value of the @code{DataRate} @code{Attribute} back to five megabits per second. Are you surprised by the result? It turns out that in order to get the original behavior of the script back, we will have to set the speed-of-light delay of the channel as well. We can ask the command line @@ -569,7 +569,7 @@ the net device: ./waf --run "scratch/myfirst --PrintAttributes=ns3::PointToPointChannel" @end verbatim -We discover the @code{Delay} attribute of the channel is set in the following +We discover the @code{Delay} @code{Attribute} of the channel is set in the following way: @verbatim @@ -603,12 +603,12 @@ in which case we recover the timing we had when we explicitly set the @end verbatim Note that the packet is again received by the server at 2.00369 seconds. We -could actually set any of the attributes used in the script in this way. In -particular we could set the @code{UdpEchoClient} attribute @code{MaxPackets} +could actually set any of the @code{Attributes} used in the script in this way. +In particular we could set the @code{UdpEchoClient Attribute MaxPackets} to some other value than one. How would you go about that? Give it a try. Remember you have to comment -out the place we override the default attribute in the script. Then you +out the place we override the default @code{Attribute} in the script. Then you have to rebuild the script using the default. You will also have to find the syntax for actually setting the new default atribute value using the command line help facility. Once you have this figured out you should be able to @@ -649,11 +649,11 @@ start with the following code, @end verbatim Scroll down to the point in the script where we set the @code{MaxPackets} -attribute and change it so that it is set to the variable @code{nPackets} +@code{Attribute} and change it so that it is set to the variable @code{nPackets} instead of the constant @code{1} as is shown below. @verbatim - echoClient.SetAppAttribute ("MaxPackets", UintegerValue (nPackets)); + echoClient.SetAttribute ("MaxPackets", UintegerValue (nPackets)); @end verbatim Now if you run the script and provide the @code{--PrintHelp} argument, you @@ -708,11 +708,11 @@ You should now see You have now echoed two packets. You can see that if you are an @command{ns-3} user, you can use the command -line argument system to control global values and attributes. If you are a -model author, you can add new attributes to your Objects and they will -automatically be available for setting by your users through the command line -system. If you are a script author, you can add new variables to your scripts -and hook them into the command line system quite painlessly. +line argument system to control global values and @code{Attributes}. If you are +a model author, you can add new @code{Attributes} to your @code{Objects} and +they will automatically be available for setting by your users through the +command line system. If you are a script author, you can add new variables to +your scripts and hook them into the command line system quite painlessly. @c ======================================================================== @c Using the Tracing System @@ -927,7 +927,7 @@ device on the node with the echo server. I have reproduced that event below. @verbatim 00 r 01 2.25732 - 02 /NodeList/1/DeviceList/0/$ns3::PointToPointNetDevice/Rx + 02 /NodeList/1/DeviceList/0/$ns3::PointToPointNetDevice/MacRx 03 ns3::PppHeader ( 04 Point-to-Point Protocol: IP (0x0021)) 05 ns3::Ipv4Header (