diff --git a/src/brite/doc/brite.rst b/src/brite/doc/brite.rst index f058cef44..8122d6155 100644 --- a/src/brite/doc/brite.rst +++ b/src/brite/doc/brite.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: bash BRITE Integration ------------------ @@ -30,9 +31,7 @@ the Waxman model or the Barbasi-Albert model. BRITE interconnects these separat router topologies as specified by the AS level topology. Once the hierarchical topology is constructed, it is flattened into a large router level topology. -Further information can be found in the BRITE user manual::: - - http://www.cs.bu.edu/brite/publications/usermanual.pdf +Further information can be found in the BRITE user manual: http://www.cs.bu.edu/brite/publications/usermanual.pdf Model Description ***************** @@ -119,14 +118,17 @@ By enabling the verbose parameter, the example will print out the node and edge information in a similar format to standard BRITE output. There are many other command-line parameters including confFile, tracing, and nix, described below: - confFile: A BRITE configuration file. Many different BRITE configuration - file examples exist in the src/brite/examples/conf_files directory, for - example, RTBarabasi20.conf and RTWaxman.conf. Please refer to - the conf_files directory for more examples. + confFile + A BRITE configuration file. Many different BRITE configuration + file examples exist in the src/brite/examples/conf_files directory, for + example, RTBarabasi20.conf and RTWaxman.conf. Please refer to + the conf_files directory for more examples. - tracing: Enables ascii tracing. + tracing + Enables ascii tracing. - nix: Enables nix-vector routing. Global routing is used by default. + nix + Enables nix-vector routing. Global routing is used by default. The generic BRITE example also support visualization using pyviz, assuming python bindings in ns-3 are enabled::: @@ -137,7 +139,7 @@ Simulations involving BRITE can also be used with MPI. The total number of MPI passed to the BRITE topology helper where a modulo divide is used to assign the nodes for each AS to a MPI instance. An example can be found in src/brite/examples::: - $ mpirun -np 2 ./waf --run brite-MPI-example + $ mpirun -np 2 ./waf --run brite-MPI-example Please see the ns-3 MPI documentation for information on setting up MPI with ns-3. diff --git a/src/buildings/doc/source/buildings-testing.rst b/src/buildings/doc/source/buildings-testing.rst index 4506634bf..c5f1ba745 100644 --- a/src/buildings/doc/source/buildings-testing.rst +++ b/src/buildings/doc/source/buildings-testing.rst @@ -1,3 +1,5 @@ +.. highlight:: bash + +++++++++++++++++++++++++++++++++++++ Testing Documentation +++++++++++++++++++++++++++++++++++++ @@ -8,20 +10,20 @@ Overview To test and validate the ns-3 Building Pathloss module, some test suites is provided which are integrated with the ns-3 test framework. To run them, you need to have configured the build of the simulator in this way:: - ./waf configure --enable-tests --enable-modules=buildings - ./test.py + $ ./waf configure --enable-tests --enable-modules=buildings + $ ./test.py The above will run not only the test suites belonging to the buildings module, but also those belonging to all the other ns-3 modules on which the buildings module depends. See the ns-3 manual for generic information on the testing framework. You can get a more detailed report in HTML format in this way:: - ./test.py -w results.html + $ ./test.py -w results.html After the above command has run, you can view the detailed result for each test by opening the file ``results.html`` with a web browser. You can run each test suite separately using this command:: - ./test.py -s test-suite-name + $ ./test.py -s test-suite-name For more details about ``test.py`` and the ns-3 testing framework, please refer to the ns-3 manual. diff --git a/src/click/doc/click.rst b/src/click/doc/click.rst index 737b5d802..d454c2a6f 100644 --- a/src/click/doc/click.rst +++ b/src/click/doc/click.rst @@ -1,3 +1,5 @@ +.. highlight:: bash + Click Modular Router Integration -------------------------------- @@ -78,10 +80,10 @@ Building Click The first step is to clone Click from the github repository and build it:: - $: git clone https://github.com/kohler/click - $: cd click/ - $: ./configure --disable-linuxmodule --enable-nsclick --enable-wifi - $: make + $ git clone https://github.com/kohler/click + $ cd click/ + $ ./configure --disable-linuxmodule --enable-nsclick --enable-wifi + $ make The --enable-wifi flag may be skipped if you don't intend on using Click with Wifi. * Note: You don't need to do a 'make install'. @@ -89,7 +91,7 @@ The --enable-wifi flag may be skipped if you don't intend on using Click with Wi Once Click has been built successfully, change into the ns-3 directory and configure ns-3 with Click Integration support:: - $: ./waf configure --enable-examples --enable-tests --with-nsclick=/path/to/click/source + $ ./waf configure --enable-examples --enable-tests --with-nsclick=/path/to/click/source Hint: If you have click installed one directory above ns-3 (such as in the ns-3-allinone directory), and the name of the directory is 'click' (or @@ -101,7 +103,7 @@ If it says 'enabled' beside 'NS-3 Click Integration Support', then you're good t Next, try running one of the examples:: - $: ./waf --run nsclick-simple-lan + $ ./waf --run nsclick-simple-lan You may then view the resulting .pcap traces, which are named nsclick-simple-lan-0-0.pcap and nsclick-simple-lan-0-1.pcap. @@ -120,7 +122,9 @@ The following should be kept in mind when making your Click graph: Debugging Packet Flows from Click ================================= -From any point within a Click graph, you may use the Print (http://read.cs.ucla.edu/click/elements/print) element and its variants for pretty printing of packet contents. Furthermore, you may generate pcap traces of packets flowing through a Click graph by using the ToDump (http://read.cs.ucla.edu/click/elements/todump) element as well. For instance:: +From any point within a Click graph, you may use the Print (http://read.cs.ucla.edu/click/elements/print) element and its variants for pretty printing of packet contents. Furthermore, you may generate pcap traces of packets flowing through a Click graph by using the ToDump (http://read.cs.ucla.edu/click/elements/todump) element as well. For instance: + +.. sourcecode:: cpp myarpquerier -> Print(fromarpquery,64) @@ -133,7 +137,9 @@ Helper ====== To have a node run Click, the easiest way would be to use the ClickInternetStackHelper -class in your simulation script. For instance:: +class in your simulation script. For instance: + +.. sourcecode:: cpp ClickInternetStackHelper click; click.SetClickFile (myNodeContainer, "nsclick-simple-lan.click"); diff --git a/src/csma/doc/csma.rst b/src/csma/doc/csma.rst index d4b21a3ec..686ff80a3 100644 --- a/src/csma/doc/csma.rst +++ b/src/csma/doc/csma.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp CSMA NetDevice -------------- diff --git a/src/dsr/doc/dsr.rst b/src/dsr/doc/dsr.rst index 1b53c24c5..5fdc21598 100644 --- a/src/dsr/doc/dsr.rst +++ b/src/dsr/doc/dsr.rst @@ -155,7 +155,9 @@ Helper ****** To have a node run DSR, the easiest way would be to use the DsrHelper -and DsrMainHelpers in your simulation script. For instance:: +and DsrMainHelpers in your simulation script. For instance: + +.. sourcecode:: cpp DsrHelper dsr; DsrMainHelper dsrMain; diff --git a/src/emu/doc/emu.rst b/src/emu/doc/emu.rst index 97c3a5f99..cd436636c 100644 --- a/src/emu/doc/emu.rst +++ b/src/emu/doc/emu.rst @@ -1,11 +1,11 @@ .. include:: replace.txt +.. highlight:: cpp Emu NetDevice ------------- **Note:** The ``EmuNetDevice`` is being deprecated as of ns-3.17. The -``EmuFdNetDeviceHelper`` class replaces this functionality and API -entirely. +:doc:`fd-net-device` and ``EmuFdNetDeviceHelper`` class replaces this functionality and API entirely. Behavior ******** diff --git a/src/fd-net-device/doc/fd-net-device.rst b/src/fd-net-device/doc/fd-net-device.rst index d5a0d45ef..e27b9701e 100644 --- a/src/fd-net-device/doc/fd-net-device.rst +++ b/src/fd-net-device/doc/fd-net-device.rst @@ -1,6 +1,7 @@ File Descriptor NetDevice ------------------------- -.. include:: replace.txt +.. include:: replace.txt +.. highlight:: cpp .. heading hierarchy: ------------- Chapter @@ -144,7 +145,7 @@ ability to create TUN/TAP devices are prerequisites to using the provided helpers. Support for these modes can be found in the output of the ``waf configure`` step, e.g.: -:: +.. sourcecode:: text Threading Primitives : enabled Real Time Simulator : enabled @@ -220,7 +221,7 @@ a network device on the host. The emulation helper permits to transparently integrate a simulated |ns3| node into a network composed of real nodes. -:: +.. sourcecode:: text +----------------------+ +-----------------------+ | host 1 | | host 2 | @@ -305,7 +306,7 @@ Users should note that this usage of TAP devices is different than that provided by the TapBridge NetDevice found in ``src/tap-bridge``. The model in this helper is as follows: -:: +.. sourcecode:: text +-------------------------------------+ | host | @@ -334,7 +335,7 @@ traffic generated by the simulation to the Internet. The model in TapBridge (in another module) is as follows: -:: +.. sourcecode:: text +--------+ | Linux | @@ -404,7 +405,7 @@ The functionality provided by this helper is similar to that provided by the FdTapNetDeviceHelper, except that the underlying mechanisms to create the TAP device are different. -:: +.. sourcecode:: text +-------------------------------------+ | PlanetLab host | diff --git a/src/internet/doc/internet-stack.rst b/src/internet/doc/internet-stack.rst index 981b2dbf5..4ab3f86b4 100644 --- a/src/internet/doc/internet-stack.rst +++ b/src/internet/doc/internet-stack.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp Internet Stack -------------- @@ -119,8 +120,8 @@ In class Ipv4L3Protocol, one method described below is ``Receive ()``::: * - implement a per-NetDevice ARP cache * - send back arp replies on the right device */ - void Receive( Ptr device, Ptr p, uint16_t protocol, - const Address &from, const Address &to, NetDevice::PacketType packetType); + void Receive( Ptr device, Ptr p, uint16_t protocol, + const Address &from, const Address &to, NetDevice::PacketType packetType); First, note that the ``Receive ()`` function has a matching signature to the ReceiveCallback in the class :cpp:class:`Node`. This function pointer is @@ -129,7 +130,7 @@ The actual registration is done with a statement such as follows::: RegisterProtocolHandler ( MakeCallback (&Ipv4Protocol::Receive, ipv4), - Ipv4L3Protocol::PROT_NUMBER, 0); + Ipv4L3Protocol::PROT_NUMBER, 0); The Ipv4L3Protocol object is aggregated to the Node; there is only one such Ipv4L3Protocol object. Higher-layer protocols that have a packet to send down to @@ -228,7 +229,8 @@ callback is invoked by the transport protocol when data is available. This callback is specified as follows::: void Socket::SetRecvCallback (Callback, - Ptr, const Address&> receivedData); + Ptr, + const Address&> receivedData); The data being received is conveyed in the Packet data buffer. An example usage is in class :cpp:class:`PacketSink`::: diff --git a/src/internet/doc/ipv6.rst b/src/internet/doc/ipv6.rst index 4acd9dec7..8876eed64 100644 --- a/src/internet/doc/ipv6.rst +++ b/src/internet/doc/ipv6.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp IPv6 ---- @@ -21,7 +22,7 @@ in the directory ``src/internet``. The implementation of IPv6 is contained in the following files: -:: +.. sourcecode:: text src/internet/model/icmpv6-header.{cc,h} src/internet/model/icmpv6-l4-protocol.{cc,h} @@ -56,7 +57,7 @@ The implementation of IPv6 is contained in the following files: Also some helpers are involved with IPv6: -:: +.. sourcecode:: text src/internet/helper/internet-stack-helper.{cc,h} src/internet/helper/ipv6-address-helper.{cc,h} diff --git a/src/internet/doc/routing-overview.rst b/src/internet/doc/routing-overview.rst index 5e2b12b54..32a1bf936 100644 --- a/src/internet/doc/routing-overview.rst +++ b/src/internet/doc/routing-overview.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp Routing overview ---------------- @@ -137,7 +138,7 @@ For instance, this scheduling call will cause the tables to be rebuilt at time 5 seconds::: Simulator::Schedule (Seconds (5), - &Ipv4GlobalRoutingHelper::RecomputeRoutingTables); + &Ipv4GlobalRoutingHelper::RecomputeRoutingTables); There are two attributes that govern the behavior. The first is @@ -338,9 +339,9 @@ to a node::: void Ipv4StaticRouting::AddMulticastRoute (Ipv4Address origin, - Ipv4Address group, - uint32_t inputInterface, - std::vector outputInterfaces); + Ipv4Address group, + uint32_t inputInterface, + std::vector outputInterfaces); A multicast route must specify an origin IP address, a multicast group and an input network interface index as conditions and provide a vector of output diff --git a/src/internet/doc/tcp.rst b/src/internet/doc/tcp.rst index d294de177..94b576c09 100644 --- a/src/internet/doc/tcp.rst +++ b/src/internet/doc/tcp.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp TCP models in ns-3 ------------------ @@ -41,7 +42,9 @@ This implementation was substantially rewritten by Adriam Tam for ns-3.10. The model is a full TCP, in that it is bidirectional and attempts to model the connection setup and close logic. -The implementation of TCP is contained in the following files::: +The implementation of TCP is contained in the following files: + +.. sourcecode:: text src/internet/model/tcp-header.{cc,h} src/internet/model/tcp-l4-protocol.{cc,h} @@ -186,9 +189,11 @@ Configuring and Downloading Using the ``build.py`` script in ns-3-allinone directory, NSC will be enabled by default unless the platform does not support it. To disable it when building -|ns3|, type::: +|ns3|, type: -./waf configure --enable-examples --enable-tests --disable-nsc +.. sourcecode:: bash + + $ ./waf configure --enable-examples --enable-tests --disable-nsc Building and validating +++++++++++++++++++++++ @@ -197,12 +202,16 @@ Building |ns3| with nsc support is the same as building it without; no additional arguments are needed for waf. Building nsc may take some time compared to |ns3|; it is interleaved in the |ns3| building process. -Try running the following ns-3 test suite::: +Try running the following ns-3 test suite: - ./test.py -s ns3-tcp-interoperability +.. sourcecode:: bash + + $ ./test.py -s ns3-tcp-interoperability If NSC has been successfully built, the following test should show up -in the results::: +in the results: + +.. sourcecode:: text PASS TestSuite ns3-tcp-interoperability @@ -211,10 +220,12 @@ This confirms that NSC is ready to use. Usage +++++ -There are a few example files. Try:: +There are a few example files. Try: - ./waf --run tcp-nsc-zoo - ./waf --run tcp-nsc-lfn +.. sourcecode:: bash + + $ ./waf --run tcp-nsc-zoo + $ ./waf --run tcp-nsc-lfn These examples will deposit some ``.pcap`` files in your directory, which can be examined by tcpdump or wireshark. @@ -240,9 +251,11 @@ to the remaining nodes. It is important that this function be called Which stacks are available to use? Presently, the focus has been on Linux 2.6.18 and Linux 2.6.26 stacks for |ns3|. To see which stacks were built, one can execute the following find command at the |ns3| top level -directory::: +directory: - ~/ns-3.10> find nsc -name "*.so" -type f +.. sourcecode:: bash + + $ find nsc -name "*.so" -type f nsc/linux-2.6.18/liblinux2.6.18.so nsc/linux-2.6.26/liblinux2.6.26.so @@ -272,10 +285,10 @@ can see the following configuration::: These additional configuration variables are not available to native |ns3| TCP. -Also note that default values for TCP attributes in |ns3| TCP may differ from the nsc TCP implementation. Specifically in |ns3|::: +Also note that default values for TCP attributes in |ns3| TCP may differ from the nsc TCP implementation. Specifically in |ns3|: - 1) TCP default MSS is 536 - 2) TCP Delayed Ack count is 2 + 1) TCP default MSS is 536 + 2) TCP Delayed Ack count is 2 Therefore when making comparisons between results obtained using nsc and |ns3| TCP, care must be taken to ensure these values are set appropriately. See /examples/tcp/tcp-nsc-comparision.cc for an example. diff --git a/src/lte/doc/source/lte-design.rst b/src/lte/doc/source/lte-design.rst index 8b2e71acf..2ddef281f 100644 --- a/src/lte/doc/source/lte-design.rst +++ b/src/lte/doc/source/lte-design.rst @@ -1,5 +1,5 @@ .. include:: replace.txt - +.. highlight:: cpp ++++++++++++++++++++ Design Documentation @@ -477,7 +477,8 @@ The subframe is divided into control and data part as described in Figure :ref:` .. _fig-lte-subframe-structure: .. figure:: figures/lte-subframe-structure.* - :width: 50px + :align: center + :width: 300px LTE subframe division. @@ -1260,6 +1261,8 @@ RBG k, the FD scheduler selects the UE :math:`j` that maximizes the product of t metric (:math:`Msch`, :math:`MCoI`) by weight :math:`W[n]`. This strategy will guarantee the throughput of lower quality UE tend towards the TBR. +:: + Config::SetDefault ("ns3::PfFfMacScheduler::HarqEnabled", BooleanValue (false)); The scheduler implements the filtering of the uplink CQIs according to their nature with ``UlCqiFilter`` attibute, in detail: diff --git a/src/lte/doc/source/lte-testing.rst b/src/lte/doc/source/lte-testing.rst index 877b258d6..64756d300 100644 --- a/src/lte/doc/source/lte-testing.rst +++ b/src/lte/doc/source/lte-testing.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: bash +++++++++++++++++++++ @@ -12,20 +13,20 @@ Overview To test and validate the ns-3 LTE module, several test suites are provided which are integrated with the ns-3 test framework. To run them, you need to have configured the build of the simulator in this way:: - ./waf configure --enable-tests --enable-modules=lte --enable-examples - ./test.py + $ ./waf configure --enable-tests --enable-modules=lte --enable-examples + $ ./test.py The above will run not only the test suites belonging to the LTE module, but also those belonging to all the other ns-3 modules on which the LTE module depends. See the ns-3 manual for generic information on the testing framework. You can get a more detailed report in HTML format in this way:: - ./test.py -w results.html + $ ./test.py -w results.html After the above command has run, you can view the detailed result for each test by opening the file ``results.html`` with a web browser. You can run each test suite separately using this command:: - ./test.py -s test-suite-name + $ ./test.py -s test-suite-name For more details about ``test.py`` and the ns-3 testing framework, please refer to the ns-3 manual. diff --git a/src/mobility/doc/mobility.rst b/src/mobility/doc/mobility.rst index c56a75606..b8e01e2cb 100644 --- a/src/mobility/doc/mobility.rst +++ b/src/mobility/doc/mobility.rst @@ -140,7 +140,9 @@ ns-2 MobilityHelper The |ns2| mobility format is a widely used mobility trace format. The documentation is available at: http://www.isi.edu/nsnam/ns/doc/node172.html -Valid trace files use the following ns2 statements: :: +Valid trace files use the following ns2 statements: + +.. sourcecode:: bash $node set X_ x1 $node set Y_ y1 @@ -166,14 +168,14 @@ Note that in |ns3|, movement along the Z dimension is not supported. Some examples of external tools that can export in this format include: -- BonnMotion http://net.cs.uni-bonn.de/wg/cs/applications/bonnmotion/ +- `BonnMotion `_ - - Some installation instructions for BonnMotion can be found here: http://www.nsnam.org/wiki/HOWTO_use_ns-3_with_BonnMotion_mobility_generator_and_analysis_tool - - Documentation on using BonnMotion with |ns3| is posted here: http://www.ida.liu.se/~rikno/files/mobility_generation.pdf + - `Installation instructions `_ and + - `Documentation `_ for using BonnMotion with |ns3| -- SUMO http://sourceforge.net/apps/mediawiki/sumo/index.php?title=Main_Page -- TraNS http://trans.epfl.ch/ -- the ``setdest`` utility in |ns2|, documented here: http://www.winlab.rutgers.edu/~zhibinwu/html/ns2_wireless_scene.htm +- `SUMO `_ +- `TraNS `_ +- |ns2| `setdest `_ utility A special Ns2MobilityHelper object can be used to parse these files and convert the statements into |ns3| mobility events. The underlying @@ -208,7 +210,7 @@ tutorial. First, the user instantiates a ``MobilityHelper`` object and sets some ``Attributes`` controlling the "position allocator" functionality. -:: +.. sourcecode:: cpp MobilityHelper mobility; @@ -227,14 +229,14 @@ this position allocator. Next, the user typically sets the MobilityModel subclass; e.g.: -:: +.. sourcecode:: cpp mobility.SetMobilityModel ("ns3::RandomWalk2dMobilityModel", "Bounds", RectangleValue (Rectangle (-50, 50, -50, 50))); Once the helper is configured, it is typically passed a container, such as: -:: +.. sourcecode:: cpp mobility.Install (wifiStaNodes); @@ -270,13 +272,17 @@ The example prints out messages generated by each read line from the ns2 movemen Example usage: -:: +.. sourcecode:: bash - ./waf --run "ns2-mobility-trace --traceFile=src/mobility/examples/default.ns_movements --nodeNum=2 --duration=100.0 --logFile=ns2-mob.log" + $ ./waf --run "ns2-mobility-trace \ + --traceFile=src/mobility/examples/default.ns_movements \ + --nodeNum=2 \ + --duration=100.0 \ + --logFile=ns2-mob.log" Sample log file output: -:: +.. sourcecode:: text +0.0ns POS: x=150, y=93.986, z=0; VEL:0, y=50.4038, z=0 +0.0ns POS: x=195.418, y=150, z=0; VEL:50.1186, y=0, z=0 @@ -299,7 +305,7 @@ as part of the BonnMotion process to output ns-2-compatible traces. The program ``bonnmotion-ns2-example.cc`` will output the following to stdout: -:: +.. sourcecode:: text At 0.00 node 0: Position(329.82, 66.06, 0.00); Speed(0.53, -0.22, 0.00) At 100.00 node 0: Position(378.38, 45.59, 0.00); Speed(0.00, 0.00, 0.00) @@ -322,7 +328,7 @@ install |ns2| and run this Tcl program to see this output). The output of the |ns2| ``bonnmotion-example.tcl`` program is shown below for comparison (file ``bonnmotion-example.tr``): -:: +.. sourcecode:: text M 0.00000 0 (329.82, 66.06, 0.00), (378.38, 45.59), 0.57 M 100.00000 0 (378.38, 45.59, 0.00), (378.38, 45.59), 0.57 @@ -362,7 +368,7 @@ use the "AssignStreams" facility of the random number system. Class ``MobilityModel`` and class ``PositionAllocator`` both have public API to assign streams to underlying random variables: -:: +.. sourcecode:: cpp /** * Assign a fixed random variable stream number to the random variables @@ -377,7 +383,7 @@ API to assign streams to underlying random variables: The class ``MobilityHelper`` also provides this API. The typical usage pattern when using the helper is: -:: +.. sourcecode:: cpp int64_t streamIndex = /*some positive integer */ MobilityHelper mobility; diff --git a/src/mpi/doc/distributed.rst b/src/mpi/doc/distributed.rst index 7341b5dd1..c613ea980 100644 --- a/src/mpi/doc/distributed.rst +++ b/src/mpi/doc/distributed.rst @@ -68,6 +68,7 @@ Running Distributed Simulations Prerequisites +++++++++++++ +.. highlight:: bash Ensure that MPI is installed, as well as mpic++. In Ubuntu repositories, these are openmpi-bin, openmpi-common, openmpi-doc, libopenmpi-dev. In @@ -78,31 +79,33 @@ Note: There is a conflict on some Fedora systems between libotf and openmpi. A possible "quick-fix" is to yum remove libotf before installing openmpi. This will remove conflict, but it will also remove emacs. Alternatively, -these steps could be followed to resolve the conflict::: +these steps could be followed to resolve the conflict: - 1) Rename the tiny otfdump which emacs says it needs: + 1) Rename the tiny otfdump which emacs says it needs:: - mv /usr/bin/otfdump /usr/bin/otfdump.emacs-version + $ mv /usr/bin/otfdump /usr/bin/otfdump.emacs-version - 2) Manually resolve openmpi dependencies: + 2) Manually resolve openmpi dependencies:: - sudo yum install libgfortran libtorque numactl + $ sudo yum install libgfortran libtorque numactl 3) Download rpm packages: + .. sourcecode:: text + openmpi-1.3.1-1.fc11.i586.rpm openmpi-devel-1.3.1-1.fc11.i586.rpm openmpi-libs-1.3.1-1.fc11.i586.rpm openmpi-vt-1.3.1-1.fc11.i586.rpm - from + from http://mirrors.kernel.org/fedora/releases/11/Everything/i386/os/Packages/ - http://mirrors.kernel.org/fedora/releases/11/Everything/i386/os/Packages/ + 4) Force the packages in:: - 4) Force the packages in: - - sudo rpm -ivh --force openmpi-1.3.1-1.fc11.i586.rpm - openmpi-libs-1.3.1-1.fc11.i586.rpm openmpi-devel-1.3.1-1.fc11.i586.rpm + $ sudo rpm -ivh --force \ + openmpi-1.3.1-1.fc11.i586.rpm \ + openmpi-libs-1.3.1-1.fc11.i586.rpm \ + openmpi-devel-1.3.1-1.fc11.i586.rpm \ openmpi-vt-1.3.1-1.fc11.i586.rpm Also, it may be necessary to add the openmpi bin directory to PATH in order to @@ -111,17 +114,17 @@ these executables can be used. Finally, if openmpi complains about the inability to open shared libraries, such as libmpi_cxx.so.0, it may be necessary to add the openmpi lib directory to LD_LIBRARY_PATH. -Here is an example of setting up PATH and LD_LIBRARY_PATH using a bash shell::: +Here is an example of setting up PATH and LD_LIBRARY_PATH using a bash shell: - For a 32-bit Linux distribution: + * For a 32-bit Linux distribution:: - export PATH=$PATH:/usr/lib/openmpi/bin - export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib/openmpi/lib + $ export PATH=$PATH:/usr/lib/openmpi/bin + $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib/openmpi/lib - For a 64-bit Linux distribution: + For a 64-bit Linux distribution:: - export PATH=$PATH:/usr/lib64/openmpi/bin - export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib64/openmpi/lib + $ export PATH=$PATH:/usr/lib64/openmpi/bin + $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib64/openmpi/lib These lines can be added into ~/.bash_profile or ~/.bashrc to avoid having to retype them when a new shell is opened. @@ -131,28 +134,30 @@ Building and Running Examples If you already built |ns3| without MPI enabled, you must re-build::: - ./waf distclean + $ ./waf distclean Configure |ns3| with the --enable-mpi option::: - ./waf -d debug configure --enable-examples --enable-tests --enable-mpi + $ ./waf -d debug configure --enable-examples --enable-tests --enable-mpi Ensure that MPI is enabled by checking the optional features shown from the output of configure. Next, build |ns3|::: - ./waf + $ ./waf After building |ns3| with mpi enabled, the example programs are now ready to run with mpirun. Here are a few examples (from the root |ns3| directory)::: - mpirun -np 2 ./waf --run simple-distributed - mpirun -np 4 -machinefile mpihosts ./waf --run 'nms-udp-nix --LAN=2 --CN=4 --nix=1' + $ mpirun -np 2 ./waf --run simple-distributed + $ mpirun -np 4 -machinefile mpihosts ./waf --run 'nms-udp-nix --LAN=2 --CN=4 --nix=1' The np switch is the number of logical processors to use. The machinefile switch is which machines to use. In order to use machinefile, the target file must -exist (in this case mpihosts). This can simply contain something like::: +exist (in this case mpihosts). This can simply contain something like: + +.. sourcecode:: text localhost localhost @@ -164,12 +169,13 @@ Or if you have a cluster of machines, you can name them. NOTE: Some users have experienced issues using mpirun and waf together. An alternative way to run distributed examples is shown below::: - ./waf shell - cd build/debug - mpirun -np 2 src/mpi/examples/simple-distributed + $ ./waf shell + $ cd build/debug + $ mpirun -np 2 src/mpi/examples/simple-distributed Creating custom topologies ++++++++++++++++++++++++++ +.. highlight:: cpp The example programs in src/mpi/examples give a good idea of how to create different topologies for distributed simulation. The main points are assigning system ids diff --git a/src/netanim/doc/animation.rst b/src/netanim/doc/animation.rst index bfa260974..0b056d843 100644 --- a/src/netanim/doc/animation.rst +++ b/src/netanim/doc/animation.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. toctree:: Animation --------- @@ -62,9 +63,11 @@ Downloading NetAnim If NetAnim is not already available in the |ns3| package you downloaded, you can do the following: Please ensure that you have installed mercurial. -The latest version of NetAnim can be downloaded using mercurial with the following command:: +The latest version of NetAnim can be downloaded using mercurial with the following command: - hg clone http://code.nsnam.org/netanim +.. sourcecode:: bash + + $ hg clone http://code.nsnam.org/netanim Building NetAnim ================ @@ -72,35 +75,41 @@ Prerequisites ~~~~~~~~~~~~~ Qt4 (4.7 and over) is required to build NetAnim. This can be obtained using the following ways: -For Debian/Ubuntu Linux distributions:: +For Debian/Ubuntu Linux distributions: - apt-get install qt4-dev-tools +.. sourcecode:: bash -For Red Hat/Fedora based distribution:: + $ apt-get install qt4-dev-tools - yum install qt4 - yum install qt4-devel +For Red Hat/Fedora based distribution: -For Mac/OSX:: +.. sourcecode:: bash - http://qt.nokia.com/downloads/ + $ yum install qt4 + $ yum install qt4-devel + +For Mac/OSX, see http://qt.nokia.com/downloads/ Build steps ~~~~~~~~~~~ -To build NetAnim use the following commands:: +To build NetAnim use the following commands: - cd netanim - make clean - qmake NetAnim.pro (For MAC Users: qmake -spec macx-g++ NetAnim.pro) - make +.. sourcecode:: bash + + $ cd netanim + $ make clean + $ qmake NetAnim.pro (For MAC Users: qmake -spec macx-g++ NetAnim.pro) + $ make Note: qmake could be "qmake-qt4" in some systems -This should create an executable named "NetAnim" in the same directory:: +This should create an executable named "NetAnim" in the same directory: - john@john-VirtualBox:~/netanim$ ls -l NetAnim +.. sourcecode:: bash + + $ ls -l NetAnim -rwxr-xr-x 1 john john 390395 2012-05-22 08:32 NetAnim Usage @@ -117,10 +126,12 @@ The class "AnimationInterface" under "src/netanim" uses underlying |ns3| trace s to construct a timestamped ASCII file in XML format. Examples are found under src/netanim/examples -Example:: +Example: - ./waf -d debug configure --enable-examples - ./waf --run "dumbbell-animation" +.. sourcecode:: bash + + $ ./waf -d debug configure --enable-examples + $ ./waf --run "dumbbell-animation" The above will create an XML file dumbbell-animation.xml @@ -131,19 +142,22 @@ Mandatory 2. Include the header [#include "ns3/netanim-module.h"] in your test program 3. Add the statement -:: +.. sourcecode:: cpp - AnimationInterface anim ("animation.xml"); - where "animation.xml" is any arbitrary filename + AnimationInterface anim ("animation.xml"); // where "animation.xml" is any arbitrary filename [for versions before ns-3.13 you also have to use the line "anim.SetXMLOutput() to set the XML mode and also use anim.StartAnimation();] Optional ######## + +.. highlight:: cpp + The following are optional but useful steps:: - 1.anim.SetMobilityPollInterval (Seconds (1)); + // Step 1 + anim.SetMobilityPollInterval (Seconds (1)); AnimationInterface records the position of all nodes every 250 ms by default. The statement above sets the periodic interval at which AnimationInterface records the position of all nodes. If the nodes are @@ -151,31 +165,35 @@ expected to move very little, it is useful to set a high mobility poll interval :: - 2. anim.SetConstantPosition (Ptr< Node > n, double x, double y); + // Step 2 + anim.SetConstantPosition (Ptr< Node > n, double x, double y); AnimationInterface requires that the position of all nodes be set. In |ns3| this is done by setting an associated MobilityModel. "SetConstantPosition" is a quick way to set the x-y coordinates of a node which is stationary. :: - 3. anim.SetStartTime (Seconds(150)); and anim.SetStopTime (Seconds(150)); + // Step 3 + anim.SetStartTime (Seconds(150)); and anim.SetStopTime (Seconds(150)); AnimationInterface can generate large XML files. The above statements restricts the window between which AnimationInterface does tracing. Restricting the window serves to focus only on relevant portions of the simulation and creating manageably small XML files :: - 4. AnimationInterface anim ("animation.xml", 50000); + // Step 4 + AnimationInterface anim ("animation.xml", 50000); Using the above constructor ensures that each animation XML trace file has only 50000 packets. For example, if AnimationInterface captures 150000 packets, using the above constructor splits the capture into 3 files -animation.xml - containing the packet range 1-50000 +* animation.xml - containing the packet range 1-50000 -animation.xml-1 - containing the packet range 50001-100000 +* animation.xml-1 - containing the packet range 50001-100000 -animation.xml-2 - containing the packet range 100001-150000 +* animation.xml-2 - containing the packet range 100001-150000 :: - 5. anim.EnablePacketMetadata (true); + // Step 5 + anim.EnablePacketMetadata (true); With the above statement, AnimationInterface records the meta-data of each packet in the xml trace file. Metadata can be used by NetAnim to provide better statistics and filter, along with providing some brief information about the packet such as TCP sequence number or source & destination IP address during packet animation. @@ -229,16 +247,20 @@ The XML trace files has the following main sections XML tags ~~~~~~~~ +.. highlight:: xml + Nodes are identified by their unique Node id. The XML begins with the "information" element describing the rest of the elements -1. element + Element +############## This is the XML root element. All other elements fall within this element. Attributes are:: lp = Logical Processor Id (Used for distributed simulations only) -2. element + Element +################## This elements contains the Node and Link elements.It describes, the co-ordinates of the canvas used for animation. Attributes are:: @@ -250,9 +272,10 @@ This elements contains the Node and Link elements.It describes, the co-ordinates Example:: - + -3. element + Element +############## This element describes each Node's Id and X,Y co-ordinate (position). Attributes are:: @@ -265,7 +288,8 @@ Example:: -4. element + Element +############## This element describes wired links between two nodes. Attributes are:: @@ -277,7 +301,8 @@ Example:: -5.

