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 Note: You must use a "make install"-ed valgrind. 165 Do *not* use vg-in-place for the outer valgrind. 166 167 If you omit the --trace-children=yes, you'll only monitor Inner's launcher 168 program, not its stage2. Outer needs --run-libc-freeres=no, as otherwise 169 it will try to find and run __libc_freeres in the inner, while libc is not 170 used by the inner. Inner needs --vgdb-prefix=./inner to avoid inner 171 gdbserver colliding with outer gdbserver. 172 Currently, inner does *not* use the client request 173 VALGRIND_DISCARD_TRANSLATIONS for the JITted code or the code patched for 174 translation chaining. So the outer needs --smc-check=all-non-file to 175 detect the modified code. 176 177 Debugging the whole thing might imply to use up to 3 GDB: 178 * a GDB attached to the Outer valgrind, allowing 179 to examine the state of Outer. 180 * a GDB using Outer gdbserver, allowing to 181 examine the state of Inner. 182 * a GDB using Inner gdbserver, allowing to 183 examine the state of prog. 184 185 The whole thing is fragile, confusing and slow, but it does work well enough 186 for you to get some useful performance data. Inner has most of 187 its output (ie. those lines beginning with "==<pid>==") prefixed with a '>', 188 which helps a lot. However, when running regression tests in an Outer/Inner 189 setup, this prefix causes the reg test diff to fail. Give 190 --sim-hints=no-inner-prefix to the Inner to disable the production 191 of the prefix in the stdout/stderr output of Inner. 192 193 The allocator (coregrind/m_mallocfree.c) is annotated with client requests 194 so Memcheck can be used to find leaks and use after free in an Inner 195 Valgrind. 196 197 The Valgrind "big lock" is annotated with helgrind client requests 198 so helgrind and drd can be used to find race conditions in an Inner 199 Valgrind. 200 201 All this has not been tested much, so don't be surprised if you hit problems. 202 203 When using self-hosting with an outer Callgrind tool, use '--pop-on-jump' 204 (on the outer). Otherwise, Callgrind has much higher memory requirements. 205 206 (B) Regression tests in an outer/inner setup: 207 208 To run all the regression tests with an outer memcheck, do : 209 perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \ 210 --all 211 212 To run a specific regression tests with an outer memcheck, do: 213 perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \ 214 none/tests/args.vgtest 215 216 To run regression tests with another outer tool: 217 perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \ 218 --outer-tool=helgrind --all 219 220 --outer-args allows to give specific arguments to the outer tool, 221 replacing the default one provided by vg_regtest. 222 223 Note: --outer-valgrind must be a "make install"-ed valgrind. 224 Do *not* use vg-in-place. 225 226 When an outer valgrind runs an inner valgrind, a regression test 227 produces one additional file <testname>.outer.log which contains the 228 errors detected by the outer valgrind. E.g. for an outer memcheck, it 229 contains the leaks found in the inner, for an outer helgrind or drd, 230 it contains the detected race conditions. 231 232 The file tests/outer_inner.supp contains suppressions for 233 the irrelevant or benign errors found in the inner. 234 235 (C) Performance tests in an outer/inner setup: 236 237 To run all the performance tests with an outer cachegrind, do : 238 perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind perf 239 240 To run a specific perf test (e.g. bz2) in this setup, do : 241 perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind perf/bz2 242 243 To run all the performance tests with an outer callgrind, do : 244 perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind \ 245 --outer-tool=callgrind perf 246 247 Note: --outer-valgrind must be a "make install"-ed valgrind. 248 Do *not* use vg-in-place. 249 250 To compare the performance of multiple Valgrind versions, do : 251 perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind \ 252 --vg=../inner_xxxx --vg=../inner_yyyy perf 253 (where inner_xxxx and inner_yyyy are the toplevel directories of 254 the versions to compare). 255 Cachegrind and cg_diff are particularly handy to obtain a delta 256 between the two versions. 257 258 When the outer tool is callgrind or cachegrind, the following 259 output files will be created for each test: 260 <outertoolname>.out.<inner_valgrind_dir>.<tt>.<perftestname>.<pid> 261 <outertoolname>.outer.log.<inner_valgrind_dir>.<tt>.<perftestname>.<pid> 262 (where tt is the two letters abbreviation for the inner tool(s) run). 263 264 For example, the command 265 perl perf/vg_perf \ 266 --outer-valgrind=../outer_trunk/install/bin/valgrind \ 267 --outer-tool=callgrind \ 268 --vg=../inner_tchain --vg=../inner_trunk perf/many-loss-records 269 270 produces the files 271 callgrind.out.inner_tchain.no.many-loss-records.18465 272 callgrind.outer.log.inner_tchain.no.many-loss-records.18465 273 callgrind.out.inner_tchain.me.many-loss-records.21899 274 callgrind.outer.log.inner_tchain.me.many-loss-records.21899 275 callgrind.out.inner_trunk.no.many-loss-records.21224 276 callgrind.outer.log.inner_trunk.no.many-loss-records.21224 277 callgrind.out.inner_trunk.me.many-loss-records.22916 278 callgrind.outer.log.inner_trunk.me.many-loss-records.22916 279 280 281 Printing out problematic blocks 282 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 283 If you want to print out a disassembly of a particular block that 284 causes a crash, do the following. 285 286 Try running with "--vex-guest-chase-thresh=0 --trace-flags=10000000 287 --trace-notbelow=999999". This should print one line for each block 288 translated, and that includes the address. 289 290 Then re-run with 999999 changed to the highest bb number shown. 291 This will print the one line per block, and also will print a 292 disassembly of the block in which the fault occurred. 293
