manual-core.xml: Fix various xmllint issues.

[valgrind.git] / README_DEVELOPERS

Building and installing it
~~~~~~~~~~~~~~~~~~~~~~~~~~
To build/install from the GIT repository or from a distribution
tarball, refer to the section with the same name in README.

Building and not installing it
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To run Valgrind without having to install it, run coregrind/valgrind
with the VALGRIND_LIB environment variable set, where <dir> is the root
of the source tree (and must be an absolute path).  Eg:

  VALGRIND_LIB=~/grind/head4/.in_place ~/grind/head4/coregrind/valgrind 

This allows you to compile and run with "make" instead of "make install",
saving you time.

Or, you can use the 'vg-in-place' script which does that for you.

I recommend compiling with "make --quiet" to further reduce the amount of
output spewed out during compilation, letting you actually see any errors,
warnings, etc.


Building a distribution tarball
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To build a distribution tarball from the valgrind sources:

  make dist

In addition to compiling, linking and packaging everything up, the command
will also attempt to build the documentation.

If you only want to test whether the generated tarball is complete and runs
regression tests successfully, building documentation is not needed.

  make dist BUILD_ALL_DOCS=no

If you insist on building documentation some embarrassing instructions
can be found in docs/README.


Running the regression tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To build and run all the regression tests, run "make [--quiet] regtest".

To run a subset of the regression tests, execute:

  perl tests/vg_regtest <name>

where <name> is a directory (all tests within will be run) or a single
.vgtest test file, or the name of a program which has a like-named .vgtest
file.  Eg:

  perl tests/vg_regtest memcheck
  perl tests/vg_regtest memcheck/tests/badfree.vgtest
  perl tests/vg_regtest memcheck/tests/badfree


Running the performance tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To build and run all the performance tests, run "make [--quiet] perf".

To run a subset of the performance suite, execute:

  perl perf/vg_perf <name>

where <name> is a directory (all tests within will be run) or a single
.vgperf test file, or the name of a program which has a like-named .vgperf
file.  Eg:

  perl perf/vg_perf perf/
  perl perf/vg_perf perf/bz2.vgperf
  perl perf/vg_perf perf/bz2

To compare multiple versions of Valgrind, use the --vg= option multiple
times.  For example, if you have two Valgrinds next to each other, one in
trunk1/ and one in trunk2/, from within either trunk1/ or trunk2/ do this to
compare them on all the performance tests:

  perl perf/vg_perf --vg=../trunk1 --vg=../trunk2 perf/


Debugging Valgrind with GDB
~~~~~~~~~~~~~~~~~~~~~~~~~~~
To debug the valgrind launcher program (<prefix>/bin/valgrind) just
run it under gdb in the normal way.

Debugging the main body of the valgrind code (and/or the code for
a particular tool) requires a bit more trickery but can be achieved
without too much problem by following these steps:

(1) Set VALGRIND_LAUNCHER to point to the valgrind executable.  Eg:

      export VALGRIND_LAUNCHER=/usr/local/bin/valgrind

    or for an uninstalled version in a source directory $DIR:

      export VALGRIND_LAUNCHER=$DIR/coregrind/valgrind

(2) Run gdb on the tool executable.  Eg:

      gdb /usr/local/lib/valgrind/lackey-ppc32-linux

    or

      gdb $DIR/.in_place/memcheck-x86-linux

(3) Do "handle SIGSEGV SIGILL nostop noprint" in GDB to prevent GDB from
    stopping on a SIGSEGV or SIGILL:

    (gdb) handle SIGILL SIGSEGV nostop noprint

(4) Set any breakpoints you want and proceed as normal for gdb. The
    macro VG_(FUNC) is expanded to vgPlain_FUNC, so If you want to set
    a breakpoint VG_(do_exec), you could do like this in GDB:

    (gdb) b vgPlain_do_exec

(5) Run the tool with required options (the --tool option is required
    for correct setup), e.g.

    (gdb) run --tool=lackey pwd

Steps (1)--(3) can be put in a .gdbinit file, but any directory names must
be fully expanded (ie. not an environment variable).

A different and possibly easier way is as follows:

(1) Run Valgrind as normal, but add the flag --wait-for-gdb=yes.  This
    puts the tool executable into a wait loop soon after it gains
    control.  This delays startup for a few seconds.

(2) In a different shell, do "gdb /proc/<pid>/exe <pid>", where
    <pid> you read from the output printed by (1).  This attaches
    GDB to the tool executable, which should be in the abovementioned
    wait loop.

