Define __cplusplus for doxygen.

[simgrid.git] / doc / doxygen / options.doc

diff --git a/doc/doxygen/options.doc b/doc/doxygen/options.doc
index 876a36d..9d08d71 100644 (file)
--- a/doc/doxygen/options.doc
+++ b/doc/doxygen/options.doc
@@ -1,5 +1,16 @@
 /*! \page options Configure SimGrid
 
 /*! \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
 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


@@ -119,6 +130,8 @@ int main(int argc, char *argv[]) {
 - \c path: \ref options_generic_path
 - \c plugin: \ref options_generic_plugin
 
 - \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 storage/max_file_descriptors: \ref option_model_storage_maxfd
 
 - \c surf/precision: \ref options_model_precision


@@ -143,6 +156,7 @@ int main(int argc, char *argv[]) {
 - \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/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
 - \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


@@ -189,8 +203,8 @@ described in
 <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
 <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.
   - \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.


@@ -241,24 +255,31 @@ when using SimDag.
 
 \subsection options_generic_plugin Plugins
 
 
 \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
 
 \verbatim

-    --cfg=plugin:Energy
+    --cfg=plugin:host_energy

 \endverbatim
 
 \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
 
 
 \subsection options_model_optim Optimization level of the platform models
 


@@ -654,7 +675,7 @@ the slowest to the most efficient:
  - \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
  - \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
    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


@@ -1017,6 +1038,24 @@ to choose between them.
 \warning
   This configuration option cannot be set in your platform file. You can only
   pass it as an argument to smpirun.
 \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
 
 
 \subsection options_model_smpi_detached Simulating MPI detached send
 


@@ -1253,6 +1292,23 @@ item several times, as in \verbatim
 --cfg=path:toto --cfg=path:tutu
 \endverbatim
 
 --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
 \subsection options_generic_exit Behavior on Ctrl-C
 
 By default, when Ctrl-C is pressed, the status of all existing