doc/mc: improve the replay documentation

[simgrid.git] / docs / source / Configuring_SimGrid.rst

diff --git a/docs/source/Configuring_SimGrid.rst b/docs/source/Configuring_SimGrid.rst
index 136c019..7c109a0 100644 (file)
--- a/docs/source/Configuring_SimGrid.rst
+++ b/docs/source/Configuring_SimGrid.rst
@@ -81,10 +81,8 @@ Existing Configuration Items
   The full list can be retrieved by passing ``--help`` and
   ``--help-cfg`` to an executable that uses SimGrid. Try passing
   ``help`` as a value to get the list of values accepted by a given
   The full list can be retrieved by passing ``--help`` and
   ``--help-cfg`` to an executable that uses SimGrid. Try passing
   ``help`` as a value to get the list of values accepted by a given

-   option. For example, ``--cfg=plugin:help`` will give you the list
-   of plugins available in your installation of SimGrid.
-
-- **clean-atexit:** :ref:`cfg=clean-atexit`
+  option. For example, ``--cfg=plugin:help`` will give you the list
+  of plugins available in your installation of SimGrid.

 
 - **contexts/factory:** :ref:`cfg=contexts/factory`
 - **contexts/guard-size:** :ref:`cfg=contexts/guard-size`
 
 - **contexts/factory:** :ref:`cfg=contexts/factory`
 - **contexts/guard-size:** :ref:`cfg=contexts/guard-size`


@@ -97,6 +95,10 @@ Existing Configuration Items
 - **cpu/model:** :ref:`options_model_select`
 - **cpu/optim:** :ref:`Cpu Optimization Level <options_model_optim>`
 
 - **cpu/model:** :ref:`options_model_select`
 - **cpu/optim:** :ref:`Cpu Optimization Level <options_model_optim>`
 

+- **debug/breakpoint:** :ref:`cfg=debug/breakpoint`
+- **debug/clean-atexit:** :ref:`cfg=debug/clean-atexit`
+- **debug/verbose-exit:** :ref:`cfg=debug/verbose-exit`
+

 - **exception/cutpath:** :ref:`cfg=exception/cutpath`
 
 - **host/model:** :ref:`options_model_select`
 - **exception/cutpath:** :ref:`cfg=exception/cutpath`
 
 - **host/model:** :ref:`options_model_select`


@@ -110,7 +112,6 @@ Existing Configuration Items
 - **model-check/checkpoint:** :ref:`cfg=model-check/checkpoint`
 - **model-check/communications-determinism:** :ref:`cfg=model-check/communications-determinism`
 - **model-check/dot-output:** :ref:`cfg=model-check/dot-output`
 - **model-check/checkpoint:** :ref:`cfg=model-check/checkpoint`
 - **model-check/communications-determinism:** :ref:`cfg=model-check/communications-determinism`
 - **model-check/dot-output:** :ref:`cfg=model-check/dot-output`

-- **model-check/hash:** :ref:`cfg=model-checker/hash`

 - **model-check/max-depth:** :ref:`cfg=model-check/max-depth`
 - **model-check/property:** :ref:`cfg=model-check/property`
 - **model-check/reduction:** :ref:`cfg=model-check/reduction`
 - **model-check/max-depth:** :ref:`cfg=model-check/max-depth`
 - **model-check/property:** :ref:`cfg=model-check/property`
 - **model-check/reduction:** :ref:`cfg=model-check/reduction`


@@ -133,8 +134,6 @@ Existing Configuration Items
 - **path:** :ref:`cfg=path`
 - **plugin:** :ref:`cfg=plugin`
 
 - **path:** :ref:`cfg=path`
 - **plugin:** :ref:`cfg=plugin`
 

-- **simix/breakpoint:** :ref:`cfg=simix/breakpoint`
-

 - **storage/max_file_descriptors:** :ref:`cfg=storage/max_file_descriptors`
 
 - **surf/precision:** :ref:`cfg=surf/precision`
 - **storage/max_file_descriptors:** :ref:`cfg=storage/max_file_descriptors`
 
 - **surf/precision:** :ref:`cfg=surf/precision`


