+\subsubsection faq_SURF_dynamic Expressing dynamic resource availability in platform files
+
+A nice feature of SimGrid is that it enables you to seamlessly have
+resources whose availability change over time. When you build a
+platform, you generally declare hosts like that:
+
+\verbatim
+ <host id="host A" power="100.00"/>
+\endverbatim
+
+If you want the availability of "host A" to change over time, the only
+thing you have to do is change this definition like that:
+
+\verbatim
+ <host id="host A" power="100.00" availability_file="trace_A.txt" state_file="trace_A_failure.txt"/>
+\endverbatim
+
+For hosts, availability files are expressed in fraction of available
+power. Let's have a look at what "trace_A.txt" may look like:
+
+\verbatim
+PERIODICITY 1.0
+0.0 1.0
+11.0 0.5
+20.0 0.9
+\endverbatim
+
+At time 0, our host will deliver 100 flop/s. At time 11.0, it will
+deliver only 50 flop/s until time 20.0 where it will will start
+delivering 90 flop/s. Last at time 21.0 (20.0 plus the periodicity
+1.0), we'll be back to the beginning and it will deliver 100 flop/s.
+
+Now let's look at the state file:
+\verbatim
+PERIODICITY 10.0
+1.0 -1.0
+2.0 1.0
+\endverbatim
+
+A negative value means "off" while a positive one means "on". At time
+1.0, the host is on. At time 1.0, it is turned off and at time 2.0, it
+is turned on again until time 12 (2.0 plus the periodicity 10.0). It
+will be turned on again at time 13.0 until time 23.0, and so on.
+
+Now, let's look how the same kind of thing can be done for network
+links. A usual declaration looks like:
+
+\verbatim
+ <link id="LinkA" bandwidth="10.0" latency="0.2"/>
+\endverbatim
+
+You have at your disposal the following options: bandwidth_file,
+latency_file and state_file. The only difference with hosts is that
+bandwidth_file and latency_file do not express fraction of available
+power but are expressed directly in bytes per seconds and seconds.
+
+\subsubsection faq_platform_multipath How to express multipath routing in platform files?
+
+It is unfortunately impossible to express the fact that there is more
+than one routing path between two given hosts. Let's consider the
+following platform file:
+
+\verbatim
+<route src="A" dst="B">
+ <link:ctn id="1"/>
+</route>
+<route src="B" dst="C">
+ <link:ctn id="2"/>
+</route>
+<route src="A" dst="C">
+ <link:ctn id="3"/>
+</route>
+\endverbatim
+
+Although it is perfectly valid, it does not mean that data traveling
+from A to C can either go directly (using link 3) or through B (using
+links 1 and 2). It simply means that the routing on the graph is not
+trivial, and that data do not following the shortest path in number of
+hops on this graph. Another way to say it is that there is no implicit
+in these routing descriptions. The system will only use the routes you
+declare (such as <route src="A" dst="C"><link:ctn
+id="3"/></route>), without trying to build new routes by aggregating
+the provided ones.
+
+You are also free to declare platform where the routing is not
+symmetric. For example, add the following to the previous file:
+
+\verbatim
+<route src="C" dst="A">
+ <link:ctn id="2"/>
+ <link:ctn id="1"/>
+</route>
+\endverbatim
+
+This makes sure that data from C to A go through B where data from A
+to C go directly. Don't worry about realism of such settings since
+we've seen ways more weird situation in real settings (in fact, that's
+the realism of very regular platforms which is questionable, but
+that's another story).
+
+\subsubsection faq_flexml_bypassing Bypassing the XML parser with your own C functions
+
+So you want to bypass the XML files parser, uh? Maybe doing some parameter
+sweep experiments on your simulations or so? This is possible, and
+it's not even really difficult (well. Such a brutal idea could be
+harder to implement). Here is how it goes.
+
+For this, you have to first remember that the XML parsing in SimGrid is done
+using a tool called FleXML. Given a DTD, this gives a flex-based parser. If
+you want to bypass the parser, you need to provide some code mimicking what
+it does and replacing it in its interactions with the SURF code. So, let's
+have a look at these interactions.
+
+FleXML parser are close to classical SAX parsers. It means that a
+well-formed SimGrid platform XML file might result in the following
+"events":
+
+ - start "platform_description" with attribute version="2"
+ - start "host" with attributes id="host1" power="1.0"
+ - end "host"
+ - start "host" with attributes id="host2" power="2.0"
+ - end "host"
+ - start "link" with ...
+ - end "link"
+ - start "route" with ...
+ - start "link:ctn" with ...
+ - end "link:ctn"
+ - end "route"
+ - end "platform_description"
+
+The communication from the parser to the SURF code uses two means:
+Attributes get copied into some global variables, and a surf-provided
+function gets called by the parser for each event. For example, the event
+ - start "host" with attributes id="host1" power="1.0"
+
+let the parser do something roughly equivalent to:
+\verbatim
+ strcpy(A_host_id,"host1");
+ A_host_power = 1.0;
+ STag_host();
+\endverbatim
+
+In SURF, we attach callbacks to the different events by initializing the
+pointer functions to some the right surf functions. Since there can be
+more than one callback attached to the same event (if more than one
+model is in use, for example), they are stored in a dynar. Example in
+workstation_ptask_L07.c:
+\verbatim
+ /* Adding callback functions */
+ surf_parse_reset_parser();
+ surfxml_add_callback(STag_surfxml_host_cb_list, &parse_cpu_init);
+ surfxml_add_callback(STag_surfxml_prop_cb_list, &parse_properties);
+ surfxml_add_callback(STag_surfxml_link_cb_list, &parse_link_init);
+ surfxml_add_callback(STag_surfxml_route_cb_list, &parse_route_set_endpoints);
+ surfxml_add_callback(ETag_surfxml_link_c_ctn_cb_list, &parse_route_elem);
+ surfxml_add_callback(ETag_surfxml_route_cb_list, &parse_route_set_route);
+
+ /* Parse the file */
+ surf_parse_open(file);
+ xbt_assert1((!surf_parse()), "Parse error in %s", file);
+ surf_parse_close();
+\endverbatim
+
+So, to bypass the FleXML parser, you need to write your own version of the
+surf_parse function, which should do the following:
+ - Fill the A_<tag>_<attribute> variables with the wanted values
+ - Call the corresponding STag_<tag>_fun function to simulate tag start
+ - Call the corresponding ETag_<tag>_fun function to simulate tag end
+ - (do the same for the next set of values, and loop)
+
+Then, tell SimGrid that you want to use your own "parser" instead of the stock one:
+\verbatim
+ surf_parse = surf_parse_bypass_environment;
+ MSG_create_environment(NULL);
+ surf_parse = surf_parse_bypass_application;
+ MSG_launch_application(NULL);
+\endverbatim
+
+A set of macros are provided at the end of
+include/surf/surfxml_parse.h to ease the writing of the bypass
+functions. An example of this trick is distributed in the file
+examples/msg/masterslave/masterslave_bypass.c
+
+\subsection faq_simgrid_configuration Changing SimGrid's behavior
+
+A number of options can be given at runtime to change the default
+SimGrid behavior. In particular, you can change the default cpu and
+network models...
+
+\subsubsection faq_simgrid_configuration_gtnets Using GTNetS
+
+It is possible to use a packet-level network simulator
+instead of the default flow-based simulation. You may want to use such
+an approach if you have doubts about the validity of the default model
+or if you want to perform some validation experiments. At the moment,
+we support the GTNetS simulator (it is still rather experimental
+though, so leave us a message if you play with it).
+
+
+<i>
+To enable GTNetS model inside SimGrid it is needed to patch the GTNetS simulator source code
+and build/install it from scratch
+</i>
+
+ - <b>Download and enter the recent downloaded GTNetS directory</b>
+
+ \verbatim
+ svn checkout svn://scm.gforge.inria.fr/svn/simgrid/contrib/trunk/GTNetS/
+ cd GTNetS
+ \endverbatim
+
+
+ - <b>Use the following commands to unzip and patch GTNetS package to work within SimGrid.</b>
+
+ \verbatim
+ unzip gtnets-current.zip
+ tar zxvf gtnets-current-patch.tgz
+ cd gtnets-current
+ cat ../00*.patch | patch -p1
+ \endverbatim
+
+ - <b>OPTIONALLY</b> you can use a patch for itanium 64bit processor family.
+
+ \verbatim
+ cat ../AMD64-FATAL-Removed-DUL_SIZE_DIFF-Added-fPIC-compillin.patch | patch -p1
+ \endverbatim
+
+ - <b>Compile GTNetS</b>
+
+ 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.
+
+
+ \verbatim
+ ln -sf Makefile.linux Makefile
+ make depend
+ make debug
+ \endverbatim
+
+
+ - <b>NOTE</b> A lot of warnings are expected but the application should compile
+ just fine. If the makefile insists in compiling some QT libraries
+ please try a make clean before asking for help.
+
+
+ - <b>To compile optimized version</b>
+
+ \verbatim
+ make opt
+ \endverbatim
+
+
+ - <b>Installing GTNetS</b>
+
+ 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.
+
+ \verbatim
+ ln -sf /<absolute_path>/gtnets_current/libgtsim-debug.so /<userhome>/usr/lib/libgtnets.so
+ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/<userhome>/usr/lib/libgtnets.so
+ mkdir /<userhome>/usr/include/gtnets
+ cp -fr SRC/*.h /<userhome>/usr/include/gtnets
+ \endverbatim
+
+
+ - <b>Enable GTNetS support in SimGrid</b>
+
+ \verbatim
+ ./configure --with-gtnets=/<userhome>/usr
+ \endverbatim
+
+ - <b>Once you have followed all the instructions for compiling and
+ installing successfully you can activate this feature at
+ runntime with the following options:</b>
+
+ \verbatim
+ cd simgrid/example/msg/
+ make
+ make check
+ \endverbatim
+
+
+ - <b>Or try the GTNetS model dogbone example with</b>
+
+ \verbatim
+ gtnets/gtnets gtnets/onelink-p.xml gtnets/onelink-d.xml --cfg=network_model:GTNets
+ \endverbatim
+
+
+ A long version of this <a href="http://gforge.inria.fr/docman/view.php/12/6283/GTNetS HowTo.html">HowTo</a> it is available
+
+
+ More about GTNetS simulator at <a href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/index.html">GTNetS Website</a>
+
+
+ - <b>DISCLAIMER</b>
+ The patches provided by us worked successfully with GTNetS found
+ <a href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/software/gtnets-current.zip">here</a>,
+ dated from 12th June 2008. Due to the discontinuing development of
+ GTNetS it is impossible to precise a version number. We STRONGLY recommend you
+ to download and install the GTNetS version found in SimGrid repository as explained above.
+
+
+
+
+\subsubsection faq_simgrid_configuration_alternate_network Using alternative flow models
+
+The default simgrid network model uses a max-min based approach as
+explained in the research report
+<a href="ftp://ftp.ens-lyon.fr/pub/LIP/Rapports/RR/RR2002/RR2002-40.ps.gz">A Network Model for Simulation of Grid Application</a>.
+Other models have been proposed and implemented since then (see for example
+<a href="http://mescal.imag.fr/membres/arnaud.legrand/articles/simutools09.pdf">Accuracy Study and Improvement of Network Simulation in the SimGrid Framework</a>)
+and can be activated at runtime. For example:
+\verbatim
+./mycode platform.xml deployment.xml --cfg=workstation_model:compound --cfg=network_model:LV08 -cfg=cpu_model:Cas01
+\endverbatim
+
+Possible models for the network are currently "Constant", "CM02",
+"LegrandVelho", "GTNets", Reno", "Reno2", "Vegas". Others will
+probably be added in the future and many of the previous ones are
+experimental and are likely to disappear without notice...
+
+\section faq_troubleshooting Troubleshooting
+
+\subsection faq_trouble_lib_compil SimGrid compilation and installation problems
+
+\subsubsection faq_trouble_lib_config ./configure fails!
+
+We know only one reason for the configure to fail:
+
+ - <b>You are using a broken build environment</b>\n
+ If symptom is that configure complains about gcc not being able to build
+ executables, you are probably missing the libc6-dev package. Damn Ubuntu.
+
+If you experience other kind of issue, please get in touch with us. We are
+always interested in improving our portability to new systems.
+
+\subsubsection faq_trouble_distcheck Dude! "make check" fails on my machine!
+
+Don't assume we never run this target, because we do. Check
+http://bob.loria.fr:8010 if you don't believe us.
+
+There is several reasons which may cause the make check to fail on your
+machine:
+
+ - <b>You are using a broken libc (probably concerning the contextes)</b>.\n
+ The symptom is that the "make check" fails within the examples/msg directory.\n
+ By default, SimGrid uses something called ucontexts. This is part of the
+ libc, but it's quite undertested. For example, some (old) versions of the
+ glibc on alpha do not implement these functions, but provide the stubs
+ (which return ENOSYS: not implemented). It may fool our detection mechanism
+ and leads to segfaults. There is not much we can do to fix the bug.
+ A workaround is to compile with --with-context=pthread to avoid
+ ucontext completely. You'll be a bit more limited in the number
+ of simulated processes you can start concurrently, but 5000
+ processes is still enough for most purposes, isn't it?\n
+ This limitation is the reason why we insist on using this piece of ...
+ software even if it's so troublesome.\n
+ <b>=> use --with-pthread on AMD64 architecture that do not have an
+ ultra-recent libc.</b>
+
+ - <b>There is a bug in SimGrid we aren't aware of</b>.\n
+ If none of the above apply, please drop us a mail on the mailing list so
+ that we can check it out. Make sure to read \ref faq_bugrepport
+ before you do so.
+
+\subsection faq_trouble_compil User code compilation problems
+
+\subsubsection faq_trouble_err_logcat "gcc: _simgrid_this_log_category_does_not_exist__??? undeclared (first use in this function)"
+
+This is because you are using the log mecanism, but you didn't created
+any default category in this file. You should refer to \ref XBT_log
+for all the details, but you simply forgot to call one of
+XBT_LOG_NEW_DEFAULT_CATEGORY() or XBT_LOG_NEW_DEFAULT_SUBCATEGORY().
+
+\subsubsection faq_trouble_pthreadstatic "gcc: undefined reference to pthread_key_create"
+
+This indicates that one of the library SimGrid depends on (libpthread
+here) was missing on the linking command line. Dependencies of
+libsimgrid are expressed directly in the dynamic library, so it's
+quite impossible that you see this message when doing dynamic linking.
+
+If you compile your code statically (and if you use a pthread version
+of SimGrid -- see \ref faq_more_processes), you must absolutely
+specify <tt>-lpthread</tt> on the linker command line. As usual, this should
+come after <tt>-lsimgrid</tt> on this command line.
+
+\subsection faq_trouble_errors Runtime error messages
+
+\subsubsection faq_flexml_limit "surf_parse_lex: Assertion `next limit' failed."