X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/d12368e5b9db4863e721dd4f9ed40574b9860da6..895710d49f77179d9893bc76b3e31b69fae638af:/doc/doxygen/module-smpi.doc?ds=sidebyside

diff --git a/doc/doxygen/module-smpi.doc b/doc/doxygen/module-smpi.doc
index 06d67b6153..ede94c177d 100644
--- a/doc/doxygen/module-smpi.doc
+++ b/doc/doxygen/module-smpi.doc
@@ -4,8 +4,6 @@
 
 @tableofcontents
 
-[TOC]
-
 SMPI enables the study of MPI application by emulating them on top of
 the SimGrid simulator. This is particularly interesting to study
 existing MPI applications within the comfort of the simulator. The
@@ -34,6 +32,7 @@ requires some specific care from you.
  - @ref SMPI_use
    - @ref SMPI_use_compile
    - @ref SMPI_use_exec
+   - @ref SMPI_use_debug
    - @ref SMPI_use_colls
      - @ref SMPI_use_colls_algos
      - @ref SMPI_use_colls_tracing
@@ -45,7 +44,9 @@ requires some specific care from you.
    - @ref SMPI_adapting_speed
  - @ref SMPI_accuracy
  - @ref SMPI_troubleshooting
-   - @ref SMPI_trouble_buildchain
+   - @ref SMPI_trouble_configure_refuses_smpicc
+   - @ref SMPI_trouble_configure_dont_find_smpicc
+   - @ref SMPI_trouble_useconds_t
 
 
 @section SMPI_use Using SMPI
@@ -87,6 +88,21 @@ by running
 smpirun -help
 @endverbatim
 
+@subsection SMPI_use_debug Debugging your code on top of SMPI
+
+If you want to explore the automatic platform and deployment files
+that are generated by @c smpirun, add @c -keep-temps to the command
+line.
+
+You can also run your simulation within valgrind or gdb using the
+following commands. Once in GDB, each MPI ranks will be represented as
+a regular thread, and you can explore the state of each of them as
+usual.
+@verbatim
+smpirun -wrapper valgrind ...other args...
+smpirun -wrapper "gdb --args" --cfg=contexts/factory:thread ...other args...
+@endverbatim
+
 @subsection SMPI_use_colls Simulating collective operations
 
 MPI collective operations are crucial to the performance of MPI
@@ -150,7 +166,7 @@ Most of these are best described in <a href="http://www.cs.arizona.edu/~dkl/rese
  - 2dmesh: organizes the nodes as a two dimensional mesh, and perform allgather 
    along the dimensions
  - 3dmesh: adds a third dimension to the previous algorithm
- - rdb: recursive doubling : extends the mesh to a nth dimension, each one 
+ - rdb: recursive doubling: extends the mesh to a nth dimension, each one 
    containing two nodes
  - pair: pairwise exchange, only works for power of 2 procs, size-1 steps,
    each process sends and receives from the same process at each step
@@ -626,11 +642,10 @@ in modeling distributed systems.
 
 @section SMPI_troubleshooting Troubleshooting with SMPI
 
-@subsection SMPI_trouble_buildchain My ./configure refuses to use smpicc
+@subsection SMPI_trouble_configure_refuses_smpicc ./configure refuses to use smpicc
 
-Alas, some building infrastructures cannot use smpicc as a project
-compiler, and your <tt>./configure</tt> may report that the compiler
-is not functional. If this happens, define the
+If your <tt>./configure</tt> reports that the compiler is not
+functional or that you are cross-compiling, try to define the
 <tt>SMPI_PRETEND_CC</tt> environment variable before running the
 configuration.
 
@@ -639,12 +654,45 @@ SMPI_PRETEND_CC=1 ./configure # here come the configure parameters
 make
 @endverbatim
 
+Indeed, the programs compiled with <tt>smpicc</tt> cannot be executed
+without <tt>smpirun</tt> (they are shared libraries, and they do weird
+things on startup), while configure wants to test them directly.
+With <tt>SMPI_PRETEND_CC</tt> smpicc does not compile as shared,
+and the SMPI initialization stops and returns 0 before doing anything
+that would fail without <tt>smpirun</tt>.
+
 \warning 
 
   Make sure that SMPI_PRETEND_CC is only set when calling ./configure,
-  not during the actual compilation. With that variable, smpicc does
-  not do anything, to not hurt the ./configure feelings. But you need
-  smpicc do actually do something to get your application compiled.
+  not during the actual execution, or any program compiled with smpicc
+  will stop before starting.
+
+@subsection SMPI_trouble_configure_dont_find_smpicc ./configure does not pick smpicc as a compiler
+
+In addition to the previous answers, some projects also need to be
+explicitely told what compiler to use, as follows:
+
+@verbatim
+SMPI_PRETEND_CC=1 ./configure CC=smpicc # here come the other configure parameters
+make
+@endverbatim
+
+Maybe your configure is using another variable, such as <tt>cc</tt> or
+similar. Just check the logs.
+
+@subsection SMPI_trouble_useconds_t  error: unknown type name 'useconds_t'
+
+Try to add <tt>-D_GNU_SOURCE</tt> to your compilation line to get ride
+of that error.
+
+The reason is that SMPI provides its own version of <tt>usleep(3)</tt>
+to override it and to block in the simulation world, not in the real
+one. It needs the <tt>useconds_t</tt> type for that, which is declared
+only if you declare <tt>_GNU_SOURCE</tt> before including
+<tt>unistd.h</tt>. If your project includes that header file before
+SMPI, then you need to ensure that you pass the right configuration
+defines as advised above.
+
 
 */