fault-tolerance. It can alleviate the state space explosion problem through `Dynamic Partial Ordering Reduction (DPOR)
<https://en.wikipedia.org/wiki/Partial_order_reduction>`_ and `state equality <https://hal.inria.fr/hal-01900120/document>`_. Note that
Mc SimGrid is currently less mature than other parts of the framework, but it improves every month. Please report any question and
-issues so that we can further improve it.
+issue so that we can further improve it.
Getting Mc SimGrid
------------------
-Denable_model-checking .``) and then compile SimGrid :ref:`as usual <install_src>`. Unfortunately, Mc SimGrid does not work natively
on Mac OS X yet, so mac users should stick to the docker method for now.
-.. code-block:: shell
+.. code-block:: console
- docker image pull simgrid/tuto-mc
- mkdir ~/tuto-mcsimgrid # or chose another directory to share between your computer and the docker container
- docker run -it --rm --name mcsimgrid --volume ~/tuto-mcsimgrid:/source/tutorial simgrid/tuto-mc bash
+ $ docker image pull simgrid/tuto-mc
+ $ mkdir ~/tuto-mcsimgrid # or chose another directory to share between your computer and the docker container
+ $ docker run -it --rm --name mcsimgrid --volume ~/tuto-mcsimgrid:/source/tutorial simgrid/tuto-mc bash
In the container, you have access to the following directories of interest:
- ``/source/simgrid.git``: Source code of SimGrid, pre-configured in MC mode. The framework is also installed in ``/usr``
so the source code is only provided for your information.
-If it fails, you may need to enable the PTRACE capability in docker, as follows:
-
-.. code-block:: shell
-
- docker run -it --cap-add SYS_PTRACE --rm --name mcsimgrid --volume ~/tuto-mcsimgrid:/source/tutorial simgrid/tuto-mc bash
-
Lab1: non-deterministic receive
-------------------------------
Let's go with a first example of a bugged program. Once in the container, copy all files from the tutorial into the directory shared
between your host computer and the container.
-.. code-block:: shell
+.. code-block:: console
# From within the container
$ cp -r /source/tuto-mc.git/* /source/tutorial/
$ cd /source/tutorial/
-Several files should have appeared in the ``~/tuto-mcsimgrid`` directory of your computer. This tutorial uses ``ndet-receive-s4u.cpp``,
-that uses the :ref:`S4U interface <S4U_doc>` of SimGrid, but we provide a MPI version if you prefer (see below for details on using the
-MPI version).
+Several files should have appeared in the ``~/tuto-mcsimgrid`` directory of your computer.
+This tutorial uses `ndet-receive-s4u.cpp <https://framagit.org/simgrid/tutorial-model-checking/-/blob/main/ndet-receive-s4u.cpp>`_,
+that uses the :ref:`S4U interface <S4U_doc>` of SimGrid, but we provide a
+`MPI version <https://framagit.org/simgrid/tutorial-model-checking/-/blob/main/ndet-receive-mpi.cpp>`_
+if you prefer (see below for details on using the MPI version).
.. toggle-header::
- :header: View ``ndet-receive-s4u.cpp`` (click on that little triangle)
+ :header: Code of ``ndet-receive-s4u.cpp``: click here to open it, or `view it online <https://framagit.org/simgrid/tutorial-model-checking/-/blob/main/ndet-receive-s4u.cpp>`_
.. literalinclude:: tuto_mc/ndet-receive-s4u.cpp
:language: cpp
+|br|
The provided code is rather simple: Three ``client`` are launched with an integer from ``1, 2, 3`` as a parameter. These actors simply
send their parameter to a given mailbox. A ``server`` receives 3 messages and assumes that the last received message is the number ``3``.
If you compile and run it, it simply works:
-.. code-block:: shell
+.. code-block:: console
$ cmake . && make
(output omitted)
source code and/or the platform file, but this is not a method. Time to start Mc SimGrid, the SimGrid model checker, to exhaustively test
all message orders. For that, you simply launch your simulation as a parameter to the ``simgrid-mc`` binary as you would do with ``valgrind``:
-.. code-block:: shell
+.. code-block:: console
$ simgrid-mc ./ndet-receive-s4u small_platform.xml
(some output ignored)
[Tremblay:server:(1) 0.000000] (...) Assertion value_got == 3 failed
(more output ignored)
-So this is it, it works: Mc SimGrid successfully triggers the bug. Looking closer at the output, it can be split in several parts:
+If it fails with the error ``[root/CRITICAL] Could not wait for the model-checker.``, you need to explicitly add the PTRACE capability to
+your docker. Restart your docker with the additional parameter ``--cap-add SYS_PTRACE``.
+
+At the end, it works: Mc SimGrid successfully triggers the bug. But the produced output is somewhat long and hairy. Don't worry, we will
+now read it together. It can be split in several parts:
- First, you have some information coming from the application.
all possible outcome of the code, the execution is sometimes rewind to explore another possible branch (here: another possible
message ordering). Note also that all times are always 0 in the model checker, since the time is abstracted away in this mode.
- .. code-block:: shell
+ .. code-block:: console
[0.000000] [mc_safety/INFO] Check a safety property. Reduction is: dpor.
[Jupiter:client:(2) 0.000000] [example/INFO] Sending 1
- Then you have the error message, along with a backtrace of the application at the point where the assertion fails. Not all the frames of
the backtrace are useful, and some are omitted here.
- .. code-block:: shell
+ .. code-block:: console
[Tremblay:server:(1) 0.000000] /source/tutorial/ndet-receive-s4u.cpp:27: [root/CRITICAL] Assertion value_got == 3 failed
Backtrace (displayed in actor server):
- First, the error message itself. The ``xbt_assert`` in the code result in an ``abort()`` in the application, that is interpreted as an
application crash by the model-checker.
- .. code-block:: shell
+ .. code-block:: console
[0.000000] [mc_ModelChecker/INFO] **************************
[0.000000] [mc_ModelChecker/INFO] ** CRASH IN THE PROGRAM **
calls we made (put/get) are split in atomic calls (iSend+Wait/iRecv+Wait), and all executions are interleaved. Also, Mc SimGrid
reports the first faulty execution it finds: it may not be the shorter possible one.
- .. code-block:: shell
+ .. code-block:: console
[0.000000] [mc_ModelChecker/INFO] Counter-example execution trace:
[0.000000] [mc_ModelChecker/INFO] [(1)Tremblay (server)] iRecv(dst=(1)Tremblay (server), buff=(verbose only), size=(verbose only))
- Then, the execution path is given.
- .. code-block:: shell
+ .. code-block:: console
[0.000000] [mc_record/INFO] Path = 1;2;1;1;2;4;1;1;3;1
without ``simgrid-mc``. This is because ``simgrid-mc`` forbids to use a debugger such as gdb or valgrind on the code during the
model-checking. For example, you can trigger the same execution in valgrind as follows:
- .. code-block:: shell
+ .. code-block:: console
$ valgrind ./ndet-receive-s4u small_platform.xml --cfg=model-check/replay:'1;2;1;1;2;4;1;1;3;1'
==402== Memcheck, a memory error detector
point of the exploration), the visited states (the amount of times we visited another state -- the same state may have been visited
several times) and the amount of transitions.
- .. code-block:: shell
+ .. code-block:: console
[0.000000] [mc_safety/INFO] Expanded states = 22
[0.000000] [mc_safety/INFO] Visited states = 56
translation of ``ndet-receive-s4u.cpp`` to MPI.
.. toggle-header::
- :header: View ``ndet-receive-mpi.c`` (click on that little triangle)
+ :header: Code of ``ndet-receive-mpi.c``: click here to open it, or `view it online <https://framagit.org/simgrid/tutorial-model-checking/-/blob/main/ndet-receive-mpi.cpp>`_
.. literalinclude:: tuto_mc/ndet-receive-mpi.c
:language: cpp
+|br|
You can compile and run it on top of SimGrid as follows.
-.. code-block:: shell
+.. code-block:: console
$ smpicc ndet-receive-mpi.c -o ndet-receive-mpi
$ smpirun -np 4 -platform small_platform.xml ndet-receive-mpi
-Interestingly enough, the bug is triggered on my machine, because the simulator happens to use the execution path leading to it. It may
-not be the case on your machine, as this order depends on the iteration order of a ``std::unordered_map``. Instead, we should use Mc
-SimGrid to exhaustively explore the state space and trigger the bug in all cases.
+Interestingly enough, the bug is triggered on my machine even without Mc SimGrid, because the simulator happens to use the execution path
+leading to it. It may not be the case on your machine, as this depends on the iteration order of an unsorted collection. Instead, we
+should use Mc SimGrid to exhaustively explore the state space and trigger the bug in all cases.
-.. code-block:: shell
+.. code-block:: console
$ smpirun -wrapper simgrid-mc -np 4 -platform small_platform.xml ndet-receive-mpi
The produced output is then very similar to the one you get with S4U, even if the exact execution path leading to the bug may differs. You
can also trigger a given execution path out of the model-checker, for example to explore it with valgrind.
-.. code-block:: shell
+.. code-block:: console
$ smpirun -wrapper valgrind -np 4 -platform small_platform.xml --cfg=model-check/replay:'1;2;1;1;4;1;1;3;1' ndet-receive-mpi
- SimGrid should naturally :ref:`be compiled <install_src>` with model-checking support. This requires a full set of dependencies
(documented on the :ref:`relevant page <install_src>`) and should not be activated by default as there is a small performance penalty for
codes using a SimGrid with MC enabled (even if you don't activate the model-checking at run time).
-- Also install ``libboost-stacktrace-dev`` to display nice backtraces from the application side (the one from the model-checking side is
- available in any case, but it contains less details).
- You should pass some specific flags to the linker when compiling your application: ``-Wl,-znorelro -Wl,-znoseparate-code`` In the
docker, the provided CMakeLists.txt provides them for you when compiling the provided code. ``smpicc`` and friends also add this
parameter automatically.
+- Also install ``libboost-stacktrace-dev`` to display nice backtraces from the application side (the one from the model-checking side is
+ available in any case, but it contains less details).
+- Mc SimGrid uses the ``ptrace`` system call to spy on the verified application. Some versions of Docker forbid the use of this call by
+ default for security reason (it could be used to escape the docker containment with older versions of Linux). If you encounter this
+ issue, you should either update your settings (the security issue was solved in later versions of Linux), or add ``--cap-add
+ SYS_PTRACE`` to the docker parameters, as hinted by the text.
+
+Going further
+-------------
+
+This tutorial is not complete yet, as there is nothing on reduction
+techniques nor on liveness properties. For now, the best source of
+information on these topics is `this old tutorial
+<https://simgrid.org/tutorials/simgrid-mc-101.pdf>`_ and `that old
+presentation
+<http://people.irisa.fr/Martin.Quinson/blog/2018/0123/McSimGrid-Boston.pdf>`_.
+
+.. |br| raw:: html
+
+ <br />
