README_DEVELOPERS

   1
   2 Building and not installing it
   3 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   4 To run Valgrind without having to install it, run coregrind/valgrind
   5 with the VALGRIND_LIB environment variable set, where <dir> is the root
   6 of the source tree (and must be an absolute path).  Eg:
   7
   8   VALGRIND_LIB=~/grind/head4/.in_place ~/grind/head4/coregrind/valgrind
   9
  10 This allows you to compile and run with "make" instead of "make install",
  11 saving you time.
  12
  13 Or, you can use the 'vg-in-place' script which does that for you.
  14
  15 I recommend compiling with "make --quiet" to further reduce the amount of
  16 output spewed out during compilation, letting you actually see any errors,
  17 warnings, etc.
  18
  19
  20 Building a distribution tarball
  21 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  22 To build a distribution tarball from the valgrind sources:
  23
  24   make dist
  25
  26 In addition to compiling, linking and packaging everything up, the command
  27 will also build the documentation. Even if all required tools for building the
  28 documentation are installed, this step may not succeed because of hidden
  29 dependencies. E.g. on Ubuntu you must have "docbook-xsl" installed.
  30 Additionally, specific tool versions maybe needed.
  31
  32 If you only want to test whether the generated tarball is complete and runs
  33 regression tests successfully, building documentation is not needed.
  34 Edit docs/Makefile.am, search for BUILD_ALL_DOCS and follow instructions there.
  35
  36
  37 Running the regression tests
  38 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  39 To build and run all the regression tests, run "make [--quiet] regtest".
  40
  41 To run a subset of the regression tests, execute:
  42
  43   perl tests/vg_regtest <name>
  44
  45 where <name> is a directory (all tests within will be run) or a single
  46 .vgtest test file, or the name of a program which has a like-named .vgtest
  47 file.  Eg:
  48
  49   perl tests/vg_regtest memcheck
  50   perl tests/vg_regtest memcheck/tests/badfree.vgtest
  51   perl tests/vg_regtest memcheck/tests/badfree
  52
  53
  54 Running the performance tests
  55 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  56 To build and run all the performance tests, run "make [--quiet] perf".
  57
  58 To run a subset of the performance suite, execute:
  59
  60   perl perf/vg_perf <name>
  61
  62 where <name> is a directory (all tests within will be run) or a single
  63 .vgperf test file, or the name of a program which has a like-named .vgperf
  64 file.  Eg:
  65
  66   perl perf/vg_perf perf/
  67   perl perf/vg_perf perf/bz2.vgperf
  68   perl perf/vg_perf perf/bz2
  69
  70 To compare multiple versions of Valgrind, use the --vg= option multiple
  71 times.  For example, if you have two Valgrinds next to each other, one in
  72 trunk1/ and one in trunk2/, from within either trunk1/ or trunk2/ do this to
  73 compare them on all the performance tests:
  74
  75   perl perf/vg_perf --vg=../trunk1 --vg=../trunk2 perf/
  76
  77
  78 Debugging Valgrind with GDB
  79 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  80 To debug the valgrind launcher program (<prefix>/bin/valgrind) just
  81 run it under gdb in the normal way.
  82
  83 Debugging the main body of the valgrind code (and/or the code for
  84 a particular tool) requires a bit more trickery but can be achieved
  85 without too much problem by following these steps:
  86
  87 (1) Set VALGRIND_LAUNCHER to point to the valgrind executable.  Eg:
  88
  89       export VALGRIND_LAUNCHER=/usr/local/bin/valgrind
  90
  91     or for an uninstalled version in a source directory $DIR:
  92
  93       export VALGRIND_LAUNCHER=$DIR/coregrind/valgrind
  94
  95 (2) Run gdb on the tool executable.  Eg:
  96
  97       gdb /usr/local/lib/valgrind/ppc32-linux/lackey
  98
  99     or
 100
 101       gdb $DIR/.in_place/x86-linux/memcheck
 102
 103 (3) Do "handle SIGSEGV SIGILL nostop noprint" in GDB to prevent GDB from
 104     stopping on a SIGSEGV or SIGILL:
 105
 106     (gdb) handle SIGILL SIGSEGV nostop noprint
 107
 108 (4) Set any breakpoints you want and proceed as normal for gdb. The
 109     macro VG_(FUNC) is expanded to vgPlain_FUNC, so If you want to set
 110     a breakpoint VG_(do_exec), you could do like this in GDB:
 111
 112     (gdb) b vgPlain_do_exec
 113
 114 (5) Run the tool with required options (the --tool option is required
 115     for correct setup), e.g.
 116
 117     (gdb) run --tool=lackey pwd
 118
 119 Steps (1)--(3) can be put in a .gdbinit file, but any directory names must
 120 be fully expanded (ie. not an environment variable).
 121
 122 A different and possibly easier way is as follows:
 123
 124 (1) Run Valgrind as normal, but add the flag --wait-for-gdb=yes.  This
 125     puts the tool executable into a wait loop soon after it gains
 126     control.  This delays startup for a few seconds.
 127
 128 (2) In a different shell, do "gdb /proc/<pid>/exe <pid>", where
 129     <pid> you read from the output printed by (1).  This attaches
 130     GDB to the tool executable, which should be in the abovementioned
 131     wait loop.
 132
 133 (3) Do "cont" to continue.  After the loop finishes spinning, startup
 134     will continue as normal.  Note that comment (3) above re passing
 135     signals applies here too.
 136
 137
 138 Self-hosting
 139 ~~~~~~~~~~~~
 140 This section explains :
 141   (A) How to configure Valgrind to run under Valgrind.
 142       Such a setup is called self hosting, or outer/inner setup.
 143   (B) How to run Valgrind regression tests in a 'self-hosting' mode,
 144       e.g. to verify Valgrind has no bugs such as memory leaks.
 145   (C) How to run Valgrind performance tests in a 'self-hosting' mode,
 146       to analyse and optimise the performance of Valgrind and its tools.
 147
 148 (A) How to configure Valgrind to run under Valgrind:
 149
 150 (1) Check out 2 trees, "Inner" and "Outer".  Inner runs the app
 151     directly.  Outer runs Inner.
 152
 153 (2) Configure inner with --enable-inner and build/install as usual.
 154
 155 (3) Configure Outer normally and build/install as usual.
 156
 157 (4) Choose a very simple program (date) and try
 158
 159     outer/.../bin/valgrind --sim-hints=enable-outer --trace-children=yes  \
 160        --smc-check=all-non-file \
 161        --run-libc-freeres=no --tool=cachegrind -v \
 162        inner/.../bin/valgrind --vgdb-prefix=./inner --tool=none -v prog
 163
 164 If you omit the --trace-children=yes, you'll only monitor Inner's launcher
 165 program, not its stage2. Outer needs --run-libc-freeres=no, as otherwise
 166 it will try to find and run __libc_freeres in the inner, while libc is not
 167 used by the inner. Inner needs --vgdb-prefix=./inner to avoid inner
 168 gdbserver colliding with outer gdbserver.
 169 Currently, inner does *not* use the client request
 170 VALGRIND_DISCARD_TRANSLATIONS for the JITted code or the code patched for
 171 translation chaining. So the outer needs --smc-check=all-non-file to
 172 detect the modified code.
 173
 174 Debugging the whole thing might imply to use up to 3 GDB:
 175   * a GDB attached to the Outer valgrind, allowing
 176     to examine the state of Outer.
 177   * a GDB using Outer gdbserver, allowing to
 178     examine the state of Inner.
 179   * a GDB using Inner gdbserver, allowing to
 180     examine the state of prog.
 181
 182 The whole thing is fragile, confusing and slow, but it does work well enough
 183 for you to get some useful performance data.  Inner has most of
 184 its output (ie. those lines beginning with "==<pid>==") prefixed with a '>',
 185 which helps a lot. However, when running regression tests in an Outer/Inner
 186 setup, this prefix causes the reg test diff to fail. Give
 187 --sim-hints=no-inner-prefix to the Inner to disable the production
 188 of the prefix in the stdout/stderr output of Inner.
 189
 190 The allocator (coregrind/m_mallocfree.c) is annotated with client requests
 191 so Memcheck can be used to find leaks and use after free in an Inner
 192 Valgrind.
 193
 194 The Valgrind "big lock" is annotated with helgrind client requests
 195 so helgrind and drd can be used to find race conditions in an Inner
 196 Valgrind.
 197
 198 All this has not been tested much, so don't be surprised if you hit problems.
 199
 200 When using self-hosting with an outer Callgrind tool, use '--pop-on-jump'
 201 (on the outer). Otherwise, Callgrind has much higher memory requirements.
 202
 203 (B) Regression tests in an outer/inner setup:
 204
 205  To run all the regression tests with an outer memcheck, do :
 206    perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \
 207                          --all
 208
 209  To run a specific regression tests with an outer memcheck, do:
 210    perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \
 211                          none/tests/args.vgtest
 212
 213  To run regression tests with another outer tool:
 214    perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \
 215                          --outer-tool=helgrind --all
 216
 217  --outer-args allows to give specific arguments to the outer tool,
 218  replacing the default one provided by vg_regtest.
 219
 220 When an outer valgrind runs an inner valgrind, a regression test
 221 produces one additional file <testname>.outer.log which contains the
 222 errors detected by the outer valgrind.  E.g. for an outer memcheck, it
 223 contains the leaks found in the inner, for an outer helgrind or drd,
 224 it contains the detected race conditions.
 225
 226 The file tests/outer_inner.supp contains suppressions for
 227 the irrelevant or benign errors found in the inner.
 228
 229 (C) Performance tests in an outer/inner setup:
 230
 231  To run all the performance tests with an outer cachegrind, do :
 232     perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind perf
 233
 234  To run a specific perf test (e.g. bz2) in this setup, do :
 235     perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind perf/bz2
 236
 237  To run all the performance tests with an outer callgrind, do :
 238     perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind \
 239                       --outer-tool=callgrind perf
 240
 241  To compare the performance of multiple Valgrind versions, do :
 242     perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind \
 243       --vg=../inner_xxxx --vg=../inner_yyyy perf
 244   (where inner_xxxx and inner_yyyy are the versions to compare).
 245   Cachegrind and cg_diff are particularly handy to obtain a delta
 246   between the two versions.
 247
 248 When the outer tool is callgrind or cachegrind, the following
 249 output files will be created for each test:
 250    <outertoolname>.out.<inner_valgrind_dir>.<tt>.<perftestname>.<pid>
 251    <outertoolname>.outer.log.<inner_valgrind_dir>.<tt>.<perftestname>.<pid>
 252  (where tt is the two letters abbreviation for the inner tool(s) run).
 253
 254 For example, the command
 255     perl perf/vg_perf \
 256       --outer-valgrind=../outer_trunk/install/bin/valgrind \
 257       --outer-tool=callgrind \
 258       --vg=../inner_tchain --vg=../inner_trunk perf/many-loss-records
 259
 260 produces the files
 261     callgrind.out.inner_tchain.no.many-loss-records.18465
 262     callgrind.outer.log.inner_tchain.no.many-loss-records.18465
 263     callgrind.out.inner_tchain.me.many-loss-records.21899
 264     callgrind.outer.log.inner_tchain.me.many-loss-records.21899
 265     callgrind.out.inner_trunk.no.many-loss-records.21224
 266     callgrind.outer.log.inner_trunk.no.many-loss-records.21224
 267     callgrind.out.inner_trunk.me.many-loss-records.22916
 268     callgrind.outer.log.inner_trunk.me.many-loss-records.22916
 269
 270
 271 Printing out problematic blocks
 272 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 273 If you want to print out a disassembly of a particular block that
 274 causes a crash, do the following.
 275
 276 Try running with "--vex-guest-chase-thresh=0 --trace-flags=10000000
 277 --trace-notbelow=999999".  This should print one line for each block
 278 translated, and that includes the address.
 279
 280 Then re-run with 999999 changed to the highest bb number shown.
 281 This will print the one line per block, and also will print a
 282 disassembly of the block in which the fault occurred.