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 You may want to replace the SimGrid network models by the ones of the
 120 well known packet-level network simulator <a href="http://www.nsnam.org/">NS-3</a> instead.
 121 This section explains how to do so.
 122
 123 \subsection pls_simgrid_configuration_ns3_install Installing NS3
 124
 125 The easiest is to install it with the package manager.  Under
 126 Debian/Ubuntu, simply type as root:
 127
 128 \verbatim
 129 apt-get install libns3-dev ns3
 130 \endverbatim
 131
 132 You can also install it from scratch with the following commands:
 133
 134 \verbatim
 135 # Download the source
 136 wget http://www.nsnam.org/release/ns-allinone-3.22.tar.bz2
 137 tar -xf ns-allinone-3.22.tar.bz2
 138 cd ns-allinone-3.22/ns-3.22/
 139 # Configure, build and install
 140 ./waf configure --prefix="ns-3_install_directory"
 141 ./waf
 142 ./waf install
 143 \endverbatim
 144
 145 For more information, please refer to the NS-3 documentation.
 146
 147 \subsection pls_simgrid_configuration_ns3_config Enabling SimGrid's support for NS3
 148
 149 Normally, you just have to enable NS3 in ccmake or cmake as follows.
 150 If you installed NS3 in a regular path, just drop the ns3_path
 151 configuration item.
 152
 153 \verbatim
 154 cmake . -Denable_ns3=ON -Dns3_path=<ns3_path>
 155 \endverbatim
 156
 157 By the end of the configuration, cmake reports whether NS-3 was found.
 158 You can also double-check by executing the tests after the compilation.
 159
 160 \verbatim
 161 $ ctest -R ns3
 162 (several tests should be run)
 163 \endverbatim
 164
 165 If you have a NS3 version that is not known (yet) to SimGrid, the
 166 detection may fail. In that case, edit  the file
 167 buildtools/Cmake/Modules/FindNS3.cmake in your SimGrid tree. The
 168 required changes are very easy, and documented at the beginning of
 169 this file.
 170
 171 If the compilation fails when linking the library because of some .a
 172 file that cannot be used dynamically, that's probably because you only
 173 installed the libns3-dev library on your Debian, where you also need
 174 libns3-3. That's probably a bug of the libns3-dev package that should
 175 depend on the dynamic libraries corresponding to its .so files.
 176
 177 \subsection pls_simgrid_configuration_ns3_use Using NS3 from SimGrid
 178
 179 A working example of NS3/SimGrid interactions can be found in
 180 examples/msg/ns3. Basically, you just have to run your SimGrid
 181 simulation with the configuration option "network/model" set to the
 182 value "NS3". The rest remains unchanged.
 183
 184 The following should work from the examples/msg/ns3 folder (ns3 here
 185 is the name of our example binary).
 186
 187 \verbatim
 188 ./ns3 ./3hosts_2links_p.xml 3hosts_2links_d.xml --cfg=network/model:NS3 --log=root.threshold:info
 189 \endverbatim
 190
 191 A ns-3 platform is automatically created from the SimGrid platform
 192 file that you will provide. There is some caveats to know:
 193
 194 <ul>
 195   <li>The default values (e.g., TCP parameters) are the ns3
 196     values. Don't blame us for them.</li>
 197
 198   <li>NS3 networks are routed using the shortest path algorithm, using
 199     ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables.</li>
 200
 201   <li>End hosts cannot have more than one interface card (so, only one
 202    &lt;link&gt; in your SimGrid platform should link an end host to
 203    the platform ; if not, your end host will be considered as a
 204    router.  </li>
 205 </ul>
 206
 207
 208 More about ns-3 simulator <a href="http://www.nsnam.org/">(Official website)</a>
 209
 210 */