@@ -170,7 +169,6 @@ Existing Configuration Items
 - **Tracing configuration options** can be found in Section :ref:`tracing_tracing_options`
 
 - **storage/model:** :ref:`options_model_select`
 - **Tracing configuration options** can be found in Section :ref:`tracing_tracing_options`
 
 - **storage/model:** :ref:`options_model_select`

-- **verbose-exit:** :ref:`cfg=verbose-exit`

 
 - **vm/model:** :ref:`options_model_select`
 
 
 - **vm/model:** :ref:`options_model_select`
 


@@ -218,11 +216,9 @@ models for all existing resources.
     poorly modeled. This model is described in `A Network Model for
     Simulation of Grid Application
     <https://hal.inria.fr/inria-00071989/document>`_.
     poorly modeled. This model is described in `A Network Model for
     Simulation of Grid Application
     <https://hal.inria.fr/inria-00071989/document>`_.

-  - **Reno/Reno2/Vegas:** Models from Steven H. Low using lagrange_solve instead of
-    lmm_solve (experts only; check the code for more info).
-  - **NS3** (only available if you compiled SimGrid accordingly):
+  - **ns-3** (only available if you compiled SimGrid accordingly):

     Use the packet-level network
     Use the packet-level network

-    simulators as network models (see :ref:`pls_ns3`).
+    simulators as network models (see :ref:`model_ns3`).

     This model can be :ref:`further configured <options_pls>`.
 
 - ``cpu/model``: specify the used CPU model.  We have only one model
     This model can be :ref:`further configured <options_pls>`.
 
 - ``cpu/model``: specify the used CPU model.  We have only one model


@@ -420,15 +416,15 @@ meant to be detached as well.
 
 .. _options_pls:
 
 
 .. _options_pls:
 

-Configuring NS3
-^^^^^^^^^^^^^^^
+Configuring ns-3
+^^^^^^^^^^^^^^^^

 
 

-**Option** ``ns3/TcpModel`` **Default:** "default" (NS3 default)
+**Option** ``ns3/TcpModel`` **Default:** "default" (ns-3 default)

 
 

-When using NS3, there is an extra item ``ns3/TcpModel``, corresponding
+When using ns-3, there is an extra item ``ns3/TcpModel``, corresponding

 to the ``ns3::TcpL4Protocol::SocketType`` configuration item in
 to the ``ns3::TcpL4Protocol::SocketType`` configuration item in

-NS3. The only valid values (enforced on the SimGrid side) are
-'default' (no change to the NS3 configuration), 'NewReno' or 'Reno' or
+ns-3. The only valid values (enforced on the SimGrid side) are
+'default' (no change to the ns-3 configuration), 'NewReno' or 'Reno' or

 'Tahoe'.
 
 Configuring the Storage model
 'Tahoe'.
 
 Configuring the Storage model


@@ -633,23 +629,6 @@ protected with guards: if the stack size is too small for your
 application, the stack will silently overflow on other parts of the
 memory (see :ref:`contexts/guard-size <cfg=contexts/guard-size>`).
 
 application, the stack will silently overflow on other parts of the
 memory (see :ref:`contexts/guard-size <cfg=contexts/guard-size>`).
 

-.. _cfg=model-checker/hash:
-
-State Hashing
-.............
-
-Usually most of the time of the model-checker is spent comparing states. This
-process is complicated and consumes a lot of bandwidth and cache.
-In order to speedup the state comparison, the experimental ``model-checker/hash``
-configuration item enables the computation of a hash summarizing as much
-information of the state as possible into a single value. This hash can be used
-to avoid most of the comparisons: the costly comparison is then only used when
-the hashes are identical.
-
-Currently most of the state is not included in the hash because the
-implementation was found to be buggy and this options is not as useful as
-it could be. For this reason, it is currently disabled by default.
-

 .. _cfg=model-check/replay:
 
 Replaying buggy execution paths out of the model-checker
 .. _cfg=model-check/replay:
 
 Replaying buggy execution paths out of the model-checker


