/*
 * This file is part of the StarPU Handbook.
 * Copyright (C) 2009--2011  Universit@'e de Bordeaux
 * Copyright (C) 2010, 2011, 2012, 2013, 2014  CNRS
 * Copyright (C) 2011, 2012 INRIA
 * See the file version.doxy for copying conditions.
 */

/*! \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 <c>--enable-debug</c> 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. If your program
is valgrind-safe, you can use it, see \ref UsingOtherDebugger.

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 gdb 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:

\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 gdb helpers are provided to show the whole StarPU state:

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

For instance, one can print all tasks with <c>starpu-print-all-tasks</c>,
print all datas with <c>starpu-print-datas</c>, 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>,
print pending MPI requests with
<c>starpu-mpi-print-detached-requests</c>

Some functions can only work if <c>--enable-debug</c> 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 ./configure
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 tools/valgrind/ *.suppr to valgrind's --suppressions option.

The environment variable \ref STARPU_DISABLE_KERNELS can also be set to 1 to make
StarPU do 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 gdb 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).



*/