element +

Element +########### This element describes a packet over wired links being transmitted at some node and received at another. @@ -298,7 +323,8 @@ Example:: A packet over wired-links from Node 1 was received at Node 0. The first bit of the packet was transmitted at the 1st second, the last bit was transmitted at the 1.000067199th second of the simulation Node 0 received the first bit of the packet at the 1.002th second and the last bit of the packet at the 1.002067199th second of the simulation NOTE: A packet with fromId == toId is a dummy packet used internally by the AnimationInterface. Please ignore this packet -7. element + Element +############ This element describes a packet over wireless links being transmitted at some node and received at another. diff --git a/src/network/doc/packets.rst b/src/network/doc/packets.rst index b6509fbe6..5710f93a3 100644 --- a/src/network/doc/packets.rst +++ b/src/network/doc/packets.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp Packets ------- diff --git a/src/network/doc/queue.rst b/src/network/doc/queue.rst index 06eef1f00..7811c5e51 100644 --- a/src/network/doc/queue.rst +++ b/src/network/doc/queue.rst @@ -85,7 +85,7 @@ A typical usage pattern is to create a device helper and to configure the queue type and attributes from the helper, such as this example from ``src/network/examples/red-tests.cc``: -:: +.. sourcecode:: cpp PointToPointHelper p2p; @@ -134,7 +134,7 @@ The ns-3 ascii trace helpers used by many of the NetDevices will hook the Enqueue, Dequeue, and Drop traces of these queues and print out trace statements, such as the following from ``examples/udp/udp-echo.cc``: -:: +.. sourcecode:: text + 2 /NodeList/0/DeviceList/1/$ns3::CsmaNetDevice/TxQueue/Enqueue ns3::EthernetHeader ( length/type=0x806, source=00:00:00:00:00:01, destination=ff:ff:ff:ff:ff:ff) diff --git a/src/network/doc/sockets-api.rst b/src/network/doc/sockets-api.rst index 3c431aa71..2f28f7d5c 100644 --- a/src/network/doc/sockets-api.rst +++ b/src/network/doc/sockets-api.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp .. _Sockets-APIs: @@ -104,14 +105,14 @@ Using sockets ============= Below is a typical sequence of socket calls for a TCP client in a -real implementation: +real implementation:: -* ``sock = socket(PF_INET, SOCK_STREAM, IPPROTO_TCP);`` -* ``bind(sock, ...);`` -* ``connect(sock, ...);`` -* ``send(sock, ...);`` -* ``recv(sock, ...);`` -* ``close(sock);`` + sock = socket(PF_INET, SOCK_STREAM, IPPROTO_TCP); + bind(sock, ...); + connect(sock, ...); + send(sock, ...); + recv(sock, ...); + close(sock); There are analogs to all of these calls in ns-3, but we will focus on two aspects here. First, most usage of sockets in real systems @@ -129,14 +130,14 @@ An application can also ask the socket how much space is available by calling :cpp:func:`ns3::Socket::GetTxAvailable`. A typical sequence of events for sending data (ignoring connection setup) might be::: - * ``SetSendCallback (MakeCallback(&HandleSendCallback));`` - * ``Send ();`` - * ``Send ();`` - * ... - * Send fails because buffer is full - * wait until :cpp:func:`HandleSendCallback` is called - * :cpp:func:`HandleSendCallback` is called by socket, since space now available - * ``Send (); // Start sending again`` + SetSendCallback (MakeCallback(&HandleSendCallback)); + Send (); + Send (); + ... + // Send fails because buffer is full + // Wait until HandleSendCallback is called + // HandleSendCallback is called by socket, since space now available + Send (); // Start sending again Similarly, on the receive side, the socket user does not block on a call to ``recv()``. Instead, the application sets a callback diff --git a/src/openflow/doc/openflow-switch.rst b/src/openflow/doc/openflow-switch.rst index df191462d..eced60364 100644 --- a/src/openflow/doc/openflow-switch.rst +++ b/src/openflow/doc/openflow-switch.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: bash OpenFlow switch support ----------------------- @@ -62,14 +63,18 @@ OpenFlow switch Model The OpenFlow switch device behaves somewhat according to the diagram setup as a classical OFSID switch, with a few modifications made for a proper simulation environment. -Normal OF-enabled Switch::: +Normal OF-enabled Switch: + +.. sourcecode:: text | Secure Channel | <--OF Protocol--> | Controller is external | | Hardware or Software Flow Table | -ns-3 OF-enabled Switch (module)::: +ns-3 OF-enabled Switch (module): +.. sourcecode:: text + | m_controller->ReceiveFromSwitch() | <--OF Protocol--> | Controller is internal | | Software Flow Table, virtual TCAM | @@ -132,42 +137,45 @@ In order to use the OpenFlowSwitch module, you must create and link the OFSID (OpenFlow Software Implementation Distribution) to ns-3. To do this: -#1 Obtain the OFSID code. An ns-3 specific OFSID branch is provided to ensure -operation with ns-3. Use mercurial to download this branch and waf to build -the library::: +1. Obtain the OFSID code. + An ns-3 specific OFSID branch is provided to ensure + operation with ns-3. Use mercurial to download this branch and waf to build + the library:: - $ hg clone http://code.nsnam.org/openflow - $ cd openflow + $ hg clone http://code.nsnam.org/openflow + $ cd openflow -From the "openflow" directory, run::: + From the "openflow" directory, run:: - $ ./waf configure - $ ./waf build + $ ./waf configure + $ ./waf build -#2 Your OFSID is now built into a libopenflow.a library! To -link to an ns-3 build with this OpenFlow switch module, run from the ns-3-dev -(or whatever you have named your distribution)::: +2. Your OFSID is now built into a libopenflow.a library! + To link to an ns-3 build with this OpenFlow switch module, run from the ns-3-dev + (or whatever you have named your distribution):: - $ ./waf configure --enable-examples --enable-tests --with-openflow=path/to/openflow + $ ./waf configure --enable-examples --enable-tests --with-openflow=path/to/openflow -#3 Under ``---- Summary of optional NS-3 features:`` you should see::: +3. Under ``---- Summary of optional NS-3 features:`` you should see: - "NS-3 OpenFlow Integration : enabled" + .. sourcecode:: text + + "NS-3 OpenFlow Integration : enabled" -indicating the library has been linked to ns-3. Run::: + indicating the library has been linked to ns-3. Run:: - $ ./waf build + $ ./waf build to build ns-3 and activate the OpenFlowSwitch module in ns-3. Examples ======== For an example demonstrating its use in a simple learning controller/switch, -run::: +run:: $ ./waf --run openflow-switch -To see it in detailed logging, run::: +To see it in detailed logging, run:: $ ./waf --run "openflow-switch -v" @@ -219,7 +227,7 @@ Caveats Validation ********** -This model has one test suite which can be run as follows::: +This model has one test suite which can be run as follows:: $ ./test.py --suite=openflow diff --git a/src/point-to-point/doc/point-to-point.rst b/src/point-to-point/doc/point-to-point.rst index 19fa99afb..70196ead2 100644 --- a/src/point-to-point/doc/point-to-point.rst +++ b/src/point-to-point/doc/point-to-point.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp PointToPoint NetDevice ---------------------- @@ -119,7 +120,7 @@ the device MAC hooks. When a packet is sent to the Point-to-Point net device for transmission it always passes through the transmit queue. The transmit queue in the PointToPointNetDevice inherits from Queue, and therefore inherits three trace -sources::: +sources: * An Enqueue operation source (see ns3::Queue::m_traceEnqueue); * A Dequeue operation source (see ns3::Queue::m_traceDequeue); diff --git a/src/propagation/doc/propagation.rst b/src/propagation/doc/propagation.rst index 459e1b58c..3fe82fb84 100644 --- a/src/propagation/doc/propagation.rst +++ b/src/propagation/doc/propagation.rst @@ -111,6 +111,7 @@ where for small or medium sized city and for large cities .. math:: + C_\mathrm{H} = \left\{\begin{array}{ll} 8.29 (\log{(1.54h_M)})^2 -1.1 & \mbox{if } 150\leq f\leq 200 \\ 3.2(\log{(11.75h_M)})^2 -4.97 & \mbox{if } 200 m_counter; // normally this would be integer type + TracedValue m_counter; // normally this would be integer type 2. through a counter whose value is posted to a second Probe, referenced by its name in the Config system: -:: + :: - void - Emitter::Count (void) - { - NS_LOG_FUNCTION (this); - NS_LOG_DEBUG ("Counting at " << Simulator::Now ().GetSeconds ()); - m_counter += 1.0; - DoubleProbe::SetValueByPath ("/Names/StaticallyAccessedProbe", m_counter); - Simulator::Schedule (Seconds (m_var->GetValue ()), &Emitter::Count, this); - } + void + Emitter::Count (void) + { + NS_LOG_FUNCTION (this); + NS_LOG_DEBUG ("Counting at " << Simulator::Now ().GetSeconds ()); + m_counter += 1.0; + DoubleProbe::SetValueByPath ("/Names/StaticallyAccessedProbe", m_counter); + Simulator::Schedule (Seconds (m_var->GetValue ()), &Emitter::Count, this); + } Let's look at the Probe more carefully. Probes can receive their values in a multiple ways: @@ -303,7 +308,7 @@ shown below. Case 0): -:: + :: // The below shows typical functionality without a probe // (connect a sink function to a trace source) @@ -314,7 +319,7 @@ Case 0): case 1): -:: + :: // // Probe1 will be hooked directly to the Emitter trace source object @@ -331,7 +336,7 @@ case 1): case 2): -:: + :: // // Probe2 will be hooked to the Emitter trace source object by @@ -347,7 +352,7 @@ case 2): case 4) (case 3 is not shown in this example): -:: + :: // // Probe3 will be called by the emitter directly through the @@ -361,12 +366,14 @@ case 4) (case 3 is not shown in this example): And finally, the example shows how the probes can be hooked to generate output: -:: + :: // The probe itself should generate output. The context that we provide // to this probe (in this case, the probe name) will help to disambiguate // the source of the trace - connected = probe3->TraceConnect ("Output", "/Names/Probes/StaticallyAccessedProbe/Output", MakeCallback (&NotifyViaProbe)); + connected = probe3->TraceConnect ("Output", + "/Names/Probes/StaticallyAccessedProbe/Output", + MakeCallback (&NotifyViaProbe)); NS_ASSERT_MSG (connected, "Trace source not .. connected to probe3 Output"); The following callback is hooked to the Probe in this example for @@ -390,21 +397,18 @@ The IPv4 packet plot example is based on the fifth.cc example from the |ns3| Tutorial. It can be found in ``src/stats/examples/ipv4-packet-plot-example.cc``. -:: - - // =========================================================================== - // - // node 0 node 1 - // +----------------+ +----------------+ - // | ns-3 TCP | | ns-3 TCP | - // +----------------+ +----------------+ - // | 10.1.1.1 | | 10.1.1.2 | - // +----------------+ +----------------+ - // | point-to-point | | point-to-point | - // +----------------+ +----------------+ - // | | - // +---------------------+ +.. sourcecode:: text + node 0 node 1 + +----------------+ +----------------+ + | ns-3 TCP | | ns-3 TCP | + +----------------+ +----------------+ + | 10.1.1.1 | | 10.1.1.2 | + +----------------+ +----------------+ + | point-to-point | | point-to-point | + +----------------+ +----------------+ + | | + +---------------------+ We'll just look at the Probe, as it illustrates that Probes may also diff --git a/src/stats/doc/statistics.rst b/src/stats/doc/statistics.rst index 3685a9760..173ca79ad 100644 --- a/src/stats/doc/statistics.rst +++ b/src/stats/doc/statistics.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp Statistical Framework --------------------- @@ -35,8 +36,8 @@ The statistics framework includes the following features: * The core framework and two basic data collectors: A counter, and a min/max/avg/total observer. * Extensions of those to easily work with times and packets. -* Plaintext output formatted for omnetpp. -* Database output using sqlite3, a standalone, lightweight, high performance SQL engine. +* Plaintext output formatted for `OMNet++`_. +* Database output using SQLite_, a standalone, lightweight, high performance SQL engine. * Mandatory and open ended metadata for describing and working with runs. * An example based on the notional experiment of examining the properties of NS-3's default ad hoc WiFi performance. It incorporates the following: @@ -47,6 +48,9 @@ The statistics framework includes the following features: * An example of using packet tags to track end-to-end delay. * A simple control script which runs a number of trials of the experiment at varying distances and queries the resulting database to produce a graph using GNUPlot. +.. _OMNet++: http://www.omnetpp.org +.. _SQLite: http://www.sqlite.org + To-Do ***** @@ -98,17 +102,18 @@ The first thing to do in implementing this experiment is developing the simulati :: + double distance = 50.0; + string format ("OMNet++"); + string experiment ("wifi-distance-test"); + string strategy ("wifi-default"); + string runID; + CommandLine cmd; - cmd.AddValue("distance", "Distance apart to place nodes (in meters).", - distance); - cmd.AddValue("format", "Format to use for data output.", - format); - cmd.AddValue("experiment", "Identifier for experiment.", - experiment); - cmd.AddValue("strategy", "Identifier for strategy.", - strategy); - cmd.AddValue("run", "Identifier for run.", - runID); + cmd.AddValue("distance", "Distance apart to place nodes (in meters).", distance); + cmd.AddValue("format", "Format to use for data output.", format); + cmd.AddValue("experiment", "Identifier for experiment.", experiment); + cmd.AddValue("strategy", "Identifier for strategy.", strategy); + cmd.AddValue("run", "Identifier for run.", runID); cmd.Parse (argc, argv); * Creating nodes and network stacks using ``ns3::NodeContainer``, ``ns3::WiFiHelper``, and ``ns3::InternetStackHelper``. @@ -170,30 +175,24 @@ The first thing to do in implementing this experiment is developing the simulati :: DataCollector data; - data.DescribeRun(experiment, - strategy, - input, - runID); + data.DescribeRun(experiment, strategy, input, runID); data.AddMetadata("author", "tjkopena"); Actual observation and calculating is done by ``ns3::DataCalculator`` objects, of which several different types exist. These are created by the simulation program, attached to reporting or sampling code, and then registered with the ``ns3::DataCollector`` so they will be queried later for their output. One easy observation mechanism is to use existing trace sources, for example to instrument objects in the ns-3 core without changing their code. Here a counter is attached directly to a trace signal in the WiFi MAC layer on the target node. :: - Ptr totalRx = - CreateObject(); + Ptr totalRx = CreateObject(); totalRx->SetKey("wifi-rx-frames"); Config::Connect("/NodeList/1/DeviceList/*/$ns3::WifiNetDevice/Rx", - MakeCallback(&PacketCounterCalculator::FrameUpdate, - totalRx)); + MakeCallback(&PacketCounterCalculator::FrameUpdate, totalRx)); data.AddDataCalculator(totalRx); Calculators may also be manipulated directly. In this example, a counter is created and passed to the traffic sink application to be updated when packets are received. :: - Ptr > appRx = - CreateObject >(); + Ptr > appRx = CreateObject >(); appRx->SetKey("receiver-rx-packets"); receiver->SetCounter(appRx); data.AddDataCalculator(appRx); @@ -212,23 +211,24 @@ The first thing to do in implementing this experiment is developing the simulati Simulator::Run(); -* Generating either omnetpp or sqlite output, depending on the command line arguments. To do this a ``ns3::DataOutputInterface`` object is created and configured. The specific type of this will determine the output format. This object is then given the ``ns3::DataCollector`` object which it interrogates to produce the output. +* Generating either `OMNet++`_ or SQLite_ output, depending on the command line arguments. To do this a ``ns3::DataOutputInterface`` object is created and configured. The specific type of this will determine the output format. This object is then given the ``ns3::DataCollector`` object which it interrogates to produce the output. - :: + .. sourcecode:: cpp Ptr output; - if (format == "omnet") { - NS_LOG_INFO("Creating omnet formatted data output."); + if (format == "OMNet++") { + NS_LOG_INFO("Creating OMNet++ formatted data output."); output = CreateObject(); } else { - #ifdef STAT_USE_DB - NS_LOG_INFO("Creating sqlite formatted data output."); + # ifdef STAT_USE_DB + NS_LOG_INFO("Creating SQLite formatted data output."); output = CreateObject(); - #endif + # endif } output->Output(data); + * Freeing any memory used by the simulation. This should come at the end of the main function for the example. :: @@ -240,18 +240,18 @@ Logging To see what the example program, applications, and stat framework are doing in detail, set the ``NS_LOG`` variable appropriately. The following will provide copious output from all three. -:: +.. sourcecode:: bash - export NS_LOG=StatFramework:WiFiDistanceExperiment:WiFiDistanceApps + $ export NS_LOG=StatFramework:WiFiDistanceExperiment:WiFiDistanceApps Note that this slows down the simulation extraordinarily. Sample Output ============= -Compiling and simply running the test program will append omnet++ formatted output such as the following to ``data.sca``. +Compiling and simply running the test program will append `OMNet++`_ formatted output such as the following to ``data.sca``. -:: +.. sourcecode:: text run run-1212239121 @@ -280,9 +280,9 @@ Compiling and simply running the test program will append omnet++ formatted outp Control Script ++++++++++++++ -In order to automate data collection at a variety of inputs (distances), a simple Bash script is used to execute a series of simulations. It can be found at ``examples/stats/wifi-example-db.sh``. The script runs through a set of distances, collecting the results into an sqlite3 database. At each distance five trials are conducted to give a better picture of expected performance. The entire experiment takes only a few dozen seconds to run on a low end machine as there is no output during the simulation and little traffic is generated. +In order to automate data collection at a variety of inputs (distances), a simple Bash script is used to execute a series of simulations. It can be found at ``examples/stats/wifi-example-db.sh``. The script runs through a set of distances, collecting the results into an SQLite_ database. At each distance five trials are conducted to give a better picture of expected performance. The entire experiment takes only a few dozen seconds to run on a low end machine as there is no output during the simulation and little traffic is generated. -:: +.. sourcecode:: bash #!/bin/sh @@ -314,9 +314,9 @@ In order to automate data collection at a variety of inputs (distances), a simpl Analysis and Conclusion +++++++++++++++++++++++ -Once all trials have been conducted, the script executes a simple SQL query over the database using the sqlite3 command line program. The query computes average packet loss in each set of trials associated with each distance. It does not take into account different strategies, but the information is present in the database to make some simple extensions and do so. The collected data is then passed to GNUPlot for graphing. +Once all trials have been conducted, the script executes a simple SQL query over the database using the SQLite_ command line program. The query computes average packet loss in each set of trials associated with each distance. It does not take into account different strategies, but the information is present in the database to make some simple extensions and do so. The collected data is then passed to GNUPlot for graphing. -:: +.. sourcecode:: sql CMD="select exp.input,avg(100-((rx.value*100)/tx.value)) \ from Singletons rx, Singletons tx, Experiments exp \ @@ -333,7 +333,7 @@ Once all trials have been conducted, the script executes a simple SQL query over The GNUPlot script found at ``examples/stats/wifi-example.gnuplot`` simply defines the output format and some basic formatting for the graph. -:: +.. sourcecode:: bash set terminal postscript portrait enhanced lw 2 "Helvetica" 14 diff --git a/src/tap-bridge/doc/tap.rst b/src/tap-bridge/doc/tap.rst index 2b865e3db..089aa1db3 100644 --- a/src/tap-bridge/doc/tap.rst +++ b/src/tap-bridge/doc/tap.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: text Tap NetDevice ------------- @@ -49,6 +50,7 @@ if it was directly connected to a simulated ns-3 network. This is illustrated below: :: + +--------+ | Linux | | host | +----------+ @@ -99,7 +101,9 @@ significant difference is, as the mode name implies, the TapBridge is going to "Use" an existing tap device previously created and configured by the user. This mode is particularly useful when a virtualization scheme automatically creates tap devices and ns-3 is used to provide -simulated networks for those devices. :: +simulated networks for those devices. + +:: +--------+ | Linux | @@ -139,11 +143,13 @@ This means that Linux bridges with more than one net device added are incompatible with UseLocal mode. In UseLocal mode, the user is expected to create and configure a tap device -completely outside the scope of the ns-3 simulation using something like: :: +completely outside the scope of the ns-3 simulation using something like: - sudo tunctl -t tap0 - sudo ifconfig tap0 hw ether 08:00:2e:00:00:01 - sudo ifconfig tap0 10.1.1.1 netmask 255.255.255.0 up +.. sourcecode:: bash + + $ sudo tunctl -t tap0 + $ sudo ifconfig tap0 hw ether 08:00:2e:00:00:01 + $ sudo ifconfig tap0 10.1.1.1 netmask 255.255.255.0 up To tell the TapBridge what is going on, the user will set either directly into the TapBridge or via the TapBridgeHelper, the "DeviceName" attribute. @@ -163,7 +169,9 @@ mode. Again, the "Use" prefix indicates that the TapBridge is going to Use an existing configuration. In this case, the TapBridge is going to logically extend a Linux bridge into ns-3. -This is illustrated below: :: +This is illustrated below: + +:: +---------+ | Linux | +----------+ @@ -203,15 +211,17 @@ addresses. Thus, ns-3 devices must support SendFrom() for use in UseBridge mode. It is expected that the user will do something like the following to -configure the bridge and tap completely outside ns-3: :: +configure the bridge and tap completely outside ns-3: - sudo brctl addbr mybridge - sudo tunctl -t mytap - sudo ifconfig mytap hw ether 00:00:00:00:00:01 - sudo ifconfig mytap 0.0.0.0 up - sudo brctl addif mybridge mytap - sudo brctl addif mybridge ... - sudo ifconfig mybridge 10.1.1.1 netmask 255.255.255.0 up +.. sourcecode:: bash + + $ sudo brctl addbr mybridge + $ sudo tunctl -t mytap + $ sudo ifconfig mytap hw ether 00:00:00:00:00:01 + $ sudo ifconfig mytap 0.0.0.0 up + $ sudo brctl addif mybridge mytap + $ sudo brctl addif mybridge ... + $ sudo ifconfig mybridge 10.1.1.1 netmask 255.255.255.0 up To tell the TapBridge what is going on, the user will set either directly into the TapBridge or via the TapBridgeHelper, the "DeviceName" attribute. diff --git a/src/wifi/doc/wifi.rst b/src/wifi/doc/wifi.rst index 1efab032c..a939171e0 100644 --- a/src/wifi/doc/wifi.rst +++ b/src/wifi/doc/wifi.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp Wifi ---- diff --git a/src/wimax/doc/wimax.rst b/src/wimax/doc/wimax.rst index c620065fc..d24795792 100644 --- a/src/wimax/doc/wimax.rst +++ b/src/wimax/doc/wimax.rst @@ -1,4 +1,5 @@ .. include:: replace.txt +.. highlight:: cpp Wimax NetDevice --------------- @@ -143,8 +144,8 @@ following code from ``src/wimax/examples/wimax-multicast.cc`` shows how this is configured from a helper level::: ServiceFlow MulticastServiceFlow = wimax.CreateServiceFlow (ServiceFlow::SF_DIRECTION_DOWN, - ServiceFlow::SF_TYPE_UGS, - MulticastClassifier); + ServiceFlow::SF_TYPE_UGS, + MulticastClassifier); bs->GetServiceFlowManager ()->AddMulticastServiceFlow (MulticastServiceFlow, WimaxPhy::MODULATION_TYPE_QPSK_12); @@ -505,7 +506,9 @@ scheme. The names of the files should respect the following format: modulation0.txt for modulation 0, modulation1.txt for modulation 1 and so on... The file format -should be as follows:: +should be as follows: + +.. sourcecode:: text SNR_value1 BER Blc_ER STANDARD_DEVIATION CONFIDENCE_INTERVAL1 CONFIDENCE_INTERVAL2 SNR_value2 BER Blc_ER STANDARD_DEVIATION CONFIDENCE_INTERVAL1 CONFIDENCE_INTERVAL2