README
1
2Release notes for Valgrind
3~~~~~~~~~~~~~~~~~~~~~~~~~~
4If you are building a binary package of Valgrind for distribution,
5please read README_PACKAGERS. It contains some important information.
6
7If you are developing Valgrind, please read README_DEVELOPERS. It contains
8some useful information.
9
10For instructions on how to build/install, see the end of this file.
11
12If you have problems, consult the FAQ to see if there are workarounds.
13
14
15Executive Summary
16~~~~~~~~~~~~~~~~~
17Valgrind is a framework for building dynamic analysis tools. There are
18Valgrind tools that can automatically detect many memory management
19and threading bugs, and profile your programs in detail. You can also
20use Valgrind to build new tools.
21
22The Valgrind distribution currently includes six production-quality
23tools: a memory error detector, two thread error detectors, a cache
24and branch-prediction profiler, a call-graph generating cache abd
25branch-prediction profiler, and a heap profiler. It also includes
26three experimental tools: a heap/stack/global array overrun detector,
27a different kind of heap profiler, and a SimPoint basic block vector
28generator.
29
30Valgrind is closely tied to details of the CPU, operating system and to
31a lesser extent, compiler and basic C libraries. This makes it difficult
32to make it portable. Nonetheless, it is available for the following
33platforms:
34
35- x86/Linux
36- AMD64/Linux
37- PPC32/Linux
38- PPC64/Linux
39- ARM/Linux
40- x86/MacOSX
41- AMD64/MacOSX
42
43Note that AMD64 is just another name for x86-64, and Valgrind runs fine
44on Intel processors. Also note that the core of MacOSX is called
45"Darwin" and this name is used sometimes.
46
47Valgrind is licensed under the GNU General Public License, version 2.
48Read the file COPYING in the source distribution for details.
49
50However: if you contribute code, you need to make it available as GPL
51version 2 or later, and not 2-only.
52
53
54Documentation
55~~~~~~~~~~~~~
56A comprehensive user guide is supplied. Point your browser at
57$PREFIX/share/doc/valgrind/manual.html, where $PREFIX is whatever you
58specified with --prefix= when building.
59
60
61Building and installing it
62~~~~~~~~~~~~~~~~~~~~~~~~~~
63To install from the Subversion repository :
64
65 0. Check out the code from SVN, following the instructions at
66 http://www.valgrind.org/downloads/repository.html.
67
68 1. cd into the source directory.
69
70 2. Run ./autogen.sh to setup the environment (you need the standard
71 autoconf tools to do so).
72
73 3. Continue with the following instructions...
74
75To install from a tar.bz2 distribution:
76
77 4. Run ./configure, with some options if you wish. The only interesting
78 one is the usual --prefix=/where/you/want/it/installed.
79
80 5. Run "make".
81
82 6. Run "make install", possibly as root if the destination permissions
83 require that.
84
85 7. See if it works. Try "valgrind ls -l". Either this works, or it
86 bombs out with some complaint. In that case, please let us know
87 (see www.valgrind.org).
88
89Important! Do not move the valgrind installation into a place
90different from that specified by --prefix at build time. This will
91cause things to break in subtle ways, mostly when Valgrind handles
92fork/exec calls.
93
94
95The Valgrind Developers
96
README_DEVELOPERS
1
2Building and not installing it
3~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4To run Valgrind without having to install it, run coregrind/valgrind
5with the VALGRIND_LIB environment variable set, where <dir> is the root
6of the source tree (and must be an absolute path). Eg:
7
8 VALGRIND_LIB=~/grind/head4/.in_place ~/grind/head4/coregrind/valgrind
9
10This allows you to compile and run with "make" instead of "make install",
11saving you time.
12
13Or, you can use the 'vg-in-place' script which does that for you.
14
15I recommend compiling with "make --quiet" to further reduce the amount of
16output spewed out during compilation, letting you actually see any errors,
17warnings, etc.
18
19
20Building a distribution tarball
21~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
22To build a distribution tarball from the valgrind sources:
23
24 make dist
25
26In addition to compiling, linking and packaging everything up, the command
27will also build the documentation. Even if all required tools for building the
28documentation are installed, this step may not succeed because of hidden
29dependencies. E.g. on Ubuntu you must have "docbook-xsl" installed.
30Additionally, specific tool versions maybe needed.
31
32If you only want to test whether the generated tarball is complete and runs
33regression tests successfully, building documentation is not needed.
34Edit docs/Makefile.am, search for BUILD_ALL_DOCS and follow instructions there.
35
36
37Running the regression tests
38~~~~~~~~~~~~~~~~~~~~~~~~~~~~
39To build and run all the regression tests, run "make [--quiet] regtest".
40
41To run a subset of the regression tests, execute:
42
43 perl tests/vg_regtest <name>
44
45where <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
47file. 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
54Running the performance tests
55~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
56To build and run all the performance tests, run "make [--quiet] perf".
57
58To run a subset of the performance suite, execute:
59
60 perl perf/vg_perf <name>
61
62where <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
64file. Eg:
65
66 perl perf/vg_perf perf/
67 perl perf/vg_perf perf/bz2.vgperf
68 perl perf/vg_perf perf/bz2
69
70To compare multiple versions of Valgrind, use the --vg= option multiple
71times. For example, if you have two Valgrinds next to each other, one in
72trunk1/ and one in trunk2/, from within either trunk1/ or trunk2/ do this to
73compare them on all the performance tests:
74
75 perl perf/vg_perf --vg=../trunk1 --vg=../trunk2 perf/
76
77
78Debugging Valgrind with GDB
79~~~~~~~~~~~~~~~~~~~~~~~~~~~
80To debug the valgrind launcher program (<prefix>/bin/valgrind) just
81run it under gdb in the normal way.
82
83Debugging the main body of the valgrind code (and/or the code for
84a particular tool) requires a bit more trickery but can be achieved
85without 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:
115
116 (gdb) run pwd
117
118Steps (1)--(3) can be put in a .gdbinit file, but any directory names must
119be fully expanded (ie. not an environment variable).
120
121A different and possibly easier way is as follows:
122
123(1) Run Valgrind as normal, but add the flag --wait-for-gdb=yes. This
124 puts the tool executable into a wait loop soon after it gains
125 control. This delays startup for a few seconds.
126
127(2) In a different shell, do "gdb /proc/<pid>/exe <pid>", where
128 <pid> you read from the output printed by (1). This attaches
129 GDB to the tool executable, which should be in the abovementioned
130 wait loop.
131
132(3) Do "cont" to continue. After the loop finishes spinning, startup
133 will continue as normal. Note that comment (3) above re passing
134 signals applies here too.
135
136
137Self-hosting
138~~~~~~~~~~~~
139To run Valgrind under Valgrind:
140
141(1) Check out 2 trees, "Inner" and "Outer". Inner runs the app
142 directly. Outer runs Inner.
143
144(2) Configure inner with --enable-inner and build/install as
145 usual.
146
147(3) Configure Outer normally and build/install as usual.
148
149(4) Choose a very simple program (date) and try
150
151 outer/.../bin/valgrind --sim-hints=enable-outer --trace-children=yes \
152 --tool=cachegrind -v inner/.../bin/valgrind --tool=none -v prog
153
154If you omit the --trace-children=yes, you'll only monitor Inner's launcher
155program, not its stage2.
156
157The whole thing is fragile, confusing and slow, but it does work well enough
158for you to get some useful performance data. Inner has most of
159its output (ie. those lines beginning with "==<pid>==") prefixed with a '>',
160which helps a lot.
161
162At the time of writing the allocator is not annotated with client requests
163so Memcheck is not as useful as it could be. It also has not been tested
164much, so don't be surprised if you hit problems.
165
166When using self-hosting with an outer Callgrind tool, use '--pop-on-jump'
167(on the outer). Otherwise, Callgrind has much higher memory requirements.
168
169
170Printing out problematic blocks
171~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
172If you want to print out a disassembly of a particular block that
173causes a crash, do the following.
174
175Try running with "--vex-guest-chase-thresh=0 --trace-flags=10000000
176--trace-notbelow=999999". This should print one line for each block
177translated, and that includes the address.
178
179Then re-run with 999999 changed to the highest bb number shown.
180This will print the one line per block, and also will print a
181disassembly of the block in which the fault occurred.
182
README_MISSING_SYSCALL_OR_IOCTL
1
2Dealing with missing system call or ioctl wrappers in Valgrind
3~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4You're probably reading this because Valgrind bombed out whilst
5running your program, and advised you to read this file. The good
6news is that, in general, it's easy to write the missing syscall or
7ioctl wrappers you need, so that you can continue your debugging. If
8you send the resulting patches to me, then you'll be doing a favour to
9all future Valgrind users too.
10
11Note that an "ioctl" is just a special kind of system call, really; so
12there's not a lot of need to distinguish them (at least conceptually)
13in the discussion that follows.
14
15All this machinery is in coregrind/m_syswrap.
16
17
18What are syscall/ioctl wrappers? What do they do?
19~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
20Valgrind does what it does, in part, by keeping track of everything your
21program does. When a system call happens, for example a request to read
22part of a file, control passes to the Linux kernel, which fulfills the
23request, and returns control to your program. The problem is that the
24kernel will often change the status of some part of your program's memory
25as a result, and tools (instrumentation plug-ins) may need to know about
26this.
27
28Syscall and ioctl wrappers have two jobs:
29
301. Tell a tool what's about to happen, before the syscall takes place. A
31 tool could perform checks beforehand, eg. if memory about to be written
32 is actually writeable. This part is useful, but not strictly
33 essential.
34
352. Tell a tool what just happened, after a syscall takes place. This is
36 so it can update its view of the program's state, eg. that memory has
37 just been written to. This step is essential.
38
39The "happenings" mostly involve reading/writing of memory.
40
41So, let's look at an example of a wrapper for a system call which
42should be familiar to many Unix programmers.
43
44
45The syscall wrapper for time()
46~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
47The wrapper for the time system call looks like this:
48
49 PRE(sys_time)
50 {
51 /* time_t time(time_t *t); */
52 PRINT("sys_time ( %p )",ARG1);
53 PRE_REG_READ1(long, "time", int *, t);
54 if (ARG1 != 0) {
55 PRE_MEM_WRITE( "time(t)", ARG1, sizeof(vki_time_t) );
56 }
57 }
58
59 POST(sys_time)
60 {
61 if (ARG1 != 0) {
62 POST_MEM_WRITE( ARG1, sizeof(vki_time_t) );
63 }
64 }
65
66The first thing we do happens before the syscall occurs, in the PRE() function.
67The PRE() function typically starts with invoking to the PRINT() macro. This
68PRINT() macro implements support for the --trace-syscalls command line option.
69Next, the tool is told the return type of the syscall, that the syscall has
70one argument, the type of the syscall argument and that the argument is being
71read from a register:
72
73 PRE_REG_READ1(long, "time", int *, t);
74
75Next, if a non-NULL buffer is passed in as the argument, tell the tool that the
76buffer is about to be written to:
77
78 if (ARG1 != 0) {
79 PRE_MEM_WRITE( "time", ARG1, sizeof(vki_time_t) );
80 }
81
82Finally, the really important bit, after the syscall occurs, in the POST()
83function: if, and only if, the system call was successful, tell the tool that
84the memory was written:
85
86 if (ARG1 != 0) {
87 POST_MEM_WRITE( ARG1, sizeof(vki_time_t) );
88 }
89
90The POST() function won't be called if the syscall failed, so you
91don't need to worry about checking that in the POST() function.
92(Note: this is sometimes a bug; some syscalls do return results when
93they "fail" - for example, nanosleep returns the amount of unslept
94time if interrupted. TODO: add another per-syscall flag for this
95case.)
96
97Note that we use the type 'vki_time_t'. This is a copy of the kernel
98type, with 'vki_' prefixed. Our copies of such types are kept in the
99appropriate vki*.h file(s). We don't include kernel headers or glibc headers
100directly.
101
102
103Writing your own syscall wrappers (see below for ioctl wrappers)
104~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
105If Valgrind tells you that system call NNN is unimplemented, do the
106following:
107
1081. Find out the name of the system call:
109
110 grep NNN /usr/include/asm/unistd*.h
111
112 This should tell you something like __NR_mysyscallname.
113 Copy this entry to include/vki/vki-scnums-$(VG_PLATFORM).h.
114
115
1162. Do 'man 2 mysyscallname' to get some idea of what the syscall
117 does. Note that the actual kernel interface can differ from this,
118 so you might also want to check a version of the Linux kernel
119 source.
120
121 NOTE: any syscall which has something to do with signals or
122 threads is probably "special", and needs more careful handling.
123 Post something to valgrind-developers if you aren't sure.
124
125
1263. Add a case to the already-huge collection of wrappers in
127 the coregrind/m_syswrap/syswrap-*.c files.
128 For each in-memory parameter which is read or written by
129 the syscall, do one of
130
131 PRE_MEM_READ( ... )
132 PRE_MEM_RASCIIZ( ... )
133 PRE_MEM_WRITE( ... )
134
135 for that parameter. Then do the syscall. Then, if the syscall
136 succeeds, issue suitable POST_MEM_WRITE( ... ) calls.
137 (There's no need for POST_MEM_READ calls.)
138
139 Also, add it to the syscall_table[] array; use one of GENX_, GENXY
140 LINX_, LINXY, PLAX_, PLAXY.
141 GEN* for generic syscalls (in syswrap-generic.c), LIN* for linux
142 specific ones (in syswrap-linux.c) and PLA* for the platform
143 dependant ones (in syswrap-$(PLATFORM)-linux.c).
144 The *XY variant if it requires a PRE() and POST() function, and
145 the *X_ variant if it only requires a PRE()
146 function.
147
148 If you find this difficult, read the wrappers for other syscalls
149 for ideas. A good tip is to look for the wrapper for a syscall
150 which has a similar behaviour to yours, and use it as a
151 starting point.
152
153 If you need structure definitions and/or constants for your syscall,
154 copy them from the kernel headers into include/vki.h and co., with
155 the appropriate vki_*/VKI_* name mangling. Don't #include any
156 kernel headers. And certainly don't #include any glibc headers.
157
158 Test it.
159
160 Note that a common error is to call POST_MEM_WRITE( ... )
161 with 0 (NULL) as the first (address) argument. This usually means
162 your logic is slightly inadequate. It's a sufficiently common bug
163 that there's a built-in check for it, and you'll get a "probably
164 sanity check failure" for the syscall wrapper you just made, if this
165 is the case.
166
167
1684. Once happy, send us the patch. Pretty please.
169
170
171
172
173Writing your own ioctl wrappers
174~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
175
176Is pretty much the same as writing syscall wrappers, except that all
177the action happens within PRE(ioctl) and POST(ioctl).
178
179There's a default case, sometimes it isn't correct and you have to write a
180more specific case to get the right behaviour.
181
182As above, please create a bug report and attach the patch as described
183on http://www.valgrind.org.
184
185
README_PACKAGERS
1
2Greetings, packaging person! This information is aimed at people
3building binary distributions of Valgrind.
4
5Thanks for taking the time and effort to make a binary distribution of
6Valgrind. The following notes may save you some trouble.
7
8
9-- Do not ship your Linux distro with a completely stripped
10 /lib/ld.so. At least leave the debugging symbol names on -- line
11 number info isn't necessary. If you don't want to leave symbols on
12 ld.so, alternatively you can have your distro install ld.so's
13 debuginfo package by default, or make ld.so.debuginfo be a
14 requirement of your Valgrind RPM/DEB/whatever.
15
16 Reason for this is that Valgrind's Memcheck tool needs to intercept
17 calls to, and provide replacements for, some symbols in ld.so at
18 startup (most importantly strlen). If it cannot do that, Memcheck
19 shows a large number of false positives due to the highly optimised
20 strlen (etc) routines in ld.so. This has caused some trouble in
21 the past. As of version 3.3.0, on some targets (ppc32-linux,
22 ppc64-linux), Memcheck will simply stop at startup (and print an
23 error message) if such symbols are not present, because it is
24 infeasible to continue.
25
26 It's not like this is going to cost you much space. We only need
27 the symbols for ld.so (a few K at most). Not the debug info and
28 not any debuginfo or extra symbols for any other libraries.
29
30
31-- (Unfortunate but true) When you configure to build with the
32 --prefix=/foo/bar/xyzzy option, the prefix /foo/bar/xyzzy gets
33 baked into valgrind. The consequence is that you _must_ install
34 valgrind at the location specified in the prefix. If you don't,
35 it may appear to work, but will break doing some obscure things,
36 particularly doing fork() and exec().
37
38 So you can't build a relocatable RPM / whatever from Valgrind.
39
40
41-- Don't strip the debug info off lib/valgrind/$platform/vgpreload*.so
42 in the installation tree. Either Valgrind won't work at all, or it
43 will still work if you do, but will generate less helpful error
44 messages. Here's an example:
45
46 Mismatched free() / delete / delete []
47 at 0x40043249: free (vg_clientfuncs.c:171)
48 by 0x4102BB4E: QGArray::~QGArray(void) (tools/qgarray.cpp:149)
49 by 0x4C261C41: PptDoc::~PptDoc(void) (include/qmemarray.h:60)
50 by 0x4C261F0E: PptXml::~PptXml(void) (pptxml.cc:44)
51 Address 0x4BB292A8 is 0 bytes inside a block of size 64 alloc'd
52 at 0x4004318C: __builtin_vec_new (vg_clientfuncs.c:152)
53 by 0x4C21BC15: KLaola::readSBStream(int) const (klaola.cc:314)
54 by 0x4C21C155: KLaola::stream(KLaola::OLENode const *) (klaola.cc:416)
55 by 0x4C21788F: OLEFilter::convert(QCString const &) (olefilter.cc:272)
56
57 This tells you that some memory allocated with new[] was freed with
58 free().
59
60 Mismatched free() / delete / delete []
61 at 0x40043249: (inside vgpreload_memcheck.so)
62 by 0x4102BB4E: QGArray::~QGArray(void) (tools/qgarray.cpp:149)
63 by 0x4C261C41: PptDoc::~PptDoc(void) (include/qmemarray.h:60)
64 by 0x4C261F0E: PptXml::~PptXml(void) (pptxml.cc:44)
65 Address 0x4BB292A8 is 0 bytes inside a block of size 64 alloc'd
66 at 0x4004318C: (inside vgpreload_memcheck.so)
67 by 0x4C21BC15: KLaola::readSBStream(int) const (klaola.cc:314)
68 by 0x4C21C155: KLaola::stream(KLaola::OLENode const *) (klaola.cc:416)
69 by 0x4C21788F: OLEFilter::convert(QCString const &) (olefilter.cc:272)
70
71 This isn't so helpful. Although you can tell there is a mismatch,
72 the names of the allocating and deallocating functions are no longer
73 visible. The same kind of thing occurs in various other messages
74 from valgrind.
75
76
77-- Don't strip symbols from lib/valgrind/* in the installation tree.
78 Doing so will likely cause problems. Removing the line number info is
79 probably OK (at least for some of the files in that directory), although
80 that has not been tested by the Valgrind developers.
81
82
83-- Please test the final installation works by running it on something
84 huge. I suggest checking that it can start and exit successfully
85 both Firefox and OpenOffice.org. I use these as test programs, and I
86 know they fairly thoroughly exercise Valgrind. The command lines to use
87 are:
88
89 valgrind -v --trace-children=yes firefox
90
91 valgrind -v --trace-children=yes soffice
92
93
94If you find any more hints/tips for packaging, please report
95it as a bugreport. See http://www.valgrind.org for details.
96