diff --git a/doc/manual/source/attributes.rst b/doc/manual/source/attributes.rst index 3c3472280..ee2e65557 100644 --- a/doc/manual/source/attributes.rst +++ b/doc/manual/source/attributes.rst @@ -1,4 +1,6 @@ .. include:: replace.txt +.. highlight:: cpp + .. _Attributes: @@ -405,7 +407,9 @@ Object Name Service-based access Another way to get at the attribute is to use the object name service facility. Here, this attribute is found using a name string. This approach is useful if one doesn't have access to the underlying pointers and it is difficult to -determine the required concrete configuration namespaced path.:: +determine the required concrete configuration namespaced path. + +:: Names::Add ("server", serverNode); Names::Add ("server/eth0", serverDevice); @@ -414,7 +418,7 @@ determine the required concrete configuration namespaced path.:: Config::Set ("/Names/server/eth0/TxQueue/MaxPackets", UintegerValue (25)); -:ref:`Object-names` for a fuller treatment of the |ns3| configuration namespace. +See :ref:`Object-names` for a fuller treatment of the |ns3| configuration namespace. Setting through constructors helper classes +++++++++++++++++++++++++++++++++++++++++++ @@ -737,7 +741,9 @@ The example shows::: Simulator::Destroy (); -After running, you can open the output-attributes.txt file and see::: +After running, you can open the output-attributes.txt file and see: + +.. sourcecode:: text default ns3::RealtimeSimulatorImpl::SynchronizationMode "BestEffort" default ns3::RealtimeSimulatorImpl::HardLimit "+100000000.0ns" @@ -769,7 +775,9 @@ are recorded. Finally, the value of the instance of A that was rooted in the configuration namespace is shown. In a real ns-3 program, many more models, attributes, and defaults would be shown. -An XML version also exists in ``output-attributes.xml``::: +An XML version also exists in ``output-attributes.xml``: + +.. sourcecode:: xml @@ -858,13 +866,17 @@ in the `|ns3| Overview `_ presentation. To use this feature, one must install libgtk and libgtk-dev; an example -Ubuntu installation command is::: +Ubuntu installation command is: - sudo apt-get install libgtk2.0-0 libgtk2.0-dev +.. sourcecode:: bash -To check whether it is configured or not, check the output of the step::: + $ sudo apt-get install libgtk2.0-0 libgtk2.0-dev - ./waf configure --enable-examples --enable-tests +To check whether it is configured or not, check the output of the step: + +.. sourcecode:: bash + + $ ./waf configure --enable-examples --enable-tests ---- Summary of optional NS-3 features: Python Bindings : enabled @@ -873,10 +885,12 @@ To check whether it is configured or not, check the output of the step::: GtkConfigStore : not enabled (library 'gtk+-2.0 >= 2.12' not found) In the above example, it was not enabled, so it cannot be used until a suitable -version is installed and:: +version is installed and: - ./waf configure --enable-examples --enable-tests - ./waf +.. sourcecode:: bash + + $ ./waf configure --enable-examples --enable-tests + $ ./waf is rerun. @@ -895,6 +909,7 @@ when you are done. Future work +++++++++++ There are a couple of possible improvements: + * save a unique version number with date and time at start of file * save rng initial seed somewhere. * make each RandomVariable serialize its own initial seed and re-read it later diff --git a/doc/manual/source/callbacks.rst b/doc/manual/source/callbacks.rst index 6436fcf21..30b4e4de6 100644 --- a/doc/manual/source/callbacks.rst +++ b/doc/manual/source/callbacks.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp Callbacks --------- @@ -364,11 +365,11 @@ Now, we need to tie together this callback instance and the actual target functi callback-- this is important. We can pass in any such properly-typed function to this callback. Let's look at this more closely:: - static double CbOne (double a, double b) {} - ^ ^ ^ - | ---| ------| - | | | - Callback one; + static double CbOne (double a, double b) {} + ^ ^ ^ + | | | + | | | + Callback one; You can only bind a function to a callback if they have the matching signature. The first template argument is the return type, and the additional template diff --git a/doc/manual/source/enable-modules.rst b/doc/manual/source/enable-modules.rst index d7fd025e2..e395acb97 100644 --- a/doc/manual/source/enable-modules.rst +++ b/doc/manual/source/enable-modules.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: bash Enabling Subsets of |ns3| Modules --------------------------------- @@ -10,11 +11,15 @@ This chapter discusses how to enable only the |ns3| modules that you are interst How to enable a subset of |ns3|'s modules ***************************************** -If shared libraries are being built, then enabling a module will cause at least one library to be built: :: +If shared libraries are being built, then enabling a module will cause at least one library to be built: + +.. sourcecode:: text libns3-modulename.so -If the module has a test library and test libraries are being built, then :: +If the module has a test library and test libraries are being built, then + +.. sourcecode:: text libns3-modulename-test.so @@ -31,29 +36,37 @@ Enable modules using waf's --enable-modules option To enable only the core module with example and tests, for example, try these commands: :: - ./waf clean - ./waf configure --enable-examples --enable-tests --enable-modules=core - ./waf build - cd build/debug/ - ls + $ ./waf clean + $ ./waf configure --enable-examples --enable-tests --enable-modules=core + $ ./waf build + $ cd build/debug/ + $ ls -and the following libraries should be present: :: +and the following libraries should be present: + +.. sourcecode:: text bindings libns3-core.so ns3 scratch utils examples libns3-core-test.so samples src Note the ``./waf clean`` step is done here only to make it more obvious which module libraries were built. You don't have to do ``./waf clean`` in order to enable subsets of modules. -Running test.py will cause only those tests that depend on module core to be run: :: +Running test.py will cause only those tests that depend on module core to be run: +.. sourcecode:: text + 24 of 24 tests passed (24 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors) -Repeat the above steps for the "network" module instead of the "core" module, and the following will be built, since network depends on core: :: +Repeat the above steps for the "network" module instead of the "core" module, and the following will be built, since network depends on core: + +.. sourcecode:: text bindings libns3-core.so libns3-network.so ns3 scratch utils examples libns3-core-test.so libns3-network-test.so samples src -Running test.py will cause those tests that depend on only the core and network modules to be run: :: +Running test.py will cause those tests that depend on only the core and network modules to be run: + +.. sourcecode:: text 31 of 31 tests passed (31 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors) @@ -74,9 +87,11 @@ The maintained version of the .ns3rc file in the |ns3| source code repository re Assuming that you are in the top level |ns3| directory, you can get a copy of the .ns3rc file that is in the ``utils`` directory as follows: :: - cp utils/.ns3rc . + $ cp utils/.ns3rc . -The .ns3rc file should now be in your top level |ns3| directory, and it contains the following: :: +The .ns3rc file should now be in your top level |ns3| directory, and it contains the following: + +.. sourcecode:: python #! /usr/bin/env python @@ -92,7 +107,9 @@ The .ns3rc file should now be in your top level |ns3| directory, and it contains # Set this equal to true if you want tests to be run. tests_enabled = False -Use your favorite editor to modify the .ns3rc file to only enable the core module with examples and tests like this: :: +Use your favorite editor to modify the .ns3rc file to only enable the core module with examples and tests like this: + +.. sourcecode:: python #! /usr/bin/env python @@ -110,28 +127,36 @@ Use your favorite editor to modify the .ns3rc file to only enable the core modul Only the core module will be enabled now if you try these commands: :: - ./waf clean - ./waf configure - ./waf build - cd build/debug/ - ls + $ ./waf clean + $ ./waf configure + $ ./waf build + $ cd build/debug/ + $ ls -and the following libraries should be present: :: +and the following libraries should be present: + +.. sourcecode:: text bindings libns3-core.so ns3 scratch utils examples libns3-core-test.so samples src Note the ``./waf clean`` step is done here only to make it more obvious which module libraries were built. You don't have to do ``./waf clean`` in order to enable subsets of modules. -Running test.py will cause only those tests that depend on module core to be run: :: +Running test.py will cause only those tests that depend on module core to be run: +.. sourcecode:: text + 24 of 24 tests passed (24 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors) -Repeat the above steps for the "network" module instead of the "core" module, and the following will be built, since network depends on core: :: +Repeat the above steps for the "network" module instead of the "core" module, and the following will be built, since network depends on core: + +.. sourcecode:: text bindings libns3-core.so libns3-network.so ns3 scratch utils examples libns3-core-test.so libns3-network-test.so samples src -Running test.py will cause those tests that depend on only the core and network modules to be run: :: +Running test.py will cause those tests that depend on only the core and network modules to be run: + +.. sourcecode:: text 31 of 31 tests passed (31 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors) diff --git a/doc/manual/source/enable-tests.rst b/doc/manual/source/enable-tests.rst index ba44dde55..3325836a9 100644 --- a/doc/manual/source/enable-tests.rst +++ b/doc/manual/source/enable-tests.rst @@ -1,4 +1,6 @@ .. include:: replace.txt +.. highlight:: bash + Enabling/disabling |ns3| Tests and Examples ------------------------------------------- @@ -26,18 +28,22 @@ By default, examples and tests are not built in |ns3|. From the ns-3-allinone directory, you can build |ns3| without any examples or tests simply by doing: :: - ./build.py + $ ./build.py -Running test.py in the top level |ns3| directory now will cause no examples or tests to be run: :: +Running test.py in the top level |ns3| directory now will cause no examples or tests to be run: +.. sourcecode:: text + 0 of 0 tests passed (0 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors) If you would like build |ns3| with examples and tests, then do the following from the ns-3-allinone directory: :: - ./build.py --enable-examples --enable-tests + $ ./build.py --enable-examples --enable-tests -Running test.py in the top level |ns3| directory will cause all of the examples and tests to be run: :: +Running test.py in the top level |ns3| directory will cause all of the examples and tests to be run: +.. sourcecode:: text + 170 of 170 tests passed (170 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors) Enable/disable examples and tests using waf @@ -50,20 +56,24 @@ By default, examples and tests are not built in |ns3|. From the top level |ns3| directory, you can build |ns3| without any examples or tests simply by doing: :: - ./waf configure - ./waf build + $ ./waf configure + $ ./waf build -Running test.py now will cause no examples or tests to be run: :: +Running test.py now will cause no examples or tests to be run: +.. sourcecode:: text + 0 of 0 tests passed (0 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors) If you would like build |ns3| with examples and tests, then do the following from the top level |ns3| directory: :: - ./waf configure --enable-examples --enable-tests - ./waf build + $ ./waf configure --enable-examples --enable-tests + $ ./waf build -Running test.py will cause all of the examples and tests to be run: :: +Running test.py will cause all of the examples and tests to be run: +.. sourcecode:: text + 170 of 170 tests passed (170 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors) Enable/disable examples and tests using the |ns3| configuration file @@ -84,9 +94,11 @@ The maintained version of the .ns3rc file in the |ns3| source code repository re Assuming that you are in the top level |ns3| directory, you can get a copy of the .ns3rc file that is in the ``utils`` directory as follows: :: - cp utils/.ns3rc . + $ cp utils/.ns3rc . -The .ns3rc file should now be in your top level |ns3| directory, and it contains the following: :: +The .ns3rc file should now be in your top level |ns3| directory, and it contains the following: + +.. sourcecode:: python #! /usr/bin/env python @@ -105,16 +117,20 @@ The .ns3rc file should now be in your top level |ns3| directory, and it contains From the top level |ns3| directory, you can build |ns3| without any examples or tests simply by doing: :: - ./waf configure - ./waf build + $ ./waf configure + $ ./waf build -Running test.py now will cause no examples or tests to be run: :: +Running test.py now will cause no examples or tests to be run: +.. sourcecode:: text + 0 of 0 tests passed (0 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors) If you would like build |ns3| with examples and tests, use your favorite editor to change the values in the .ns3rc file for -examples_enabled and tests_enabled file to be True: :: +examples_enabled and tests_enabled file to be True: + +.. sourcecode:: python #! /usr/bin/env python @@ -133,9 +149,11 @@ examples_enabled and tests_enabled file to be True: :: From the top level |ns3| directory, you can build |ns3| with examples and tests simply by doing: :: - ./waf configure - ./waf build + $ ./waf configure + $ ./waf build -Running test.py will cause all of the examples and tests to be run: :: +Running test.py will cause all of the examples and tests to be run: +.. sourcecode:: text + 170 of 170 tests passed (170 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors) diff --git a/doc/manual/source/events.rst b/doc/manual/source/events.rst index bfd3d5983..763713f82 100644 --- a/doc/manual/source/events.rst +++ b/doc/manual/source/events.rst @@ -1,4 +1,6 @@ .. include:: replace.txt +.. highlight:: cpp + .. heading hierarchy: ------------- Chapter @@ -42,7 +44,7 @@ Simulator The Simulator class is the public entry point to access event scheduling facilities. Once a couple of events have been scheduled to start the simulation, the user can start to execute them by entering the simulator -main loop (call Simulator::Run). Once the main loop starts running, it +main loop (call ``Simulator::Run``). Once the main loop starts running, it will sequentially execute all scheduled events in order from oldest to most recent until there are either no more events left in the event queue or Simulator::Stop has been called. @@ -70,7 +72,7 @@ might write this: Which will output: -:: +.. sourcecode:: text handler called with argument arg0=10 and arg1=5 diff --git a/doc/manual/source/gnuplot.rst b/doc/manual/source/gnuplot.rst index ca4ec33be..3ba1f714c 100644 --- a/doc/manual/source/gnuplot.rst +++ b/doc/manual/source/gnuplot.rst @@ -1,5 +1,6 @@ .. include:: replace.txt - +.. highlight:: cpp + Making Plots using the Gnuplot Class ------------------------------------ @@ -25,39 +26,51 @@ See the code from the example plots that are discussed below for details on step An Example Program that Uses the Gnuplot Class ********************************************** -An example program that uses |ns3|'s Gnuplot class can be found here: :: +An example program that uses |ns3|'s Gnuplot class can be found here: + +.. sourcecode:: bash src/stats/examples/gnuplot-example.cc -In order to run this example, do the following: :: +In order to run this example, do the following: - ./waf shell - cd build/debug/src/stats/examples - ./gnuplot-example +.. sourcecode:: bash -This should produce the following gnuplot control files in the directory where the example is located: :: + $ ./waf shell + $ cd build/debug/src/stats/examples + $ ./gnuplot-example + +This should produce the following gnuplot control files in the directory where the example is located: + +.. sourcecode:: text plot-2d.plt plot-2d-with-error-bars.plt plot-3d.plt -In order to process these gnuplot control files, do the following: :: +In order to process these gnuplot control files, do the following: - gnuplot plot-2d.plt - gnuplot plot-2d-with-error-bars.plt - gnuplot plot-3d.plt +.. sourcecode:: bash -This should produce the following graphics files in the directory where the example is located: :: + $ gnuplot plot-2d.plt + $ gnuplot plot-2d-with-error-bars.plt + $ gnuplot plot-3d.plt + +This should produce the following graphics files in the directory where the example is located: + +.. sourcecode:: text plot-2d.png plot-2d-with-error-bars.png plot-3d.png -You can view these graphics files in your favorite graphics viewer. If you have gimp installed on your machine, for example, you can do this: :: +You can view these graphics files in your favorite graphics viewer. If you have gimp installed on your machine, for example, you can do this: - gimp plot-2d.png - gimp plot-2d-with-error-bars.png - gimp plot-3d.png +.. sourcecode:: bash + + $ gimp plot-2d.png + $ gimp plot-2d-with-error-bars.png + $ gimp plot-3d.png An Example 2-Dimensional Plot ***************************** diff --git a/doc/manual/source/hash-functions.rst b/doc/manual/source/hash-functions.rst index 7977ad403..88bea60f2 100644 --- a/doc/manual/source/hash-functions.rst +++ b/doc/manual/source/hash-functions.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp Hash Functions ---------------- diff --git a/doc/manual/source/helpers.rst b/doc/manual/source/helpers.rst index c8c5a98fa..ca6980eec 100644 --- a/doc/manual/source/helpers.rst +++ b/doc/manual/source/helpers.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp Helpers ------- diff --git a/doc/manual/source/how-to-write-tests.rst b/doc/manual/source/how-to-write-tests.rst index afc4355dd..3becadbcb 100644 --- a/doc/manual/source/how-to-write-tests.rst +++ b/doc/manual/source/how-to-write-tests.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp How to write tests ------------------ @@ -46,7 +47,7 @@ more descriptive test case name. You also need to add a block into your wscript to get this test to compile: -:: +.. sourcecode:: python module_test.source = [ 'test/router-test-suite.cc', @@ -64,13 +65,13 @@ is called "router" such as here: Try this command: -:: +.. sourcecode:: bash - ./test.py -s router + $ ./test.py -s router Output such as below should be produced: -:: +.. sourcecode:: text PASS: TestSuite router 1 of 1 tests passed (1 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors) diff --git a/doc/manual/source/logging.rst b/doc/manual/source/logging.rst index eaea17f65..014e46ecf 100644 --- a/doc/manual/source/logging.rst +++ b/doc/manual/source/logging.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp .. heading hierarchy: ------------- Chapter @@ -71,7 +72,7 @@ Logging prefixes This section still needs documentation; bug 1496 is open on this: -:: +.. sourcecode:: bash $ NS_LOG="*=all|prefix_all" ./waf --run scratch-simulator Scratch Simulator @@ -88,16 +89,16 @@ Enabling logging output There are two ways that users typically control logging output. The first is by setting an ``NS_LOG`` environment variable; e.g.: -:: +.. sourcecode:: bash - NS_LOG="*" ./waf --run first + $ NS_LOG="*" ./waf --run first will run the first tutorial program with all logging output. This can be made more granular by selecting individual components: -:: +.. sourcecode:: bash - NS_LOG="Ipv4L3Protocol" ./waf --run first + $ NS_LOG="Ipv4L3Protocol" ./waf --run first The second way to enable this is to use explicit statements in your program, such as in the first tutorial program: diff --git a/doc/manual/source/new-models.rst b/doc/manual/source/new-models.rst index 00b83cc70..b875d0dfe 100644 --- a/doc/manual/source/new-models.rst +++ b/doc/manual/source/new-models.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp Creating a new ns-3 model ------------------------- @@ -408,7 +409,7 @@ Add basic support in the class :: - point-to-point-net-device.h + /* point-to-point-net-device.h */ class ErrorModel; /** @@ -473,7 +474,7 @@ Create null functional script :: - simple-error-model.cc + /* simple-error-model.cc */ // Error model // We want to add an error model to node 3's NetDevice diff --git a/doc/manual/source/new-modules.rst b/doc/manual/source/new-modules.rst index 2018d32dd..dd2cd79e6 100644 --- a/doc/manual/source/new-modules.rst +++ b/doc/manual/source/new-modules.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp Adding a New Module to |ns3| ---------------------------- @@ -20,7 +21,9 @@ example, the spectrum module can be found here: :: src/spectrum A prototypical module has the following directory structure and -required files: :: +required files: + +.. sourcecode:: text src/ module-name/ @@ -39,29 +42,39 @@ Not all directories will be present in each module. Step 2 - Create your new module based on the template module ************************************************************ -A python program is provided in the source directory that will create a skeleton for a new module :: +A python program is provided in the source directory that will create a skeleton for a new module - src/create-module.py +.. sourcecode:: bash -For the purposes of this discussion we will assume that your new module is called "new-module". From the ``src`` directory, do the following to create the new module: :: + $ src/create-module.py - ./create-module.py new-module +For the purposes of this discussion we will assume that your new module is called "new-module". From the ``src`` directory, do the following to create the new module: -Next, cd into ``new-module``; you will find this directory layout: :: +.. sourcecode:: bash - examples helper model test wscript + $ ./create-module.py new-module + +Next, cd into ``new-module``; you will find this directory layout: + +.. sourcecode:: text + + $ examples helper model test wscript We next walk through how to customize this module. All |ns3| modules depend on the 'core' module and usually on other modules. This dependency is specified in the wscript file. Let's assume that 'new-module' depends on the internet, mobility, and aodv modules. Then the call to the function that will -create this module should look like this before editing: :: +create this module should look like this before editing: + +.. sourcecode:: python def build(bld): module = bld.create_ns3_module('new-module', ['core']) -and after editing: :: +and after editing: + +.. sourcecode:: python def build(bld): module = bld.create_ns3_module('new-module', ['internet', 'mobility', 'aodv']) @@ -82,18 +95,24 @@ Step 3 - Adding to your module's source files ********************************************* If your new module has model and/or helper source files, then they -must be specified in your :: +must be specified in your + +.. sourcecode:: text src/new-module/wscript file by modifying it with your text editor. As an example, the source files for the spectrum module are specified -in :: +in + +.. sourcecode:: text src/spectrum/wscript -with the following list of source files: :: +with the following list of source files: + +.. sourcecode:: python module.source = [ 'model/spectrum-model.cc', @@ -112,20 +131,26 @@ Step 4 - Specify your module's header files ******************************************* If your new module has model and/or helper header files, then they -must be specified in your :: +must be specified in your + +.. sourcecode:: text src/new-module/wscript file by modifying it with your text editor. As an example, the header files for the spectrum module are specified -in :: +in + +.. sourcecode:: text src/spectrum/wscript with the following function call, module name, and list of header files. Note that the argument for the function new_task_gen() tells -waf to install this module's headers with the other |ns3| headers: :: +waf to install this module's headers with the other |ns3| headers: + +.. sourcecode:: python headers = bld.new_task_gen(features=['ns3header']) @@ -147,17 +172,23 @@ waf to install this module's headers with the other |ns3| headers: :: Step 5 - Specify your module's tests ************************************ -If your new module has tests, then they must be specified in your :: +If your new module has tests, then they must be specified in your + +.. sourcecode:: text src/new-module/wscript file by modifying it with your text editor. -As an example, the tests for the spectrum module are specified in :: +As an example, the tests for the spectrum module are specified in + +.. sourcecode:: text src/spectrum/wscript -with the following function call and list of test suites: :: +with the following function call and list of test suites: + +.. sourcecode:: python module_test = bld.create_ns3_module_test_library('spectrum') @@ -170,20 +201,26 @@ with the following function call and list of test suites: :: Step 6 - Specify your module's examples *************************************** -If your new module has examples, then they must be specified in your :: +If your new module has examples, then they must be specified in your + +.. sourcecode:: text src/new-module/examples/wscript file by modifying it with your text editor. -As an example, the examples for the core module are specified in :: +As an example, the examples for the core module are specified in + +.. sourcecode:: text src/core/examples/wscript The core module's C++ examples are specified using the following function calls and source file names. Note that the second argument for the function ``create_ns3_program()`` is the list of modules that the -program being created depends on: :: +program being created depends on: + +.. sourcecode:: python obj = bld.create_ns3_program('main-callback', ['core']) obj.source = 'main-callback.cc' @@ -194,7 +231,9 @@ program being created depends on: :: The core module's Python examples are specified using the following function call. Note that the second argument for the function register_ns3_script() is the list of modules that the Python example -depends on: :: +depends on: + +.. sourcecode:: python bld.register_ns3_script('sample-simulator.py', ['core']) @@ -207,11 +246,15 @@ are suitable for regression tests. A file called ``examples-to-run.py`` that exists in each module's test directory can control the invocation of the examples when the test framework runs. -As an example, the examples that are run by ``test.py`` for the core module are specified in :: +As an example, the examples that are run by ``test.py`` for the core module are specified in + +.. sourcecode:: text src/core/test/examples-to-run.py -using the following two lists of C++ and Python examples: :: +using the following two lists of C++ and Python examples: + +.. sourcecode:: python # A list of C++ examples to run in order to ensure that they remain # buildable and runnable over time. Each tuple in the list contains @@ -238,7 +281,9 @@ using the following two lists of C++ and Python examples: :: ("sample-simulator.py", "True"), ] -Each tuple in the C++ list of examples to run contains :: +Each tuple in the C++ list of examples to run contains + +.. sourcecode:: python (example_name, do_run, do_valgrind_run) @@ -249,11 +294,15 @@ is needed because NSC causes illegal instruction crashes with some tests when they are run under valgrind. Note that the two conditions are Python statements that -can depend on waf configuration variables. For example, :: +can depend on waf configuration variables. For example, + +.. sourcecode:: python ("tcp-nsc-lfn", "NSC_ENABLED == True", "NSC_ENABLED == False"), -Each tuple in the Python list of examples to run contains :: +Each tuple in the Python list of examples to run contains + +.. sourcecode:: python (example_name, do_run) @@ -261,12 +310,16 @@ where example_name is the Python script to be run and do_run is a condition under which to run the example. Note that the condition is a Python statement that can -depend on waf configuration variables. For example, :: +depend on waf configuration variables. For example, + +.. sourcecode:: python ("realtime-udp-echo.py", "ENABLE_REAL_TIME == False"), If your new module has examples, then you must specify which of them -should be run in your :: +should be run in your + +.. sourcecode:: text src/new-module/test/examples-to-run.py @@ -276,10 +329,12 @@ test.py. Step 8 - Build and test your new module *************************************** -You can now build and test your module as normal: :: +You can now build and test your module as normal: - ./waf configure --enable-examples --enable-tests - ./waf build - ./test.py +.. sourcecode:: bash + + $ ./waf configure --enable-examples --enable-tests + $ ./waf build + $ ./test.py and look for your new module's test suite (and example programs, if enabled) in the test output. diff --git a/doc/manual/source/object-model.rst b/doc/manual/source/object-model.rst index 41b2ea335..c5879385d 100644 --- a/doc/manual/source/object-model.rst +++ b/doc/manual/source/object-model.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp .. _Object-model: diff --git a/doc/manual/source/object-names.rst b/doc/manual/source/object-names.rst index 932485368..d1b287e84 100644 --- a/doc/manual/source/object-names.rst +++ b/doc/manual/source/object-names.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp .. _Object-names: diff --git a/doc/manual/source/organization.rst b/doc/manual/source/organization.rst index 9648c0197..01c650a67 100644 --- a/doc/manual/source/organization.rst +++ b/doc/manual/source/organization.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp Organization diff --git a/doc/manual/source/python.rst b/doc/manual/source/python.rst index 3732dfbe8..c8a983ff0 100644 --- a/doc/manual/source/python.rst +++ b/doc/manual/source/python.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: python Using Python to Run |ns3| ------------------------- @@ -74,30 +75,30 @@ Running Python Scripts waf contains some options that automatically update the python path to find the ns3 module. To run example programs, there are two ways to use waf to take care of this. One is to run a waf shell; e.g.: -:: +.. sourcecode:: bash - ./waf --shell - python examples/wireless/mixed-wireless.py + $ ./waf --shell + $ python examples/wireless/mixed-wireless.py and the other is to use the --pyrun option to waf: -:: +.. sourcecode:: bash - ./waf --pyrun examples/wireless/mixed-wireless.py + $ ./waf --pyrun examples/wireless/mixed-wireless.py To run a python script under the C debugger: -:: +.. sourcecode:: bash - ./waf --shell - gdb --args python examples/wireless/mixed-wireless.py + $ ./waf --shell + $ gdb --args python examples/wireless/mixed-wireless.py To run your own Python script that calls |ns3| and that has this path, ``/path/to/your/example/my-script.py``, do the following: -:: +.. sourcecode:: bash - ./waf --shell - python /path/to/your/example/my-script.py + $ ./waf --shell + $ python /path/to/your/example/my-script.py Caveats ******* @@ -118,9 +119,9 @@ Most of the missing APIs can be wrapped, given enough time, patience, and expert Conversion Constructors +++++++++++++++++++++++ -Conversion constructors (http://publib.boulder.ibm.com/infocenter/compbgpl/v9v111/topic/com.ibm.xlcpp9.bg.doc/language_ref/cplr384.htm) are not fully supported yet by PyBindGen, and they always act as explicit constructors when translating an API into Python. For example, in C++ you can do this: +`Conversion constructors `_ are not fully supported yet by PyBindGen, and they always act as explicit constructors when translating an API into Python. For example, in C++ you can do this: -:: +.. sourcecode:: cpp Ipv4AddressHelper ipAddrs; ipAddrs.SetBase ("192.168.0.0", "255.255.255.0"); @@ -188,9 +189,9 @@ will probably have to be that we disable python bindings in CygWin. If you really care about Python bindings on Windows, try building with mingw and native python instead. Or else, to build without python bindings, disable python bindings in the configuration stage: -:: +.. sourcecode:: bash - ./waf configure --disable-python + $ ./waf configure --disable-python Working with Python Bindings **************************** @@ -211,9 +212,9 @@ The process by which Python bindings are handled is the following: If something goes wrong with compiling Python bindings and you just want to ignore them and move on with C++, you can disable Python with: -:: +.. sourcecode:: bash - ./waf --disable-python + $ ./waf --disable-python Instructions for Handling New Files or Changed API's **************************************************** @@ -230,9 +231,9 @@ Scanning the Monolithic Python Bindings To scan the monolithic Python bindings do the following: -:: +.. sourcecode:: bash - ./waf --python-scan + $ ./waf --python-scan Organization of the Monolithic Python Bindings ++++++++++++++++++++++++++++++++++++++++++++++ @@ -269,15 +270,15 @@ Scanning the Modular Python Bindings To scan the modular Python bindings for the core module, for example, do the following: -:: +.. sourcecode:: bash - ./waf --apiscan=core + $ ./waf --apiscan=core To scan the modular Python bindings for all of the modules, do the following: -:: +.. sourcecode:: bash - ./waf --apiscan=all + $ ./waf --apiscan=all Creating a New Module +++++++++++++++++++++ @@ -311,5 +312,4 @@ The ``src//bindings`` directory may contain the following files, some of More Information for Developers ******************************* -If you are a developer and need more information on |ns3|'s Python bindings, please see the Python Bindings wiki page at -``_. +If you are a developer and need more information on |ns3|'s Python bindings, please see the `Python Bindings wiki page `_. diff --git a/doc/manual/source/random-variables.rst b/doc/manual/source/random-variables.rst index ae36fe7cf..3d6d8d37a 100644 --- a/doc/manual/source/random-variables.rst +++ b/doc/manual/source/random-variables.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp Random Variables ---------------- @@ -125,7 +126,7 @@ run number behavior. This seeding and substream state setting must be called before any random variables are created; e.g:: RngSeedManager::SetSeed (3); // Changes seed from default of 1 to 3 - RngSeedManager::SetRun (7); // Changes run number from default of 1 to 7 + RngSeedManager::SetRun (7); // Changes run number from default of 1 to 7 // Now, create random variables Ptr x = CreateObject (); Ptr y = CreateObject (); @@ -143,18 +144,24 @@ independent replications using the substreams. For ease of use, it is not necessary to control the seed and run number from within the program; the user can set the ``NS_GLOBAL_VALUE`` environment -variable as follows:: +variable as follows: - NS_GLOBAL_VALUE="RngRun=3" ./waf --run program-name +.. sourcecode:: bash + + $ NS_GLOBAL_VALUE="RngRun=3" ./waf --run program-name Another way to control this is by passing a command-line argument; since this is -an |ns3| GlobalValue instance, it is equivalently done such as follows:: +an |ns3| GlobalValue instance, it is equivalently done such as follows: - ./waf --command-template="%s --RngRun=3" --run program-name +.. sourcecode:: bash -or, if you are running programs directly outside of waf:: + $ ./waf --command-template="%s --RngRun=3" --run program-name - ./build/optimized/scratch/program-name --RngRun=3 +or, if you are running programs directly outside of waf: + +.. sourcecode:: bash + + $ ./build/optimized/scratch/program-name --RngRun=3 The above command-line variants make it easy to run lots of different runs from a shell script by just passing a different RngRun index. @@ -177,7 +184,9 @@ Base class public API ********************* Below are excerpted a few public methods of class :cpp:class:`RandomVariableStream` -that access the next value in the substream.:: +that access the next value in the substream. + +:: /** * \brief Returns a random double from the underlying distribution @@ -226,7 +235,7 @@ handled by smart pointers. RandomVariableStream instances can also be used in |ns3| attributes, which means that values can be set for them through the |ns3| attribute system. -An example is in the propagation models for WifiNetDevice::: +An example is in the propagation models for WifiNetDevice:: TypeId RandomPropagationDelayModel::GetTypeId (void) @@ -278,20 +287,20 @@ of the base class RandomVariableStream. By partitioning the existing sequence of streams from before: -:: +.. sourcecode:: text <--------------------------------------------------------------------------> - stream 0 stream (2^64 - 1) + stream 0 stream (2^64 - 1) into two equal-sized sets: -:: +.. sourcecode:: text - <---------------------------------------------------------------------------> - ^ ^^ ^ - | || | - stream 0 stream (2^63 - 1) stream 2^63 stream (2^64 - 1) - <- automatically assigned -----><-------- assigned by user-----------> + <--------------------------------------------------------------------------> + ^ ^^ ^ + | || | + stream 0 stream (2^63 - 1) stream 2^63 stream (2^64 - 1) + <- automatically assigned -----------><- assigned by user -----------------> The first 2^63 streams continue to be automatically assigned, while the last 2^63 are given stream indices starting with zero up to diff --git a/doc/manual/source/realtime.rst b/doc/manual/source/realtime.rst index 47d6be20e..0d22982e0 100644 --- a/doc/manual/source/realtime.rst +++ b/doc/manual/source/realtime.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp RealTime -------- @@ -61,9 +62,11 @@ perspective. Users just need to set the attribute StringValue ("ns3::RealtimeSimulatorImpl")); There is a script in ``examples/realtime/realtime-udp-echo.cc`` that -has an example of how to configure the realtime behavior. Try: :: +has an example of how to configure the realtime behavior. Try: - ./waf --run realtime-udp-echo +.. sourcecode:: bash + + $ ./waf --run realtime-udp-echo Whether the simulator will work in a best effort or hard limit policy fashion is governed by the attributes explained in the previous section. diff --git a/doc/manual/source/test-framework.rst b/doc/manual/source/test-framework.rst index 6ec109d23..0fa404693 100644 --- a/doc/manual/source/test-framework.rst +++ b/doc/manual/source/test-framework.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: bash Testing framework ----------------- @@ -27,7 +28,9 @@ properly on all of its supported systems. Users (and developers) typically will not interact with the buildbot system other than to read its messages regarding test results. If a failure is detected in one of the automated build and test jobs, the buildbot will send an email to the -*ns-developers* mailing list. This email will look something like:: +*ns-developers* mailing list. This email will look something like + +.. sourcecode: text The Buildbot has detected a new failure of osx-ppc-g++-4.2 on NsNam. Full details are available at: @@ -69,20 +72,20 @@ have been built by doing the following :: - ./waf configure --enable-examples --enable-tests - ./waf + $ ./waf configure --enable-examples --enable-tests + $ ./waf By default, ``test.py`` will run all available tests and report status back in a very concise form. Running the command :: - ./test.py + $ ./test.py will result in a number of ``PASS``, ``FAIL``, ``CRASH`` or ``SKIP`` indications followed by the kind of test that was run and its display name. -:: +.. sourcecode:: text Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build' Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build' @@ -103,7 +106,7 @@ in determining if changes they have made have caused any regressions. There are a number of options available to control the behavior of ``test.py``. if you run ``test.py --help`` you should see a command summary like: -:: +.. sourcecode:: text Usage: test.py [options] @@ -145,7 +148,7 @@ nightly builds using :: - ./test.py --html=nightly.html + $ ./test.py --html=nightly.html In this case, an HTML file named ''nightly.html'' would be created with a pretty summary of the testing done. A ''human readable'' format is available for users @@ -153,7 +156,7 @@ interested in the details. :: - ./test.py --text=results.txt + $ ./test.py --text=results.txt In the example above, the test suite checking the |ns3| wireless device propagation loss models failed. By default no further information is @@ -164,17 +167,17 @@ to be specified. Running the command :: - ./test.py --suite=ns3-wifi-propagation-loss-models + $ ./test.py --suite=ns3-wifi-propagation-loss-models or equivalently :: - ./test.py -s ns3-wifi-propagation-loss-models + $ ./test.py -s ns3-wifi-propagation-loss-models results in that single test suite being run. -:: +.. sourcecode:: text FAIL: TestSuite ns3-wifi-propagation-loss-models @@ -182,13 +185,14 @@ To find detailed information regarding the failure, one must specify the kind of output desired. For example, most people will probably be interested in a text file:: - ./test.py --suite=ns3-wifi-propagation-loss-models --text=results.txt + $ ./test.py --suite=ns3-wifi-propagation-loss-models --text=results.txt This will result in that single test suite being run with the test status written to the file ''results.txt''. -You should find something similar to the following in that file:: +You should find something similar to the following in that file +.. sourcecode:: text FAIL: Test Suite ''ns3-wifi-propagation-loss-models'' (real 0.02 user 0.01 system 0.00) PASS: Test Case "Check ... Friis ... model ..." (real 0.01 user 0.00 system 0.00) @@ -222,21 +226,23 @@ changes to a repository. In this case, ``test.py`` can be told to constrain the types of tests being run to a particular class of tests. The following command will result in only the unit tests being run:: - ./test.py --constrain=unit + $ ./test.py --constrain=unit Similarly, the following command will result in only the example smoke tests being run:: - ./test.py --constrain=unit + $ ./test.py --constrain=unit To see a quick list of the legal kinds of constraints, you can ask for them to be listed. The following command :: - ./test.py --kinds + $ ./test.py --kinds -will result in the following list being displayed:: +will result in the following list being displayed: + +.. sourcecode:: text Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build' Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build' @@ -256,9 +262,11 @@ to be listed. The following command, :: - ./test.py --list + $ ./test.py --list -will result in a list of the test suite being displayed, similar to:: +will result in a list of the test suite being displayed, similar to + +.. sourcecode:: text Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build' Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build' @@ -291,11 +299,11 @@ for C++ examples do not have extensions. Entering :: - ./test.py --example=udp-echo + $ ./test.py --example=udp-echo results in that single example being run. -:: +.. sourcecode:: text PASS: Example examples/udp/udp-echo @@ -304,7 +312,7 @@ You can specify the directory where ns-3 was built using the :: - ./test.py --buildpath=/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build/debug --example=wifi-simple-adhoc + $ ./test.py --buildpath=/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build/debug --example=wifi-simple-adhoc One can run a single Python example program using the ``--pyexample`` option. Note that the relative path for the example must be included @@ -312,11 +320,11 @@ and that Python examples do need their extensions. Entering :: - ./test.py --pyexample=examples/tutorial/first.py + $ ./test.py --pyexample=examples/tutorial/first.py results in that single example being run. -:: +.. sourcecode:: text PASS: Example examples/tutorial/first.py @@ -344,9 +352,11 @@ option. :: - ./test.py --list --nowaf + $ ./test.py --list --nowaf -will result in a list of the currently built test suites being displayed, similar to:: +will result in a list of the currently built test suites being displayed, similar to: + +.. sourcecode:: text ns3-wifi-propagation-loss-models ns3-tcp-cwnd @@ -366,7 +376,7 @@ leaks. This can be selected by using the ``--grind`` option. :: - ./test.py --grind + $ ./test.py --grind As it runs, ``test.py`` and the programs that it runs indirectly, generate large numbers of temporary files. Usually, the content of these files is not interesting, @@ -378,7 +388,7 @@ Universal Time (also known as Greenwich Mean Time). :: - ./test.py --retain + $ ./test.py --retain Finally, ``test.py`` provides a ``--verbose`` option which will print large amounts of information about its progress. It is not expected that this @@ -386,13 +396,13 @@ will be terribly useful unless there is an error. In this case, you can get access to the standard output and standard error reported by running test suites and examples. Select verbose in the following way:: - ./test.py --verbose + $ ./test.py --verbose All of these options can be mixed and matched. For example, to run all of the ns-3 core test suites under valgrind, in verbose mode, while generating an HTML output file, one would do:: - ./test.py --verbose --grind --constrain=core --html=results.html + $ ./test.py --verbose --grind --constrain=core --html=results.html TestTaxonomy ************ @@ -480,7 +490,7 @@ stage, and also (optionally) examples if examples are to be checked: :: - ./waf --configure --enable-examples --enable-tests + $ ./waf --configure --enable-examples --enable-tests Then, build ns-3, and after it is built, just run ``test.py``. ``test.py -h`` will show a number of configuration options that modify the behavior @@ -501,9 +511,11 @@ The main reason why ``test.py`` is not suitable for debugging is that it is not In order to execute the test-runner, you run it like any other ns-3 executable -- using ``waf``. To get a list of available options, you can type:: - ./waf --run "test-runner --help" + $ ./waf --run "test-runner --help" -You should see something like the following:: +You should see something like the following + +.. sourcecode:: text Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build' Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build' @@ -537,10 +549,10 @@ option something like, :: - ./waf shell - cd build/debug/utils - gdb test-runner - run --suite=global-value --assert + $ ./waf shell + $ cd build/debug/utils + $ gdb test-runner + $ run --suite=global-value --assert If an error is then found in the global-value test suite, a segfault would be generated and the (source level) debugger would stop at the ``NS_TEST_ASSERT_MSG`` @@ -556,7 +568,7 @@ option for you. To run one of the tests directly from the test-runner using ``waf``, you will need to specify the test suite to run along with the base directory. So you could use the shell and do:: - ./waf --run "test-runner --basedir=`pwd` --suite=pcap-file-object" + $ ./waf --run "test-runner --basedir=`pwd` --suite=pcap-file-object" Note the ''backward'' quotation marks on the ``pwd`` command. @@ -601,7 +613,7 @@ output, run ``test.py`` with the "retain" option: :: - ./test.py -r + $ ./test.py -r and test output can be found in the ``testpy-output/`` directory. @@ -619,11 +631,11 @@ Try, :: - ./waf --run "test-runner --basedir=`pwd` --suite=pcap-file-object --out=myfile.xml" + $ ./waf --run "test-runner --basedir=`pwd` --suite=pcap-file-object --out=myfile.xml" If you look at the file ``myfile.xml`` you should see something like, -:: +.. sourcecode:: xml pcap-file-object @@ -669,7 +681,9 @@ section. Debugging test suite failures +++++++++++++++++++++++++++++ -To debug test crashes, such as:: +To debug test crashes, such as + +.. sourcecode:: text CRASH: TestSuite ns3-wifi-interference @@ -677,7 +691,7 @@ You can access the underlying test-runner program via gdb as follows, and then pass the "--basedir=`pwd`" argument to run (you can also pass other arguments as needed, but basedir is the minimum needed):: - ./waf --command-template="gdb %s" --run "test-runner" + $ ./waf --command-template="gdb %s" --run "test-runner" Waf: Entering directory `/home/tomh/hg/sep09/ns-3-allinone/ns-3-dev-678/build' Waf: Leaving directory `/home/tomh/hg/sep09/ns-3-allinone/ns-3-dev-678/build' 'build' finished successfully (0.380s) @@ -699,7 +713,7 @@ such as:: VALGR: TestSuite devices-mesh-dot11s-regression - ./waf --command-template="valgrind %s --basedir=`pwd` --suite=devices-mesh-dot11s-regression" --run test-runner + $ ./waf --command-template="valgrind %s --basedir=`pwd` --suite=devices-mesh-dot11s-regression" --run test-runner Class TestRunner **************** @@ -736,7 +750,7 @@ and perform these two duties. The following code will define a new class that can be run by ``test.py`` as a ''unit'' test with the display name, ``my-test-suite-name``. -:: +.. sourcecode:: cpp class MySuite : public TestSuite { @@ -766,7 +780,7 @@ In order to create a new test case in the system, all one has to do is to inheri from the ``TestCase`` base class, override the constructor to give the test case a name and override the ``DoRun`` method to run the test. -:: +.. sourcecode:: cpp class MyTestCase : public TestCase { diff --git a/doc/manual/source/tracing.rst b/doc/manual/source/tracing.rst index 3e65834c2..f6dabe2bf 100644 --- a/doc/manual/source/tracing.rst +++ b/doc/manual/source/tracing.rst @@ -1,4 +1,7 @@ .. include:: replace.txt +.. highlight:: cpp +.. role:: raw-role(raw) + :format: html latex Tracing ------- @@ -269,7 +272,7 @@ aggregation model. The next path segment begins with the "$" character which indicates a ``GetObject`` call should be made looking for the type that follows. When a node is initialized by an ``InternetStackHelper`` a number of interfaces are aggregated to the node. One of these is the TCP level four protocol. The -runtime type of this protocol object is "ns3::TcpL4Protocol". When the +runtime type of this protocol object is ``ns3::TcpL4Protocol''. When the ``GetObject`` is executed, it returns a pointer to the object of this type. The ``TcpL4Protocol`` class defines an Attribute called "SocketList" which is a @@ -342,14 +345,15 @@ stack helpers. Naturally, the trace files should follow a The trace helpers therefore fall naturally into a two-dimensional taxonomy. 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.:: +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 is @@ -393,11 +397,16 @@ Pcap Tracing Device Helper Methods :: - void EnablePcap (std::string prefix, Ptr nd, bool promiscuous = false, bool explicitFilename = false); - void EnablePcap (std::string prefix, std::string ndName, bool promiscuous = false, bool explicitFilename = false); - void EnablePcap (std::string prefix, NetDeviceContainer d, bool promiscuous = false); - void EnablePcap (std::string prefix, NodeContainer n, bool promiscuous = false); - void EnablePcap (std::string prefix, uint32_t nodeid, uint32_t deviceid, bool promiscuous = false); + void EnablePcap (std::string prefix, Ptr nd, + bool promiscuous = false, bool explicitFilename = false); + void EnablePcap (std::string prefix, std::string ndName, + bool promiscuous = false, bool explicitFilename = false); + void EnablePcap (std::string prefix, NetDeviceContainer d, + bool promiscuous = false); + void EnablePcap (std::string prefix, NodeContainer n, + bool promiscuous = false); + void EnablePcap (std::string prefix, uint32_t nodeid, uint32_t deviceid, + bool promiscuous = false); void EnablePcapAll (std::string prefix, bool promiscuous = false); In each of the methods shown above, there is a default parameter called diff --git a/doc/manual/source/troubleshoot.rst b/doc/manual/source/troubleshoot.rst index e59c83923..45809f7c0 100644 --- a/doc/manual/source/troubleshoot.rst +++ b/doc/manual/source/troubleshoot.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: bash Troubleshooting --------------- @@ -22,18 +23,20 @@ values are unexpectedly null. Here is an example of what might occur::: - ns-old:~/ns-3-nsc$ ./waf --run tcp-point-to-point - Entering directory `/home/tomh/ns-3-nsc/build' + $ ./waf --run tcp-point-to-point + Entering directory '/home/tomh/ns-3-nsc/build' Compilation finished successfully Command ['/home/tomh/ns-3-nsc/build/debug/examples/tcp-point-to-point'] exited with code -11 The error message says that the program terminated unsuccessfully, but it is not clear from this information what might be wrong. To examine more closely, try running it under the `gdb debugger -`_::: +`_: - ns-old:~/ns-3-nsc$ ./waf --run tcp-point-to-point --command-template="gdb %s" - Entering directory `/home/tomh/ns-3-nsc/build' +.. sourcecode:: bash + + $ ./waf --run tcp-point-to-point --command-template="gdb %s" + Entering directory '/home/tomh/ns-3-nsc/build' Compilation finished successfully GNU gdb Red Hat Linux (6.3.0.0-1.134.fc5rh) Copyright 2004 Free Software Foundation, Inc. @@ -66,7 +69,9 @@ argument to the command template "gdb %s". This tells us that there was an attempt to dereference a null pointer socketFactory. -Let's look around line 136 of tcp-point-to-point, as gdb suggests::: +Let's look around line 136 of tcp-point-to-point, as gdb suggests: + +.. sourcecode:: cpp Ptr socketFactory = n2->GetObject (Tcp::iid); Ptr localSocket = socketFactory->CreateSocket (); @@ -77,6 +82,6 @@ may be null. Sometimes you may need to use the `valgrind memory checker `_ for more subtle errors. Again, you invoke the use of -valgrind similarly::: +valgrind similarly:: - ns-old:~/ns-3-nsc$ ./waf --run tcp-point-to-point --command-template="valgrind %s" + $ ./waf --run tcp-point-to-point --command-template="valgrind %s" diff --git a/doc/ns3_html_theme/static/ns3_stylesheet.css b/doc/ns3_html_theme/static/ns3_stylesheet.css index 5b99b5cc6..1c9a10be3 100644 --- a/doc/ns3_html_theme/static/ns3_stylesheet.css +++ b/doc/ns3_html_theme/static/ns3_stylesheet.css @@ -25,6 +25,11 @@ div.body h6 { background-image: url('nav_f.png'); } +/* Sphinx figure captions */ +p.caption { + font-weight: bold; +} + /* Doxygen side bar */ #nav-tree { font-size: 12px; diff --git a/doc/tutorial/source/building-topologies.rst b/doc/tutorial/source/building-topologies.rst index 69d713458..44d36fbf7 100644 --- a/doc/tutorial/source/building-topologies.rst +++ b/doc/tutorial/source/building-topologies.rst @@ -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 diff --git a/doc/tutorial/source/conceptual-overview.rst b/doc/tutorial/source/conceptual-overview.rst index d0538a33b..b75feced9 100644 --- a/doc/tutorial/source/conceptual-overview.rst +++ b/doc/tutorial/source/conceptual-overview.rst @@ -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 diff --git a/doc/tutorial/source/getting-started.rst b/doc/tutorial/source/getting-started.rst index 9d4f88b94..877cd43c3 100644 --- a/doc/tutorial/source/getting-started.rst +++ b/doc/tutorial/source/getting-started.rst @@ -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. diff --git a/doc/tutorial/source/tracing.rst b/doc/tutorial/source/tracing.rst index c80600796..a8cf87db8 100644 --- a/doc/tutorial/source/tracing.rst +++ b/doc/tutorial/source/tracing.rst @@ -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 diff --git a/doc/tutorial/source/tweaking.rst b/doc/tutorial/source/tweaking.rst index bb4d200a3..fd98b68b7 100644 --- a/doc/tutorial/source/tweaking.rst +++ b/doc/tutorial/source/tweaking.rst @@ -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