/* StarPU --- Runtime system for heterogeneous multicore architectures.
 *
 * Copyright (C) 2010-2017, 2019                          CNRS
 * Copyright (C) 2009-2011,2014,2016                      Université de Bordeaux
 * Copyright (C) 2011,2012                                Inria
 *
 * StarPU is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or (at
 * your option) any later version.
 *
 * StarPU is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 *
 * See the GNU Lesser General Public License in COPYING.LGPL for more details.
 */

/*! \page DebuggingTools Debugging Tools

StarPU provides several tools to help debugging applications. Execution traces
can be generated and displayed graphically, see \ref GeneratingTracesWithFxT.

\section DebuggingInGeneral TroubleShooting In General

Generally-speaking, if you have troubles, pass \ref enable-debug "--enable-debug" to
<c>configure</c> to enable some checks which impact performance, but will
catch common issues, possibly earlier than the actual problem you are observing,
which may just be a consequence of a bug that happened earlier. Also, make sure
not to have the \ref enable-fast "--enable-fast" \c configure option which drops very useful
catchup assertions. If your program is valgrind-safe, you can use it, see \ref
UsingOtherDebugger.

Depending on your toolchain, it might happen that you get
<c>undefined reference to `__stack_chk_guard'</c> errors. In that case, use the
<c>--disable-fstack-protector-all</c> option to avoid the issue.

Then, if your program crashes with an assertion error, a segfault, etc. you can send us the result of

\verbatim
thread apply all bt
\endverbatim

run in <c>gdb</c> at the point of the crash.

In case your program just hangs, but it may also be useful in case of a crash
too, it helps to source <c>gdbinit</c> as described in the next section to be
able to run and send us the output of the following commands:

\verbatim
starpu-workers
starpu-tasks
starpu-print-requests
starpu-print-prequests
starpu-print-frrequests
starpu-print-irrequests
\endverbatim

To give us an idea of what is happening within StarPU. If the outputs are not too long, you can even run

\verbatim
starpu-all-tasks
starpu-print-all-tasks
starpu-print-datas-summary
starpu-print-datas
\endverbatim

\section UsingGdb Using The Gdb Debugger

Some <c>gdb</c> helpers are provided to show the whole StarPU state:

\verbatim
(gdb) source tools/gdbinit
(gdb) help starpu
\endverbatim

For instance,
<ul>
<li> one can print all tasks with <c>starpu-print-all-tasks</c>, </li>
<li> print all datas with <c>starpu-print-datas</c>, </li>
<li> print all pending data transfers with <c>starpu-print-prequests</c>, <c>starpu-print-requests</c>, <c>starpu-print-frequests</c>, <c>starpu-print-irequests</c>,</li>
<li> print pending MPI requests with <c>starpu-mpi-print-detached-requests</c></li>
</ul>

Some functions can only work if \ref enable-debug "--enable-debug"
was passed to <c>configure</c>
(because they impact performance)

\section UsingOtherDebugger Using Other Debugging Tools

Valgrind can be used on StarPU: valgrind.h just needs to be found at <c>configure</c>
time, to tell valgrind about some known false positives and disable host memory
pinning. Other known false positives can be suppressed by giving the suppression
files in <c>tools/valgrind/*.suppr</c> to valgrind's <c>--suppressions</c> option.

The environment variable \ref STARPU_DISABLE_KERNELS can also be set to <c>1</c> to make
StarPU does everything (schedule tasks, transfer memory, etc.) except actually
calling the application-provided kernel functions, i.e. the computation will not
happen. This permits to quickly check that the task scheme is working properly.

\section UsingTheTemanejoTaskDebugger Using The Temanejo Task Debugger

StarPU can connect to Temanejo >= 1.0rc2 (see
http://www.hlrs.de/temanejo), to permit
nice visual task debugging. To do so, build Temanejo's <c>libayudame.so</c>,
install <c>Ayudame.h</c> to e.g. <c>/usr/local/include</c>, apply the
<c>tools/patch-ayudame</c> to it to fix C build, re-<c>configure</c>, make
sure that it found it, rebuild StarPU.  Run the Temanejo GUI, give it the path
to your application, any options you want to pass it, the path to <c>libayudame.so</c>.

It permits to visualize the task graph, add breakpoints, continue execution
task-by-task, and run <c>gdb</c> on a given task, etc.

\image html temanejo.png
\image latex temanejo.png "" width=\textwidth

Make sure to specify at least the same number of CPUs in the dialog box as your
machine has, otherwise an error will happen during execution. Future versions
of Temanejo should be able to tell StarPU the number of CPUs to use.

Tag numbers have to be below <c>4000000000000000000ULL</c> to be usable for
Temanejo (so as to distinguish them from tasks).



*/