From 2bc7094498ec2b482928830f5270fe21f9efe800 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Sat, 31 Dec 2016 00:08:14 +0100 Subject: [PATCH] rewrite the NS3/SimGrid doc --- doc/doxygen/ns3.doc | 101 ++++++++++++++++++------------ tools/cmake/Modules/FindNS3.cmake | 4 +- 2 files changed, 63 insertions(+), 42 deletions(-) diff --git a/doc/doxygen/ns3.doc b/doc/doxygen/ns3.doc index c34f7831ae..20a967da4a 100644 --- a/doc/doxygen/ns3.doc +++ b/doc/doxygen/ns3.doc @@ -5,16 +5,8 @@ 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. - -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 +of your simulation. Once NS3 is installed, and SimGrid compiled with +the N3 support, enabling this model is very easy. \section pls_ns3_install Installing ns-3 @@ -28,71 +20,100 @@ You can also install it from scratch with the following commands: \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 -For more information, please refer to the ns-3 documentation. +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_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 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. You can also double-check by executing the tests -after the compilation. +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 the variable \c HAVE_NS3 is defined to 1, then NS3 +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. + +You can also double-check by executing the +tests after the compilation. \verbatim $ ctest -R ns3 (test(s) should be run) \endverbatim -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. +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 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. +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. \section pls_ns3_use Using ns-3 from SimGrid -Basically, you just have to run your SimGrid simulation with the -configuration option "network/model" set to "NS3". The rest remains -unchanged. +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. + +If your platform have longer routes, simply add some routers to break +these routes. SimGrid's routers are similar to hosts, without +computational abilities. + +Once your platform is OK, just change the "network/model" +configuration option to "NS3". The rest remains unchanged. -The following should work from the examples/msg/network-ns3 folder (network-ns3 is the name of our example binary). +The following should work from the examples/msg/network-ns3 folder, +where the \c network-ns3 binary example lives. \verbatim -./network-ns3 ./3hosts_2links_p.xml 3hosts_2links_d.xml --cfg=network/model:NS3 --log=root.threshold:info +./network-ns3 ../../platforms/small_platform_one_link_routes.xml 3hosts_2links_d.xml --cfg=network/model:NS3 --log=root.threshold:info \endverbatim -A ns-3 platform is automatically created from the provided SimGrid platform file. However, there are some known caveats: +Many other files from the examples/platform directory are usable with +the ns-3 model. Check the file +examples/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". + +A ns-3 platform is automatically created from the provided SimGrid +platform. However, there are some known caveats: +
  • ns-3 networks are routed using the shortest path algorithm, using + ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables.
    • -More about ns-3 simulator (Official website) +
  • 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.
    • -\subsection ns3_examples Examples + -For an example using NS3 as a SimGrid module, please refer to the -@ref msg_ex_ns3 "relevant section" of the documentation. +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. */ diff --git a/tools/cmake/Modules/FindNS3.cmake b/tools/cmake/Modules/FindNS3.cmake index 2fc3f7688b..750400e53f 100644 --- a/tools/cmake/Modules/FindNS3.cmake +++ b/tools/cmake/Modules/FindNS3.cmake @@ -13,8 +13,8 @@ # - No proper find_package() integration ## ADDING A NS3 VERSION. -# - Add ns3.${version}-core to the NAME line of the find_library below -# - Add include/ns3{version} to the PATH_SUFFIXES line of the find_path below +# - Add "ns3.${version}-core ns3.${version}-core-debug ns3.${version}-core-optimized" to the NAME line of the find_library below +# - Add "include/ns3{version}" to the PATH_SUFFIXES line of the find_path below set(HAVE_NS3 0) set(NS3_HINT ${ns3_path} CACHE PATH "Path to search for NS3 lib and include") -- 2.20.1