From 62af461109d7cffb84a3d5d017c4740c9cbe0802 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Sat, 15 Jun 2019 21:17:56 +0200 Subject: [PATCH] convert the doc of ns-3 to the new formalism Fix https://framagit.org/simgrid/simgrid/issues/17 --- ChangeLog | 1 + doc/doxygen/ns3.doc | 176 ------------------------------- docs/source/index.rst | 1 + docs/source/ns3.rst | 176 +++++++++++++++++++++++++++++++ tools/cmake/DefinePackages.cmake | 2 +- 5 files changed, 179 insertions(+), 177 deletions(-) delete mode 100644 doc/doxygen/ns3.doc create mode 100644 docs/source/ns3.rst diff --git a/ChangeLog b/ChangeLog index 7a1499194b..9680036ca2 100644 --- a/ChangeLog +++ b/ChangeLog @@ -43,6 +43,7 @@ Fixed bugs (FG=FramaGit; GH=GitHub): - FG#13: Installs unstripped file 'bin/graphicator' - FG#14: Installs the empty directory 'doc/simgrid/html' - FG#15: Setting -Denable_python=OFF doesn't disable the search for pybind11 + - FG#17: Dead link in doc (pls_ns3) - FG#20: 'tesh --help' should return 0 - FG#21: Documentation link on http://simgrid.org/ broken - FG#22: Debian installation instruction are broken diff --git a/doc/doxygen/ns3.doc b/doc/doxygen/ns3.doc deleted file mode 100644 index b1763a7147..0000000000 --- a/doc/doxygen/ns3.doc +++ /dev/null @@ -1,176 +0,0 @@ -/*! @page pls_ns3 ns-3 as a SimGrid model - -@tableofcontents - -You can use the well-known -ns-3 packet-level network -simulator as a SimGrid model, for example to investigate the validity -of your simulation. Just install ns-3 and recompile SimGrid accordingly. - -@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 -apt-get install libns3-dev ns3 -@endverbatim - -You can also install it from scratch with the following commands: - -@verbatim -# Download the source -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 - -For more information, please refer to the ns-3 documentation -(official website). - -@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_HINT configuration item. - -@verbatim -cmake . -Denable_ns3=ON -DNS3_HINT=/opt/ns3 # or change the path if needed -@endverbatim - -By the end of the configuration, cmake reports whether ns-3 was found, -and this information is also available in include/simgrid/config.h -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 CMakeFiles/CMakeOutput.log and -CMakeFiles/CMakeError.log to diagnose the problem. - -Afterward, you can test your installation as follows: - -@verbatim -$ ctest -R ns3 -@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} - - - - - - - - - - - - -@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} - - - - - - - - - - - - - - - - - -@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: - - - -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. - -@section pls_trouble Troubleshooting with ns-3 and SimGrid - -@subsection pls_ns3_config_trouble I fail to compile ns-3 within SimGrid - -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. - -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) libns3-dev -package. Update it, or install libns3-3 manually. - -@subsection pls_trouble_hang The simulation hangs at some point - -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. - -@subsection pls_trouble_warning I get a warning that some routes are ignored - -Please read again the @ref pls_ns3_use section. - - -@example examples/platforms/dogbone.xml -*/ diff --git a/docs/source/index.rst b/docs/source/index.rst index 91fd582cd3..e2ec137a73 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -31,6 +31,7 @@ Welcome to SimGrid's documentation!    The Java Bindings Describing the Simulated Platform    Modeling Hints +    ns-3 as a SimGrid model    DTD Reference Describing the Experimental Scenario    Configuring SimGrid diff --git a/docs/source/ns3.rst b/docs/source/ns3.rst new file mode 100644 index 0000000000..5e3cb563aa --- /dev/null +++ b/docs/source/ns3.rst @@ -0,0 +1,176 @@ +.. _model_ns3: + +ns-3 as a SimGrid model +####################### + +You can use the well-known `ns-3 `_ packet-level network +simulator as a SimGrid model, for example to investigate the validity of your +simulation. Just install ns-3 and recompile SimGrid accordingly. + +Installing ns-3 +*************** + +The easiest is to install it with the package manager. Under Debian/Ubuntu, +simply type as root: + +.. code-block:: shell + + apt-get install libns3-dev ns3 + +You can also install it from scratch with the following commands: + +.. code-block:: shell + + # Download the source + 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 + +For more information, please refer to the ns-3 documentation +(`official website `_). + +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_HINT configuration item. + +.. code-block:: shell + + cmake . -Denable_ns3=ON -DNS3_HINT=/opt/ns3 # or change the path if needed + +By the end of the configuration, cmake reports whether ns-3 was found, +and this information is also available in ``include/simgrid/config.h`` +If your local copy defines the variable ``SIMGRID_HAVE_NS3`` to 1, then ns-3 +was correctly detected. If it's defined to 0, then something went +wrong. Explore ``CMakeFiles/CMakeOutput.log`` and +``CMakeFiles/CMakeError.log`` to diagnose the problem. + +Afterward, you can test your installation as follows: + +.. code-block:: shell + + ctest -R ns3 + +.. _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-block:: shell + + + + + + + + + + + + + + +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-block:: shell + + + + + + + + + + + + + + + + + + + +Once your platform is OK, just change the :ref:`network/model +` configuration option to "NS3" as follows. The rest +is unchanged. + +.. code-block:: shell + + ./network-ns3 --cfg=network/model:NS3 (other parameters) + +Many other files from the ``examples/platform directory`` are usable with the +ns-3 model, such as `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. + +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: + + * The default values (e.g., TCP parameters) are the ns3 default values. + * ns-3 networks are routed using the shortest path algorithm, using + ``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``. + * 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. + +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. + +Troubleshooting with ns-3 and SimGrid +************************************* + +I fail to compile ns-3 within SimGrid +------------------------------------- + +If you have a ns-3 version that is not known to SimGrid yet, edit +``tools/cmake/Modules/FindNS3.cmake`` in your SimGrid tree, according to +the comments on top of this file. + +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) ``libns3-dev`` +package. Update it, or install ``libns3-3`` manually. + +The simulation hangs at some point +---------------------------------- + +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. + +I get a warning that some routes are ignored +-------------------------------------------- + +Any routes longer than one hop are ignored in ns-3. Please refer to +:ref:`ns3_use` for details. diff --git a/tools/cmake/DefinePackages.cmake b/tools/cmake/DefinePackages.cmake index a70f4fde0d..03ff163bbe 100644 --- a/tools/cmake/DefinePackages.cmake +++ b/tools/cmake/DefinePackages.cmake @@ -848,7 +848,6 @@ set(DOC_SOURCES doc/doxygen/module-trace.doc doc/doxygen/module-xbt.doc doc/doxygen/module-index.doc - doc/doxygen/ns3.doc doc/doxygen/outcomes.doc doc/doxygen/outcomes_logs.doc doc/doxygen/outcomes_vizu.doc @@ -895,6 +894,7 @@ set(DOC_SOURCES docs/source/Installing_SimGrid.rst docs/source/Start_Your_Own_Project.rst docs/source/models.rst + docs/source/ns3.rst docs/source/platform.rst docs/source/platform_howtos.rst docs/source/platform_reference.rst -- 2.20.1