/*! \page options Configure SimGrid
+\htmlonly
+<div align="center">
+\endhtmlonly
+\htmlinclude graphical-toc.svg
+\htmlonly
+</div>
+<script>
+document.getElementById("Config").style="opacity:0.93999999;fill:#ff0000;fill-opacity:0.1;stroke:#000000;stroke-width:0.35277778;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1";
+</script>
+\endhtmlonly
+
A number of options can be given at runtime to change the default
SimGrid behavior. For a complete list of all configuration options
accepted by the SimGrid version used in your simulator, simply pass
- \c path: \ref options_generic_path
- \c plugin: \ref options_generic_plugin
+- \c simix/breakpoint: \ref options_generic_breakpoint
+
- \c storage/max_file_descriptors: \ref option_model_storage_maxfd
- \c surf/precision: \ref options_model_precision
- \c smpi/os: \ref options_model_smpi_os
- \c smpi/papi-events: \ref options_smpi_papi_events
- \c smpi/privatization: \ref options_smpi_privatization
+- \c smpi/privatize-libs: \ref options_smpi_privatize_libs
- \c smpi/send-is-detached-thresh: \ref options_model_smpi_detached
- \c smpi/shared-malloc: \ref options_model_smpi_shared_malloc
- \c smpi/shared-malloc-hugepage: \ref options_model_smpi_shared_malloc
<a href="http://mescal.imag.fr/membres/arnaud.legrand/articles/simutools09.pdf">Accuracy Study and Improvement of Network Simulation in the SimGrid Framework</a>.
- \b LV08 (default one): Realistic network analytic model
- (slow-start modeled by multiplying latency by 10.4, bandwidth by
- .92; bottleneck sharing uses a payload of S=8775 for evaluating RTT)
+ (slow-start modeled by multiplying latency by 13.01, bandwidth by
+ .97; bottleneck sharing uses a payload of S=20537 for evaluating RTT)
- \anchor options_model_select_network_constant \b Constant: Simplistic network model where all communication
take a constant time (one second). This model provides the lowest
realism, but is (marginally) faster.
\subsection options_generic_plugin Plugins
-SimGrid supports the use of plugins; currently, no known plugins
-can be activated but there are use-cases where you may want to write
-your own plugin (for instance, for logging).
-
-Plugins can for instance define own classes that inherit from
-existing classes (for instance, a class "CpuEnergy" inherits from
-"Cpu" to assess energy consumption).
+SimGrid plugins allow to extend the framework without changing its
+source code directly. Read the source code of the existing plugins to
+learn how to do so (in ``src/plugins``), and ask your questions to the
+usual channels (Stack Overflow, Mailing list, IRC). The basic idea is
+that plugins usually register callbacks to some signals of interest.
+If they need to store some information about a given object (Link, CPU
+or Actor), they do so through the use of a dedicated object extension.
-The plugin connects to the code by registering callbacks using
-``signal.connect(callback)`` (see file ``src/surf/plugins/energy.cpp`` for
-details).
+Some of the existing plugins can be activated from the command line,
+meaning that you can activate them from the command line without any
+modification to your simulation code. For example, you can activate
+the host energy plugin by adding the following to your command line:
\verbatim
- --cfg=plugin:Energy
+ --cfg=plugin:host_energy
\endverbatim
-\note
- This option is case-sensitive: Energy and energy are not the same!
+Here is the full list of plugins that can be activated this way:
+
+ - \b host_energy: keeps track of the energy dissipated by
+ computations. More details in @ref plugin_energy.
+ - \b link_energy: keeps track of the energy dissipated by
+ communications. More details in @ref SURF_plugin_energy.
+ - \b host_load: keeps track of the computational load.
+ More details in @ref plugin_load.
\subsection options_model_optim Optimization level of the platform models
- \b ucontext: fast factory using System V contexts (Linux and FreeBSD only)
- \b boost: This uses the [context implementation](http://www.boost.org/doc/libs/1_59_0/libs/context/doc/html/index.html)
of the boost library for a performance that is comparable to our
- raw implementation.\nInstall the relevant library (e.g. with the
+ raw implementation.\n Install the relevant library (e.g. with the
libboost-contexts-dev package on Debian/Ubuntu) and recompile
SimGrid. Note that our implementation is not compatible with recent
implementations of the library, and it will be hard to fix this since
\subsection options_smpi_privatization smpi/privatization: Automatic privatization of global variables
-MPI executables are usually meant to be executed in separated processes, but SMPI is
-executed in only one process. Global variables from executables will be placed
-in the same memory zone and shared between processes, causing intricate bugs.
-Several options are possible to avoid this, as described in the main
-<a href="https://hal.inria.fr/hal-01415484">SMPI publication</a>.
-SimGrid provides two ways of automatically privatizing the globals,
-and this option allows to choose between them.
-
- - <b>no</b> (default): Do not automatically privatize variables.
- - <b>mmap</b> or <b>yes</b>: Runtime automatic switching of the data segments.\n
- SMPI stores a copy of each global data segment for each process,
- and at each context switch replaces the actual data with its copy
- from the right process. No copy actually occures as this mechanism
- uses mmap for efficiency. As such, it is for now limited to
- systems supporting this functionnality (all Linux and most BSD).\n
- Another limitation is that SMPI only accounts for global variables
- defined in the executable. If the processes use external global
- variables from dynamic libraries, they won't be switched
- correctly. The easiest way to solve this is to statically link
- against the library with these globals (but you should never
- statically link against the simgrid library itself).
- - <b>dlopen</b>: Link multiple times against the binary.\n
- SMPI loads several copy of the same binary in memory, resulting in
- the natural duplication global variables. Since the dynamic linker
- refuses to link the same file several times, the binary is copied
- in a temporary file before being dl-loaded (it is erased right
- after loading).\n
- Note that this feature is somewhat experimental at time of writing
- (v3.16) but seems to work.\n
- This approach greatly speeds up the context switching, down to
- about 40 CPU cycles with our raw contextes, instead of requesting
- several syscalls with the \c mmap approach. Another advantage is
- that it permits to run the SMPI contexts in parallel, which is
- obviously not possible with the \c mmap approach.\n
- Further work may be possible to alleviate the memory and disk
- overconsumption. It seems that we could
- <a href="https://lwn.net/Articles/415889/">punch holes</a>
- in the files before dl-loading them to remove the code and
- constants, and mmap these area onto a unique copy. This require
- to understand the ELF layout of the file, but would
- reduce the disk- and memory- usage to the bare minimum. In
- addition, this would reduce the pressure on the CPU caches (in
- particular on instruction one).
+MPI executables are usually meant to be executed in separated
+processes, but SMPI is executed in only one process. Global variables
+from executables will be placed in the same memory zone and shared
+between processes, causing intricate bugs. Several options are
+possible to avoid this, as described in the main
+<a href="https://hal.inria.fr/hal-01415484">SMPI publication</a> and in
+the @ref SMPI_what_globals "SMPI documentation". SimGrid provides two
+ways of automatically privatizing the globals, and this option allows
+to choose between them.
+
+ - <b>no</b> (default when not using smpirun): Do not automatically privatize variables.
+ Pass \c -no-privatize to smpirun to disable this feature.
+ - <b>dlopen</b> or <b>yes</b> (default when using smpirun): Link multiple times against the binary.
+ - <b>mmap</b> (slower, but maybe somewhat more stable):
+ Runtime automatic switching of the data segments.
\warning
This configuration option cannot be set in your platform file. You can only
pass it as an argument to smpirun.
+
+\subsection options_smpi_privatize_libs smpi/privatize-libs: Automatic privatization of
+ global variables inside external libraries
+
+Linux/BSD only: When using dlopen (default) privatization, privatize specific
+shared libraries with internal global variables, if they can't be linked statically.
+For example libgfortran is usually used for Fortran I/O and indexes in files
+can be mixed up.
+
+\warning
+ This configuration option can only use either full paths to libraries, or full names.
+ Check with ldd the name of the library you want to use.
+ Example:
+ ldd allpairf90
+ libgfortran.so.3 => /usr/lib/x86_64-linux-gnu/libgfortran.so.3 (0x00007fbb4d91b000)
+ Then you can use --cfg=smpi/privatize-libs:"libgfortran.so.3" or --cfg=smpi/privatize-libs:"/usr/lib/x86_64-linux-gnu/libgfortran.so.3", but not "libgfortran" or "libgfortran.so".
+ Multiple libraries can be given, semicolon separated.
+
\subsection options_model_smpi_detached Simulating MPI detached send
--cfg=path:toto --cfg=path:tutu
\endverbatim
+\subsection options_generic_breakpoint Set a breakpoint
+
+\verbatim
+--cfg=simix/breakpoint:3.1416
+\endverbatim
+
+This configuration option sets a breakpoint: when the simulated clock reaches
+the given time, a SIGTRAP is raised. This can be used to stop the execution and
+get a backtrace with a debugger.
+
+It is also possible to set the breakpoint from inside the debugger, by writing
+in global variable simgrid::simix::breakpoint. For example, with gdb:
+
+\verbatim
+set variable simgrid::simix::breakpoint = 3.1416
+\endverbatim
+
\subsection options_generic_exit Behavior on Ctrl-C
By default, when Ctrl-C is pressed, the status of all existing