(3) Do "cont" to continue.  After the loop finishes spinning, startup
    will continue as normal.  Note that comment (3) above re passing
    signals applies here too.


Self-hosting
~~~~~~~~~~~~
This section explains :
  (A) How to configure Valgrind to run under Valgrind.
      Such a setup is called self hosting, or outer/inner setup.
  (B) How to run Valgrind regression tests in a 'self-hosting' mode,
      e.g. to verify Valgrind has no bugs such as memory leaks.
  (C) How to run Valgrind performance tests in a 'self-hosting' mode,
      to analyse and optimise the performance of Valgrind and its tools.

(A) How to configure Valgrind to run under Valgrind:

(1) Check out 2 trees, "Inner" and "Outer".  Inner runs the app
    directly.  Outer runs Inner.

(2) Configure Inner with --enable-inner and build as usual.

(3) Configure Outer normally and build+install as usual.
    Note: You must use a "make install"-ed valgrind.
    Do *not* use vg-in-place for the Outer valgrind.

(4) Choose a very simple program (date) and try

    outer/.../bin/valgrind --sim-hints=enable-outer --trace-children=yes  \
       --smc-check=all-non-file \
       --run-libc-freeres=no --tool=cachegrind -v \
       inner/.../vg-in-place --vgdb-prefix=./inner --tool=none -v prog

If you omit the --trace-children=yes, you'll only monitor Inner's launcher
program, not its stage2. Outer needs --run-libc-freeres=no, as otherwise
it will try to find and run __libc_freeres in the inner, while libc is not
used by the inner. Inner needs --vgdb-prefix=./inner to avoid inner
gdbserver colliding with outer gdbserver.
Currently, inner does *not* use the client request 
VALGRIND_DISCARD_TRANSLATIONS for the JITted code or the code patched for
translation chaining. So the outer needs --smc-check=all-non-file to
detect the modified code.

Debugging the whole thing might imply to use up to 3 GDB:
  * a GDB attached to the Outer valgrind, allowing
    to examine the state of Outer.
  * a GDB using Outer gdbserver, allowing to
    examine the state of Inner.
  * a GDB using Inner gdbserver, allowing to
    examine the state of prog.

The whole thing is fragile, confusing and slow, but it does work well enough
for you to get some useful performance data.  Inner has most of
its output (ie. those lines beginning with "==<pid>==") prefixed with a '>',
which helps a lot. However, when running regression tests in an Outer/Inner
setup, this prefix causes the reg test diff to fail. Give 
--sim-hints=no-inner-prefix to the Inner to disable the production
of the prefix in the stdout/stderr output of Inner.

The allocators in coregrind/m_mallocfree.c and VEX/priv/main_util.h are
annotated with client requests so Memcheck can be used to find leaks
and use after free in an Inner Valgrind.

The Valgrind "big lock" is annotated with helgrind client requests
so Helgrind and DRD can be used to find race conditions in an Inner
Valgrind.

All this has not been tested much, so don't be surprised if you hit problems.

When using self-hosting with an outer Callgrind tool, use '--pop-on-jump'
(on the outer). Otherwise, Callgrind has much higher memory requirements. 

(B) Regression tests in an outer/inner setup:

 To run all the regression tests with an outer memcheck, do :
   perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \
                         --all

 To run a specific regression tests with an outer memcheck, do:
   perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \
                         none/tests/args.vgtest

 To run regression tests with another outer tool:
   perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \
                         --outer-tool=helgrind --all

 --outer-args allows to give specific arguments to the outer tool,
 replacing the default one provided by vg_regtest.

Note: --outer-valgrind must be a "make install"-ed valgrind.
Do *not* use vg-in-place.

When an outer valgrind runs an inner valgrind, a regression test
produces one additional file <testname>.outer.log which contains the
errors detected by the outer valgrind.  E.g. for an outer memcheck, it
contains the leaks found in the inner, for an outer helgrind or drd,
it contains the detected race conditions.

The file tests/outer_inner.supp contains suppressions for 
the irrelevant or benign errors found in the inner.

