1 Building and installing it
2 ~~~~~~~~~~~~~~~~~~~~~~~~~~
3 To build/install from the GIT repository or from a distribution
4 tarball, refer to the section with the same name in README.
6 Building and not installing it
7 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
8 To run Valgrind without having to install it, run coregrind/valgrind
9 with the VALGRIND_LIB environment variable set, where <dir> is the root
10 of the source tree (and must be an absolute path). Eg:
12 VALGRIND_LIB=~/grind/head4/.in_place ~/grind/head4/coregrind/valgrind
14 This allows you to compile and run with "make" instead of "make install",
17 Or, you can use the 'vg-in-place' script which does that for you.
19 I recommend compiling with "make --quiet" to further reduce the amount of
20 output spewed out during compilation, letting you actually see any errors,
24 Building a distribution tarball
25 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
26 To build a distribution tarball from the valgrind sources:
30 In addition to compiling, linking and packaging everything up, the command
31 will also attempt to build the documentation.
33 If you only want to test whether the generated tarball is complete and runs
34 regression tests successfully, building documentation is not needed.
36 make dist BUILD_ALL_DOCS=no
38 If you insist on building documentation some embarrassing instructions
39 can be found in docs/README.
42 Running the regression tests
43 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
44 To build and run all the regression tests, run "make [--quiet] regtest".
46 To run a subset of the regression tests, execute:
48 perl tests/vg_regtest <name>
50 where <name> is a directory (all tests within will be run) or a single
51 .vgtest test file, or the name of a program which has a like-named .vgtest
54 perl tests/vg_regtest memcheck
55 perl tests/vg_regtest memcheck/tests/badfree.vgtest
56 perl tests/vg_regtest memcheck/tests/badfree
59 Running the performance tests
60 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
61 To build and run all the performance tests, run "make [--quiet] perf".
63 To run a subset of the performance suite, execute:
65 perl perf/vg_perf <name>
67 where <name> is a directory (all tests within will be run) or a single
68 .vgperf test file, or the name of a program which has a like-named .vgperf
71 perl perf/vg_perf perf/
72 perl perf/vg_perf perf/bz2.vgperf
73 perl perf/vg_perf perf/bz2
75 To compare multiple versions of Valgrind, use the --vg= option multiple
76 times. For example, if you have two Valgrinds next to each other, one in
77 trunk1/ and one in trunk2/, from within either trunk1/ or trunk2/ do this to
78 compare them on all the performance tests:
80 perl perf/vg_perf --vg=../trunk1 --vg=../trunk2 perf/
83 Commit access and try branches
84 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
85 To get commit access to the valgrind git repository on sourceware
86 you will have to ask an existing developer and fill in the following
87 form: https://sourceware.org/cgi-bin/pdw/ps_form.cgi
89 Every developer with commit access can use try branches. Code committed
90 to a try branch will be build by the buildbot at builder.sourceware.org
91 https://builder.sourceware.org/buildbot/#/builders?tags=valgrind-try
93 If you want to try a commit you can push to a special named try branch
94 (users/<your-user-name>/try-<topic>) as follows:
97 ...hack, hack, hack... OK, looks good to submit
98 git commit -a -m "Awesome hack"
99 git push origin frob:users/username/try-frob
101 When all builders have build your patch the buildbot will sent you (or
102 actually the patch author) an email telling you if any builds failed and
103 references to all the logs. You can also find the logs and the builds here:
104 https://builder.sourceware.org/buildbot/#/builders?tags=valgrind-try
106 Afterwards you can delete the branch again:
108 git push origin :users/username/try-frob
110 Debugging Valgrind with GDB
111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
112 To debug the valgrind launcher program (<prefix>/bin/valgrind) just
113 run it under gdb in the normal way.
115 Debugging the main body of the valgrind code (and/or the code for
116 a particular tool) requires a bit more trickery but can be achieved
117 without too much problem by following these steps:
119 (1) Set VALGRIND_LAUNCHER to point to the valgrind executable. Eg:
121 export VALGRIND_LAUNCHER=/usr/local/bin/valgrind
123 or for an uninstalled version in a source directory $DIR:
125 export VALGRIND_LAUNCHER=$DIR/coregrind/valgrind
126 export VALGRIND_LIB=$DIR/.in_place
128 VALGRIND_LIB is where the default.supp and vgpreload_ libraries
129 are found (which is under /usr/libexec/valgrind for an installed
132 (2) Run gdb on the tool executable. Eg:
134 gdb /usr/local/lib/valgrind/lackey-ppc32-linux
138 gdb $DIR/.in_place/memcheck-x86-linux
140 (3) Do "handle SIGSEGV SIGILL nostop noprint" in GDB to prevent GDB from
141 stopping on a SIGSEGV or SIGILL:
143 (gdb) handle SIGILL SIGSEGV nostop noprint
145 If you are using lldb, then the equivalent command is
147 (lldb) pro hand -p true -s false -n false SIGILL SIGSEGV
149 (4) Set any breakpoints you want and proceed as normal for gdb. The
150 macro VG_(FUNC) is expanded to vgPlain_FUNC, so If you want to set
151 a breakpoint VG_(do_exec), you could do like this in GDB:
153 (gdb) b vgPlain_do_exec
155 (5) Run the tool with required options (the --tool option is required
156 for correct setup), e.g.
158 (gdb) run --tool=lackey pwd
160 Steps (1)--(3) can be put in a .gdbinit file, but any directory names must
161 be fully expanded (ie. not an environment variable).
163 A different and possibly easier way is as follows:
165 (1) Run Valgrind as normal, but add the flag --wait-for-gdb=yes. This
166 puts the tool executable into a wait loop soon after it gains
167 control. This delays startup for a few seconds.
169 (2) In a different shell, do "gdb /proc/<pid>/exe <pid>", where
170 <pid> you read from the output printed by (1). This attaches
171 GDB to the tool executable, which should be in the above mentioned
174 (3) Do "cont" to continue. After the loop finishes spinning, startup
175 will continue as normal. Note that comment (3) above re passing
176 signals applies here too.
181 This section explains :
182 (A) How to configure Valgrind to run under Valgrind.
183 Such a setup is called self hosting, or outer/inner setup.
184 (B) How to run Valgrind regression tests in a 'self-hosting' mode,
185 e.g. to verify Valgrind has no bugs such as memory leaks.
186 (C) How to run Valgrind performance tests in a 'self-hosting' mode,
187 to analyse and optimise the performance of Valgrind and its tools.
189 (A) How to configure Valgrind to run under Valgrind:
191 (1) Check out 2 trees, "Inner" and "Outer". Inner runs the app
192 directly. Outer runs Inner.
194 (2) Configure Inner with --enable-inner and build as usual.
196 (3) Configure Outer normally and build+install as usual.
197 Note: You must use a "make install"-ed valgrind.
198 Do *not* use vg-in-place for the Outer valgrind.
200 (4) Choose a very simple program (date) and try
202 outer/.../bin/valgrind --sim-hints=enable-outer --trace-children=yes \
203 --smc-check=all-non-file \
204 --run-libc-freeres=no --tool=cachegrind -v \
205 inner/.../vg-in-place --vgdb-prefix=./inner --tool=none -v prog
207 If you omit the --trace-children=yes, you'll only monitor Inner's launcher
208 program, not its stage2. Outer needs --run-libc-freeres=no, as otherwise
209 it will try to find and run __libc_freeres in the inner, while libc is not
210 used by the inner. Inner needs --vgdb-prefix=./inner to avoid inner
211 gdbserver colliding with outer gdbserver.
212 Currently, inner does *not* use the client request
213 VALGRIND_DISCARD_TRANSLATIONS for the JITted code or the code patched for
214 translation chaining. So the outer needs --smc-check=all-non-file to
215 detect the modified code.
217 Debugging the whole thing might imply to use up to 3 GDB:
218 * a GDB attached to the Outer valgrind, allowing
219 to examine the state of Outer.
220 * a GDB using Outer gdbserver, allowing to
221 examine the state of Inner.
222 * a GDB using Inner gdbserver, allowing to
223 examine the state of prog.
225 The whole thing is fragile, confusing and slow, but it does work well enough
226 for you to get some useful performance data. Inner has most of
227 its output (ie. those lines beginning with "==<pid>==") prefixed with a '>',
228 which helps a lot. However, when running regression tests in an Outer/Inner
229 setup, this prefix causes the reg test diff to fail. Give
230 --sim-hints=no-inner-prefix to the Inner to disable the production
231 of the prefix in the stdout/stderr output of Inner.
233 The allocators in coregrind/m_mallocfree.c and VEX/priv/main_util.h are
234 annotated with client requests so Memcheck can be used to find leaks
235 and use after free in an Inner Valgrind.
237 The Valgrind "big lock" is annotated with helgrind client requests
238 so Helgrind and DRD can be used to find race conditions in an Inner
241 All this has not been tested much, so don't be surprised if you hit problems.
243 When using self-hosting with an outer Callgrind tool, use '--pop-on-jump'
244 (on the outer). Otherwise, Callgrind has much higher memory requirements.
246 (B) Regression tests in an outer/inner setup:
248 To run all the regression tests with an outer memcheck, do :
249 perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \
252 To run a specific regression tests with an outer memcheck, do:
253 perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \
254 none/tests/args.vgtest
256 To run regression tests with another outer tool:
257 perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \
258 --outer-tool=helgrind --all
260 --outer-args allows to give specific arguments to the outer tool,
261 replacing the default one provided by vg_regtest.
263 Note: --outer-valgrind must be a "make install"-ed valgrind.
264 Do *not* use vg-in-place.
266 When an outer valgrind runs an inner valgrind, a regression test
267 produces one additional file <testname>.outer.log which contains the
268 errors detected by the outer valgrind. E.g. for an outer memcheck, it
269 contains the leaks found in the inner, for an outer helgrind or drd,
270 it contains the detected race conditions.
272 The file tests/outer_inner.supp contains suppressions for
273 the irrelevant or benign errors found in the inner.
275 An regression test running in the inner (e.g. memcheck/tests/badrw) will
276 cause the inner to report an error, which is expected and checked
277 as usual when running the regtests in an outer/inner setup.
278 However, the outer will often also observe an error, e.g. a jump
279 using uninitialised data, or a read/write outside the bounds of a heap
280 block. When the outer reports such an error, it will output the
281 inner host stacktrace. To this stacktrace, it will append the
282 stacktrace of the inner guest program. For example, this is an error
283 reported by the outer when the inner runs the badrw regtest:
284 ==8119== Invalid read of size 2
285 ==8119== at 0x7F2EFD7AF: ???
286 ==8119== by 0x7F2C82EAF: ???
287 ==8119== by 0x7F180867F: ???
288 ==8119== by 0x40051D: main (badrw.c:5)
289 ==8119== by 0x7F180867F: ???
290 ==8119== by 0x1BFF: ???
291 ==8119== by 0x3803B7F0: _______VVVVVVVV_appended_inner_guest_stack_VVVVVVVV_______ (m_execontext.c:332)
292 ==8119== by 0x40055C: main (badrw.c:22)
293 ==8119== Address 0x55cd03c is 4 bytes before a block of size 16 alloc'd
294 ==8119== at 0x2804E26D: vgPlain_arena_malloc (m_mallocfree.c:1914)
295 ==8119== by 0x2800BAB4: vgMemCheck_new_block (mc_malloc_wrappers.c:368)
296 ==8119== by 0x2800BC87: vgMemCheck_malloc (mc_malloc_wrappers.c:403)
297 ==8119== by 0x28097EAE: do_client_request (scheduler.c:1861)
298 ==8119== by 0x28097EAE: vgPlain_scheduler (scheduler.c:1425)
299 ==8119== by 0x280A7237: thread_wrapper (syswrap-linux.c:103)
300 ==8119== by 0x280A7237: run_a_thread_NORETURN (syswrap-linux.c:156)
301 ==8119== by 0x3803B7F0: _______VVVVVVVV_appended_inner_guest_stack_VVVVVVVV_______ (m_execontext.c:332)
302 ==8119== by 0x4C294C4: malloc (vg_replace_malloc.c:298)
303 ==8119== by 0x40051D: main (badrw.c:5)
304 In the above, the first stacktrace starts with the inner host stacktrace,
305 which in this case is some JITted code. Such code sometimes contains IPs
306 that points in the inner guest code (0x40051D: main (badrw.c:5)).
307 After the separator, we have the inner guest stacktrace.
308 The second stacktrace gives the stacktrace where the heap block that was
309 overrun was allocated. We see it was allocated by the inner valgrind
310 in the client arena (first part of the stacktrace). The second part is
311 the guest stacktrace that did the allocation.
314 (C) Performance tests in an outer/inner setup:
316 To run all the performance tests with an outer cachegrind, do :
317 perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind perf
319 To run a specific perf test (e.g. bz2) in this setup, do :
320 perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind perf/bz2
322 To run all the performance tests with an outer callgrind, do :
323 perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind \
324 --outer-tool=callgrind perf
326 Note: --outer-valgrind must be a "make install"-ed valgrind.
327 Do *not* use vg-in-place.
329 To compare the performance of multiple Valgrind versions, do :
330 perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind \
331 --outer-tool=callgrind \
332 --vg=../inner_xxxx --vg=../inner_yyyy perf
333 (where inner_xxxx and inner_yyyy are the toplevel directories of
334 the versions to compare).
335 Cachegrind and cg_diff are particularly handy to obtain a delta
336 between the two versions.
338 When the outer tool is callgrind or cachegrind, the following
339 output files will be created for each test:
340 <outertoolname>.out.<inner_valgrind_dir>.<tt>.<perftestname>.<pid>
341 <outertoolname>.outer.log.<inner_valgrind_dir>.<tt>.<perftestname>.<pid>
342 (where tt is the two letters abbreviation for the inner tool(s) run).
344 For example, the command
346 --outer-valgrind=../outer_trunk/install/bin/valgrind \
347 --outer-tool=callgrind \
348 --vg=../inner_tchain --vg=../inner_trunk perf/many-loss-records
351 callgrind.out.inner_tchain.no.many-loss-records.18465
352 callgrind.outer.log.inner_tchain.no.many-loss-records.18465
353 callgrind.out.inner_tchain.me.many-loss-records.21899
354 callgrind.outer.log.inner_tchain.me.many-loss-records.21899
355 callgrind.out.inner_trunk.no.many-loss-records.21224
356 callgrind.outer.log.inner_trunk.no.many-loss-records.21224
357 callgrind.out.inner_trunk.me.many-loss-records.22916
358 callgrind.outer.log.inner_trunk.me.many-loss-records.22916
361 Printing out problematic blocks
362 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
363 If you want to print out a disassembly of a particular block that
364 causes a crash, do the following.
366 Try running with "--vex-guest-chase=no --trace-flags=10000000
367 --trace-notbelow=999999". This should print one line for each block
368 translated, and that includes the address.
370 Then re-run with 999999 changed to the highest bb number shown.
371 This will print the one line per block, and also will print a
372 disassembly of the block in which the fault occurred.