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

Manual and Tutorial syntax coloring

Browse Source
This commit is contained in:
Peter D. Barnes, Jr.
2013-07-17 17:09:36 -07:00
parent 9659e95a7d
commit 9f77e699cb
27 changed files with 668 additions and 478 deletions
Download Patch File Download Diff File Expand all files Collapse all files

127
doc/tutorial/source/building-topologies.rst
View File

@@ -1,5 +1,5 @@
.. include:: replace.txt
.. highlight:: cpp
Building Topologies
-------------------
@@ -337,10 +337,10 @@ the scratch directory and use waf to build just as you did with
the ``first.cc`` example. If you are in the top-level directory of the
repository you just type,
::
.. sourcecode:: bash
cp examples/tutorial/second.cc scratch/mysecond.cc
./waf
$ cp examples/tutorial/second.cc scratch/mysecond.cc
$ ./waf
Warning: We use the file ``second.cc`` as one of our regression tests to
verify that it works exactly as we think it should in order to make your
@@ -353,15 +353,15 @@ If you are following the tutorial religiously (you are, aren't you) you will
still have the NS_LOG variable set, so go ahead and clear that variable and
run the program.
::
.. sourcecode:: bash
export NS_LOG=
./waf --run scratch/mysecond
$ export NS_LOG=
$ ./waf --run scratch/mysecond
Since we have set up the UDP echo applications to log just as we did in
``first.cc``, you will see similar output when you run the script.
::
.. sourcecode:: text
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -381,7 +381,7 @@ the server.
If you now go and look in the top level directory, you will find three trace
files:
::
.. sourcecode:: text
second-0-0.pcap second-1-0.pcap second-2-0.pcap
@@ -403,13 +403,13 @@ promiscuous-mode trace.
Now, let's follow the echo packet through the internetwork. First, do a
tcpdump of the trace file for the leftmost point-to-point node --- node zero.
::
.. sourcecode:: bash
tcpdump -nn -tt -r second-0-0.pcap
$ tcpdump -nn -tt -r second-0-0.pcap
You should see the contents of the pcap file displayed:
::
.. sourcecode:: text
reading from file second-0-0.pcap, link-type PPP (PPP)
2.000000 IP 10.1.1.1.49153 > 10.1.2.4.9: UDP, length 1024
@@ -422,14 +422,14 @@ device associated with IP address 10.1.1.1 headed for IP address
point-to-point link and be received by the point-to-point net device on node
one. Let's take a look:
::
.. sourcecode:: bash
tcpdump -nn -tt -r second-1-0.pcap
$ tcpdump -nn -tt -r second-1-0.pcap
You should now see the pcap trace output of the other side of the point-to-point
link:
::
.. sourcecode:: text
reading from file second-1-0.pcap, link-type PPP (PPP)
2.003686 IP 10.1.1.1.49153 > 10.1.2.4.9: UDP, length 1024
@@ -444,13 +444,13 @@ pop out on that device headed for its ultimate destination.
Remember that we selected node 2 as the promiscuous sniffer node for the CSMA
network so let's then look at second-2-0.pcap and see if its there.
::
.. sourcecode:: bash
tcpdump -nn -tt -r second-2-0.pcap
$ tcpdump -nn -tt -r second-2-0.pcap
You should now see the promiscuous dump of node two, device zero:
::
.. sourcecode:: text
reading from file second-2-0.pcap, link-type EN10MB (Ethernet)
2.003696 arp who-has 10.1.2.4 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1
@@ -471,7 +471,7 @@ exchange, but is sniffing the network and reporting all of the traffic it sees.
This exchange is seen in the following lines,
::
.. sourcecode:: text
2.003696 arp who-has 10.1.2.4 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1
2.003707 arp reply 10.1.2.4 is-at 00:00:00:00:00:06
@@ -479,7 +479,7 @@ This exchange is seen in the following lines,
Then node one, device one goes ahead and sends the echo packet to the UDP echo
server at IP address 10.1.2.4.
::
.. sourcecode:: text
2.003801 IP 10.1.1.1.49153 > 10.1.2.4.9: UDP, length 1024
@@ -490,40 +490,41 @@ routing and it has figured all of this out for us. But, the echo server node
doesn't know the MAC address of the first CSMA node, so it has to ARP for it
just like the first CSMA node had to do.
::
.. sourcecode:: text
2.003811 arp who-has 10.1.2.1 (ff:ff:ff:ff:ff:ff) tell 10.1.2.4
2.003822 arp reply 10.1.2.1 is-at 00:00:00:00:00:03
The server then sends the echo back to the forwarding node.
::
.. sourcecode:: text
2.003915 IP 10.1.2.4.9 > 10.1.1.1.49153: UDP, length 1024
Looking back at the rightmost node of the point-to-point link,
::
.. sourcecode:: bash
tcpdump -nn -tt -r second-1-0.pcap
$ tcpdump -nn -tt -r second-1-0.pcap
You can now see the echoed packet coming back onto the point-to-point link as
the last line of the trace dump.
::
.. sourcecode:: text
reading from file second-1-0.pcap, link-type PPP (PPP)
2.003686 IP 10.1.1.1.49153 > 10.1.2.4.9: UDP, length 1024
2.003915 IP 10.1.2.4.9 > 10.1.1.1.49153: UDP, length 1024
Lastly, you can look back at the node that originated the echo
::
tcpdump -nn -tt -r second-0-0.pcap
.. sourcecode:: bash
$ tcpdump -nn -tt -r second-0-0.pcap
and see that the echoed packet arrives back at the source at 2.007602 seconds,
::
.. sourcecode:: text
reading from file second-0-0.pcap, link-type PPP (PPP)
2.000000 IP 10.1.1.1.49153 > 10.1.2.4.9: UDP, length 1024
@@ -535,13 +536,13 @@ the same way as when we looked at changing the number of packets echoed in the
``first.cc`` example. Try running the program with the number of "extra"
devices set to four:
::
.. sourcecode:: bash
./waf --run "scratch/mysecond --nCsma=4"
$ ./waf --run "scratch/mysecond --nCsma=4"
You should now see,
::
.. sourcecode:: text
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -602,20 +603,20 @@ determining node numbers much easier in complex topologies.
Let's clear the old trace files out of the top-level directory to avoid confusion
about what is going on,
::
.. sourcecode:: bash
rm *.pcap
rm *.tr
$ rm *.pcap
$ rm *.tr
If you build the new script and run the simulation setting ``nCsma`` to 100,
::
.. sourcecode:: bash
./waf --run "scratch/mysecond --nCsma=100"
$ ./waf --run "scratch/mysecond --nCsma=100"
you will see the following output:
::
.. sourcecode:: text
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -628,7 +629,7 @@ Note that the echo server is now located at 10.1.2.101 which corresponds to
having 100 "extra" CSMA nodes with the echo server on the last one. If you
list the pcap files in the top level directory you will see,
::
.. sourcecode:: text
second-0-0.pcap second-100-0.pcap second-101-0.pcap
@@ -643,15 +644,15 @@ To illustrate the difference between promiscuous and non-promiscuous traces, we
also requested a non-promiscuous trace for the next-to-last node. Go ahead and
take a look at the ``tcpdump`` for ``second-100-0.pcap``.
::
.. sourcecode:: bash
tcpdump -nn -tt -r second-100-0.pcap
$ tcpdump -nn -tt -r second-100-0.pcap
You can now see that node 100 is really a bystander in the echo exchange. The
only packets that it receives are the ARP requests which are broadcast to the
entire CSMA network.
::
.. sourcecode:: text
reading from file second-100-0.pcap, link-type EN10MB (Ethernet)
2.003696 arp who-has 10.1.2.101 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1
@@ -659,13 +660,13 @@ entire CSMA network.
Now take a look at the ``tcpdump`` for ``second-101-0.pcap``.
::
.. sourcecode:: bash
tcpdump -nn -tt -r second-101-0.pcap
$ tcpdump -nn -tt -r second-101-0.pcap
You can now see that node 101 is really the participant in the echo exchange.
::
.. sourcecode:: text
reading from file second-101-0.pcap, link-type EN10MB (Ethernet)
2.003696 arp who-has 10.1.2.101 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1
@@ -1180,16 +1181,16 @@ script into the scratch directory and use Waf to build just as you did with
the ``second.cc`` example. If you are in the top-level directory of the
repository you would type,
::
.. sourcecode:: bash
cp examples/third.cc scratch/mythird.cc
./waf
./waf --run scratch/mythird
$ cp examples/third.cc scratch/mythird.cc
$ ./waf
$ ./waf --run scratch/mythird
Again, since we have set up the UDP echo applications just as we did in the
``second.cc`` script, you will see similar output.
::
.. sourcecode:: text
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -1209,7 +1210,7 @@ that it has received its echo back from the server.
If you now go and look in the top level directory, you will find four trace
files from this simulation, two from node zero and two from node one:
::
.. sourcecode:: text
third-0-0.pcap third-0-1.pcap third-1-0.pcap third-1-1.pcap
@@ -1224,13 +1225,13 @@ the code?
Since the echo client is on the Wifi network, let's start there. Let's take
a look at the promiscuous (monitor mode) trace we captured on that network.
::
.. sourcecode:: bash
tcpdump -nn -tt -r third-0-1.pcap
$ tcpdump -nn -tt -r third-0-1.pcap
You should see some wifi-looking contents you haven't seen here before:
::
.. sourcecode:: text
reading from file third-0-1.pcap, link-type IEEE802_11 (802.11)
0.000025 Beacon (ns-3-ssid) [6.0* 9.0 12.0 18.0 24.0 36.0 48.0 54.0 Mbit] IBSS
@@ -1258,13 +1259,13 @@ trace dump.
Now, look at the pcap file of the right side of the point-to-point link,
::
.. sourcecode:: bash
tcpdump -nn -tt -r third-0-0.pcap
$ tcpdump -nn -tt -r third-0-0.pcap
Again, you should see some familiar looking contents:
::
.. sourcecode:: text
reading from file third-0-0.pcap, link-type PPP (PPP)
2.002160 IP 10.1.3.3.49153 > 10.1.2.4.9: UDP, length 1024
@@ -1275,13 +1276,13 @@ again across the point-to-point link.
Now, look at the pcap file of the right side of the point-to-point link,
::
.. sourcecode:: bash
tcpdump -nn -tt -r third-1-0.pcap
$ tcpdump -nn -tt -r third-1-0.pcap
Again, you should see some familiar looking contents:
::
.. sourcecode:: text
reading from file third-1-0.pcap, link-type PPP (PPP)
2.005846 IP 10.1.3.3.49153 > 10.1.2.4.9: UDP, length 1024
@@ -1294,13 +1295,13 @@ as you might expect.
The echo server is on the CSMA network, let's look at the promiscuous trace
there:
::
.. sourcecode:: bash
tcpdump -nn -tt -r third-1-1.pcap
$ tcpdump -nn -tt -r third-1-1.pcap
You should see some familiar looking contents:
::
.. sourcecode:: text
reading from file third-1-1.pcap, link-type EN10MB (Ethernet)
2.005846 ARP, Request who-has 10.1.2.4 (ff:ff:ff:ff:ff:ff) tell 10.1.2.1, length 50
@@ -1382,7 +1383,7 @@ trace sink, which will in turn print out the new position.
If you now run the simulation, you will see the course changes displayed as
they happen.
::
.. sourcecode:: text
Build finished successfully (00:00:01)
/NodeList/7/$ns3::MobilityModel/CourseChange x = 10, y = 0

34
doc/tutorial/source/conceptual-overview.rst
View File

@@ -1,5 +1,5 @@
.. include:: replace.txt
.. highlight:: cpp
Conceptual Overview
-------------------
@@ -153,7 +153,7 @@ of |ns3| in a directory called ``repos`` under your home
directory. Change into that release directory, and you should find a
directory structure something like the following:
::
.. sourcecode:: bash
AUTHORS examples scratch utils waf.bat*
bindings LICENSE src utils.py waf-tools
@@ -250,16 +250,16 @@ load all of the public header files.
Since you are, of course, following this tutorial religiously, you will
already have done a
::
.. sourcecode:: bash
./waf -d debug --enable-examples --enable-tests configure
$ ./waf -d debug --enable-examples --enable-tests configure
in order to configure the project to perform debug builds that include
examples and tests. You will also have done a
::
.. sourcecode:: bash
./waf
$ ./waf
to build the project. So now if you look in the directory
``../../build/debug/ns3`` you will find the four module include files shown
@@ -735,21 +735,21 @@ to drop your script into the scratch directory and it will automatically be
built if you run Waf. Let's try it. Copy ``examples/tutorial/first.cc`` into
the ``scratch`` directory after changing back into the top level directory.
::
.. sourcecode:: bash
cd ../..
cp examples/tutorial/first.cc scratch/myfirst.cc
$ cd ../..
$ cp examples/tutorial/first.cc scratch/myfirst.cc
Now build your first example script using waf:
::
.. sourcecode:: bash
./waf
$ ./waf
You should see messages reporting that your ``myfirst`` example was built
successfully.
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
[614/708] cxx: scratch/myfirst.cc -> build/debug/scratch/myfirst_3.o
@@ -760,13 +760,13 @@ successfully.
You can now run the example (note that if you build your program in the scratch
directory you must run it out of the scratch directory):
::
.. sourcecode:: bash
./waf --run scratch/myfirst
$ ./waf --run scratch/myfirst
You should see some output:
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -794,14 +794,14 @@ summary page for our |ns3| development tree.
At the top of the page, you will see a number of links,
::
.. sourcecode:: text
summary | shortlog | changelog | graph | tags | files
Go ahead and select the ``files`` link. This is what the top-level of
most of our *repositories* will look:
::
.. sourcecode:: text
drwxr-xr-x [up]
drwxr-xr-x bindings python files

76
doc/tutorial/source/getting-started.rst
View File

@@ -1,5 +1,5 @@
.. include:: replace.txt
.. include:: replace.txt
.. highlight:: bash
Getting Started
---------------
@@ -89,11 +89,11 @@ get a copy of a release by typing the following into your Linux shell
::
cd
mkdir workspace
cd workspace
wget http://www.nsnam.org/releases/ns-allinone-3.17.tar.bz2
tar xjf ns-allinone-3.17.tar.bz2
$ cd
$ mkdir workspace
$ cd workspace
$ wget http://www.nsnam.org/releases/ns-allinone-3.17.tar.bz2
$ tar xjf ns-allinone-3.17.tar.bz2
If you change into the directory ``ns-allinone-3.17`` you should see a
number of files:
@@ -123,10 +123,10 @@ following into your Linux shell (assuming you have installed Mercurial):
::
cd
mkdir workspace
cd workspace
hg clone http://code.nsnam.org/bake
$ cd
$ mkdir workspace
$ cd workspace
$ hg clone http://code.nsnam.org/bake
As the hg (Mercurial) command executes, you should see something like the
following displayed,
@@ -191,9 +191,9 @@ to put bake into your path, such as follows (Linux bash shell example):
::
export BAKE_HOME=`pwd`/bake
export PATH=$PATH:$BAKE_HOME
export PYTHONPATH=$PYTHONPATH:$BAKE_HOME
$ export BAKE_HOME=`pwd`/bake
$ export PATH=$PATH:$BAKE_HOME
$ export PYTHONPATH=$PYTHONPATH:$BAKE_HOME
However, setting environment variables is not strictly necessary to
complete this tutorial, so we'll call bake directly by specifying the path
@@ -203,14 +203,14 @@ Step into the workspace directory and type the following into your shell:
::
./bake.py configure -e ns-3-dev
$ ./bake.py configure -e ns-3-dev
Next, we'l ask bake to check whether we have enough tools to download
various components. Type:
::
./bake.py check
$ ./bake.py check
You should see something like the following,
@@ -232,7 +232,9 @@ You should see something like the following,
> patch tool - OK
> autoreconf tool - OK
> Path searched for tools: /usr/lib64/qt-3.3/bin /usr/lib64/ccache /usr/local/bin /bin /usr/bin /usr/local/sbin /usr/sbin /sbin /home/tomh/bin bin
> Path searched for tools: /usr/lib64/qt-3.3/bin /usr/lib64/ccache
/usr/local/bin /bin /usr/bin /usr/local/sbin /usr/sbin /sbin
/home/tomh/bin bin
In particular, download tools such as Mercurial, CVS, GIT, and Bazaar
are our principal concerns at this point, since they allow us to fetch
@@ -286,7 +288,7 @@ Type the following:
::
./build.py --enable-examples --enable-tests
$ ./build.py --enable-examples --enable-tests
Because we are working with examples and tests in this tutorial, and
because they are not built by default in |ns3|, the arguments for
@@ -323,7 +325,7 @@ following magic words:
brite click openflow
visualizer
Leaving directory `./ns-3.17`
Leaving directory `./ns-3.17'
Regarding the portion about modules not built:
@@ -347,7 +349,7 @@ may continue to use it to build |ns3|. Type
::
./bake.py build
$ ./bake.py build
and you should see something like:
@@ -364,7 +366,7 @@ command tells you; it may give a hint as to a missing dependency:
::
./bake.py show
$ ./bake.py show
This will list out the various dependencies of the packages you are
trying to build.
@@ -392,8 +394,8 @@ following commands,
::
./waf clean
./waf -d optimized --enable-examples --enable-tests configure
$ ./waf clean
$ ./waf -d optimized --enable-examples --enable-tests configure
This runs Waf out of the local directory (which is provided as a convenience
for you). The first command to clean out the previous build is not
@@ -476,15 +478,15 @@ Now go ahead and switch back to the debug build that includes the examples and t
::
./waf clean
./waf -d debug --enable-examples --enable-tests configure
$ ./waf clean
$ ./waf -d debug --enable-examples --enable-tests configure
The build system is now configured and you can build the debug versions of
the |ns3| programs by simply typing
::
./waf
$ ./waf
Okay, sorry, I made you build the |ns3| part of the system twice,
but now you know how to change the configuration and build optimized code.
@@ -498,7 +500,7 @@ you could reconfigure using the following command that also includes the example
::
./waf configure -d debug --enable-sudo --enable-examples --enable-tests
$ ./waf configure -d debug --enable-sudo --enable-examples --enable-tests
If you do this, waf will have run sudo to change the socket creator programs of the
emulation code to run as root. There are many other configure- and build-time options
@@ -506,7 +508,7 @@ available in waf. To explore these options, type:
::
./waf --help
$ ./waf --help
We'll use some of the testing-related commands in the next section.
@@ -517,7 +519,7 @@ the ``-o`` option to configure; e.g.
::
./waf configure -d debug -o build/debug --enable-examples --enable-tests
$ ./waf configure -d debug -o build/debug --enable-examples --enable-tests
This allows users to work with multiple builds rather than always
overwriting the last build.
@@ -528,16 +530,16 @@ Say one wants to use Clang C++ compiler, command ``clang++``; it's done by
::
CXX="clang++" ./waf configure
./waf build
$ CXX="clang++" ./waf configure
$ ./waf build
One can also set up waf to do distributed compilation with ``distcc`` in
a similar way:
::
CXX="distcc g++" ./waf configure
./waf build
$ CXX="distcc g++" ./waf configure
$ ./waf build
More info on distcc and distributed compilation can be found on it's
`project page
@@ -552,7 +554,7 @@ You can run the unit tests of the |ns3| distribution by running the
::
./test.py -c core
$ ./test.py -c core
These tests are run in parallel by waf. You should eventually
see a report saying that,
@@ -617,7 +619,7 @@ ubiquitous hello world program by typing the following:
::
./waf --run hello-simulator
$ ./waf --run hello-simulator
Waf first checks to make sure that the program is built correctly and
executes a build if required. Waf then executes the program, which
@@ -644,7 +646,7 @@ type the following,
::
./waf configure -d debug --enable-examples --enable-tests
$ ./waf configure -d debug --enable-examples --enable-tests
to tell ``waf`` to build the debug versions of the |ns3|
programs that includes the examples and tests. You must still build
@@ -652,7 +654,7 @@ the actual debug version of the code by typing,
::
./waf
$ ./waf
Now, if you run the ``hello-simulator`` program, you should see the
expected output.

80
doc/tutorial/source/tracing.rst
View File

@@ -1,5 +1,7 @@
.. include:: replace.txt
.. highlight:: cpp
.. role:: raw-role(raw)
:format: html latex
Tracing
-------
@@ -426,14 +428,14 @@ called with the parameters provided by the source.
If you now build and run this example,
::
.. sourcecode:: bash
./waf --run fourth
$ ./waf --run fourth
you will see the output from the ``IntTrace`` function execute as soon as the
trace source is hit:
::
.. sourcecode:: bash
Traced 0 to 1234
@@ -679,9 +681,9 @@ The easiest way to do this is to grep around in the |ns3| codebase for someone
who has already figured it out, You should always try to copy someone else's
working code before you start to write your own. Try something like:
::
.. sourcecode:: bash
find . -name '*.cc' | xargs grep CourseChange | grep Connect
$ find . -name '*.cc' | xargs grep CourseChange | grep Connect
and you may find your answer along with working code. For example, in this
case, ``./ns-3-dev/examples/wireless/mixed-wireless.cc`` has something
@@ -732,7 +734,7 @@ connect.
You are looking at the same information for the RandomWalk2dMobilityModel; and
the information you want is now right there in front of you in the Doxygen:
::
.. sourcecode:: bash
This object is accessible through the following paths with Config::Set and Config::Connect:
@@ -756,7 +758,7 @@ going to be looking for is found in the base class as we have seen.
Look further down in the ``GetTypeId`` doxygen. You will find,
::
.. sourcecode:: bash
No TraceSources defined for this type.
TraceSources defined in parent class ns3::MobilityModel:
@@ -788,9 +790,9 @@ The easiest way to do this is to grep around in the |ns3| codebase for someone
who has already figured it out, You should always try to copy someone else's
working code. Try something like:
::
.. sourcecode:: bash
find . -name '*.cc' | xargs grep CourseChange | grep Connect
$ find . -name '*.cc' | xargs grep CourseChange | grep Connect
and you may find your answer along with working code. For example, in this
case, ``./ns-3-dev/examples/wireless/mixed-wireless.cc`` has something
@@ -812,7 +814,7 @@ there is a callback function there which you can use. Sure enough, there is:
...
}
Take my Word for It
Take My Word for It
~~~~~~~~~~~~~~~~~~~
If there are no examples to work from, this can be, well, challenging to
@@ -899,9 +901,9 @@ We are probably going to be interested in some kind of declaration in the
we know this declaration is going to have to be in some kind of header file,
so just grep for it using:
::
.. sourcecode:: bash
find . -name '*.h' | xargs grep TracedCallback
$ find . -name '*.h' | xargs grep TracedCallback
You'll see 124 lines fly by (I piped this through wc to see how bad it was).
Although that may seem like it, that's not really a lot. Just pipe the output
@@ -943,7 +945,7 @@ in your favorite editor to see what is happening.
You will see a comment at the top of the file that should be comforting:
::
.. sourcecode:: text
An ns3::TracedCallback has almost exactly the same API as a normal ns3::Callback but
instead of forwarding calls to a single function (as an ns3::Callback normally does),
@@ -1019,7 +1021,7 @@ If you look down through the file, you will see a lot of probably almost
incomprehensible template code. You will eventually come to some Doxygen for
the Callback template class, though. Fortunately, there is some English:
::
.. sourcecode:: text
This class template implements the Functor Design Pattern.
It is used to declare the type of a Callback:
@@ -1179,7 +1181,7 @@ trace sources" to see what we have to work with. Recall that this is found
in the |ns3| Doxygen in the "C++ Constructs Used by All Modules" Module section. If you scroll
through the list, you will eventually find:
::
.. sourcecode:: bash
ns3::TcpNewReno
CongestionWindow: The TCP connection's congestion window
@@ -1189,9 +1191,9 @@ file ``src/internet/model/tcp-socket-base.cc`` while congestion control
variants are in files such as ``src/internet/model/tcp-newreno.cc``.
If you don't know this a priori, you can use the recursive grep trick:
::
.. sourcecode:: bash
find . -name '*.cc' | xargs grep -i tcp
$ find . -name '*.cc' | xargs grep -i tcp
You will find page after page of instances of tcp pointing you to that file.
@@ -1247,9 +1249,9 @@ modify, rather than starting from scratch. So the first order of business now
is to find some code that already hooks the "CongestionWindow" trace source
and see if we can modify it. As usual, grep is your friend:
::
.. sourcecode:: bash
find . -name '*.cc' | xargs grep CongestionWindow
$ find . -name '*.cc' | xargs grep CongestionWindow
This will point out a couple of promising candidates:
``examples/tcp/tcp-large-transfer.cc`` and
@@ -1954,10 +1956,10 @@ Since we have provided the file ``fifth.cc`` for you, if you have built
your distribution (in debug mode since it uses NS_LOG -- recall that optimized
builds optimize out NS_LOGs) it will be waiting for you to run.
::
.. sourcecode:: bash
./waf --run fifth
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-dev/ns-3-dev/build
$ ./waf --run fifth
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-dev/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-dev/ns-3-dev/build'
'build' finished successfully (0.684s)
1.20919 1072
@@ -1976,9 +1978,9 @@ information along with those RxDrop messages. We will remedy that soon, but I'm
sure you can't wait to see the results of all of this work. Let's redirect that
output to a file called ``cwnd.dat``:
::
.. sourcecode:: bash
./waf --run fifth > cwnd.dat 2>&1
$ ./waf --run fifth > cwnd.dat 2>&1
Now edit up "cwnd.dat" in your favorite editor and remove the waf build status
and drop lines, leaving only the traced data (you could also comment out the
@@ -1988,8 +1990,9 @@ script to get rid of the drop prints just as easily.
You can now run gnuplot (if you have it installed) and tell it to generate some
pretty pictures:
::
.. sourcecode:: bash
$ gnuplot
gnuplot> set terminal png size 640,480
gnuplot> set output "cwnd.png"
gnuplot> plot "cwnd.dat" using 1:2 title 'Congestion Window' with linespoints
@@ -2187,21 +2190,21 @@ mean that "something" is an |ns3| Object on which you can hang |ns3|
Now, back to the example. If you now build and run this example,
::
.. sourcecode:: bash
./waf --run sixth
$ ./waf --run sixth
you will see the same messages appear as when you ran "fifth", but two new
files will appear in the top-level directory of your |ns3| distribution.
::
.. sourcecode:: bash
sixth.cwnd sixth.pcap
Since "sixth.cwnd" is an ASCII text file, you can view it with ``cat``
or your favorite file viewer.
::
.. sourcecode:: bash
1.20919 536 1072
1.21511 1072 1608
@@ -2215,7 +2218,7 @@ There are no extraneous prints in the file, no parsing or editing is required.
Since "sixth.pcap" is a pcap file, you can fiew it with ``tcpdump``.
::
.. sourcecode:: bash
reading from file ../../sixth.pcap, link-type PPP (PPP)
1.251507 IP 10.1.1.1.49153 > 10.1.1.2.8080: . 17689:18225(536) ack 1 win 65535
@@ -2305,14 +2308,13 @@ There are subtleties that prevent all four classes from behaving identically,
but we do strive to make them all work as similarly as possible; and whenever
possible there are analogs for all methods in all classes.
::
| pcap | ascii |
-----------------+------+-------|
Device Helper | | |
-----------------+------+-------|
Protocol Helper | | |
-----------------+------+-------|
+-----------------+----------------------+----------------------+
| \ | pcap | ascii |
+=================+======================+======================+
| Device Helper | :raw-role:`✓` | :raw-role:`✓` |
+-----------------+----------------------+----------------------+
| Protocol Helper | :raw-role:`✓` | :raw-role:`✓` |
+-----------------+----------------------+----------------------+
We use an approach called a ``mixin`` to add tracing functionality to our
helper classes. A ``mixin`` is a class that provides functionality to that

185
doc/tutorial/source/tweaking.rst
View File

@@ -1,4 +1,5 @@
.. include:: replace.txt
.. highlight:: cpp
Tweaking
@@ -80,16 +81,16 @@ Let's use the NS_LOG environment variable to turn on some more logging, but
first, just to get our bearings, go ahead and run the last script just as you
did previously,
::
.. sourcecode:: bash
./waf --run scratch/myfirst
$ ./waf --run scratch/myfirst
You should see the now familiar output of the first |ns3| example
program
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
$ Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
'build' finished successfully (0.413s)
Sent 1024 bytes to 10.1.1.2
@@ -121,13 +122,13 @@ all lower levels. In this case, we have enabled ``NS_LOG_INFO``,
increase the logging level and get more information without changing the
script and recompiling by setting the NS_LOG environment variable like this:
::
.. sourcecode:: bash
export NS_LOG=UdpEchoClientApplication=level_all
$ export NS_LOG=UdpEchoClientApplication=level_all
This sets the shell environment variable ``NS_LOG`` to the string,
::
.. sourcecode:: bash
UdpEchoClientApplication=level_all
@@ -137,9 +138,9 @@ we are going to turn on all of the debugging levels for the application. If
you run the script with NS_LOG set this way, the |ns3| logging
system will pick up the change and you should see the following output:
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
'build' finished successfully (0.404s)
UdpEchoClientApplication:UdpEchoClient()
@@ -183,9 +184,9 @@ wonder where the string "``Received 1024 bytes from 10.1.1.2``" comes
from. You can resolve this by OR'ing the ``prefix_func`` level into the
``NS_LOG`` environment variable. Try doing the following,
::
.. sourcecode:: bash
export 'NS_LOG=UdpEchoClientApplication=level_all|prefix_func'
$ export 'NS_LOG=UdpEchoClientApplication=level_all|prefix_func'
Note that the quotes are required since the vertical bar we use to indicate an
OR operation is also a Unix pipe connector.
@@ -194,7 +195,7 @@ Now, if you run the script you will see that the logging system makes sure
that every message from the given log component is prefixed with the component
name.
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -219,9 +220,9 @@ remaining message must be coming from the UDP echo server application. We
can enable that component by entering a colon separated list of components in
the NS_LOG environment variable.
::
.. sourcecode:: bash
export 'NS_LOG=UdpEchoClientApplication=level_all|prefix_func:
$ export 'NS_LOG=UdpEchoClientApplication=level_all|prefix_func:
UdpEchoServerApplication=level_all|prefix_func'
Warning: You will need to remove the newline after the ``:`` in the
@@ -231,7 +232,7 @@ Now, if you run the script you will see all of the log messages from both the
echo client and server applications. You may see that this can be very useful
in debugging problems.
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -258,15 +259,15 @@ in debugging problems.
It is also sometimes useful to be able to see the simulation time at which a
log message is generated. You can do this by ORing in the prefix_time bit.
::
.. sourcecode:: bash
export 'NS_LOG=UdpEchoClientApplication=level_all|prefix_func|prefix_time:
$ export 'NS_LOG=UdpEchoClientApplication=level_all|prefix_func|prefix_time:
UdpEchoServerApplication=level_all|prefix_func|prefix_time'
Again, you will have to remove the newline above. If you run the script now,
you should see the following output:
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -314,9 +315,9 @@ are not seeing as well. You can very easily follow the entire process by
turning on all of the logging components in the system. Try setting the
``NS_LOG`` variable to the following,
::
.. sourcecode:: bash
export 'NS_LOG=*=level_all|prefix_func|prefix_time'
$ export 'NS_LOG=*=level_all|prefix_func|prefix_time'
The asterisk above is the logging component wildcard. This will turn on all
of the logging in all of the components used in the simulation. I won't
@@ -324,9 +325,9 @@ reproduce the output here (as of this writing it produces 1265 lines of output
for the single packet echo) but you can redirect this information into a file
and look through it with your favorite editor if you like,
::
.. sourcecode:: bash
./waf --run scratch/myfirst > log.out 2>&1
$ ./waf --run scratch/myfirst > log.out 2>&1
I personally use this extremely verbose version of logging when I am presented
with a problem and I have no idea where things are going wrong. I can follow the
@@ -374,16 +375,16 @@ right before the lines,
Now build the script using waf and clear the ``NS_LOG`` variable to turn
off the torrent of logging we previously enabled:
::
.. sourcecode:: bash
./waf
export NS_LOG=
$ ./waf
$ export NS_LOG=
Now, if you run the script,
::
.. sourcecode:: bash
./waf --run scratch/myfirst
$ ./waf --run scratch/myfirst
you will ``not`` see your new message since its associated logging
component (``FirstScriptExample``) has not been enabled. In order to see your
@@ -391,14 +392,14 @@ message you will have to enable the ``FirstScriptExample`` logging component
with a level greater than or equal to ``NS_LOG_INFO``. If you just want to
see this particular level of logging, you can enable it by,
::
.. sourcecode:: bash
export NS_LOG=FirstScriptExample=info
$ export NS_LOG=FirstScriptExample=info
If you now run the script you will see your new "Creating Topology" log
message,
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -441,16 +442,16 @@ ahead and add that two lines of code to the ``scratch/myfirst.cc`` script at
the start of ``main``. Go ahead and build the script and run it, but ask
the script for help in the following way,
::
.. sourcecode:: bash
./waf --run "scratch/myfirst --PrintHelp"
$ ./waf --run "scratch/myfirst --PrintHelp"
This will ask Waf to run the ``scratch/myfirst`` script and pass the command
line argument ``--PrintHelp`` to the script. The quotes are required to
sort out which program gets which argument. The command line parser will
now see the ``--PrintHelp`` argument and respond with,
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -481,14 +482,14 @@ listing says that we should provide a ``TypeId``. This corresponds to the
class name of the class to which the ``Attributes`` belong. In this case it
will be ``ns3::PointToPointNetDevice``. Let's go ahead and type in,
::
.. sourcecode:: bash
./waf --run "scratch/myfirst --PrintAttributes=ns3::PointToPointNetDevice"
$ ./waf --run "scratch/myfirst --PrintAttributes=ns3::PointToPointNetDevice"
The system will print out all of the ``Attributes`` of this kind of net device.
Among the ``Attributes`` you will see listed is,
::
.. sourcecode:: bash
--ns3::PointToPointNetDevice::DataRate=[32768bps]:
The default data rate for point to point links
@@ -521,13 +522,13 @@ Go ahead and build the new script with Waf (``./waf``) and let's go back
and enable some logging from the UDP echo server application and turn on the
time prefix.
::
.. sourcecode:: bash
export 'NS_LOG=UdpEchoServerApplication=level_all|prefix_time'
$ export 'NS_LOG=UdpEchoServerApplication=level_all|prefix_time'
If you run the script, you should now see the following output,
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -545,7 +546,7 @@ If you run the script, you should now see the following output,
Recall that the last time we looked at the simulation time at which the packet
was received by the echo server, it was at 2.00369 seconds.
::
.. sourcecode:: bash
2.00369s UdpEchoServerApplication:HandleRead(): Received 1024 bytes from 10.1.1.1
@@ -557,9 +558,9 @@ If we were to provide a new ``DataRate`` using the command line, we could
speed our simulation up again. We do this in the following way, according to
the formula implied by the help item:
::
.. sourcecode:: bash
./waf --run "scratch/myfirst --ns3::PointToPointNetDevice::DataRate=5Mbps"
$ ./waf --run "scratch/myfirst --ns3::PointToPointNetDevice::DataRate=5Mbps"
This will set the default value of the ``DataRate`` ``Attribute`` back to
five megabits per second. Are you surprised by the result? It turns out that
@@ -568,30 +569,30 @@ the speed-of-light delay of the channel as well. We can ask the command line
system to print out the ``Attributes`` of the channel just like we did for
the net device:
::
.. sourcecode:: bash
./waf --run "scratch/myfirst --PrintAttributes=ns3::PointToPointChannel"
$ ./waf --run "scratch/myfirst --PrintAttributes=ns3::PointToPointChannel"
We discover the ``Delay`` ``Attribute`` of the channel is set in the following
way:
::
.. sourcecode:: bash
--ns3::PointToPointChannel::Delay=[0ns]:
Transmission delay through the channel
We can then set both of these default values through the command line system,
::
.. sourcecode:: bash
./waf --run "scratch/myfirst
$ ./waf --run "scratch/myfirst
--ns3::PointToPointNetDevice::DataRate=5Mbps
--ns3::PointToPointChannel::Delay=2ms"
in which case we recover the timing we had when we explicitly set the
``DataRate`` and ``Delay`` in the script:
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -620,9 +621,9 @@ you should be able to control the number of packets echoed from the command
line. Since we're nice folks, we'll tell you that your command line should
end up looking something like,
::
.. sourcecode:: bash
./waf --run "scratch/myfirst
$ ./waf --run "scratch/myfirst
--ns3::PointToPointNetDevice::DataRate=5Mbps
--ns3::PointToPointChannel::Delay=2ms
--ns3::UdpEchoClient::MaxPackets=2"
@@ -666,11 +667,11 @@ should see your new ``User Argument`` listed in the help display.
Try,
::
.. sourcecode:: bash
./waf --run "scratch/myfirst --PrintHelp"
$ ./waf --run "scratch/myfirst --PrintHelp"
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -687,13 +688,13 @@ Try,
If you want to specify the number of packets to echo, you can now do so by
setting the ``--nPackets`` argument in the command line,
::
.. sourcecode:: bash
./waf --run "scratch/myfirst --nPackets=2"
$ ./waf --run "scratch/myfirst --nPackets=2"
You should now see
::
.. sourcecode:: bash
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
@@ -821,9 +822,9 @@ the popular trace points that log "+", "-", "d", and "r" events.
You can now build the script and run it from the command line:
::
.. sourcecode:: bash
./waf --run scratch/myfirst
$ ./waf --run scratch/myfirst
Just as you have seen many times before, you will see some messages from Waf and then
"'build' finished successfully" with some number of messages from
@@ -856,31 +857,32 @@ space after it). This character will have the following meaning:
* ``r``: A packet was received by the net device.
Let's take a more detailed view of the first line in the trace file. I'll
break it down into sections (indented for clarity) with a two digit reference
break it down into sections (indented for clarity) with a reference
number on the left side:
::
.. sourcecode:: text
:linenos:
00 +
01 2
02 /NodeList/0/DeviceList/0/$ns3::PointToPointNetDevice/TxQueue/Enqueue
03 ns3::PppHeader (
04 Point-to-Point Protocol: IP (0x0021))
05 ns3::Ipv4Header (
06 tos 0x0 ttl 64 id 0 protocol 17 offset 0 flags [none]
07 length: 1052 10.1.1.1 > 10.1.1.2)
08 ns3::UdpHeader (
09 length: 1032 49153 > 9)
10 Payload (size=1024)
+
2
/NodeList/0/DeviceList/0/$ns3::PointToPointNetDevice/TxQueue/Enqueue
ns3::PppHeader (
Point-to-Point Protocol: IP (0x0021))
ns3::Ipv4Header (
tos 0x0 ttl 64 id 0 protocol 17 offset 0 flags [none]
length: 1052 10.1.1.1 > 10.1.1.2)
ns3::UdpHeader (
length: 1032 49153 > 9)
Payload (size=1024)
The first line of this expanded trace event (reference number 00) is the
The first section of this expanded trace event (reference number 0) is the
operation. We have a ``+`` character, so this corresponds to an
*enqueue* operation on the transmit queue. The second line (reference 01)
*enqueue* operation on the transmit queue. The second section (reference 1)
is the simulation time expressed in seconds. You may recall that we asked the
``UdpEchoClientApplication`` to start sending packets at two seconds. Here
we see confirmation that this is, indeed, happening.
The next line of the example trace (reference 02) tell us which trace source
The next section of the example trace (reference 2) tell us which trace source
originated this event (expressed in the tracing namespace). You can think
of the tracing namespace somewhat like you would a filesystem namespace. The
root of the namespace is the ``NodeList``. This corresponds to a container
@@ -899,11 +901,11 @@ Recall that the operation ``+`` found at reference 00 meant that an enqueue
operation happened on the transmit queue of the device. This is reflected in
the final segments of the "trace path" which are ``TxQueue/Enqueue``.
The remaining lines in the trace should be fairly intuitive. References 03-04
The remaining sections in the trace should be fairly intuitive. References 3-4
indicate that the packet is encapsulated in the point-to-point protocol.
References 05-07 show that the packet has an IP version four header and has
References 5-7 show that the packet has an IP version four header and has
originated from IP address 10.1.1.1 and is destined for 10.1.1.2. References
08-09 show that this packet has a UDP header and, finally, reference 10 shows
8-9 show that this packet has a UDP header and, finally, reference 10 shows
that the payload is the expected 1024 bytes.
The next line in the trace file shows the same packet being dequeued from the
@@ -912,17 +914,18 @@ transmit queue on the same node.
The Third line in the trace file shows the packet being received by the net
device on the node with the echo server. I have reproduced that event below.
::
.. sourcecode:: text
:linenos:
00 r
01 2.25732
02 /NodeList/1/DeviceList/0/$ns3::PointToPointNetDevice/MacRx
03 ns3::Ipv4Header (
04 tos 0x0 ttl 64 id 0 protocol 17 offset 0 flags [none]
05 length: 1052 10.1.1.1 > 10.1.1.2)
06 ns3::UdpHeader (
07 length: 1032 49153 > 9)
08 Payload (size=1024)
r
2.25732
/NodeList/1/DeviceList/0/$ns3::PointToPointNetDevice/MacRx
ns3::Ipv4Header (
tos 0x0 ttl 64 id 0 protocol 17 offset 0 flags [none]
length: 1052 10.1.1.1 > 10.1.1.2)
ns3::UdpHeader (
length: 1032 49153 > 9)
Payload (size=1024)
Notice that the trace operation is now ``r`` and the simulation time has
increased to 2.25732 seconds. If you have been following the tutorial steps
@@ -968,9 +971,9 @@ node 1-device 0, respectively.
Once you have added the line of code to enable pcap tracing, you can run the
script in the usual way:
::
.. sourcecode:: bash
./waf --run scratch/myfirst
$ ./waf --run scratch/myfirst
If you look at the top level directory of your distribution, you should now
see three log files: ``myfirst.tr`` is the ASCII trace file we have
@@ -982,9 +985,9 @@ Reading output with tcpdump
The easiest thing to do at this point will be to use ``tcpdump`` to look
at the ``pcap`` files.
::
.. sourcecode:: bash
tcpdump -nn -tt -r myfirst-0-0.pcap
$ tcpdump -nn -tt -r myfirst-0-0.pcap
reading from file myfirst-0-0.pcap, link-type PPP (PPP)
2.000000 IP 10.1.1.1.49153 > 10.1.1.2.9: UDP, length 1024
2.514648 IP 10.1.1.2.9 > 10.1.1.1.49153: UDP, length 1024