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:
8 VALGRIND_LIB=~/grind/head4/.in_place ~/grind/head4/coregrind/valgrind
10 This allows you to compile and run with "make" instead of "make install",
13 Or, you can use the 'vg-in-place' script which does that for you.
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,
20 Building a distribution tarball
21 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
22 To build a distribution tarball from the valgrind sources:
26 In addition to compiling, linking and packaging everything up, the command
27 will also attempt to build the documentation.
29 If you only want to test whether the generated tarball is complete and runs
30 regression tests successfully, building documentation is not needed.
32 make dist BUILD_ALL_DOCS=no
34 If you insist on building documentation some embarrassing instructions
35 can be found in docs/README.
38 Running the regression tests
39 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
40 To build and run all the regression tests, run "make [--quiet] regtest".
42 To run a subset of the regression tests, execute:
44 perl tests/vg_regtest <name>
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
50 perl tests/vg_regtest memcheck
51 perl tests/vg_regtest memcheck/tests/badfree.vgtest
52 perl tests/vg_regtest memcheck/tests/badfree
55 Running the performance tests
56 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
57 To build and run all the performance tests, run "make [--quiet] perf".
59 To run a subset of the performance suite, execute:
61 perl perf/vg_perf <name>
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
67 perl perf/vg_perf perf/
68 perl perf/vg_perf perf/bz2.vgperf
69 perl perf/vg_perf perf/bz2
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:
76 perl perf/vg_perf --vg=../trunk1 --vg=../trunk2 perf/
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.
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:
88 (1) Set VALGRIND_LAUNCHER to point to the valgrind executable. Eg:
90 export VALGRIND_LAUNCHER=/usr/local/bin/valgrind
92 or for an uninstalled version in a source directory $DIR:
94 export VALGRIND_LAUNCHER=$DIR/coregrind/valgrind
96 (2) Run gdb on the tool executable. Eg:
98 gdb /usr/local/lib/valgrind/ppc32-linux/lackey
102 gdb $DIR/.in_place/x86-linux/memcheck
104 (3) Do "handle SIGSEGV SIGILL nostop noprint" in GDB to prevent GDB from
105 stopping on a SIGSEGV or SIGILL:
107 (gdb) handle SIGILL SIGSEGV nostop noprint
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:
113 (gdb) b vgPlain_do_exec
115 (5) Run the tool with required options (the --tool option is required
116 for correct setup), e.g.
118 (gdb) run --tool=lackey pwd
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).
123 A different and possibly easier way is as follows:
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.
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
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.
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.
149 (A) How to configure Valgrind to run under Valgrind:
151 (1) Check out 2 trees, "Inner" and "Outer". Inner runs the app
152 directly. Outer runs Inner.
154 (2) Configure inner with --enable-inner and build/install as usual.
156 (3) Configure Outer normally and build/install as usual.
158 (4) Choose a very simple program (date) and try
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
165 Note: You must use a "make install"-ed valgrind.
166 Do *not* use vg-in-place for the outer valgrind.
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.
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.
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.
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
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
202 All this has not been tested much, so don't be surprised if you hit problems.
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.
207 (B) Regression tests in an outer/inner setup:
209 To run all the regression tests with an outer memcheck, do :
210 perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \
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
217 To run regression tests with another outer tool:
218 perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \
219 --outer-tool=helgrind --all
221 --outer-args allows to give specific arguments to the outer tool,
222 replacing the default one provided by vg_regtest.
224 Note: --outer-valgrind must be a "make install"-ed valgrind.
225 Do *not* use vg-in-place.
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.
233 The file tests/outer_inner.supp contains suppressions for
234 the irrelevant or benign errors found in the inner.
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.
275 (C) Performance tests in an outer/inner setup:
277 To run all the performance tests with an outer cachegrind, do :
278 perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind perf
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
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
287 Note: --outer-valgrind must be a "make install"-ed valgrind.
288 Do *not* use vg-in-place.
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.
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).
305 For example, the command
307 --outer-valgrind=../outer_trunk/install/bin/valgrind \
308 --outer-tool=callgrind \
309 --vg=../inner_tchain --vg=../inner_trunk perf/many-loss-records
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
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.
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.
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.