And improve a bit the corresponding bits in the new doc.
If you are stuck at any point and if this FAQ cannot help you, please drop us a
mail to the user mailing list: <simgrid-user@lists.gforge.inria.fr>.
-@subsection faq_interfaces What is the difference between MSG and SimDag? Do they serve the same purpose?
-
-It depend on how you define "purpose", I guess ;)
-
-They all allow you to build a prototype of application which you can run
-within the simulator afterward. They all share the same simulation kernel,
-which is the core of the SimGrid project. They differ by the way you express
-your application.
-
-With SimDag, you express your code as a collection of interdependent
-parallel tasks. So, in this model, applications can be seen as a DAG of
-tasks. This is the interface of choice for people wanting to port old
-code designed for SimGrid v1 or v2 to the framework current version.
-
-With MSG, your application is seen as a set of communicating
-processes, exchanging data by the way of messages and performing
-computation on their own.
-
@subsection faq_visualization Visualizing and analyzing the results
It is sometime convenient to "see" how the agents are behaving. If you
We also have a more graphical output. Have a look at section @ref options_tracing.
-@subsection faq_C Argh! Do I really have to code in C?
-
-We provide Java bindings of the MSG interface, which is the main
-SimGrid user API.
-
-Moreover 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).
-
-For now, we do not feel a real demand for any other language. But if
-you think there is one, please speak up!
-
@section faq_howto Feature related questions
@subsection faq_MIA "Could you please add (your favorite feature here) to SimGrid?"
and put his code in the contrib directory of our SVN so that other can
keep working on it. You may find inspiring ideas in it.
-@subsubsection 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 exist 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.
-
@subsection faq_platform Platform building and Dynamic resources
@subsubsection faq_platform_example Where can I find SimGrid platform files?
@section faq_troubleshooting Troubleshooting
-@subsection faq_trouble_changelog The feature X stopped to work after my last update
-
-I guess that you want to read the ChangeLog file, that always contains
-all the information that could be important to the users during the
-upgrade. Actually, you may want to read it (alongside with the NEWS
-file that highlights the most important changes) even before you
-upgrade your copy of SimGrid, too.
-
-We do our best to maintain the backward compatibility, but we
-sometimes have to fix the things that are too broken. If we happen to
-kill a feature that you were using, we are sorry. We think that you
-should update to the new way of doing things, but if you can't afford
-it, that's ok. Just stick to the last version that were working for
-you, and have a pleasant day.
-
@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)"
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), 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_trouble_errors_big_fat_warning I'm told that my XML files are too old.
Both options are needed in order to run the SMPI process under GDB.
-@subsection faq_trouble_valgrind Valgrind-related and other debugger issues
-
-If you don't, you really should use valgrind to debug your code, it's
-almost magic.
-
-@subsubsection faq_trouble_backtraces Truncated backtraces
-
-When debugging SimGrid, it's easier to pass the
---disable-compiler-optimization flag to the configure if valgrind or
-gdb get fooled by the optimization done by the compiler. But you
-should remove these flag when everything works before going in
-production (before launching your 1252135 experiments), or everything
-will run only one half of the true SimGrid potential.
-
@subsection faq_deadlock There is a deadlock in my code!!!
Unfortunately, we cannot debug every code written in SimGrid. We
If you do, the best solution is to drop an email either on the simgrid-user
or the simgrid-devel mailing list and explain us about the issue. You can
also decide to open a formal bug report using the
-<a href="https://gforge.inria.fr/tracker/?atid=165&group_id=12&func=browse">relevant
+<a href="https://framagit.org/simgrid/simgrid/issues">relevant
interface</a>. You need to login on the server to get the ability to submit
bugs.
-We will do our best to solve any problem repported, but you need to help us
+We will do our best to solve any problem reported, but you need to help us
finding the issue. Just telling "it segfault" isn't enough. Telling "It
segfaults when running the attached simulator" doesn't really help either.
-You may find the following article interesting to see how to repport
+You may find the following article interesting to see how to report
informative bug repports:
http://www.chiark.greenend.org.uk/~sgtatham/bugs.html (it is not SimGrid
specific at all, but it's full of good advices).
If you want to represent an entity like a switch, you must use ``<link>`` (see section). Routers are used
to run some routing algorithm and determine routes (see Section @ref pf_routing for details).
-@subsubsection pf_tag_link <link>
-
-Network links can represent one-hop network connections. They are
-characterized by their id and their bandwidth; links can (but may not) be subject
-to latency.
-
-#### Attributes ####
-
-Attribute name | Mandatory | Values | Description
---------------- | --------- | ------ | -----------
-id | yes | string | The identifier of the link to be used when referring to it.
-bandwidth | yes | string | Maximum bandwidth for this link, along with its unit.
-latency | no | double (default: 0.0) | Latency for this link.
-sharing_policy | no | @ref sharing_policy_shared "SHARED"@|@ref pf_sharing_policy_fatpipe "FATPIPE"@|@ref pf_sharing_policy_splitduplex "SPLITDUPLEX" (default: SHARED) | Sharing policy for the link.
-bandwidth_file | no | string | Allows you to use a file as input for bandwidth.
-latency_file | no | string | Allows you to use a file as input for latency.
-state_file | no | string | Allows you to use a file as input for states.
-
-
-#### Possible shortcuts for ``latency`` ####
-
-When using the latency attribute, you can specify the latency by using the scientific
-notation or by using common abbreviations. For instance, the following three tags
-are equivalent:
-
-@verbatim
- <link id="LINK1" bandwidth="125000000" latency="5E-6"/>
- <link id="LINK1" bandwidth="125000000" latency="5us"/>
- <link id="LINK1" bandwidth="125000000" latency="0.000005"/>
-@endverbatim
-
-Here, the second tag uses "us", meaning "microseconds". Other shortcuts are:
-
-Name | Abbreviation | Time (in seconds)
----- | ------------ | -----------------
-Week | w | 7 * 24 * 60 * 60
-Day | d | 24 * 60 * 60
-Hour | h | 60 * 60
-Minute | m | 60
-Second | s | 1
-Millisecond | ms | 0.001 = 10^(-3)
-Microsecond | us | 0.000001 = 10^(-6)
-Nanosecond | ns | 0.000000001 = 10^(-9)
-Picosecond | ps | 0.000000000001 = 10^(-12)
-
-#### Sharing policy ####
-
-@anchor sharing_policy_shared
-By default a network link is @b SHARED, i.e., if two or more data flows go
-through a link, the bandwidth is shared fairly among all data flows. This
-is similar to the sharing policy TCP uses.
-
-@anchor pf_sharing_policy_fatpipe
-On the other hand, if a link is defined as a @b FATPIPE,
-each flow going through this link will be provided with the complete bandwidth,
-i.e., no sharing occurs and the bandwidth is only limiting each flow individually.
-Please note that this is really on a per-flow basis, not only on a per-host basis!
-The complete bandwidth provided by this link in this mode
-is ``number_of_flows*bandwidth``, with at most ``bandwidth`` being available per flow.
-
-Using the FATPIPE mode allows to model backbones that won't affect performance
-(except latency).
-
-@anchor pf_sharing_policy_splitduplex
-The last mode available is @b SPLITDUPLEX. This means that SimGrid will
-automatically generate two links (one carrying the suffix _UP and the other the
-suffix _DOWN) for each ``<link>`` tag. This models situations when the direction
-of traffic is important.
-
-@remark
- Transfers from one side to the other will interact similarly as
- TCP when ACK returning packets circulate on the other direction. More
- discussion about it is available in the description of link_ctn description.
-
-In other words: The SHARED policy defines a physical limit for the bandwidth.
-The FATPIPE mode defines a limit for each application,
-with no upper total limit.
-
-@remark
- Tip: By using the FATPIPE mode, you can model big backbones that
- won't affect performance (except latency).
-
-#### Example ####
-
-@verbatim
- <link id="SWITCH" bandwidth="125000000" latency="5E-5" sharing_policy="FATPIPE" />
-@endverbatim
-
-#### Expressing dynamism and failures ####
-
-Similar to hosts, it is possible to declare links whose state, bandwidth
-or latency changes over time (see Section @ref pf_host_dynamism for details).
-
-In the case of network links, the ``bandwidth`` and ``latency`` attributes are
-replaced by the ``bandwidth_file`` and ``latency_file`` attributes.
-The following XML snippet demonstrates how to use this feature in the platform
-file. The structure of the files "link1.bw" and "link1.lat" is shown below.
-
-@verbatim
-<link id="LINK1" state_file="link1.fail" bandwidth="80000000" latency=".0001" bandwidth_file="link1.bw" latency_file="link1.lat" />
-@endverbatim
-
-@note
- Even if the syntax is the same, the semantic of bandwidth and latency
- trace files differs from that of host availability files. For bandwidth and
- latency, the corresponding files do not
- express availability as a fraction of the available capacity but directly in
- bytes per seconds for the bandwidth and in seconds for the latency. This is
- because most tools allowing to capture traces on real platforms (such as NWS)
- express their results this way.
-
-##### Example of "link1.bw" file #####
-
-~~~{.py}
-PERIODICITY 12.0
-4.0 40000000
-8.0 60000000
-~~~
-
-In this example, the bandwidth changes repeatedly, with all changes
-being repeated every 12 seconds.
-
-At the beginning of the the simulation, the link's bandwidth is 80,000,000
-B/s (i.e., 80 Mb/s); this value was defined in the XML snippet above.
-After four seconds, it drops to 40 Mb/s (line 2), and climbs
-back to 60 Mb/s after another 4 seconds (line 3). The value does not change any
-more until the end of the period, that is, after 12 seconds have been simulated).
-At this point, periodicity kicks in and this behavior is repeated: Seconds
-12-16 will experience 80 Mb/s, 16-20 40 Mb/s etc.).
-
-##### Example of "link1.lat" file #####
-
-~~~{.py}
-PERIODICITY 5.0
-1.0 0.001
-2.0 0.01
-3.0 0.001
-~~~
-
-In this example, the latency varies with a period of 5 seconds.
-In the xml snippet above, the latency is initialized to be 0.0001s (100µs). This
-value will be kept during the first second, since the latency_file contains
-changes to this value at second one, two and three.
-At second one, the value will be 0.001, i.e., 1ms. One second later it will
-be adjusted to 0.01 (or 10ms) and one second later it will be set again to 1ms. The
-value will not change until second 5, when the periodicity defined in line 1
-kicks in. It then loops back, starting at 100µs (the initial value) for one second.
-
-#### The ``<prop/>`` tag ####
-
-Similar to the ``<host>`` tag, a link may also contain the ``<prop/>`` tag; see the host
-documentation (Section @ref pf_tag_host) for an example.
-
-
@subsubsection pf_backbone <backbone/>
@note
pass through link1, and get into zone2 by being received by router2.
router1 must belong to zone1 and router2 must belong to zone2.
-@subsubsection pf_tag_linkctn <link_ctn>
-
-This entity has only one purpose: Refer to an already existing
-@ref pf_tag_link "<link/>" when defining a route, i.e., it
-can only occur as a child of @ref pf_tag_route "<route/>"
-
-| Attribute name | Mandatory | Values | Description |
-| --------------- | --------- | ------ | ----------- |
-| id | yes | String | The identifier of the link that should be added to the route. |
-| direction | maybe | UP@|DOWN | If the link referenced by @c id has been declared as @ref pf_sharing_policy_splitduplex "SPLITDUPLEX", this indicates which direction the route traverses through this link: UP or DOWN. If you don't use SPLITDUPLEX, do not use this attribute or SimGrid will not find the right link.
-
-#### Example Files ####
-
-This is an automatically generated list of example files that use the @c <link_ctn/>
-entity (the path is given relative to SimGrid's source directory):
-
-@verbinclude example_filelist_xmltag_linkctn
-
@subsubsection pf_tag_zoneroute <zoneRoute>
The purpose of this entity is to define a route between two
- @ref pf_tag_config passes configuration options, e.g. to change the network model;
- @ref pf_tag_prop gives user-defined properties to various elements
-@subsection pf_tag_config <config>
-
-Adding configuration flags into the platform file is particularly
-useful when the described platform is best used with specific
-flags. For example, you could finely tune SMPI in your platform file directly.
-
-| Attribute | Values | Description |
-| ---------- | ------------------- | ---------------------------------------------- |
-| id | String (optional) | This optional identifier is ignored by SimGrid |
-
-* **Included tags:** @ref pf_tag_prop to specify a given configuration item (see @ref options).
-
-Any such configuration must be given at the very top of the platform file.
-
-* **Example**
-
-@verbatim
-<?xml version='1.0'?>
-<!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
-<platform version="4">
-<config>
- <prop id="maxmin/precision" value="0.000010" />
- <prop id="cpu/optim" value="TI" />
- <prop id="network/model" value="SMPI" />
- <prop id="smpi/bw-factor" value="65472:0.940694;15424:0.697866;9376:0.58729" />
-</config>
-
-<zone id="zone0" routing="Full">
-...
-@endverbatim
-
-@subsection pf_tag_prop <prop>
-
-Defines a user-defined property, identified with a name and having a
-value. You can specify such properties to most kind of resources:
-@ref pf_tag_zone, @ref pf_tag_host, @ref pf_tag_storage,
-@ref pf_tag_cluster and @ref pf_tag_link. These values can be retrieved
-at runtime with MSG_zone_property() or simgrid::s4u::NetZone::property(),
-or similar functions.
-
-| Attribute | Values | Description |
-| --------- | ---------------------- | ----------------------------------------------------------------------------------------- |
-| id | String (mandatory) | Identifier of this property. Must be unique for a given property holder, eg host or link. |
-| value | String (mandatory) | Value of this property; The semantic is completely up to you. |
-
-* **Included tags:** none.
-
-#### Example ####
-
-@code{.xml}
-<prop id="Operating System" value="Linux" />
-@endcode
-
-
@subsection pf_trace trace and trace_connect
Both tags are an alternate way to pass files containing information on
<config>
--------
-Adding configuration flags directly into the platform file becomes particularly useful when the realism of the described
-platform depends on some specific flags. For example, this could help you to finely tune SMPI. Almost all
-:ref:`command-line configuration items <options_list>` can be configured this way.
+Adding configuration flags directly into the platform file becomes particularly
+useful when the realism of the described platform depends on some specific
+flags. For example, this could help you to finely tune SMPI. Almost all
+:ref:`command-line configuration items <options_list>` can be configured this
+way.
-Each configuration flag is described as a :ref:`pf_tag_prop` whose 'id' is the name of the flag and 'value' is what it
-has to be set to.
+Each configuration flag is described as a :ref:`pf_tag_prop` whose ``id`` is the
+name of the flag and ``value`` is what it has to be set to.
**Parent tags:** :ref:`pf_tag_platform` (must appear before any other tags) |br|
**Children tags:** :ref:`pf_tag_prop` |br|
- At time t = 10, the profile is reset (as we are 5 seconds after the last event). Then the available speed will drop
again to 50% at time t = 11.
- If your profile does not contain any LOOPAFTER line, then it will be executed only once and not in a repetitive way.
+ If your profile does not contain any LOOPAFTER line, then it will
+ be executed only once and not repeated.
.. warning:: Don't get fooled: Bandwidth and Latency profiles of a :ref:`pf_tag_link` contain absolute values, while
Availability profiles of a :ref:`pf_tag_host` contain ratios.
- At time t = 10, the profile is reset (as we are 8 seconds after the last event). Then the host will be turned off
again at time t = 11.
- If your profile does not contain any LOOPAFTER line, then it will be executed only once and not in a repetitive way.
+ If your profile does not contain any LOOPAFTER line, then it will
+ be executed only once and not repeated.
:``coordinates``: Vivaldi coordinates (meaningful for Vivaldi zones only).
See :ref:`pf_tag_peer`.
==== =========== ======================
:``sharing_policy``: Sharing policy for the link. Possible values are ``SHARED``, ``FATPIPE`` or ``SPLITDUPLEX``
- (default: ``SHARED``).
+ (default: ``SPLITDUPLEX``).
- If set to ``SHARED``, the available bandwidth is fairly shared among all the flows traversing this link. This tend to
- model the bandwidth sharing behavior of the UDP or TCP protocols.
+ If set to ``SPLITDUPLEX``, the link models the full-duplex
+ behavior, as meant in TCP or UDP. To that extend, the link is
+ actually split in two links whose names are suffixed with "_UP" and
+ "_DOWN". You should then specify the direction to use when
+ referring to that link in a :ref:`pf_tag_link_ctn`.
- If set to ``FATPIPE``, flows have no impact on each other, hence each flow can exploit the full bandwidth of this
- link. This aims at modeling the behavior of the Internet backbones that cannot get saturated by your application.
- What you experience of such networks usually is their latency only.
+ If set to ``FATPIPE``, flows have no impact on each other, hence
+ each flow can exploit the full bandwidth. This models Internet
+ backbones that cannot get saturated by your application. From your
+ application point of view, there is no congestion on these
+ backbones.
- If set to ``SPLITDUPLEX``, the link models cross-traffic
- effects. Under the ``SHARED`` policy, two flows of reverse
- direction share the same resource, and can only get half of the
- bandwidth each. But TCP connections are full duplex, meaning that
- both directions can get the full bandwidth. To model this, any
- link under the ``SPLITDUPLEX`` policy is split in two links (whose
- names are suffixed with "_UP" and "_DOWN"). Then you must specify
- which direction gets actually used when referring to that link in a
- :ref:`pf_tag_link_ctn`.
+ If set to ``SHARED``, the available bandwidth is fairly shared
+ among ALL flows traversing this link. The resulting link is not
+ full-duplex (as UDP or TCP would be): communications in both
+ directions share the same link. Prefer ``SPLITDUPLEX`` for TCP flows.
:``bandwidth_file``: File containing the bandwidth profile.
Almost every lines of such files describe timed events as ``date
- At time t = 8, it raises to 60MBps.
- At time t = 24, it drops at 40 MBps again.
+ If your profile does not contain any LOOPAFTER line, then it will
+ be executed only once and not repeated.
+
.. warning:: Don't get fooled: Bandwidth and Latency profiles of a :ref:`pf_tag_link` contain absolute values, while
Availability profiles of a :ref:`pf_tag_host` contain ratios.
- At time t = 8 (5 seconds after the last event), the profile loops.
- At time t = 9 (1 second after the loop reset), the latency is back at 1ms.
- If your profile does not contain any LOOPAFTER line, then it will be executed only once and not in a repetitive way.
+ If your profile does not contain any LOOPAFTER line, then it will
+ be executed only once and not repeated.
.. warning:: Don't get fooled: Bandwidth and Latency profiles of a :ref:`pf_tag_link` contain absolute values, while
Availability profiles of a :ref:`pf_tag_host` contain ratios.
**Attributes:**
:``id``: Link that is to be included in this route.
-:``direction``: Whether to use the uplink (with ``UP``) or downlink
- (with ``DOWN``) of the link. This is only valid if the
- link has ``sharing=SPLITDUPLEX``.
+:``direction``: either ``UP`` (by default) or ``DOWN``, specifying whether to
+ use the uplink or downlink component of the link (that must
+ follow the ``SPLITDUPLEX`` sharing policy). |br|
+ Please refer to the ``sharing_policy`` attribute in
+ :ref:`pf_tag_link`.
-------------------------------------------------------------------------------