@@ -682,10 +661,20 @@ generates an identifier for this path. Here is an example of output:
    [  0.000000] (0:@) Executed transitions = 46
 
 The interesting line is ``Path = 1/3;1/4``, which means that you should use
    [  0.000000] (0:@) Executed transitions = 46
 
 The interesting line is ``Path = 1/3;1/4``, which means that you should use

-`--cfg=model-check/replay:1/3;1/4`` to replay your application on the buggy
-execution path. The other options should be the same (but the model-checker
-should be disabled). Note that format and meaning of the path may change between
-different releases.
+``--cfg=model-check/replay:1/3;1/4`` to replay your application on the buggy
+execution path. All options (but the model-checker related ones) must
+remain the same. In particular, if you ran your application with
+``smpirun -wrapper simgrid-mc``, then do it again. Remove all
+MC-related options, keep the other ones and add
+``--cfg=model-check/replay``.
+
+Currently, if the path is of the form ``X;Y;Z``, each number denotes
+the actor's pid that is selected at each indecision point. If it's of
+the form ``X/a;Y/b``, the X and Y are the selected pids while the a
+and b are the return values of their simcalls. In the previouse
+example, ``1/3;1/4``, you can see from the full output that the actor
+1 is doing MC_RANDOM simcalls, so the 3 and 4 simply denote the values
+that these simcall return.

 
 Configuring the User Code Virtualization
 ----------------------------------------
 
 Configuring the User Code Virtualization
 ----------------------------------------


@@ -1427,12 +1416,12 @@ extra delay by setting smpi/wtime to 0.
 Other Configurations
 --------------------
 
 Other Configurations
 --------------------
 

-.. _cfg=clean-atexit:
+.. _cfg=debug/clean-atexit:

 
 Cleanup at Termination
 ......................
 
 
 Cleanup at Termination
 ......................
 

-**Option** ``clean-atexit`` **default:** on
+**Option** ``debug/clean-atexit`` **default:** on

 
 If your code is segfaulting during its finalization, it may help to
 disable this option to request SimGrid to not attempt any cleanups at
 
 If your code is segfaulting during its finalization, it may help to
 disable this option to request SimGrid to not attempt any cleanups at


@@ -1451,12 +1440,12 @@ trace files (see :ref:`pf_trace`) by using this configuration
 item. To add several directory to the path, set the configuration
 item several times, as in ``--cfg=path:toto --cfg=path:tutu``
 
 item. To add several directory to the path, set the configuration
 item several times, as in ``--cfg=path:toto --cfg=path:tutu``
 

-.. _cfg=simix/breakpoint:
+.. _cfg=debug/breakpoint:

 
 Set a Breakpoint
 ................
 
 
 Set a Breakpoint
 ................
 

-**Option** ``simix/breakpoint`` **default:** unset
+**Option** ``debug/breakpoint`` **default:** unset

 
 This configuration option sets a breakpoint: when the simulated clock
 reaches the given time, a SIGTRAP is raised.  This can be used to stop
 
 This configuration option sets a breakpoint: when the simulated clock
 reaches the given time, a SIGTRAP is raised.  This can be used to stop


@@ -1470,12 +1459,12 @@ with gdb:
 
    set variable simgrid::simix::breakpoint = 3.1416
 
 
    set variable simgrid::simix::breakpoint = 3.1416
 

-.. _cfg=verbose-exit:
+.. _cfg=debug/verbose-exit:

 
 Behavior on Ctrl-C
 ..................
 
 
 Behavior on Ctrl-C
 ..................
 

-**Option** ``verbose-exit`` **default:** on
+**Option** ``debug/verbose-exit`` **default:** on

 
 By default, when Ctrl-C is pressed, the status of all existing actors
 is displayed before exiting the simulation. This is very useful to
 
 By default, when Ctrl-C is pressed, the status of all existing actors
 is displayed before exiting the simulation. This is very useful to