An regression test running in the inner (e.g. memcheck/tests/badrw) will
cause the inner to report an error, which is expected and checked
as usual when running the regtests in an outer/inner setup.
However, the outer will often also observe an error, e.g. a jump
using uninitialised data, or a read/write outside the bounds of a heap
block. When the outer reports such an error, it will output the
inner host stacktrace. To this stacktrace, it will append the
stacktrace of the inner guest program. For example, this is an error
reported by the outer when the inner runs the badrw regtest:
  ==8119== Invalid read of size 2
  ==8119==    at 0x7F2EFD7AF: ???
  ==8119==    by 0x7F2C82EAF: ???
  ==8119==    by 0x7F180867F: ???
  ==8119==    by 0x40051D: main (badrw.c:5)
  ==8119==    by 0x7F180867F: ???
  ==8119==    by 0x1BFF: ???
  ==8119==    by 0x3803B7F0: _______VVVVVVVV_appended_inner_guest_stack_VVVVVVVV_______ (m_execontext.c:332)
  ==8119==    by 0x40055C: main (badrw.c:22)
  ==8119==  Address 0x55cd03c is 4 bytes before a block of size 16 alloc'd
  ==8119==    at 0x2804E26D: vgPlain_arena_malloc (m_mallocfree.c:1914)
  ==8119==    by 0x2800BAB4: vgMemCheck_new_block (mc_malloc_wrappers.c:368)
  ==8119==    by 0x2800BC87: vgMemCheck_malloc (mc_malloc_wrappers.c:403)
  ==8119==    by 0x28097EAE: do_client_request (scheduler.c:1861)
  ==8119==    by 0x28097EAE: vgPlain_scheduler (scheduler.c:1425)
  ==8119==    by 0x280A7237: thread_wrapper (syswrap-linux.c:103)
  ==8119==    by 0x280A7237: run_a_thread_NORETURN (syswrap-linux.c:156)
  ==8119==    by 0x3803B7F0: _______VVVVVVVV_appended_inner_guest_stack_VVVVVVVV_______ (m_execontext.c:332)
  ==8119==    by 0x4C294C4: malloc (vg_replace_malloc.c:298)
  ==8119==    by 0x40051D: main (badrw.c:5)
In the above, the first stacktrace starts with the inner host stacktrace,
which in this case is some JITted code. Such code sometimes contains IPs
that points in the inner guest code (0x40051D: main (badrw.c:5)).
After the separator, we have the inner guest stacktrace.
The second stacktrace gives the stacktrace where the heap block that was
overrun was allocated. We see it was allocated by the inner valgrind
in the client arena (first part of the stacktrace). The second part is
the guest stacktrace that did the allocation.


(C) Performance tests in an outer/inner setup:

 To run all the performance tests with an outer cachegrind, do :
    perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind perf

 To run a specific perf test (e.g. bz2) in this setup, do :
    perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind perf/bz2

 To run all the performance tests with an outer callgrind, do :
    perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind \
                      --outer-tool=callgrind perf

Note: --outer-valgrind must be a "make install"-ed valgrind.
Do *not* use vg-in-place.

 To compare the performance of multiple Valgrind versions, do :
    perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind \
      --outer-tool=callgrind \
      --vg=../inner_xxxx --vg=../inner_yyyy perf
  (where inner_xxxx and inner_yyyy are the toplevel directories of
  the versions to compare).
  Cachegrind and cg_diff are particularly handy to obtain a delta
  between the two versions.

When the outer tool is callgrind or cachegrind, the following
output files will be created for each test:
   <outertoolname>.out.<inner_valgrind_dir>.<tt>.<perftestname>.<pid>
   <outertoolname>.outer.log.<inner_valgrind_dir>.<tt>.<perftestname>.<pid>
 (where tt is the two letters abbreviation for the inner tool(s) run).

For example, the command
    perl perf/vg_perf \
      --outer-valgrind=../outer_trunk/install/bin/valgrind \
      --outer-tool=callgrind \
      --vg=../inner_tchain --vg=../inner_trunk perf/many-loss-records

produces the files
    callgrind.out.inner_tchain.no.many-loss-records.18465
    callgrind.outer.log.inner_tchain.no.many-loss-records.18465
    callgrind.out.inner_tchain.me.many-loss-records.21899
    callgrind.outer.log.inner_tchain.me.many-loss-records.21899
    callgrind.out.inner_trunk.no.many-loss-records.21224
    callgrind.outer.log.inner_trunk.no.many-loss-records.21224
    callgrind.out.inner_trunk.me.many-loss-records.22916
    callgrind.outer.log.inner_trunk.me.many-loss-records.22916


Printing out problematic blocks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you want to print out a disassembly of a particular block that
causes a crash, do the following.

Try running with "--vex-guest-chase-thresh=0 --trace-flags=10000000
--trace-notbelow=999999".  This should print one line for each block
translated, and that includes the address.

Then re-run with 999999 changed to the highest bb number shown.
This will print the one line per block, and also will print a
disassembly of the block in which the fault occurred.