docs/source/Tutorial_Model-checking.rst

   1 .. _usecase_modelchecking:
   2
   3 Formal Verification and Model-checking
   4 ======================================
   5
   6 SimGrid can not only predict the performance of your application, but also assess its correctness through formal methods. Mc SimGrid is
   7 a full-featured model-checker that is embedded in the SimGrid framework. It can be used to formally verify safety and liveness
   8 properties on codes running on top of SimGrid, be it :ref:`simple algorithms <usecase_simalgo>` or :ref:`full MPI applications
   9 <usecase_smpi>`.
  10
  11 Primer on formal methods
  12 ------------------------
  13
  14 Formal methods are techniques leveraging mathematics to test and assess systems. They are routinely used to assess computer hardware,
  15 transportation systems or any other complex engineering process. Among these methods, model-checking is a technique to automatically
  16 prove that a given model verifies a given property by systematically checking all states of the model. The property and model are
  17 written in a mathematical language and fed to an automated tool called model checker. When the model does not verify the property, the
  18 model checker gives a counter-example that can be used to refine and improve the model. Conversely, if no counter-example can be found
  19 after an exhaustive exploration of the model, we know that the property holds for the model. It may also happen that the model is too
  20 large to be exhaustively explored, in which case the model-checker is not conclusive. Model checkers rely on so-called reduction
  21 techniques (based on symmetries and equivalence) to efficiently explore the system state.
  22
  23 Dynamic verification applies similar ideas to programs, without requiring a mathematical model of the system. Instead, the program
  24 itself is used as a model to verify against a property. Along these lines, Mc SimGrid is a stateful model checker: it does not leverage
  25 static analysis nor symbolic execution. Instead, the program is simply executed through all possible outcomes. On indecision points, a
  26 system checkpoint is taken, the first branch is executed exhaustively, and then the system is roll back to that point to explore the
  27 other branch.
  28
  29 Mc SimGrid targets distributed applications that interact through message passing or through synchronization mechanisms (mutex,
  30 barrier, etc). Since it does not explicitly observe memory accesses, Mc SimGrid cannot automatically detect race conditions in
  31 multithreaded programs. It can however be used to detect misuses of the synchronization functions, such as the ones resulting in
  32 deadlocks.
  33
  34 Mc SimGrid can be used to verify classical `safety and liveness properties <https://en.wikipedia.org/wiki/Linear_time_property>`_, but
  35 also `communication determinism <https://hal.inria.fr/hal-01953167/document>`_, a property that allows more efficient solutions toward
  36 fault-tolerance. It can alleviate the state space explosion problem through `Dynamic Partial Ordering Reduction (DPOR)
  37 <https://en.wikipedia.org/wiki/Partial_order_reduction>`_ and `state equality <https://hal.inria.fr/hal-01900120/document>`_. Note that
  38 Mc SimGrid is currently less mature than other parts of the framework, but it improves every month. Please report any question and
  39 issue so that we can further improve it.
  40
  41 Getting Mc SimGrid
  42 ------------------
  43
  44 It is included in the SimGrid source code, but it is not compiled in by default as it induces a small performance overhead to the
  45 simulations. It is also not activated in the Debian package, nor in the Java or Python binary distributions. If you just plan to
  46 experiment with Mc SimGrid, the easiest is to get the corresponding docker image. On the long term, you probably want to install it on
  47 your machine: it works out of the box on Linux, Windows (with WSL2) and FreeBSD. Simply request it from cmake (``cmake
  48 -Denable_model-checking .``) and then compile SimGrid :ref:`as usual <install_src>`. Unfortunately, Mc SimGrid does not work natively
  49 on Mac OS X yet, so mac users should stick to the docker method for now.
  50
  51 .. code-block:: console
  52
  53    $ docker image pull simgrid/tuto-mc
  54    $ mkdir ~/tuto-mcsimgrid # or chose another directory to share between your computer and the docker container
  55    $ docker run --user $UID:$GID -it --rm --name mcsimgrid --volume ~/tuto-mcsimgrid:/source/tutorial simgrid/tuto-mc bash
  56
  57 In the container, you have access to the following directories of interest:
  58
  59 - ``/source/tutorial``: A view to the ``~/tuto-mcsimgrid`` directory on your disk, out of the container.
  60   Edit the files you want from your computer and save them in ``~/tuto-mcsimgrid``;
  61   Compile and use them immediately within the container in ``/source/tutorial``.
  62 - ``/source/tuto-mc.git``: Files provided with this tutorial.
  63 - ``/source/simgrid.git``: Source code of SimGrid, pre-configured in MC mode. The framework is also installed in ``/usr``
  64   so the source code is only provided for your information.
  65
  66 Lab1: non-deterministic receive
  67 -------------------------------
  68
  69 Motivational example
  70 ^^^^^^^^^^^^^^^^^^^^
  71
  72 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
  73 between your host computer and the container.
  74
  75 .. code-block:: console
  76
  77   # From within the container
  78   $ cp -r /source/tuto-mc.git/* /source/tutorial/
  79   $ cd /source/tutorial/
  80
  81 Several files should have appeared in the ``~/tuto-mcsimgrid`` directory of your computer.
  82 This tutorial uses `ndet-receive-s4u.cpp <https://framagit.org/simgrid/tutorial-model-checking/-/blob/main/ndet-receive-s4u.cpp>`_,
  83 that uses the :ref:`S4U interface <S4U_doc>` of SimGrid, but we provide a
  84 `MPI version <https://framagit.org/simgrid/tutorial-model-checking/-/blob/main/ndet-receive-mpi.cpp>`_
  85 if you prefer (see below for details on using the MPI version).
  86
  87 .. toggle-header::
  88    :header: Code of ``ndet-receive-s4u.cpp``: click here to open
  89
  90    You can also `view it online <https://framagit.org/simgrid/tutorial-model-checking/-/blob/main/ndet-receive-s4u.cpp>`_
  91
  92    .. literalinclude:: tuto_mc/ndet-receive-s4u.cpp
  93       :language: cpp
  94
  95 |br|
  96 The provided code is rather simple: Three ``client`` are launched with an integer from ``1, 2, 3`` as a parameter. These actors simply
  97 send their parameter to a given mailbox. A ``server`` receives 3 messages and assumes that the last received message is the number ``3``.
  98 If you compile and run it, it simply works:
  99
 100 .. code-block:: console
 101
 102    $ cmake . && make
 103    (output omitted)
 104    $ ./ndet-receive-s4u small_platform.xml
 105    [Jupiter:client:(2) 0.000000] [example/INFO] Sending 1
 106    [Bourassa:client:(3) 0.000000] [example/INFO] Sending 2
 107    [Ginette:client:(4) 0.000000] [example/INFO] Sending 3
 108    [Jupiter:client:(2) 0.020516] [example/INFO] Sent!
 109    [Bourassa:client:(3) 0.047027] [example/INFO] Sent!
 110    [Ginette:client:(4) 0.064651] [example/INFO] Sent!
 111    [Tremblay:server:(1) 0.064651] [example/INFO] OK
 112
 113 Running and understanding Mc SimGrid
 114 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 115
 116 If you think of it, that's weird that this code works: all the messages are sent at the exact same time (t=0), so there is no reason for
 117 the message ``3`` to arrive last. Depending on the link speed, any order should be possible. To trigger the bug, you could fiddle with the
 118 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
 119 all message orders. For that, you simply launch your simulation as a parameter to the ``simgrid-mc`` binary as you would do with ``valgrind``:
 120
 121 .. code-block:: console
 122
 123    $ simgrid-mc ./ndet-receive-s4u small_platform.xml
 124    (some output ignored)
 125    [Tremblay:server:(1) 0.000000] (...) Assertion value_got == 3 failed
 126    (more output ignored)
 127
 128 If it fails with the error ``[root/CRITICAL] Could not wait for the model-checker.``, you need to explicitly add the PTRACE capability to
 129 your docker. Restart your docker with the additional parameter ``--cap-add SYS_PTRACE``.
 130
 131 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
 132 now read it together. It can be split in several parts:
 133
 134 - First, you have some information coming from the application.
 135
 136   - On top, you see the output of the application, but somewhat stuttering. This is exactly what happens: since Mc SimGrid is exploring
 137     all possible outcome of the code, the execution is sometimes rewind to explore another possible branch (here: another possible
 138     message ordering). Note also that all times are always 0 in the model checker, since the time is abstracted away in this mode.
 139
 140     .. code-block:: console
 141
 142        [0.000000] [mc_safety/INFO] Check a safety property. Reduction is: dpor.
 143        [Jupiter:client:(2) 0.000000] [example/INFO] Sending 1
 144        [Bourassa:client:(3) 0.000000] [example/INFO] Sending 2
 145        [Ginette:client:(4) 0.000000] [example/INFO] Sending 3
 146        [Jupiter:client:(2) 0.000000] [example/INFO] Sent!
 147        [Bourassa:client:(3) 0.000000] [example/INFO] Sent!
 148        [Tremblay:server:(1) 0.000000] [example/INFO] OK
 149        [Ginette:client:(4) 0.000000] [example/INFO] Sent!
 150        [Jupiter:client:(2) 0.000000] [example/INFO] Sent!
 151        [Bourassa:client:(3) 0.000000] [example/INFO] Sent!
 152        [Jupiter:client:(2) 0.000000] [example/INFO] Sent!
 153        [Bourassa:client:(3) 0.000000] [example/INFO] Sent!
 154        [Tremblay:server:(1) 0.000000] [example/INFO] OK
 155        [Ginette:client:(4) 0.000000] [example/INFO] Sent!
 156        [Jupiter:client:(2) 0.000000] [example/INFO] Sent!
 157        [Bourassa:client:(3) 0.000000] [example/INFO] Sent!
 158        [Jupiter:client:(2) 0.000000] [example/INFO] Sent!
 159
 160   - 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
 161     the backtrace are useful, and some are omitted here.
 162
 163     .. code-block:: console
 164
 165        [Tremblay:server:(1) 0.000000] /source/tutorial/ndet-receive-s4u.cpp:27: [root/CRITICAL] Assertion value_got == 3 failed
 166        Backtrace (displayed in actor server):
 167          ->  0# xbt_backtrace_display_current at /source/simgrid.git/src/xbt/backtrace.cpp:30
 168          ->  1# server() at /source/tutorial/ndet-receive-s4u.cpp:27
 169
 170 -  After that comes a lot of information from the model-checker.
 171
 172   - First, the error message itself. The ``xbt_assert`` in the code result in an ``abort()`` in the application, that is interpreted as an
 173     application crash by the model-checker.
 174
 175     .. code-block:: console
 176
 177        [0.000000] [mc_ModelChecker/INFO] **************************
 178        [0.000000] [mc_ModelChecker/INFO] ** CRASH IN THE PROGRAM **
 179        [0.000000] [mc_ModelChecker/INFO] **************************
 180        [0.000000] [mc_ModelChecker/INFO] From signal: Aborted
 181        [0.000000] [mc_ModelChecker/INFO] A core dump was generated by the system.
 182
 183   - An execution trace is then given, listing all the actions that led to that faulty execution. This is not easy to read, because the API
 184     calls we made (put/get) are split in atomic calls (iSend+Wait/iRecv+Wait), and all executions are interleaved. Also, Mc SimGrid
 185     reports the first faulty execution it finds: it may not be the shorter possible one.
 186
 187     .. code-block:: console
 188
 189        [0.000000] [mc_ModelChecker/INFO] Counter-example execution trace:
 190        [0.000000] [mc_ModelChecker/INFO]   [(1)Tremblay (server)] iRecv(dst=(1)Tremblay (server), buff=(verbose only), size=(verbose only))
 191        [0.000000] [mc_ModelChecker/INFO]   [(2)Jupiter (client)] iSend(src=(2)Jupiter (client), buff=(verbose only), size=(verbose only))
 192        [0.000000] [mc_ModelChecker/INFO]   [(1)Tremblay (server)] Wait(comm=(verbose only) [(2)Jupiter (client)-> (1)Tremblay (server)])
 193        [0.000000] [mc_ModelChecker/INFO]   [(1)Tremblay (server)] iRecv(dst=(1)Tremblay (server), buff=(verbose only), size=(verbose only))
 194        [0.000000] [mc_ModelChecker/INFO]   [(2)Jupiter (client)] Wait(comm=(verbose only) [(2)Jupiter (client)-> (1)Tremblay (server)])
 195        [0.000000] [mc_ModelChecker/INFO]   [(4)Ginette (client)] iSend(src=(4)Ginette (client), buff=(verbose only), size=(verbose only))
 196        [0.000000] [mc_ModelChecker/INFO]   [(1)Tremblay (server)] Wait(comm=(verbose only) [(4)Ginette (client)-> (1)Tremblay (server)])
 197        [0.000000] [mc_ModelChecker/INFO]   [(1)Tremblay (server)] iRecv(dst=(1)Tremblay (server), buff=(verbose only), size=(verbose only))
 198        [0.000000] [mc_ModelChecker/INFO]   [(3)Bourassa (client)] iSend(src=(3)Bourassa (client), buff=(verbose only), size=(verbose only))
 199        [0.000000] [mc_ModelChecker/INFO]   [(1)Tremblay (server)] Wait(comm=(verbose only) [(3)Bourassa (client)-> (1)Tremblay (server)])
 200
 201   - Then, the execution path is given.
 202
 203     .. code-block:: console
 204
 205        [0.000000] [mc_record/INFO] Path = 1;2;1;1;2;4;1;1;3;1
 206
 207     This is the magical string (here: ``1;2;1;1;2;4;1;1;3;1``) that you should pass to your simulator to follow the same execution path
 208     without ``simgrid-mc``. This is because ``simgrid-mc`` forbids to use a debugger such as gdb or valgrind on the code during the
 209     model-checking. For example, you can trigger the same execution in valgrind as follows:
 210
 211     .. code-block:: console
 212
 213        $ valgrind ./ndet-receive-s4u small_platform.xml --cfg=model-check/replay:'1;2;1;1;2;4;1;1;3;1'
 214        ==402== Memcheck, a memory error detector
 215        ==402== Copyright (C) 2002-2017, and GNU GPL'd, by Julian Seward et al.
 216        ==402== Using Valgrind-3.16.1 and LibVEX; rerun with -h for copyright info
 217        ==402== Command: ./ndet-receive-s4u small_platform.xml --cfg=model-check/replay:1;2;1;1;2;4;1;1;3;1
 218        ==402==
 219        [0.000000] [xbt_cfg/INFO] Configuration change: Set 'model-check/replay' to '1;2;1;1;2;4;1;1;3;1'
 220        [0.000000] [mc_record/INFO] path=1;2;1;1;2;4;1;1;3;1
 221        [Jupiter:client:(2) 0.000000] [example/INFO] Sending 1
 222        [Bourassa:client:(3) 0.000000] [example/INFO] Sending 2
 223        [Ginette:client:(4) 0.000000] [example/INFO] Sending 3
 224        [Jupiter:client:(2) 0.000000] [example/INFO] Sent!
 225        [Tremblay:server:(1) 0.000000] /source/tutorial/ndet-receive-s4u.cpp:27: [root/CRITICAL] Assertion value_got == 3 failed
 226        (some output ignored)
 227        ==402==
 228        ==402== Process terminating with default action of signal 6 (SIGABRT): dumping core
 229        ==402==    at 0x550FCE1: raise (raise.c:51)
 230        ==402==    by 0x54F9536: abort (abort.c:79)
 231        ==402==    by 0x10C696: server() (ndet-receive-s4u.cpp:27)
 232        (more valgrind output ignored)
 233
 234   - Then, Mc SimGrid displays some statistics about the amount of expanded states (the unique states in which your program was at a given
 235     point of the exploration), the visited states (the amount of times we visited another state -- the same state may have been visited
 236     several times) and the amount of transitions.
 237
 238     .. code-block:: console
 239
 240        [0.000000] [mc_safety/INFO] Expanded states = 22
 241        [0.000000] [mc_safety/INFO] Visited states = 56
 242        [0.000000] [mc_safety/INFO] Executed transitions = 52
 243
 244   - Finally, the application stack trace is displayed as the model-checker sees it. It should be the same as the one displayed from the
 245     application side, unless you found a bug our tools.
 246
 247 Using MPI instead of S4U
 248 ^^^^^^^^^^^^^^^^^^^^^^^^
 249
 250 If you prefer, you can use MPI instead of the SimGrid-specific interface. Inspect the provided ``ndet-receive-mpi.c`` file: that's just a
 251 translation of ``ndet-receive-s4u.cpp`` to MPI.
 252
 253 .. toggle-header::
 254    :header: Code of ``ndet-receive-mpi.c``: click here to open
 255
 256    You can also `view it online <https://framagit.org/simgrid/tutorial-model-checking/-/blob/main/ndet-receive-mpi.c>`_.
 257
 258    .. literalinclude:: tuto_mc/ndet-receive-mpi.c
 259       :language: cpp
 260
 261 |br|
 262 You can compile and run it on top of SimGrid as follows.
 263
 264 .. code-block:: console
 265
 266    $ smpicc ndet-receive-mpi.c -o ndet-receive-mpi
 267    $ smpirun -np 4 -platform small_platform.xml ndet-receive-mpi
 268
 269 Interestingly enough, the bug is triggered on my machine even without Mc SimGrid, because the simulator happens to use the execution path
 270 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
 271 should use Mc SimGrid to exhaustively explore the state space and trigger the bug in all cases.
 272
 273 .. code-block:: console
 274
 275    $ smpirun -wrapper simgrid-mc -np 4 -platform small_platform.xml ndet-receive-mpi
 276
 277 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
 278 can also trigger a given execution path out of the model-checker, for example to explore it with valgrind.
 279
 280 .. code-block:: console
 281
 282    $ 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
 283
 284 Under the hood
 285 ^^^^^^^^^^^^^^
 286
 287 If you want to run such analysis on your own code, out of the provided docker, there is some steps that you should take.
 288
 289 - SimGrid should naturally :ref:`be compiled <install_src>` with model-checking support. This requires a full set of dependencies
 290   (documented on the :ref:`relevant page <install_src>`) and should not be activated by default as there is a small performance penalty for
 291   codes using a SimGrid with MC enabled (even if you don't activate the model-checking at run time).
 292 - You should pass some specific flags to the linker when compiling your application: ``-Wl,-znorelro -Wl,-znoseparate-code`` In the
 293   docker, the provided CMakeLists.txt provides them for you when compiling the provided code. ``smpicc`` and friends also add this
 294   parameter automatically.
 295 - Also install ``libboost-stacktrace-dev`` to display nice backtraces from the application side (the one from the model-checking side is
 296   available in any case, but it contains less details).
 297 - Mc SimGrid uses the ``ptrace`` system call to spy on the verified application. Some versions of Docker forbid the use of this call by
 298   default for security reason (it could be used to escape the docker containment with older versions of Linux). If you encounter this
 299   issue, you should either update your settings (the security issue was solved in later versions of Linux), or add ``--cap-add
 300   SYS_PTRACE`` to the docker parameters, as hinted by the text.
 301
 302 Going further
 303 -------------
 304
 305 This tutorial is not complete yet, as there is nothing on reduction
 306 techniques nor on liveness properties. For now, the best source of
 307 information on these topics is `this old tutorial
 308 <https://simgrid.org/tutorials/simgrid-mc-101.pdf>`_ and `that old
 309 presentation
 310 <http://people.irisa.fr/Martin.Quinson/blog/2018/0123/McSimGrid-Boston.pdf>`_.
 311
 312 .. |br| raw:: html
 313
 314    <br />