doc/doxygen/pls.doc

   1 /*! \page pls Packet level simulation
   2
   3 It is possible to use a packet-level network simulator
   4 instead of the default flow-based simulation. You may want to use such
   5 an approach if you have doubts about the validity of the default model
   6 or if you want to perform some validation experiments. At the moment,
   7 we support the GTNetS simulator and since version 3.6.2, ns-3.
   8
   9
  10 \section pls_simgrid_configuration_gtnets Using GTNetS
  11
  12
  13 <i>
  14 To enable GTNetS model inside SimGrid it is needed to patch the GTNetS simulator source code
  15 and build/install it from scratch
  16 </i>
  17
  18  - <b>Download and enter the recent downloaded GTNetS directory</b>
  19
  20 \verbatim
  21 svn checkout svn://scm.gforge.inria.fr/svn/simgrid/contrib/trunk/GTNetS/
  22 cd GTNetS
  23 \endverbatim
  24
  25
  26  - <b>Use the following commands to unzip and patch GTNetS package to work within SimGrid.</b>
  27
  28 \verbatim
  29 unzip gtnets-current.zip
  30 tar zxvf gtnets-current-patch.tgz
  31 cd gtnets-current
  32 cat ../00*.patch | patch -p1
  33 \endverbatim
  34
  35   - <b>OPTIONALLY</b> you can use a patch for itanium 64bit processor family.
  36
  37 \verbatim
  38 cat ../AMD64-FATAL-Removed-DUL_SIZE_DIFF-Added-fPIC-compillin.patch | patch -p1
  39 \endverbatim
  40
  41  - <b>Compile GTNetS</b>
  42
  43    Due to portability issues it is possible that GTNetS does not compile in your architecture. The patches furnished in SimGrid SVN repository are intended for use in Linux architecture only. Unfortunately, we do not have the time, the money, neither the manpower to guarantee GTNetS portability. We advice you to use one of GTNetS communication channel to get more help in compiling GTNetS.
  44
  45
  46 \verbatim
  47 ln -sf Makefile.linux Makefile
  48 sed -i 's/-fPIC/-fPIC -fpermissive/g' Makefile
  49 make depend
  50 make debug
  51 \endverbatim
  52
  53
  54  - <b>NOTE</b> A lot of warnings are expected but the application should compile
  55  just fine. If the makefile insists in compiling some QT libraries
  56  please try a make clean before asking for help.
  57
  58
  59  - <b>To compile optimized version</b>
  60
  61 \verbatim
  62 make opt
  63 \endverbatim
  64
  65
  66  - <b>Installing GTNetS</b>
  67
  68  It is important to put the full path of your libgtsim-xxxx.so file when creating the symbolic link. Replace < userhome > by some path you have write access to.
  69
  70 \verbatim
  71 ln -sf /<absolute_path>/gtnets_current/libgtsim-debug.so /<userhome>/usr/lib/libgtnets.so
  72 export LD_LIBRARY_PATH=${LD_LIBRARY_PATH:+$LD_LIBRARY_PATH:}/<userhome>/usr/lib/
  73 mkdir /<userhome>/usr/include/gtnets
  74 cp -fr SRC/*.h /<userhome>/usr/include/gtnets
  75 \endverbatim
  76
  77
  78  - <b>Enable GTNetS support in SimGrid</b>
  79
  80 In order to enable gtnets with simgrid you have to give where is gtnets. (path to \<gtnets_path\>/lib and \<gtnets_path\>/include)
  81
  82 \verbatim
  83 cmake . -Denable_gtnets=ON -Dgtnets_path=/<userhome>/usr
  84 \endverbatim
  85
  86  - <b>Once you have followed all the instructions for compiling and
  87    installing successfully you can activate this feature at
  88    runntime with the following options:</b>
  89
  90 \verbatim
  91 cd simgrid
  92 make
  93 ctest -R gtnets
  94 \endverbatim
  95
  96
  97  - <b>Or try the GTNetS model dogbone example with</b>
  98
  99 \verbatim
 100 gtnets/gtnets gtnets/onelink-p.xml gtnets/onelink-d.xml --cfg=network_model:GTNets
 101 \endverbatim
 102
 103
 104  A long version of this <a href="http://gforge.inria.fr/docman/view.php/12/6283/GTNetS HowTo.html">HowTo</a>  it is available
 105
 106
 107  More about GTNetS simulator at <a href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/index.html">GTNetS Website</a>
 108
 109
 110  - <b>DISCLAIMER</b>
 111  The patches provided by us worked successfully with GTNetS found
 112  <a href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/software/gtnets-current.zip">here</a>,
 113  dated from 12th June 2008. Due to the discontinuing development of
 114  GTNetS it is impossible to precise a version number. We STRONGLY recommend you
 115  to download and install the GTNetS version found in SimGrid repository as explained above.
 116
 117 \section pls_simgrid_configuration_ns3 Using NS3
 118
 119 It is possible to use discrete-event network simulator <a href="http://www.nsnam.org/">(ns-3)</a> for Internet systems
 120 instead of the default one.
 121
 122 A ns-3 platform is created according to the platform file you provide in SimGrid format. However from this configuration, we had to set up some extra parameters :
 123
 124 <ul>
 125 <li>
 126 First, whenever possible, we let default ns3 values and we don't changed it ; in case you have doubts on values for those parameters (TCP parameters for example), blame ns-3...
 127 </li>
 128
 129 <li>
 130 Second, routing used inside ns-3 is a global and static one, relying on a shortest path algorithm. We did so by using ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables.
 131 </li>
 132
 133 <li>
 134 Third, we also choose to restrict the way your platform is built : end hosts cannot have more than one interface card (so, only one &lt;link&gt; in your SimGrid platform should link
 135 an end host to the platform ; if not, your end host will be considered as a router.
 136 </li>
 137
 138 </ul>
 139 <i>
 140 To use ns3 model inside SimGrid you have to install at least the version 3.10 of ns3 simulator.
 141 </i>
 142
 143 - <b>Download and enter the lateast release (here the 3.12.1)</b>
 144
 145 \verbatim
 146 http://www.nsnam.org/release/ns-allinone-3.12.1.tar.bz2
 147 tar -xf ns-allinone-3.12.1.tar.bz2
 148 cd ns-allinone-3.12.1/ns-3.12.1/
 149 \endverbatim
 150
 151 - <b>Configure, make and install ns3</b>
 152
 153 \verbatim
 154 ./waf configure --prefix="ns-3_install_directory"
 155 ./waf
 156 ./waf install
 157 \endverbatim
 158
 159 After install ns-3 you should have directories into your "ns-3_install_directory":
 160         \li include/ns3/
 161   \li lib/
 162   \li bin/ (with 3.12)
 163
 164 In some cases, include/ns3 does not exist, but there is an /include/ns3.XX . Then, a simple symbolic link is enough. From the /path/to/ns3/installation/include directory, run:
 165 \verbatim
 166 ln -s -T ns3.XX/ns3 ns3
 167 \endverbatim
 168
 169 Make sure to replace 3.XX with your version of NS3, e.g., 3.17, or 3.18.
 170 Check the correct presence of the symbolic link using
 171 \verbatim
 172 ls -al
 173 \endverbatim
 174
 175 and you should see an ns3 link pointing to ns3.XX. E.g., ns3 -> ns3.17/ns3
 176 You also need to add to the LD_LIBRARY_PATH : "ns-3_install_directory/lib".
 177
 178 - <b>Enable ns-3 support on SimGrid</b>
 179
 180 Enabling ns-3 integration with Simgrid requires several intermediate steps.
 181 -# Modify "simgrid_path/buildtools/CMake/MakeLib.cmake".\n
 182 The "-lns3.${NS3_VERSION_MINOR}-[module]" should match the library names in your "ns-3_install_directory/lib". The "module" can be one of the following: core, csma, point-to-oint, internet, applications, bridge, mpi, config-store, stats, network. For this, in the "MakeLib.cmake" file find the "else" branch of "if(HAVE_NS3)" statement. Replace the se of "-lns3.${NS3_VERSION_MINOR}-[module]" with "-lns3[version]-[module]-debug" in "SET(SIMGRID_DEP)". On the same branch, add "-I/path/to/ns-3_install_directory/include" to MAKE_C_FLAGS and "CMAKE_CXX_FLAGS".
 183 -# There might be a need for creating symbolic links of each ns3 library from "ns-3_install_directory/lib" to "/usr/lib".
 184 -# In order to enable ns-3 with simgrid you have to give where is ns-3 to the simgrid configuration command. (path to \<ns3_path\>/lib and \<ns3_path\>/include)
 185
 186 \verbatim
 187 cmake . -Denable_ns3=ON -Dns3_path=<ns3_path>
 188 \endverbatim
 189
 190 With the output of the configuration you can see if ns-3 is detected (see CFlags: ; CPPFlags: ; Compile NS-3: , NS-3 path:).
 191
 192 \verbatim
 193 Configuration of package `simgrid' on arch (=4):
 194              BUILDNAME :        UNIX
 195              SITE      :        Linux_2.6.38-11-generic_x86_64
 196              Release   :        simgrid-3.6.1
 197
 198          Compiler: c++ :        /usr/bin/c++
 199                 version:        4.6.1
 200          Compiler: c   :        /usr/bin/gcc
 201                 version:        4.6.1
 202
 203                CFlags  :        -O3 -finline-functions -funroll-loops -fno-strict-aliasing -L/usr/lib/x86_64-linux-gnu -I/usr/include
 204                                         -L/home/navarrop/Install/ns3-3.10/lib -I/home/navarrop/Install/ns3-3.10/include -g3  -D_NS3_3_10
 205                CPPFlags:        -I/home/navarrop/Install/ns3-3.10/include -L/home/navarrop/Install/ns3-3.10/lib
 206
 207         Compile Gtnets :        0
 208         Compile NS-3   :        1 ---------------------> Be sure this option is "1" otherwise ns-3 is not activated
 209         Gtnets path    :
 210         NS-3 path      :        /home/navarrop/Install/ns3-3.10
 211         Compile Lua    :
 212         Compile Smpi   :        OFF
 213         Compile Static :        OFF
 214
 215         Maintainer mode:        OFF
 216         Supernovae mode:        OFF
 217         Model checking :        OFF
 218         Tracing mode   :        OFF
 219         Jedule  mode   :        OFF
 220         Latency bound  :        OFF
 221         Graphviz mode  :
 222
 223         Simgrid dependencies:   -lm -lpthread -lns3 -lrt
 224         Smpi dependencies   :
 225
 226         INSTALL_PREFIX:         /usr/local
 227 -- Configuring done
 228 -- Generating done
 229 -- Build files have been written to: /home/navarrop/workspace/simgrid/build
 230 \endverbatim
 231
 232 Now you can compile SimGrid
 233 \verbatim
 234 make
 235 \endverbatim
 236
 237 Then you can see if ns-3 is well activated by testing
 238 \verbatim
 239 ctest -R ns3
 240 \endverbatim
 241
 242 You should see
 243 \verbatim
 244     Start 182: msg-ns3-thread
 245 1/3 Test #182: msg-ns3-thread ...................   Passed    0.35 sec
 246     Start 183: msg-ns3-ucontext
 247 2/3 Test #183: msg-ns3-ucontext .................   Passed    0.22 sec
 248     Start 184: msg-ns3-raw
 249 3/3 Test #184: msg-ns3-raw ......................   Passed    0.23 sec
 250 \endverbatim
 251
 252 - <b>Use case</b>
 253
 254 An example of using Simgrid with NS3 can be found in:
 255
 256 \verbatim
 257 path/to/simgrid/examples/src/surf/ns3/
 258 \endverbatim
 259
 260 From the example folder above, the command line sintax is
 261
 262 \verbatim
 263 <simgrid_executable> <platform description file> <deployment file> --cfg=network/model:NS3 --log=surf.threshold:info
 264 \endverbatim
 265
 266 This example should work:
 267 \verbatim
 268 ./ns3 ./3hosts_2links_p.xml 3hosts_2links_d.xml --cfg=network/model:NS3 --log=root.threshold:info
 269 \endverbatim
 270
 271 More about ns-3 simulator <a href="http://www.nsnam.org/">(Official website)</a>
 272
 273 */