/*! \page faq Frequently Asked Questions
-\author Arnaud Legrand <arnaud.legrand@imag.fr>
+\htmlinclude .FAQ.doc.toc
\section faq_installation Installing the SimGrid library
installation process. This section is intended to help people that are
not familiar with compiling C files under UNIX. If you follow these
instructions and still have some troubles, drop an e-mail to
-<simgrid2-users@listes.ens-lyon.fr>.
+<simgrid-user@lists.gforge.inria.fr>.
\subsection faq_compiling Compiling SimGrid
Suppose you have uncompressed SimGrid in some temporary location of
-your home directory (say <tt>/home/joe/tmp/simgrid-2.18.2 </tt>). The
+your home directory (say <tt>/home/joe/tmp/simgrid-3.0.1 </tt>). The
simplest way to use SimGrid is to install it in your home
directory. Change your directory to
-<tt>/home/joe/tmp/simgrid-2.18.2</tt> and type
+<tt>/home/joe/tmp/simgrid-3.0.1</tt> and type
\verbatim./configure --prefix=$HOME
make
make install
\endverbatim
-If at some point, something fails, you can report me this problem but,
-please, avoid sending a laconic mail like "There is a problem. Is it
-normal ?". Send me the config.log file which is automatically
-generated by configure. Try to capture both the standard output and
-the error output of the <tt>make</tt> command. There is no way for me
-to help you if you do not give me a little bit of information.
+If at some point, something fails, check the section "\ref
+faq_compil_trouble". If it does not help, you can report this problem to the
+list but, please, avoid sending a laconic mail like "There is a problem. Is it
+okay?". Send the config.log file which is automatically generated by
+configure. Try to capture both the standard output and the error output of the
+<tt>make</tt> command with <tt>script</tt>. There is no way for us to help you
+without the relevant bits of information.
Now, the following directory should have been created :
version are available. Here is what you can find if you try a <tt>ls
/home/joe/lib</tt>:
-\verbatim libsimgrid.a libsimgrid.la libsimgrid.so libsimgrid.so.0 libsimgrid.so.0.0.1
+\verbatim libsimgrid.a libsimgrid.la libsimgrid.so libsimgrid.so.0 libsimgrid.so.0.0.1
\endverbatim
Thus, there is two ways to link your program with SimGrid:
MSG_launch_application()) and the call to
MSG_main()).
-To compile such a program, I suggest to use the following Makefile. It
-is a generic Makefile that I generally use with my students when I
-teach the C language.
+To compile such a program, we suggest to use the following
+Makefile. It is a generic Makefile that we have used many times with
+our students when we teach the C language.
\verbatim
all: masterslave
previous example should be enough for a first try but you may want to
perform some more complex compilations...
-\section faq_simgrid I'm new to SimGrid. I have some questions. Where should I start ?
+\section faq_simgrid I'm new to SimGrid. I have some questions. Where should I start?
-You are at the right place... Having a look to these <a
-href="http://graal.ens-lyon.fr/~alegrand/articles/Simgrid-Introduction.pdf">slides</a>
+You are at the right place... Having a look to these
+<a href="http://graal.ens-lyon.fr/~alegrand/articles/Simgrid-Introduction.pdf">slides</a>
may give you some insights on what SimGrid can help you to do and what
are its limitations. Then you definitely should read the \ref
-MSG_examples.
+MSG_examples. There is also a mailing list: <simgrid-user@lists.gforge.inria.fr>.
\subsection faq_generic Building a generic simulator
Please read carefully the \ref MSG_examples. You'll find in \ref
-msg_test.c a very simple consisting of a master (that owns a bunch of
+MSG_ex_master_slave a very simple consisting of a master (that owns a bunch of
tasks and distributes them) , some slaves (that process tasks whenever
they receive one) and some forwarder agents (that simply pass the
tasks they receive to some slaves).
-\subsection faq_examples I want some more complex examples !
+\subsection faq_visualization Visualizing the schedule
+
+It is sometime convenient to "see" how the agents are behaving. If you
+like colors, you can use <tt>tools/MSG_visualization/colorize.pl </tt>
+as a filter to your MSG outputs. It works directly with INFO. Beware,
+INFO() prints on stderr. Do not forget to redirect if you want to
+filter (e.g. with bash):
+\verbatim
+./msg_test small_platform.xml small_deployment.xml 2>&1 | ../../tools/MSG_visualization/colorize.pl
+\endverbatim
+
+We also have a more graphical output. Have a look at MSG_paje_output(). It
+generates an input to <a href="http://www-id.imag.fr/Logiciels/paje/">Paje</a>.
+<center>
+\htmlonly
+ <a href="Paje_MSG_screenshot.jpg"><img src="Paje_MSG_screenshot_thn.jpg"></a>
+\endhtmlonly
+</center>
+
+\subsection faq_postmortem_analysis Online/postmortem analysis
+
+Vizualization with Paje can be seen as a kind of postmortem
+analysis. However, as soon as you start playing with big simulations,
+you'll realize that processing such output is kind of tricky. There is
+so much generic informations that it is hard to find the information
+you are looking for.
+
+As a matter of fact, loging really depends on simulations (e.g. what
+kind of events is important...). That is why we do not propose a big
+dump of your whole simulation (it would slow everything down) but give
+you neat tools to structure you logs. Have a look at \ref XBT_log. In
+fact, rather than a post-mortem analysis, you may want to do it on the
+fly. The process you are running can do whatever you want. Have you
+thought about adding a global structure where you directly compute the
+informations that are really important rather than writing everything
+down and then processing huge files ?
+
+\subsection faq_C Argh! Do I really have to code in C ?
+
+Up until now, there is no binding for other languages. If you use C++,
+you should be able to use the SimGrid library as a standard C library
+and everything should work fine (simply <i>link</i> against this
+library; recompiling SimGrid with a C++ compiler won't work and it
+wouldn't help if you could).
+
+In fact, the bindings needed to allow one to use SimGrid from Perl,
+Python, Java, etc. are double-layered. The first layer would allow
+you to call for example the MSG_task_get_name(task) function while
+what you really want is a proper object wrapping allowing you to call
+task->name(). That's the purpose of the second layer. The first one
+is granted with C++ but can be done with tools like
+<a href="www.swig.org/">swig</a> for other languages like Perl, Ruby,
+Python, CAML. None of us really need the second one (which is a bit
+more demanding and cannot be automatically generated) yet and there is
+no real point in doing the first one without the second. :)
+
+As usual, you're welcome to participate.
+
+\section faq_MIA How to ....? Is there a function in the API to simply ....?
+
+Here is the deal. The whole SimGrid project (MSG, SURF, GRAS, ...) is
+meant to be kept as simple and generic as possible. We cannot add
+functions for everybody's need when these functions can easily be
+built from the ones already in the API. Most of the time, it is
+possible and when it was not possible we always have upgraded the API
+accordingly. When somebody asks us a question like "How to do that ?
+Is there a function in the API to simply do this ?", we're always glad
+to answer and help. However if we don't need this code for our own
+need, there is no chance we're going to write it... it's your job! :)
+The counterpart to our answers is that once you come up with a neat
+implementation of this feature (task duplication, RPC, thread
+synchronization, ...), you should send it to us and we will be glad to
+add it to the distribution. Thus, other people will take advantage of
+it (and we don't have to answer this question again and again ;).
+
+You'll find in this section a few "Missing In Action" features. Many
+people have asked about it and we have given hints on how to simply do
+it with MSG. Feel free to contribute...
+
+\subsection faq_MIA_examples I want some more complex examples!
Many people have come to ask me a more complex example and each time,
they have realized afterward that the basics were in the previous three
communications or computations). But the examples are sufficient to
start.
-I know I should add some more examples, but not some more complex
-ones... I should add some examples that illustrate some other
+We know. We should add some more examples, but not really some more
+complex ones... We should add some examples that illustrate some other
functionalities (like how to simply encode asynchronous
communications, RPC, process migrations, thread synchronization, ...)
-and I will do it when I will have a little bit more time. I have tried
-to document the examples so that they are understandable. I know it is
-not really satisfying but it is the best I have managed to do yet.
+and we will do it when we will have a little bit more time. We have
+tried to document the examples so that they are understandable. Tell
+us if something is not clear and once again feel free to participate!
+:)
+
+\subsection faq_MIA_taskdup Missing in action: Task duplication/replication
+
+There is no task duplication in MSG. When you create a task, you can
+process it or send it somewhere else. As soon as a process has sent
+this task, he doesn't have this task anymore. It's gone. The receiver
+process has got the task. However, you could decide upon receiving to
+create a "copy" of a task but you have to handle by yourself the
+semantic associated to this "duplication".
+
+As we already told, we prefer keeping the API as simple as
+possible. This kind of feature is rather easy to implement by users
+and the semantic you associate really depends on people. Having a
+*generic* task duplication mechanism is not that trivial (in
+particular because of the data field). That is why I would recommand
+that you write it by yourself even if I can give you advice on how to
+do it.
+
+You have the following functions to get informations about a task:
+MSG_task_get_name(), MSG_task_get_compute_duration(),
+MSG_task_get_remaining_computation(), MSG_task_get_data_size(),
+and MSG_task_get_data().
+
+You could use a dictionnary (#xbt_dict_t) of dynars (#xbt_dict_t). If
+you still don't see how to do it, please come back to us...
+
+\subsection faq_MIA_asynchronous I want to do asynchronous communications.
+
+Up until now, there is no asynchronous communications in MSG. However,
+you can create as many process as you want so you should be able to do
+whatever you want... I've written a queue module to help implementing
+some asynchronous communications at low cost (creating thousands of
+process only to handle communications may be problematic in term of
+performance at some point). I'll add it in the distribution asap.
+
+\subsection faq_MIA_thread_synchronization I need to synchronize my processes
+
+You obviously cannot use pthread_mutexes of pthread_conds. The best
+thing would be to propose similar structures. Unfortunately, we
+haven't found time to do it yet. However you can try to play with
+MSG_process_suspend() and MSG_process_resume(). You can even do some
+synchronization with fake communications (using MSG_task_get(),
+MSG_task_put() and MSG_task_Iprobe()).
+
+\subsection faq_MIA_host_load Where is the get_host_load function hidden in MSG?
+
+There is no such thing because its semantic wouldn't be really
+clear. Of course, it is something about the amount of host throughput,
+but there is as many definition of "host load" as people asking for
+this function. First, you have to remember that resource availability
+may vary over time, which make any load notion harder to define.
+
+It may be instantaneous value or an average one. Moreover it may be only the
+power of the computer, or may take the background load into account, or may
+even take the currently running tasks into account. In some SURF models,
+communications have an influence on computational power. Should it be taken
+into account too?
+
+So, we decided not to include such a function into MSG and let people do it
+thereselves so that they get the value matching exactly what they mean. One
+possibility is to run active measurement as in next code snippet. It is very
+close from what you would have to do out of the simulator, and thus gives
+you information that you could also get in real settings to not hinder the
+realism of your simulation.
+
+\verbatim
+double get_host_load() {
+ m_task_t task = MSG_task_create("test", 0.001, 0, NULL);
+ double date = MSG_get_clock();
+
+ MSG_task_execute(task);
+ date = MSG_get_clock() - date;
+ MSG_task_destroy(task);
+ return (0.001/date);
+}
+\endverbatim
+
+Of course, it may not match your personal definition of "host load". In this
+case, please detail what you mean on the mailing list, and we will extend
+this FAQ section to fit your taste if possible.
+
+\subsection faq_MIA_batch_scheduler Is there a native support for batch schedulers in SimGrid ?
+
+No, there is no native support for batch schedulers and none is
+planned because this is a very specific need (and doing it in a
+generic way is thus very hard). However some people have implemented
+their own batch schedulers. Vincent Garonne wrote one during his PhD
+and put his code in the contrib directory of our CVS so that other can
+keep working on it. You may find inspinring ideas in it.
+
+\subsection faq_MIA_checkpointing I need a checkpointing thing
+
+Actually, it depends on whether you want to checkpoint the simulation, or to
+simulate checkpoints.
+
+The first one could help if your simulation is a long standing process you
+want to keep running even on hardware issues. It could also help to
+<i>rewind</i> the simulation by jumping sometimes on an old checkpoint to
+cancel recent calculations.\n
+Unfortunately, such thing will probably never exist in SG. One would have to
+duplicate all data structures because doing a rewind at the simulator level
+is very very hard (not talking about the malloc free operations that might
+have been done in between). Instead, you may be interested in the Libckpt
+library (http://www.cs.utk.edu/~plank/plank/www/libckpt.html). This is the
+checkpointing solution used in the condor project, for example. It makes it
+easy to create checkpoints (at the OS level, creating something like core
+files), and rerunning them on need.
+
+If you want to simulate checkpoints instead, it means that you want the
+state of an executing task (in particular, the progress made towards
+completion) to be saved somewhere. So if a host (and the task executing on
+it) fails (cf. #MSG_HOST_FAILURE), then the task can be restarted
+from the last checkpoint.\n
+
+Actually, such a thing does not exists in SimGrid either, but it's just
+because we don't think it is fundamental and it may be done in the user code
+at relatively low cost. You could for example use a watcher that
+periodically get the remaining amount of things to do (using
+MSG_task_get_remaining_computation()), or fragment the task in smaller
+subtasks.
+
+\section faq_SG Where has SG disappeared?!?
+
+OK, it's time to explain what's happening to the SimGrid project. Let's
+start with a little bit of history.
+
+* Historically, SimGrid was a low-level toolkit for scheduling with
+classical models such as DAGs. That was SimGrid v.1.* aka SG, written
+by Henri Casanova. I (Arnaud) had been using it in its earliest
+versions during an internship at UCSD.
+
+Then we have realized that encoding distributed algorithm in SG was a
+real pain.
+
+* So we have built MSG on top of SG and have released SimGrid v.2.*. MSG
+offered a very basic API to encode a distributed application easily.
+However encoding MSG on top of SG was not really convenient and did not
+use the DAG part since the control of the task synchronization was done
+on top of MSG and no more in SG. We have been playing a little bit with
+MSG. We have realized that:
+
+ \li 1) the platform modeling was quite flexible and could be "almost"
+ automated (e.g. using random generator and post-annotations);
+
+ \li 2) SG was the bottleneck because of the way we were using
+ it. We needed to simulate concurrent transfers, complex load
+ sharing mechanisms. Many optimizations (e.g. trace integration)
+ were totally inefficient when combined with MSG and made extending SG
+ to implement new sharing policies, parallel tasks models, or failures
+ (many people were asking for these kind of features) a real pain;
+
+ \li 3) the application modeling was not really easy. Even though the
+ application modeling depends on people's applications, we thought
+ we could improve things here. One of our target here was realistic
+distributed applications ranging from computer sensor networks like
+the NWS to peer-to-peer applications;
+
+* So we have been planning mainly two things for SimGrid 3:
+
+ \li 1) I have proposed to get rid of SG and to re-implement a new kernel
+ that would be faster and more flexible. That is what I did in the
+end of 2004: SURF. SURF is based on a fast max-min linear solver
+using O(1) data-structures. I have quickly replaced SG by SURF in
+MSG and the result has been that on the MSG example, the new
+version was more than 10 times faster while we had gain a lot of
+flexibility. I think I could still easily make MSG faster but I
+have to work on MSG now (e.g. using some of the O(1)
+data-structures I've been using to build SURF) since it has become
+the bottleneck. Some MSG functions have been removed from the API
+but they were mainly intended to build the platform by hand (they
+had appeared in the earliest versions of MSG) and were therefore
+not useful anymore since we are providing a complete mechanism to
+automatically build the platform and deploy the agents on it.;
+
+ \li 2) GRAS is a new project Martin and I have come up with. The idea is
+to have a programming environment that let you program real
+distributed applications while letting you the ability to run it in
+the simulator without having to change the slightest line of your
+code. From the simulation point of view, GRAS performs the
+application modeling automatically... Up until now, GRAS works on
+top MSG for historical reasons but I'm going to make it work
+directly on top of SURF so that it can use all the flex and the
+speed provided by SURF.
+
+Those two things are working, but we want to make everything as clean as
+possible before releasing SimGrid v.3.
+
+So what about those nice DAGs we used to have in SimGrid v.1.? They're not
+anymore in SimGrid v.3. Let me recall you the way SimGrid 3 is organized:
+
+\verbatim
+________________
+| User code |
+|______________|
+| | MSG | GRAS |
+| -------------|
+| | SURF |
+| -------------|
+| XBT |
+----------------
+\endverbatim
+
+XBT is our tool box and now, you should have an idea of what the other ones
+are. As you can see, the primitive SG is not here anymore. However it could
+still be brought back if people really need it. Here is how it would fit.
+
+\verbatim
+______________________
+| User code |
+|____________________|
+| | MSG | GRAS | SG |
+| -------------------|
+| | SURF |
+| -------------------|
+| XBT |
+----------------------
+\endverbatim
+
+Re-implementing SG on top of SURF is really straightforward (it only
+requires a little bit of time that I really don't have right now)
+since the only thing that lacks to SURF is the DAG part. But adding it
+to SURF would slow it down and therefore slow MSG and GRAS which is
+not a good thing. However it is really not on the top of our TODO
+list because we have to work on GRAS, and its MPI counterpart, and a
+parallel task model, and ... Anyway, we finally have migrated our CVS
+to gforge so people that are interested by helping on this part will
+have the possibility to do it.
+
+\subsection faq_SG_DAG How to implement a distributed dynamic scheduler of DAGs.
+
+Distributed is somehow "contagious". If you start making distributed
+decisions, there is no way to handle DAGs directly anymore (unless I am
+missing something). You have to encode your DAGs in term of communicating
+process to make the whole scheduling process distributed. Believe me, it is
+worth the effort since you'll then be able to try your algorithms in a very
+wide variety of conditions. Here is an example of how you could do that.
+Assume T1 has to be done before T2.
+
+\verbatim
+ int your_agent(int argc, char *argv[] {
+ ...
+ T1 = MSG_task_create(...);
+ T2 = MSG_task_create(...);
+ ...
+ while(1) {
+ ...
+ if(cond) MSG_task_execute(T1);
+ ...
+ if((MSG_task_get_remaining_computation(T1)=0.0) && (you_re_in_a_good_mood))
+ MSG_task_execute(T2)
+ else {
+ /* do something else */
+ }
+ }
+ }
+\endverbatim
+
+If you decide that the distributed part is not that much important and that
+DAG is really the level of abstraction you want to work with (but it
+prevents you from having "realistic" platform modeling), then you should
+keep using the 2.18.5 versions until somebody has ported SG on top of SURF.
+Note however that SURF will be slower than the old SG to handle traces with
+a lots of variations (there is no trace integration anymore).
+
+\subsection faq_SG_future Will SG come back in the maintained branch one day?
+
+Sure. In fact, we already have thought about a new and cleaner API:
+\verbatim
+void* SG_link_get_data(SG_link_t link);
+void SG_link_set_data(SG_link_t link, void *data);
+const char* SG_link_get_name(SG_link_t link);
+double SG_link_get_capacity(SG_link_t link);
+double SG_link_get_current_bandwidth(SG_link_t link);
+double SG_link_get_current_latency(SG_link_t link);
+
+SG_workstation_t SG_workstation_get_by_name(const char *name);
+SG_workstation_t* SG_workstation_get_list(void);
+int SG_workstation_get_number(void);
+void SG_workstation_set_data(SG_workstation_t workstation, void *data);
+void * SG_workstation_get_data(SG_workstation_t workstation);
+const char* SG_workstation_get_name(SG_workstation_t workstation);
+SG_link_t* SG_workstation_route_get_list(SG_workstation_t src, SG_workstation_t dst);
+int SG_workstation_route_get_size(SG_workstation_t src, SG_workstation_t dst);
+double SG_workstation_get_power(SG_workstation_t workstation);
+double SG_workstation_get_available_power(SG_workstation_t workstation);
+
+SG_task_t SG_task_create(const char *name, void *data, double amount);
+int SG_task_schedule(SG_task_t task, int workstation_nb,
+ SG_workstation_t **workstation_list, double *computation_amount,
+ double *communication_amount, double rate);
+
+void* SG_task_get_data(SG_task_t task);
+void SG_task_set_data(SG_task_t task, void *data);
+const char* SG_task_get_name(SG_task_t task);
+double SG_task_get_amount(SG_task_t task);
+double SG_task_get_remaining_amount(SG_task_t task);
+void SG_task_dependency_add(const char *name, void *data, SG_task_t src, SG_task_t dst);
+void SG_task_dependency_remove(SG_task_t src, SG_task_t dst);
+e_SG_task_state_t SG_task_state_get(SG_task_t task); /* e_SG_task_state_t can be either SG_SCHEDULED, SG_RUNNING, SG_DONE, or SG_FAILED */
+void SG_task_watch(SG_task_t task, e_SG_task_state_t state); /* SG_simulate will stop as soon as the state of this task is the one given in argument.
+ Watch-point is then automatically removed */
+void SG_task_unwatch(SG_task_t task, e_SG_task_state_t state);
+
+void SG_task_unschedule(SG_task_t task); /* change state and rerun.. */
+
+SG_task_t *SG_simulate(double how_long); /* returns a NULL-terminated array of SG_task_t whose state has changed */
+\endverbatim
+
+We're just looking for somebody to implement it... :)
+
+\section faq_dynamic Dynamic resources and platform building
\subsection faq_platform Building a realistic platform
-I can speak more than an hour on this subject and I still do not have
-the right answer, just some ideas. You can read the following <a
-href="http://graal.ens-lyon.fr/~alegrand/articles/Simgrid-Introduction.pdf">slides</a>.
+We can speak more than an hour on this subject and we still do not have
+the right answer, just some ideas. You can read the following
+<a href="http://graal.ens-lyon.fr/~alegrand/articles/Simgrid-Introduction.pdf">slides</a>.
It may give you some hints. You can also have a look at the
<tt>tools/platform_generation/</tt> directory. There is a perl-script
-I use to annotate a Tiers generated platform (may not be up-to-date
-though).
+we use to annotate a Tiers generated platform.
-\subsection faq_visualization Visualizing the schedule
+\subsection faq_SURF_dynamic How can I have variable resource availability?
-It is sometime convenient to "see" how the agents are behaving. If you
-like colors, you can use <tt>tools/colorize.pl</tt> as a filter to you
-MSG outputs. It is intended to work with the output generated by
-PRINT_MESSAGE() (a macro defined in
-<tt>example/msg/messages.h</tt>). Beware, PRINT_MESSAGE() prints on
-stderr. Do not forget to redirect if you want to filter (e.g. with
-bash):
-\verbatim ./masterslave3 platform.txt deployment.txt 2>&1 | ../../tools/colorize.pl \endverbatim
-
-That would be great to have something more graphical. As soon as I'll
-have a little bit more time, I will write a piece of code that
-generates an input to <a href="http://www-id.imag.fr/Logiciels/paje/">Paje</a>.
+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 CPUs like that:
-\subsection faq_context I have tons of process and it is limiting my simulation.
+\verbatim
+ <cpu name="Cpu A" power="100.00"/>
+\endverbatim
-MSG can use either pthreads or the GNU context library. On most
-systems, the number of pthreads is limited (especially with the
-current linux pthreads) and then your simulation may be limited for a
-stupid reason. If you enable the context option
-(<tt>--enable-context</tt> in the <tt>./configure</tt> phase), you
-will not use the pthread anymore and the context switching will be
-done manually, which enables us to have as much agents as your memory
-can hold and should be much faster... So think about it if your
-simulation is getting really big.
+If you want the availability of "CPU A" to change over time, the only
+thing you have to do is change this definition like that:
-Nevertheless, be aware that this code does not work on some system. It
-is not very clean. As usual, as soon as I will have a little bit more
-time, I will recode it in a cleaner way.
+\verbatim
+ <cpu name="Cpu A" power="100.00" availability_file="trace_A.txt" state_file="trace_A_failure.txt"/>
+\endverbatim
-\section faq_stupid Stupid Questions
+For CPUs, availability files are expressed in fraction of available
+power. Let's have a look at what "trace_A.txt" may look like:
-\subsection faq_GridSim Are SimGrid and GridSim the same ?
+\verbatim
+PERIODICITY 1.0
+0.0 1.0
+11.0 0.5
+20.0 0.9
+\endverbatim
-Are you kidding ? SimGrid is plain C and GridSim is written in
-Java... I'm sarcastic but I'm pissed of all these poeple arguing that
-their software is well-structured and higly portable thanks to Java. A
-C program can also be structured in an object-oriented way and be
-highly portable (just try to run Java on IRIX... ;).
+At time 0, our CPU will deliver 100 Mflop/s. At time 11.0, it will
+deliver only 50 Mflop/s until time 20.0 where it will will start
+delivering 90 Mflop/s. Last at time 21.0 (20.0 plus the periodicity
+1.0), we'll be back to the beginning and it will deliver 100Mflop/s.
-According to different published papers, both SimGrid and GridSim seem
-to have the same kind of goal but I have never succeeded in compiling
-GridSim (but I may not be very objective since I always have troubles
-when trying to run java programs) and its documentation has not
-enlightened me. If you have suceeded and can tell me more about it,
-please tell me.
+Now let's look at the state file:
+\verbatim
+PERIODICITY 10.0
+1.0 -1.0
+2.0 1.0
+\endverbatim
-\subsection faq_stupid_MSG What is MSG and why do you like it ?
+A negative value means "off" while a positive one means "on". At time
+1.0, the CPU 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.
-Monosodium glutamate (MSG) is used as a flavor enhancer in a variety
-of foods prepared at home, in restaurants, and by food processors. Its
-use has become controversial in the past 30 years because of reports of
-adverse reactions in people who've eaten foods that contain MSG. Research
-on the role of glutamate--a group of chemicals that includes MSG--in the
-nervous system also has raised questions about the chemical's safety.
+Now, let's look how the same kind of thing can be done for network
+links. A usual declaration looks like:
+
+\verbatim
+ <network_link name="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 CPUs is that
+bandwidth_file and latency_file do not express fraction of available
+power but are expressed directly in Mb/s and seconds.
+
+\subsection faq_flexml_bypassing How can I have some C functions do what the platform file does?
+
+So you want to bypass the XML files parser, uh? Maybe doin some parameter
+sweep experiments on your simulations or so? This is possible, but it's not
+really easy. 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"
+ - start "cpu" with attributes name="host1" power="1.0"
+ - end "cpu"
+ - start "cpu" with attributes name="host2" power="2.0"
+ - end "cpu"
+ - start "network_link" with ...
+ - end "network_link"
+ - start "route" with ...
+ - end "route"
+ - start "route" with ...
+ - 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 "cpu" with attributes name="host1" power="1.0"
+
+let the parser do the equivalent of:
+\verbatim
+ strcpy("host1",A_cpu_name);
+ A_cpu_power = 1.0;
+ (*STag_cpu_fun)();
+\endverbatim
-For more information, see http://www.truthinlabeling.org/ or
-http://www.msg.net/
+In SURF, we attach callbacks to the different events by initializing the
+pointer functions to some the right surf functions. Example in
+workstation_KCCFLN05.c (surf_parse_open() ends up calling surf_parse()):
+\verbatim
+ // Building the routes
+ surf_parse_reset_parser();
+ STag_route_fun=parse_route_set_endpoints;
+ ETag_route_element_fun=parse_route_elem;
+ ETag_route_fun=parse_route_set_route;
+ 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:
+ - Call the corresponding STag_<tag>_fun function to simulate tag start
+ - Fill the A_<tag>_<attribute> variables with the wanted values
+ - 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;
+ MSG_create_environment(NULL);
+\endverbatim
+
+An example of this trick is distributed in the file examples/msg/msg_test_surfxml_bypassed.c
+
+\section faq_troubleshooting Troubleshooting
+
+\subsection faq_compil_trouble ./configure fails!
+
+We now only one reason for the configure to fail:
+
+ - <b>You are using a borken 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.
+
+\subsection faq_distcheck_fails Dude! "make check" fails on my machine!
+
+Don't assume we never run this target, because we do. Really. Promise!
+
+There is several reasons which may cause the make check to fail on your
+machine:
+
+ - <b>You are using a borken compiler</b>.\n
+ The symptom may be that the "make check" fails within testsuite/gras
+ directory.\n
+ For example, the breezy release of Ubuntu comes with a prerelease of the
+ 4.0 gcc compiler. This version happens to be completely unusable, and you
+ should install a gcc-3.4 compiler and change the /usr/bin/gcc link to let
+ it point on /usr/bin/gcc-3.4.
+ - <b>You are using a borken 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 fools our detection mecanism
+ and leads to segfaults.\n
+ On some x86_64, the pointer to function is stored into a integer, but int
+ are 32bits only on this arch while pointers are 64bits. Our detection
+ mecanism also fails to detect the problem, which leads to segfaults.\n
+ In both cases, there is not much we can do to fix the bug. We are working
+ on a workaround for x86_64 machines, but in the meanwhile, you can
+ compile with --with-context=pthread to avoid ucontext completely. You'll
+ be a bit more limitated in the number of simulated processes you can start
+ concurently, 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.
+ - <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.
+
+\subsection faq_context_1000 I want thousands of simulated processes
+
+SimGrid can use either pthreads library or the UNIX98 contextes. On most
+systems, the number of pthreads is limited and then your simulation may be
+limited for a stupid reason. This is especially true with the current linux
+pthreads, and I cannot get more than 2000 simulated processes with pthreads
+on my box. The UNIX98 contexts allow me to raise the limit to 25,000
+simulated processes on my laptop.
+
+The <tt>--with-context</tt> option of the <tt>./configure</tt> script allows
+you to choose between UNIX98 contextes (<tt>--with-context=ucontext</tt>)
+and the pthread version ( (<tt>--with-context=pthread</tt>). The default
+value is ucontext when the script detect a working UNIX98 context
+implementation. On Windows boxes, the provided value is discarded and an
+adapted version is picked up.
+
+We experienced some issues with contextes on some rare systems (solaris 8
+and lower or old alpha linuxes comes to mind). The main problem is that the
+configure script detect the contextes as being functional when it's not
+true. If you happen to use such a system, switch manually to the pthread
+version, and provide us with a good patch for the configure script so that
+it is done automatically ;)
+
+\subsection faq_context_10000 I want hundred thousands of simulated processes
+
+As explained above, SimGrid can use UNIX98 contextes to represent and handle
+the simulated processes. Thanks to this, the main limitation to the number
+of simulated processes becomes the available memory.
+
+Here are some tricks I had to use in order to run a token ring between
+25,000 processes on my laptop (1Gb memory, 1.5Gb swap).
+
+ - First of all, make sure your code runs for a few hundreds processes
+ before trying to push the limit. Make sure it's valgrind-clean, ie that
+ valgrind does not report neither memory error nor memory leaks. Indeed,
+ numerous simulated processes result in *fat* simulation hindering debugging.
+
+ - It was really boring to write 25,000 entries in the deployment file, so I wrote
+ a little script <tt>examples/gras/tokenS/make_deployment.pl</tt>, which you may
+ want to adapt to your case.
+
+ - The deployment file became quite big, so I had to do what is in the FAQ
+ entry \ref faq_flexml_limit
+
+ - Each UNIX98 context has its own stack entry. As debugging this is quite
+ hairly, the default value is a bit overestimated so that user don't get
+ into trouble about this. You want to tune this size to increse the number
+ of processes. This is the <tt>STACK_SIZE</tt> define in
+ <tt>src/xbt/context_private.h</tt>, which is 128kb by default.
+ Reduce this as much as you can, but be warned that if this value is too
+ low, you'll get a segfault. The token ring example, which is quite simple,
+ runs with 40kb stacks.
+
+\subsection faq_longjmp longjmp madness
+
+This is when valgrind starts complaining about longjmp things, just like:
+
+\verbatim ==21434== Conditional jump or move depends on uninitialised value(s)
+==21434== at 0x420DBE5: longjmp (longjmp.c:33)
+==21434==
+==21434== Use of uninitialised value of size 4
+==21434== at 0x420DC3A: __longjmp (__longjmp.S:48)
+\endverbatim
+
+or even when it reports scary things like:
+
+\verbatim ==24023== Warning: client switching stacks? SP change: 0xBE3FF618 --> 0xBE7FF710
+x86->IR: unhandled instruction bytes: 0xF4 0xC7 0x83 0xD0
+==24023== to suppress, use: --max-stackframe=4194552 or greater
+==24023== Your program just tried to execute an instruction that Valgrind
+==24023== did not recognise. There are two possible reasons for this.
+==24023== 1. Your program has a bug and erroneously jumped to a non-code
+==24023== location. If you are running Memcheck and you just saw a
+==24023== warning about a bad jump, it's probably your program's fault.
+==24023== 2. The instruction is legitimate but Valgrind doesn't handle it,
+==24023== i.e. it's Valgrind's fault. If you think this is the case or
+==24023== you are not sure, please let us know.
+==24023== Either way, Valgrind will now raise a SIGILL signal which will
+==24023== probably kill your program.
+==24023==
+==24023== Process terminating with default action of signal 4 (SIGILL)
+==24023== Illegal opcode at address 0x420D234
+==24023== at 0x420D234: abort (abort.c:124)
+\endverbatim
-It also stands for Meta-SimgGrid. It is a simulator written on top of
-Simgrid that can be used to easily simulate many process running on a
-computing platform.
+This is the sign that you didn't used the exception mecanism well. Most
+probably, you have a <tt>return;</tt> somewhere within a <tt>TRY{}</tt>
+block. This is <b>evil</b>, and you must not do this. Did you read the section
+about \ref XBT_ex??
+
+\subsection faq_flexml_limit I get the message "surf_parse_lex: Assertion `next<limit' failed."
+
+This is because your platform file is too big for the parser.
+
+Actually, the message comes directly from FleXML, the technology on top of
+which the parser is built. FleXML has the bad idea of fetching the whole
+document in memory before parsing it. And moreover, the memory buffer size
+must be determinded at compilation time.
+
+We use a value which seems big enough for our need without bloating the
+simulators footprints. But of course your mileage may vary. In this case,
+just edit src/surf/surfxml.l modify the definition of
+FLEXML_BUFFERSTACKSIZE. E.g.
+
+\verbatim
+#define FLEXML_BUFFERSTACKSIZE 1000000000
+\endverbatim
+
+Then recompile and everything should be fine, provided that your version of
+Flex is recent enough (>= 2.5.31). If not the compilation process should
+warn you.
+
+A while ago, we worked on FleXML to reduce a bit its memory consumtion, but
+these issues remain. There is two things we should do:
+
+ - use a dynamic buffer instead of a static one so that the only limit
+ becomes your memory, not a stupid constant fixed at compilation time
+ (maybe not so difficult).
+ - change the parser so that it does not need to get the whole file in
+ memory before parsing
+ (seems quite difficult, but I'm a complete newbe wrt flex stuff).
+
+These are changes to FleXML itself, not SimGrid. But since we kinda hijacked
+the development of FleXML, I can grant you that any patches would be really
+welcome and quickly integrated.
+
+\subsection faq_deadlock There is a deadlock !!!
+
+Unfortunately, we cannot debug every code written in SimGrid. We
+furthermore believe that the framework provides ways enough
+information to debug such informations yourself. If the textual output
+is not enough, Make sure to check the \ref faq_visualization FAQ entry to see
+how to get a graphical one.
+
+Now, if you come up with a really simple example that deadlocks and
+you're absolutely convinced that it should not, you can ask on the
+list. Just be aware that you'll be severely punished if the mistake is
+on your side... We have plenty of FAQ entries to redact and new
+features to implement for the impenitents! ;)
+
+\author Arnaud Legrand (arnaud.legrand::imag.fr)
+\author Martin Quinson (martin.quinson::loria.fr)
-I also like it because it gives flavor and it's addictive. ;)
*/
+
