improve the doc of the SMPI module

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

diff --git a/doc/doxygen/options.doc b/doc/doxygen/options.doc
index 76f67d8..43b618b 100644 (file)
--- a/doc/doxygen/options.doc
+++ b/doc/doxygen/options.doc
@@ -998,53 +998,26 @@ of counters, the "default" set.
 
 \subsection options_smpi_privatization smpi/privatization: Automatic privatization of global variables
 
 
 \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.
+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>mmap</b> or <b>yes</b> (default when using smpirun):
+    Runtime automatic switching of the data segments.
+  - <b>dlopen</b> (faster but less tested): Link multiple times against the binary.

 
 \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.
 

-  - <b>no</b> (default when not using smpirun): Do not automatically privatize variables.
-  - <b>mmap</b> or <b>yes</b> (default when using smpirun): 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> (faster but less tested): Link multiple times against the binary.\n  
-    Asks SMPI to load several copies of the same binary in memory, so
-    that the global variables get naturally duplicated. Since the
-    dynamic linker refuses to link the same file several times, the
-    binary is copied in a temporary file before being dl-loaded.\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. If done
-    correctly, this would reduce the disk- and memory- usage to the
-    bare minimum, and would also reduce the pressure on the CPU
-    instruction cache.\n
-    For now, this still requires any external dependencies to be
-    statically linked into your application. We could extend this
-    mechanism to change this, but we never felt the need so far.
-

 \subsection options_model_smpi_detached Simulating MPI detached send
 
 This threshold specifies the size in bytes under which the send will return
 \subsection options_model_smpi_detached Simulating MPI detached send
 
 This threshold specifies the size in bytes under which the send will return