-/*! \page pls_ns3 ns-3 as a SimGrid model
+/*! @page pls_ns3 ns-3 as a SimGrid model
-\tableofcontents
+@tableofcontents
You can use the well-known
<a href="http://www.nsnam.org/"><b>ns-3</b></a> packet-level network
simulator as a SimGrid model, for example to investigate the validity
-of your simulation.
+of your simulation. Just install ns-3 and recompile SimGrid accordingly.
-This binding is still somehow limited: you can only express what is at
-the intersection between ns-3 and SimGrid. For example, ns-3 wireless
-models are not available, while no route longuer than 1 must appear in
-your SimGrid platform (add routers on need).
-
-But if you stick to what is possible in both systems, there should be
-very little things to change in your SimGrid settings (platform and
-experimental scenario) to use ns-3
-
-\section pls_ns3_install Installing ns-3
+@section pls_ns3_install Installing ns-3
The easiest is to install it with the package manager. Under Debian/Ubuntu, simply type as root:
-\verbatim
+@verbatim
apt-get install libns3-dev ns3
-\endverbatim
+@endverbatim
You can also install it from scratch with the following commands:
-\verbatim
+@verbatim
# Download the source
-wget http://www.nsnam.org/release/ns-allinone-3.25.tar.bz2
-tar -xf ns-allinone-3.25.tar.bz2
-cd ns-allinone-3.25/ns-3.25/
+wget http://www.nsnam.org/release/ns-allinone-3.26.tar.bz2
+tar -xf ns-allinone-3.26.tar.bz2
+cd ns-allinone-3.26/ns-3.26/
# Configure, build and install
./waf configure --prefix="/opt/ns3" # or give another path if you prefer
./waf
./waf install
-\endverbatim
+@endverbatim
-For more information, please refer to the ns-3 documentation.
+For more information, please refer to the ns-3 documentation
+<a href="http://www.nsnam.org/">(official website)</a>.
-\section pls_ns3_config Enabling SimGrid's support for ns-3
+@section pls_ns3_config Enabling SimGrid's support for ns-3
-Normally, you just have to enable ns-3 in ccmake or cmake as follows. If you installed ns-3 in a regular path, just
-drop the ns3_path configuration item.
+Normally, you just have to enable ns-3 in ccmake or cmake as
+follows. If you installed ns-3 in a regular path, just drop the
+NS3_HINT configuration item.
-\verbatim
+@verbatim
cmake . -Denable_ns3=ON -DNS3_HINT=/opt/ns3 # or change the path if needed
-\endverbatim
+@endverbatim
+
+By the end of the configuration, cmake reports whether ns-3 was found,
+and this information is also available in <tt>include/simgrid/config.h</tt>
+If your local copy defines the variable @c SIMGRID_HAVE_NS3 to 1, then ns-3
+was correctly detected. If it's defined to 0, then something went
+wrong. Explore <tt>CMakeFiles/CMakeOutput.log</tt> and
+<tt>CMakeFiles/CMakeError.log</tt> to diagnose the problem.
-By the end of the configuration, cmake reports whether ns-3 was found. You can also double-check by executing the tests
-after the compilation.
+Afterward, you can test your installation as follows:
-\verbatim
+@verbatim
$ ctest -R ns3
-(test(s) should be run)
-\endverbatim
+@endverbatim
+
+@section pls_ns3_use Using ns-3 from SimGrid
+
+The SimGrid-ns3 binding only contains features that are common to both
+systems: ns-3 wireless models are not available, while SimGrid routes
+cannot be longer than 1. Also, the platform built in ns-3 from the
+SimGrid description is very basic.
+
+Any route longer than one will be ignored when using ns-3. They are
+harmless, but you still need to connect your hosts using one-hop routes.
+The best solution is to add routers to split your route. Here is an
+example of invalid platform:
+
+@code{.xml}
+<platform>
+ <host id="alice" speed="1Gf" />
+ <host id="bob" speed="1Gf" />
+
+ <link id="l1" bw="1Mbps" />
+ <link id="l2" bw="1Mbps" />
+
+ <route src="alice" dst="bob">
+ <link_ctn id="l1"/> <!-- INVALID WITH NS-3 -->
+ <link_ctn id="l2"/> <!-- length=2 IS TOO MUCH -->
+ </route>
+</platform>
+@endcode
+
+Here is the same platform expressed in a way that ns-3 will understand.
+There is no direct connexion from alice to bob, but that's OK because
+ns-3 will find the path from point to point.
+
+@code{.xml}
+<platform>
+ <host id="alice" speed="1Gf" />
+ <host id="bob" speed="1Gf" />
+
+ <router id="r1" /> <!-- routers are compute-less hosts -->
+
+ <link id="l1" bw="1Mbps" />
+ <link id="l2" bw="1Mbps" />
+
+ <route src="alice" dst="r1">
+ <link_ctn id="l1"/>
+ </route>
+
+ <route src="r1" dst="bob">
+ <link_ctn id="l2"/>
+ </route>
+</platform>
+@endcode
+
+
+Once your platform is OK, just change the "network/model"
+configuration option to "NS3" as follows. The rest remains unchanged.
+
+@verbatim
+./network-ns3 ../../platforms/small_platform_one_link_routes.xml 3hosts_2links_d.xml --cfg=network/model:NS3
+@endverbatim
+
+Many other files from the examples/platform directory are usable with
+the ns-3 model, such as @ref examples/platforms/dogbone.xml. Check the file
+examples/deprecated/msg/network-ns3/network-ns3.tesh to see which ones are used
+in our regression tests. You may also be interested in the
+@ref msg_ex_ns3 "ns-3/SimGrid examples".
+
+@subsection pls_ns3_shortcomings Shortcomings of the ns-3 bindings in SimGrid
+
+A ns-3 platform is automatically created from the provided SimGrid
+platform. However, there are some known caveats:
+
+<ul>
+
+ <li>The default values (e.g., TCP parameters) are the ns3 default
+ values.</li>
-If you have a ns-3 version that is not known to SimGrid (yet), the detection may fail. In that case, edit the
-tools/cmake/Modules/FindNS3.cmake file in your SimGrid tree. The
-required changes are very easy, and documented in the file header.
+ <li>ns-3 networks are routed using the shortest path algorithm, using
+ ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables.</li>
-If the compilation fails when linking the library because of some .a file that cannot be used dynamically, this is
-probably because you only installed the libns3-dev library on your Debian, where you also need libns3-3. This is
-probably a bug of the libns3-dev package that should depend on the dynamic libraries corresponding to its .so files.
+ <li>End hosts cannot have more than one interface card. So, your
+ SimGrid hosts should be connected to the platform through only
+ one link. Otherwise, your SimGrid host will be considered as a
+ router.</li>
-\section pls_ns3_use Using ns-3 from SimGrid
+</ul>
-Basically, you just have to run your SimGrid simulation with the
-configuration option "network/model" set to "NS3". The rest remains
-unchanged.
+Our goal is to keep the ns-3 plugin of SimGrid as easy (and hopefully
+readable) as possible. If the current state does not fit your needs,
+you should modify this plugin, and/or create your own plugin from the
+existing one.
-The following should work from the examples/msg/network-ns3 folder (network-ns3 is the name of our example binary).
+@section pls_trouble Troubleshooting with ns-3 and SimGrid
-\verbatim
-./network-ns3 ./3hosts_2links_p.xml 3hosts_2links_d.xml --cfg=network/model:NS3 --log=root.threshold:info
-\endverbatim
+@subsection pls_ns3_config_trouble I fail to compile ns-3 within SimGrid
-A ns-3 platform is automatically created from the provided SimGrid platform file. However, there are some known caveats:
+If you have a ns-3 version that is not known to SimGrid yet, edit @c
+tools/cmake/Modules/FindNS3.cmake in your SimGrid tree, according to
+the comments on top of this file.
-<ul>
- <li>The default values (e.g., TCP parameters) are the ns3 values. Don't blame us for them.</li>
+If the compilation fails on Debian/Ubuntu when linking the library
+because of some .a file that cannot be used dynamically, then you are
+probably using a very old (and buggy) <tt>libns3-dev</tt>
+package. Update it, or install <tt>libns3-3</tt> manually.
- <li>ns-3 networks are routed using the shortest path algorithm, using
- ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables.</li>
+@subsection pls_trouble_hang The simulation hangs at some point
- <li>End hosts cannot have more than one interface card (so, only one <link> in your SimGrid platform should
- link an end host to the platform ; if not, your end host will be considered as a router. </li>
-</ul>
+If your simulation hangs in a communication, this is probably because
+one host is sending data that is not routable in your platform. Make
+sure that you only use routes of length 1, and that any host is
+connected to the platform.
+
+Arguably, SimGrid could detect this situation and report it, but
+unfortunately, this is still to be done.
-More about ns-3 simulator <a href="http://www.nsnam.org/">(Official website)</a>
+@subsection pls_trouble_warning I get a warning that some routes are ignored
-\subsection ns3_examples Examples
+Please read again the @ref pls_ns3_use section.
-For an example using NS3 as a SimGrid module, please refer to the
-@ref msg_ex_ns3 "relevant section" of the documentation.
+@example examples/platforms/dogbone.xml
*/
