F5/unison
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

fix some tutorial nits

Browse Source
This commit is contained in:
Craig Dowell
2009-03-25 09:34:39 -07:00
parent f2c609494d
commit 0bc0bc5d15
4 changed files with 95 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
doc/tutorial/building-topologies.texi
View File

@@ -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.

45
doc/tutorial/conceptual-overview.texi
View File

@@ -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

24
doc/tutorial/getting-started.texi
View File

@@ -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

50
doc/tutorial/tweaking.texi
View File

@@ -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 (