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 attempt to build the documentation. 28 29 If you only want to test whether the generated tarball is complete and runs 30 regression tests successfully, building documentation is not needed. 31 32 make dist BUILD_ALL_DOCS=no 33 34 If you insist on building documentation some embarrassing instructions 35 can be found in docs/README. 36 37 38 Running the regression tests 39 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 40 To build and run all the regression tests, run "make [--quiet] regtest". 41 42 To run a subset of the regression tests, execute: 43 44 perl tests/vg_regtest <name> 45 46 where <name> is a directory (all tests within will be run) or a single 47 .vgtest test file, or the name of a program which has a like-named .vgtest 48 file. Eg: 49 50 perl tests/vg_regtest memcheck 51 perl tests/vg_regtest memcheck/tests/badfree.vgtest 52 perl tests/vg_regtest memcheck/tests/badfree 53 54 55 Running the performance tests 56 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 57 To build and run all the performance tests, run "make [--quiet] perf". 58 59 To run a subset of the performance suite, execute: 60 61 perl perf/vg_perf <name> 62 63 where <name> is a directory (all tests within will be run) or a single 64 .vgperf test file, or the name of a program which has a like-named .vgperf 65 file. Eg: 66 67 perl perf/vg_perf perf/ 68 perl perf/vg_perf perf/bz2.vgperf 69 perl perf/vg_perf perf/bz2 70 71 To compare multiple versions of Valgrind, use the --vg= option multiple 72 times. For example, if you have two Valgrinds next to each other, one in 73 trunk1/ and one in trunk2/, from within either trunk1/ or trunk2/ do this to 74 compare them on all the performance tests: 75 76 perl perf/vg_perf --vg=../trunk1 --vg=../trunk2 perf/ 77 78 79 Debugging Valgrind with GDB 80 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 81 To debug the valgrind launcher program (<prefix>/bin/valgrind) just 82 run it under gdb in the normal way. 83 84 Debugging the main body of the valgrind code (and/or the code for 85 a particular tool) requires a bit more trickery but can be achieved 86 without too much problem by following these steps: 87 88 (1) Set VALGRIND_LAUNCHER to point to the valgrind executable. Eg: 89 90 export VALGRIND_LAUNCHER=/usr/local/bin/valgrind 91 92 or for an uninstalled version in a source directory $DIR: 93 94 export VALGRIND_LAUNCHER=$DIR/coregrind/valgrind 95 96 (2) Run gdb on the tool executable. Eg: 97 98 gdb /usr/local/lib/valgrind/ppc32-linux/lackey 99 100 or 101 102 gdb $DIR/.in_place/x86-linux/memcheck 103 104 (3) Do "handle SIGSEGV SIGILL nostop noprint" in GDB to prevent GDB from 105 stopping on a SIGSEGV or SIGILL: 106 107 (gdb) handle SIGILL SIGSEGV nostop noprint 108 109 (4) Set any breakpoints you want and proceed as normal for gdb. The 110 macro VG_(FUNC) is expanded to vgPlain_FUNC, so If you want to set 111 a breakpoint VG_(do_exec), you could do like this in GDB: 112 113 (gdb) b vgPlain_do_exec 114 115 (5) Run the tool with required options (the --tool option is required 116 for correct setup), e.g. 117 118 (gdb) run --tool=lackey pwd 119 120 Steps (1)--(3) can be put in a .gdbinit file, but any directory names must 121 be fully expanded (ie. not an environment variable). 122 123 A different and possibly easier way is as follows: 124 125 (1) Run Valgrind as normal, but add the flag --wait-for-gdb=yes. This 126 puts the tool executable into a wait loop soon after it gains 127 control. This delays startup for a few seconds. 128 129 (2) In a different shell, do "gdb /proc/<pid>/exe <pid>", where 130 <pid> you read from the output printed by (1). This attaches 131 GDB to the tool executable, which should be in the abovementioned 132 wait loop. 133 134 (3) Do "cont" to continue. After the loop finishes spinning, startup 135 will continue as normal. Note that comment (3) above re passing 136 signals applies here too. 137 138 139 Self-hosting 140 ~~~~~~~~~~~~ 141 This section explains : 142 (A) How to configure Valgrind to run under Valgrind. 143 Such a setup is called self hosting, or outer/inner setup. 144 (B) How to run Valgrind regression tests in a 'self-hosting' mode, 145 e.g. to verify Valgrind has no bugs such as memory leaks. 146 (C) How to run Valgrind performance tests in a 'self-hosting' mode, 147 to analyse and optimise the performance of Valgrind and its tools. 148 149 (A) How to configure Valgrind to run under Valgrind: 150 151 (1) Check out 2 trees, "Inner" and "Outer". Inner runs the app 152 directly. Outer runs Inner. 153 154 (2) Configure inner with --enable-inner and build/install as usual. 155 156 (3) Configure Outer normally and build/install as usual. 157 158 (4) Choose a very simple program (date) and try 159 160 outer/.../bin/valgrind --sim-hints=enable-outer --trace-children=yes \ 161 --smc-check=all-non-file \ 162 --run-libc-freeres=no --tool=cachegrind -v \ 163 inner/.../bin/valgrind --vgdb-prefix=./inner --tool=none -v prog 164 165 Note: You must use a "make install"-ed valgrind. 166 Do *not* use vg-in-place for the outer valgrind. 167 168 If you omit the --trace-children=yes, you'll only monitor Inner's launcher 169 program, not its stage2. Outer needs --run-libc-freeres=no, as otherwise 170 it will try to find and run __libc_freeres in the inner, while libc is not 171 used by the inner. Inner needs --vgdb-prefix=./inner to avoid inner 172 gdbserver colliding with outer gdbserver. 173 Currently, inner does *not* use the client request 174 VALGRIND_DISCARD_TRANSLATIONS for the JITted code or the code patched for 175 translation chaining. So the outer needs --smc-check=all-non-file to 176 detect the modified code. 177 178 Debugging the whole thing might imply to use up to 3 GDB: 179 * a GDB attached to the Outer valgrind, allowing 180 to examine the state of Outer. 181 * a GDB using Outer gdbserver, allowing to 182 examine the state of Inner. 183 * a GDB using Inner gdbserver, allowing to 184 examine the state of prog. 185 186 The whole thing is fragile, confusing and slow, but it does work well enough 187 for you to get some useful performance data. Inner has most of 188 its output (ie. those lines beginning with "==<pid>==") prefixed with a '>', 189 which helps a lot. However, when running regression tests in an Outer/Inner 190 setup, this prefix causes the reg test diff to fail. Give 191 --sim-hints=no-inner-prefix to the Inner to disable the production 192 of the prefix in the stdout/stderr output of Inner. 193 194 The allocator (coregrind/m_mallocfree.c) is annotated with client requests 195 so Memcheck can be used to find leaks and use after free in an Inner 196 Valgrind. 197 198 The Valgrind "big lock" is annotated with helgrind client requests 199 so helgrind and drd can be used to find race conditions in an Inner 200 Valgrind. 201 202 All this has not been tested much, so don't be surprised if you hit problems. 203 204 When using self-hosting with an outer Callgrind tool, use '--pop-on-jump' 205 (on the outer). Otherwise, Callgrind has much higher memory requirements. 206 207 (B) Regression tests in an outer/inner setup: 208 209 To run all the regression tests with an outer memcheck, do : 210 perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \ 211 --all 212 213 To run a specific regression tests with an outer memcheck, do: 214 perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \ 215 none/tests/args.vgtest 216 217 To run regression tests with another outer tool: 218 perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \ 219 --outer-tool=helgrind --all 220 221 --outer-args allows to give specific arguments to the outer tool, 222 replacing the default one provided by vg_regtest. 223 224 Note: --outer-valgrind must be a "make install"-ed valgrind. 225 Do *not* use vg-in-place. 226 227 When an outer valgrind runs an inner valgrind, a regression test 228 produces one additional file <testname>.outer.log which contains the 229 errors detected by the outer valgrind. E.g. for an outer memcheck, it 230 contains the leaks found in the inner, for an outer helgrind or drd, 231 it contains the detected race conditions. 232 233 The file tests/outer_inner.supp contains suppressions for 234 the irrelevant or benign errors found in the inner. 235 236 An regression test running in the inner (e.g. memcheck/tests/badrw) will 237 cause the inner to report an error, which is expected and checked 238 as usual when running the regtests in an outer/inner setup. 239 However, the outer will often also observe an error, e.g. a jump 240 using uninitialised data, or a read/write outside the bounds of a heap 241 block. When the outer reports such an error, it will output the 242 inner host stacktrace. To this stacktrace, it will append the 243 stacktrace of the inner guest program. For example, this is an error 244 reported by the outer when the inner runs the badrw regtest: 245 ==8119== Invalid read of size 2 246 ==8119== at 0x7F2EFD7AF: ??? 247 ==8119== by 0x7F2C82EAF: ??? 248 ==8119== by 0x7F180867F: ??? 249 ==8119== by 0x40051D: main (badrw.c:5) 250 ==8119== by 0x7F180867F: ??? 251 ==8119== by 0x1BFF: ??? 252 ==8119== by 0x3803B7F0: _______VVVVVVVV_appended_inner_guest_stack_VVVVVVVV_______ (m_execontext.c:332) 253 ==8119== by 0x40055C: main (badrw.c:22) 254 ==8119== Address 0x55cd03c is 4 bytes before a block of size 16 alloc'd 255 ==8119== at 0x2804E26D: vgPlain_arena_malloc (m_mallocfree.c:1914) 256 ==8119== by 0x2800BAB4: vgMemCheck_new_block (mc_malloc_wrappers.c:368) 257 ==8119== by 0x2800BC87: vgMemCheck_malloc (mc_malloc_wrappers.c:403) 258 ==8119== by 0x28097EAE: do_client_request (scheduler.c:1861) 259 ==8119== by 0x28097EAE: vgPlain_scheduler (scheduler.c:1425) 260 ==8119== by 0x280A7237: thread_wrapper (syswrap-linux.c:103) 261 ==8119== by 0x280A7237: run_a_thread_NORETURN (syswrap-linux.c:156) 262 ==8119== by 0x3803B7F0: _______VVVVVVVV_appended_inner_guest_stack_VVVVVVVV_______ (m_execontext.c:332) 263 ==8119== by 0x4C294C4: malloc (vg_replace_malloc.c:298) 264 ==8119== by 0x40051D: main (badrw.c:5) 265 In the above, the first stacktrace starts with the inner host stacktrace, 266 which in this case is some JITted code. Such code sometimes contains IPs 267 that points in the inner guest code (0x40051D: main (badrw.c:5)). 268 After the separator, we have the inner guest stacktrace. 269 The second stacktrace gives the stacktrace where the heap block that was 270 overrun was allocated. We see it was allocated by the inner valgrind 271 in the client arena (first part of the stacktrace). The second part is 272 the guest stacktrace that did the allocation. 273 274 275 (C) Performance tests in an outer/inner setup: 276 277 To run all the performance tests with an outer cachegrind, do : 278 perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind perf 279 280 To run a specific perf test (e.g. bz2) in this setup, do : 281 perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind perf/bz2 282 283 To run all the performance tests with an outer callgrind, do : 284 perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind \ 285 --outer-tool=callgrind perf 286 287 Note: --outer-valgrind must be a "make install"-ed valgrind. 288 Do *not* use vg-in-place. 289 290 To compare the performance of multiple Valgrind versions, do : 291 perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind \ 292 --outer-tool=callgrind \ 293 --vg=../inner_xxxx --vg=../inner_yyyy perf 294 (where inner_xxxx and inner_yyyy are the toplevel directories of 295 the versions to compare). 296 Cachegrind and cg_diff are particularly handy to obtain a delta 297 between the two versions. 298 299 When the outer tool is callgrind or cachegrind, the following 300 output files will be created for each test: 301 <outertoolname>.out.<inner_valgrind_dir>.<tt>.<perftestname>.<pid> 302 <outertoolname>.outer.log.<inner_valgrind_dir>.<tt>.<perftestname>.<pid> 303 (where tt is the two letters abbreviation for the inner tool(s) run). 304 305 For example, the command 306 perl perf/vg_perf \ 307 --outer-valgrind=../outer_trunk/install/bin/valgrind \ 308 --outer-tool=callgrind \ 309 --vg=../inner_tchain --vg=../inner_trunk perf/many-loss-records 310 311 produces the files 312 callgrind.out.inner_tchain.no.many-loss-records.18465 313 callgrind.outer.log.inner_tchain.no.many-loss-records.18465 314 callgrind.out.inner_tchain.me.many-loss-records.21899 315 callgrind.outer.log.inner_tchain.me.many-loss-records.21899 316 callgrind.out.inner_trunk.no.many-loss-records.21224 317 callgrind.outer.log.inner_trunk.no.many-loss-records.21224 318 callgrind.out.inner_trunk.me.many-loss-records.22916 319 callgrind.outer.log.inner_trunk.me.many-loss-records.22916 320 321 322 Printing out problematic blocks 323 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 324 If you want to print out a disassembly of a particular block that 325 causes a crash, do the following. 326 327 Try running with "--vex-guest-chase-thresh=0 --trace-flags=10000000 328 --trace-notbelow=999999". This should print one line for each block 329 translated, and that includes the address. 330 331 Then re-run with 999999 changed to the highest bb number shown. 332 This will print the one line per block, and also will print a 333 disassembly of the block in which the fault occurred. 334
