Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / valgrind / ab1d9d183ef70cb329d175bc56fc7e4103bfdc85 / . / memcheck / docs / manual.html
blob: db1d28326f7cf261aca4b03089d66e08f5f7e1bb [file] [log] [blame]
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]1<html>
2 <head>
3 <style type="text/css">
4 body { background-color: #ffffff;
5 color: #000000;
6 font-family: Times, Helvetica, Arial;
7 font-size: 14pt}
8 h4 { margin-bottom: 0.3em}
9 code { color: #000000;
10 font-family: Courier;
11 font-size: 13pt }
12 pre { color: #000000;
13 font-family: Courier;
14 font-size: 13pt }
15 a:link { color: #0000C0;
16 text-decoration: none; }
17 a:visited { color: #0000C0;
18 text-decoration: none; }
19 a:active { color: #0000C0;
20 text-decoration: none; }
21 </style>
22 </head>
23
24<body bgcolor="#ffffff">
25
26<a name="title">&nbsp;</a>
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]27<h1 align=center>Valgrind, snapshot 20020501</h1>
28<center>This manual was majorly updated on 20020501</center>
sewardjc7529c32002-04-16 01:55:18 +0000[diff] [blame]29<p>
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]30
31<center>
32<a href="mailto:jseward@acm.org">jseward@acm.org<br>
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]33Copyright &copy; 2000-2002 Julian Seward
34<p>
35Valgrind is licensed under the GNU General Public License,
36version 2<br>
37An open-source tool for finding memory-management problems in
38Linux-x86 executables.
39</center>
40
41<p>
42
43<hr width="100%">
44<a name="contents"></a>
45<h2>Contents of this manual</h2>
46
47<h4>1&nbsp; <a href="#intro">Introduction</a></h4>
48 1.1&nbsp; <a href="#whatfor">What Valgrind is for</a><br>
49 1.2&nbsp; <a href="#whatdoes">What it does with your program</a>
50
51<h4>2&nbsp; <a href="#howtouse">How to use it, and how to make sense
52 of the results</a></h4>
53 2.1&nbsp; <a href="#starta">Getting started</a><br>
54 2.2&nbsp; <a href="#comment">The commentary</a><br>
55 2.3&nbsp; <a href="#report">Reporting of errors</a><br>
56 2.4&nbsp; <a href="#suppress">Suppressing errors</a><br>
57 2.5&nbsp; <a href="#flags">Command-line flags</a><br>
58 2.6&nbsp; <a href="#errormsgs">Explaination of error messages</a><br>
59 2.7&nbsp; <a href="#suppfiles">Writing suppressions files</a><br>
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]60 2.8&nbsp; <a href="#clientreq">The Client Request mechanism</a><br>
61 2.9&nbsp; <a href="#pthreads">Support for POSIX pthreads</a><br>
62 2.10&nbsp; <a href="#install">Building and installing</a><br>
63 2.11&nbsp; <a href="#problems">If you have problems</a><br>
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]64
65<h4>3&nbsp; <a href="#machine">Details of the checking machinery</a></h4>
66 3.1&nbsp; <a href="#vvalue">Valid-value (V) bits</a><br>
67 3.2&nbsp; <a href="#vaddress">Valid-address (A)&nbsp;bits</a><br>
68 3.3&nbsp; <a href="#together">Putting it all together</a><br>
69 3.4&nbsp; <a href="#signals">Signals</a><br>
70 3.5&nbsp; <a href="#leaks">Memory leak detection</a><br>
71
72<h4>4&nbsp; <a href="#limits">Limitations</a></h4>
73
74<h4>5&nbsp; <a href="#howitworks">How it works -- a rough overview</a></h4>
75 5.1&nbsp; <a href="#startb">Getting started</a><br>
76 5.2&nbsp; <a href="#engine">The translation/instrumentation engine</a><br>
77 5.3&nbsp; <a href="#track">Tracking the status of memory</a><br>
78 5.4&nbsp; <a href="#sys_calls">System calls</a><br>
79 5.5&nbsp; <a href="#sys_signals">Signals</a><br>
80
81<h4>6&nbsp; <a href="#example">An example</a></h4>
82
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]83<h4>7&nbsp; <a href="#cache">Cache profiling</a></h4>
84
85<h4>8&nbsp; <a href="techdocs.html">The design and implementation of Valgrind</a></h4>
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]86
87<hr width="100%">
88
89<a name="intro"></a>
90<h2>1&nbsp; Introduction</h2>
91
92<a name="whatfor"></a>
93<h3>1.1&nbsp; What Valgrind is for</h3>
94
95Valgrind is a tool to help you find memory-management problems in your
96programs. When a program is run under Valgrind's supervision, all
97reads and writes of memory are checked, and calls to
98malloc/new/free/delete are intercepted. As a result, Valgrind can
99detect problems such as:
100<ul>
101 <li>Use of uninitialised memory</li>
102 <li>Reading/writing memory after it has been free'd</li>
103 <li>Reading/writing off the end of malloc'd blocks</li>
104 <li>Reading/writing inappropriate areas on the stack</li>
105 <li>Memory leaks -- where pointers to malloc'd blocks are lost forever</li>
106</ul>
107
108Problems like these can be difficult to find by other means, often
109lying undetected for long periods, then causing occasional,
110difficult-to-diagnose crashes.
111
112<p>
113Valgrind is closely tied to details of the CPU, operating system and
114to a less extent, compiler and basic C libraries. This makes it
115difficult to make it portable, so I have chosen at the outset to
116concentrate on what I believe to be a widely used platform: Red Hat
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]117Linux 7.2, on x86s. Valgrind uses the standard Unix
118<code>./configure</code>, <code>make</code>, <code>make install</code>
119mechanism, and I have attempted to ensure that it works on machines
120with kernel 2.2 or 2.4 and glibc 2.1.X or 2.2.X. This should cover
121the vast majority of modern Linux installations.
122
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]123
124<p>
125Valgrind is licensed under the GNU General Public License, version
1262. Read the file LICENSE in the source distribution for details.
127
128<a name="whatdoes">
129<h3>1.2&nbsp; What it does with your program</h3>
130
131Valgrind is designed to be as non-intrusive as possible. It works
132directly with existing executables. You don't need to recompile,
133relink, or otherwise modify, the program to be checked. Simply place
134the word <code>valgrind</code> at the start of the command line
135normally used to run the program. So, for example, if you want to run
136the command <code>ls -l</code> on Valgrind, simply issue the
137command: <code>valgrind ls -l</code>.
138
139<p>Valgrind takes control of your program before it starts. Debugging
140information is read from the executable and associated libraries, so
141that error messages can be phrased in terms of source code
142locations. Your program is then run on a synthetic x86 CPU which
143checks every memory access. All detected errors are written to a
144log. When the program finishes, Valgrind searches for and reports on
145leaked memory.
146
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]147<p>You can run pretty much any dynamically linked ELF x86 executable
148using Valgrind. Programs run 25 to 50 times slower, and take a lot
149more memory, than they usually would. It works well enough to run
150large programs. For example, the Konqueror web browser from the KDE
151Desktop Environment, version 3.0, runs slowly but usably on Valgrind.
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]152
153<p>Valgrind simulates every single instruction your program executes.
154Because of this, it finds errors not only in your application but also
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]155in all supporting dynamically-linked (<code>.so</code>-format)
156libraries, including the GNU C library, the X client libraries, Qt, if
157you work with KDE, and so on. That often includes libraries, for
158example the GNU C library, which contain memory access violations, but
159which you cannot or do not want to fix.
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]160
161<p>Rather than swamping you with errors in which you are not
162interested, Valgrind allows you to selectively suppress errors, by
163recording them in a suppressions file which is read when Valgrind
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]164starts up. The build mechanism attempts to select suppressions which
165give reasonable behaviour for the libc and XFree86 versions detected
166on your machine.
167
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]168
169<p><a href="#example">Section 6</a> shows an example of use.
170<p>
171<hr width="100%">
172
173<a name="howtouse"></a>
174<h2>2&nbsp; How to use it, and how to make sense of the results</h2>
175
176<a name="starta"></a>
177<h3>2.1&nbsp; Getting started</h3>
178
179First off, consider whether it might be beneficial to recompile your
180application and supporting libraries with optimisation disabled and
181debugging info enabled (the <code>-g</code> flag). You don't have to
182do this, but doing so helps Valgrind produce more accurate and less
183confusing error reports. Chances are you're set up like this already,
184if you intended to debug your program with GNU gdb, or some other
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]185debugger.
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]186
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]187<p>
188A plausible compromise is to use <code>-g -O</code>.
189Optimisation levels above <code>-O</code> have been observed, on very
190rare occasions, to cause gcc to generate code which fools Valgrind's
191error tracking machinery into wrongly reporting uninitialised value
192errors. <code>-O</code> gets you the vast majority of the benefits of
193higher optimisation levels anyway, so you don't lose much there.
194
195<p>
196Note that as of 1 May 2002 Valgrind does not understand the DWARF
197debugging format, which is unfortunate since the upcoming gcc-3.1 uses
198it by default. Valgrind only knows about the older "stabs" format.
199If you use gcc-3.1 or above, you can still ask for stabs-format debug
200info by passing <code>-gstabs</code> to gcc.
201
202<p>
203Then just run your application, but place the word
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]204<code>valgrind</code> in front of your usual command-line invokation.
205Note that you should run the real (machine-code) executable here. If
206your application is started by, for example, a shell or perl script,
207you'll need to modify it to invoke Valgrind on the real executables.
208Running such scripts directly under Valgrind will result in you
209getting error reports pertaining to <code>/bin/sh</code>,
210<code>/usr/bin/perl</code>, or whatever interpreter you're using.
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]211This almost certainly isn't what you want and can be confusing.
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]212
213<a name="comment"></a>
214<h3>2.2&nbsp; The commentary</h3>
215
216Valgrind writes a commentary, detailing error reports and other
217significant events. The commentary goes to standard output by
218default. This may interfere with your program, so you can ask for it
219to be directed elsewhere.
220
221<p>All lines in the commentary are of the following form:<br>
222<pre>
223 ==12345== some-message-from-Valgrind
224</pre>
225<p>The <code>12345</code> is the process ID. This scheme makes it easy
226to distinguish program output from Valgrind commentary, and also easy
227to differentiate commentaries from different processes which have
228become merged together, for whatever reason.
229
230<p>By default, Valgrind writes only essential messages to the commentary,
231so as to avoid flooding you with information of secondary importance.
232If you want more information about what is happening, re-run, passing
233the <code>-v</code> flag to Valgrind.
234
235
236<a name="report"></a>
237<h3>2.3&nbsp; Reporting of errors</h3>
238
239When Valgrind detects something bad happening in the program, an error
240message is written to the commentary. For example:<br>
241<pre>
242 ==25832== Invalid read of size 4
243 ==25832== at 0x8048724: BandMatrix::ReSize(int, int, int) (bogon.cpp:45)
244 ==25832== by 0x80487AF: main (bogon.cpp:66)
245 ==25832== by 0x40371E5E: __libc_start_main (libc-start.c:129)
246 ==25832== by 0x80485D1: (within /home/sewardj/newmat10/bogon)
247 ==25832== Address 0xBFFFF74C is not stack'd, malloc'd or free'd
248</pre>
249
250<p>This message says that the program did an illegal 4-byte read of
251address 0xBFFFF74C, which, as far as it can tell, is not a valid stack
252address, nor corresponds to any currently malloc'd or free'd blocks.
253The read is happening at line 45 of <code>bogon.cpp</code>, called
254from line 66 of the same file, etc. For errors associated with an
255identified malloc'd/free'd block, for example reading free'd memory,
256Valgrind reports not only the location where the error happened, but
257also where the associated block was malloc'd/free'd.
258
259<p>Valgrind remembers all error reports. When an error is detected,
260it is compared against old reports, to see if it is a duplicate. If
261so, the error is noted, but no further commentary is emitted. This
262avoids you being swamped with bazillions of duplicate error reports.
263
264<p>If you want to know how many times each error occurred, run with
265the <code>-v</code> option. When execution finishes, all the reports
266are printed out, along with, and sorted by, their occurrence counts.
267This makes it easy to see which errors have occurred most frequently.
268
269<p>Errors are reported before the associated operation actually
270happens. For example, if you program decides to read from address
271zero, Valgrind will emit a message to this effect, and the program
272will then duly die with a segmentation fault.
273
274<p>In general, you should try and fix errors in the order that they
275are reported. Not doing so can be confusing. For example, a program
276which copies uninitialised values to several memory locations, and
277later uses them, will generate several error messages. The first such
278error message may well give the most direct clue to the root cause of
279the problem.
280
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]281<p>The process of detecting duplicate errors is quite an expensive
282one and can become a significant performance overhead if your program
283generates huge quantities of errors. To avoid serious problems here,
284Valgrind will simply stop collecting errors after 300 different errors
285have been seen, or 30000 errors in total have been seen. In this
286situation you might as well stop your program and fix it, because
287Valgrind won't tell you anything else useful after this. Note that
288the 300/30000 limits apply after suppressed errors are removed. These
289limits are defined in <code>vg_include.h</code> and can be increased
290if necessary.
291
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]292<a name="suppress"></a>
293<h3>2.4&nbsp; Suppressing errors</h3>
294
295Valgrind detects numerous problems in the base libraries, such as the
296GNU C library, and the XFree86 client libraries, which come
297pre-installed on your GNU/Linux system. You can't easily fix these,
298but you don't want to see these errors (and yes, there are many!) So
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]299Valgrind reads a list of errors to suppress at startup.
300A default suppression file is cooked up by the
301<code>./configure</code> script.
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]302
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]303<p>You can modify and add to the suppressions file at your leisure,
304or, better, write your own. Multiple suppression files are allowed.
305This is useful if part of your project contains errors you can't or
306don't want to fix, yet you don't want to continuously be reminded of
307them.
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]308
309<p>Each error to be suppressed is described very specifically, to
310minimise the possibility that a suppression-directive inadvertantly
311suppresses a bunch of similar errors which you did want to see. The
312suppression mechanism is designed to allow precise yet flexible
313specification of errors to suppress.
314
315<p>If you use the <code>-v</code> flag, at the end of execution, Valgrind
316prints out one line for each used suppression, giving its name and the
317number of times it got used. Here's the suppressions used by a run of
318<code>ls -l</code>:
319<pre>
320 --27579-- supp: 1 socketcall.connect(serv_addr)/__libc_connect/__nscd_getgrgid_r
321 --27579-- supp: 1 socketcall.connect(serv_addr)/__libc_connect/__nscd_getpwuid_r
322 --27579-- supp: 6 strrchr/_dl_map_object_from_fd/_dl_map_object
323</pre>
324
325<a name="flags"></a>
326<h3>2.5&nbsp; Command-line flags</h3>
327
328You invoke Valgrind like this:
329<pre>
330 valgrind [options-for-Valgrind] your-prog [options for your-prog]
331</pre>
332
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]333<p>Note that Valgrind also reads options from the environment variable
334<code>$VALGRIND</code>, and processes them before the command-line
335options.
336
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]337<p>Valgrind's default settings succeed in giving reasonable behaviour
338in most cases. Available options, in no particular order, are as
339follows:
340<ul>
341 <li><code>--help</code></li><br>
342
343 <li><code>--version</code><br>
344 <p>The usual deal.</li><br><p>
345
346 <li><code>-v --verbose</code><br>
347 <p>Be more verbose. Gives extra information on various aspects
348 of your program, such as: the shared objects loaded, the
349 suppressions used, the progress of the instrumentation engine,
350 and warnings about unusual behaviour.
351 </li><br><p>
352
353 <li><code>-q --quiet</code><br>
354 <p>Run silently, and only print error messages. Useful if you
355 are running regression tests or have some other automated test
356 machinery.
357 </li><br><p>
358
359 <li><code>--demangle=no</code><br>
360 <code>--demangle=yes</code> [the default]
361 <p>Disable/enable automatic demangling (decoding) of C++ names.
362 Enabled by default. When enabled, Valgrind will attempt to
363 translate encoded C++ procedure names back to something
364 approaching the original. The demangler handles symbols mangled
365 by g++ versions 2.X and 3.X.
366
367 <p>An important fact about demangling is that function
368 names mentioned in suppressions files should be in their mangled
369 form. Valgrind does not demangle function names when searching
370 for applicable suppressions, because to do otherwise would make
371 suppressions file contents dependent on the state of Valgrind's
372 demangling machinery, and would also be slow and pointless.
373 </li><br><p>
374
375 <li><code>--num-callers=&lt;number&gt;</code> [default=4]<br>
376 <p>By default, Valgrind shows four levels of function call names
377 to help you identify program locations. You can change that
378 number with this option. This can help in determining the
379 program's location in deeply-nested call chains. Note that errors
380 are commoned up using only the top three function locations (the
381 place in the current function, and that of its two immediate
382 callers). So this doesn't affect the total number of errors
383 reported.
384 <p>
385 The maximum value for this is 50. Note that higher settings
386 will make Valgrind run a bit more slowly and take a bit more
387 memory, but can be useful when working with programs with
388 deeply-nested call chains.
389 </li><br><p>
390
391 <li><code>--gdb-attach=no</code> [the default]<br>
392 <code>--gdb-attach=yes</code>
393 <p>When enabled, Valgrind will pause after every error shown,
394 and print the line
395 <br>
396 <code>---- Attach to GDB ? --- [Return/N/n/Y/y/C/c] ----</code>
397 <p>
398 Pressing <code>Ret</code>, or <code>N</code> <code>Ret</code>
399 or <code>n</code> <code>Ret</code>, causes Valgrind not to
400 start GDB for this error.
401 <p>
402 <code>Y</code> <code>Ret</code>
403 or <code>y</code> <code>Ret</code> causes Valgrind to
404 start GDB, for the program at this point. When you have
405 finished with GDB, quit from it, and the program will continue.
406 Trying to continue from inside GDB doesn't work.
407 <p>
408 <code>C</code> <code>Ret</code>
409 or <code>c</code> <code>Ret</code> causes Valgrind not to
410 start GDB, and not to ask again.
411 <p>
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]412 <code>--gdb-attach=yes</code> conflicts with
413 <code>--trace-children=yes</code>. You can't use them together.
414 Valgrind refuses to start up in this situation. 1 May 2002:
415 this is a historical relic which could be easily fixed if it
416 gets in your way. Mail me and complain if this is a problem for
417 you. </li><br><p>
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]418
419 <li><code>--partial-loads-ok=yes</code> [the default]<br>
420 <code>--partial-loads-ok=no</code>
421 <p>Controls how Valgrind handles word (4-byte) loads from
422 addresses for which some bytes are addressible and others
423 are not. When <code>yes</code> (the default), such loads
424 do not elicit an address error. Instead, the loaded V bytes
425 corresponding to the illegal addresses indicate undefined, and
426 those corresponding to legal addresses are loaded from shadow
427 memory, as usual.
428 <p>
429 When <code>no</code>, loads from partially
430 invalid addresses are treated the same as loads from completely
431 invalid addresses: an illegal-address error is issued,
432 and the resulting V bytes indicate valid data.
433 </li><br><p>
434
435 <li><code>--sloppy-malloc=no</code> [the default]<br>
436 <code>--sloppy-malloc=yes</code>
437 <p>When enabled, all requests for malloc/calloc are rounded up
438 to a whole number of machine words -- in other words, made
439 divisible by 4. For example, a request for 17 bytes of space
440 would result in a 20-byte area being made available. This works
441 around bugs in sloppy libraries which assume that they can
442 safely rely on malloc/calloc requests being rounded up in this
443 fashion. Without the workaround, these libraries tend to
444 generate large numbers of errors when they access the ends of
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]445 these areas.
446 <p>
447 Valgrind snapshots dated 17 Feb 2002 and later are
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]448 cleverer about this problem, and you should no longer need to
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]449 use this flag. To put it bluntly, if you do need to use this
450 flag, your program violates the ANSI C semantics defined for
451 <code>malloc</code> and <code>free</code>, even if it appears to
452 work correctly, and you should fix it, at least if you hope for
453 maximum portability.
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]454 </li><br><p>
455
456 <li><code>--trace-children=no</code> [the default]</br>
457 <code>--trace-children=yes</code>
458 <p>When enabled, Valgrind will trace into child processes. This
459 is confusing and usually not what you want, so is disabled by
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]460 default. As of 1 May 2002, tracing into a child process from a
461 parent which uses <code>libpthread.so</code> is probably broken
462 and is likely to cause breakage. Please report any such
463 problems to me. </li><br><p>
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]464
465 <li><code>--freelist-vol=&lt;number></code> [default: 1000000]
466 <p>When the client program releases memory using free (in C) or
467 delete (C++), that memory is not immediately made available for
468 re-allocation. Instead it is marked inaccessible and placed in
469 a queue of freed blocks. The purpose is to delay the point at
470 which freed-up memory comes back into circulation. This
471 increases the chance that Valgrind will be able to detect
472 invalid accesses to blocks for some significant period of time
473 after they have been freed.
474 <p>
475 This flag specifies the maximum total size, in bytes, of the
476 blocks in the queue. The default value is one million bytes.
477 Increasing this increases the total amount of memory used by
478 Valgrind but may detect invalid uses of freed blocks which would
479 otherwise go undetected.</li><br><p>
480
481 <li><code>--logfile-fd=&lt;number></code> [default: 2, stderr]
482 <p>Specifies the file descriptor on which Valgrind communicates
483 all of its messages. The default, 2, is the standard error
484 channel. This may interfere with the client's own use of
485 stderr. To dump Valgrind's commentary in a file without using
486 stderr, something like the following works well (sh/bash
487 syntax):<br>
488 <code>&nbsp;&nbsp;
489 valgrind --logfile-fd=9 my_prog 9> logfile</code><br>
490 That is: tell Valgrind to send all output to file descriptor 9,
491 and ask the shell to route file descriptor 9 to "logfile".
492 </li><br><p>
493
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]494 <li><code>--suppressions=&lt;filename></code>
495 [default: $PREFIX/lib/valgrind/default.supp]
496 <p>Specifies an extra
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]497 file from which to read descriptions of errors to suppress. You
498 may use as many extra suppressions files as you
499 like.</li><br><p>
500
501 <li><code>--leak-check=no</code> [default]<br>
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]502 <code>--leak-check=yes</code>
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]503 <p>When enabled, search for memory leaks when the client program
504 finishes. A memory leak means a malloc'd block, which has not
505 yet been free'd, but to which no pointer can be found. Such a
506 block can never be free'd by the program, since no pointer to it
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]507 exists. Leak checking is disabled by default because it tends
508 to generate dozens of error messages. </li><br><p>
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]509
510 <li><code>--show-reachable=no</code> [default]<br>
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]511 <code>--show-reachable=yes</code>
512 <p>When disabled, the memory leak detector only shows blocks for
513 which it cannot find a pointer to at all, or it can only find a
514 pointer to the middle of. These blocks are prime candidates for
515 memory leaks. When enabled, the leak detector also reports on
516 blocks which it could find a pointer to. Your program could, at
517 least in principle, have freed such blocks before exit.
518 Contrast this to blocks for which no pointer, or only an
519 interior pointer could be found: they are more likely to
520 indicate memory leaks, because you do not actually have a
521 pointer to the start of the block which you can hand to
522 <code>free</code>, even if you wanted to. </li><br><p>
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]523
524 <li><code>--leak-resolution=low</code> [default]<br>
525 <code>--leak-resolution=med</code> <br>
526 <code>--leak-resolution=high</code>
527 <p>When doing leak checking, determines how willing Valgrind is
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]528 to consider different backtraces to be the same. When set to
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]529 <code>low</code>, the default, only the first two entries need
530 match. When <code>med</code>, four entries have to match. When
531 <code>high</code>, all entries need to match.
532 <p>
533 For hardcore leak debugging, you probably want to use
534 <code>--leak-resolution=high</code> together with
535 <code>--num-callers=40</code> or some such large number. Note
536 however that this can give an overwhelming amount of
537 information, which is why the defaults are 4 callers and
538 low-resolution matching.
539 <p>
540 Note that the <code>--leak-resolution=</code> setting does not
541 affect Valgrind's ability to find leaks. It only changes how
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]542 the results are presented.
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]543 </li><br><p>
544
545 <li><code>--workaround-gcc296-bugs=no</code> [default]<br>
546 <code>--workaround-gcc296-bugs=yes</code> <p>When enabled,
547 assume that reads and writes some small distance below the stack
548 pointer <code>%esp</code> are due to bugs in gcc 2.96, and does
549 not report them. The "small distance" is 256 bytes by default.
550 Note that gcc 2.96 is the default compiler on some popular Linux
551 distributions (RedHat 7.X, Mandrake) and so you may well need to
552 use this flag. Do not use it if you do not have to, as it can
553 cause real errors to be overlooked. A better option is to use a
554 gcc/g++ which works properly; 2.95.3 seems to be a good choice.
555 <p>
556 Unfortunately (27 Feb 02) it looks like g++ 3.0.4 is similarly
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]557 buggy, so you may need to issue this flag if you use 3.0.4. A
558 while later (early Apr 02) this is confirmed as a scheduling bug
559 in g++-3.0.4.
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]560 </li><br><p>
561
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]562 <li><code>--cachesim=no</code> [default]<br>
sewardj434f57f2002-05-01 01:24:52 +0000[diff] [blame]563 <code>--cachesim=yes</code> <p>When enabled, turns off memory
564 checking, and turns on cache profiling. Cache profiling is
565 described in detail in <a href="#cache">Section 7</a>. </li><p>
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]566</ul>
567
568There are also some options for debugging Valgrind itself. You
569shouldn't need to use them in the normal run of things. Nevertheless:
570
571<ul>
572
573 <li><code>--single-step=no</code> [default]<br>
574 <code>--single-step=yes</code>
575 <p>When enabled, each x86 insn is translated seperately into
576 instrumented code. When disabled, translation is done on a
577 per-basic-block basis, giving much better translations.</li><br>
578 <p>
579
580 <li><code>--optimise=no</code><br>
581 <code>--optimise=yes</code> [default]
582 <p>When enabled, various improvements are applied to the
583 intermediate code, mainly aimed at allowing the simulated CPU's
584 registers to be cached in the real CPU's registers over several
585 simulated instructions.</li><br>
586 <p>
587
588 <li><code>--instrument=no</code><br>
589 <code>--instrument=yes</code> [default]
590 <p>When disabled, the translations don't actually contain any
591 instrumentation.</li><br>
592 <p>
593
594 <li><code>--cleanup=no</code><br>
595 <code>--cleanup=yes</code> [default]
596 <p>When enabled, various improvments are applied to the
597 post-instrumented intermediate code, aimed at removing redundant
598 value checks.</li><br>
599 <p>
600
601 <li><code>--trace-syscalls=no</code> [default]<br>
602 <code>--trace-syscalls=yes</code>
603 <p>Enable/disable tracing of system call intercepts.</li><br>
604 <p>
605
606 <li><code>--trace-signals=no</code> [default]<br>
607 <code>--trace-signals=yes</code>
608 <p>Enable/disable tracing of signal handling.</li><br>
609 <p>
610
sewardjc7529c32002-04-16 01:55:18 +0000[diff] [blame]611 <li><code>--trace-sched=no</code> [default]<br>
612 <code>--trace-sched=yes</code>
613 <p>Enable/disable tracing of thread scheduling events.</li><br>
614 <p>
615
sewardj45b4b372002-04-16 22:50:32 +0000[diff] [blame]616 <li><code>--trace-pthread=none</code> [default]<br>
617 <code>--trace-pthread=some</code> <br>
618 <code>--trace-pthread=all</code>
619 <p>Specifies amount of trace detail for pthread-related events.</li><br>
sewardjc7529c32002-04-16 01:55:18 +0000[diff] [blame]620 <p>
621
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]622 <li><code>--trace-symtab=no</code> [default]<br>
623 <code>--trace-symtab=yes</code>
624 <p>Enable/disable tracing of symbol table reading.</li><br>
625 <p>
626
627 <li><code>--trace-malloc=no</code> [default]<br>
628 <code>--trace-malloc=yes</code>
629 <p>Enable/disable tracing of malloc/free (et al) intercepts.
630 </li><br>
631 <p>
632
633 <li><code>--stop-after=&lt;number></code>
634 [default: infinity, more or less]
635 <p>After &lt;number> basic blocks have been executed, shut down
636 Valgrind and switch back to running the client on the real CPU.
637 </li><br>
638 <p>
639
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]640 <li><code>--dump-error=&lt;number></code> [default: inactive]
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]641 <p>After the program has exited, show gory details of the
642 translation of the basic block containing the &lt;number>'th
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]643 error context. When used with <code>--single-step=yes</code>,
644 can show the exact x86 instruction causing an error. This is
645 all fairly dodgy and doesn't work at all if threads are
646 involved.</li><br>
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]647 <p>
648
649 <li><code>--smc-check=none</code><br>
650 <code>--smc-check=some</code> [default]<br>
651 <code>--smc-check=all</code>
652 <p>How carefully should Valgrind check for self-modifying code
653 writes, so that translations can be discarded?&nbsp; When
654 "none", no writes are checked. When "some", only writes
655 resulting from moves from integer registers to memory are
656 checked. When "all", all memory writes are checked, even those
657 with which are no sane program would generate code -- for
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]658 example, floating-point writes.
659 <p>
660 NOTE that this is all a bit bogus. This mechanism has never
661 been enabled in any snapshot of Valgrind which was made
662 available to the general public, because the extra checks reduce
663 performance, increase complexity, and I have yet to come across
664 any programs which actually use self-modifying code. I think
665 the flag is ignored.
666 </li>
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]667</ul>
668
669
670<a name="errormsgs">
671<h3>2.6&nbsp; Explaination of error messages</h3>
672
673Despite considerable sophistication under the hood, Valgrind can only
674really detect two kinds of errors, use of illegal addresses, and use
675of undefined values. Nevertheless, this is enough to help you
676discover all sorts of memory-management nasties in your code. This
677section presents a quick summary of what error messages mean. The
678precise behaviour of the error-checking machinery is described in
679<a href="#machine">Section 4</a>.
680
681
682<h4>2.6.1&nbsp; Illegal read / Illegal write errors</h4>
683For example:
684<pre>
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]685 Invalid read of size 4
686 at 0x40F6BBCC: (within /usr/lib/libpng.so.2.1.0.9)
687 by 0x40F6B804: (within /usr/lib/libpng.so.2.1.0.9)
688 by 0x40B07FF4: read_png_image__FP8QImageIO (kernel/qpngio.cpp:326)
689 by 0x40AC751B: QImageIO::read() (kernel/qimage.cpp:3621)
690 Address 0xBFFFF0E0 is not stack'd, malloc'd or free'd
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]691</pre>
692
693<p>This happens when your program reads or writes memory at a place
694which Valgrind reckons it shouldn't. In this example, the program did
695a 4-byte read at address 0xBFFFF0E0, somewhere within the
696system-supplied library libpng.so.2.1.0.9, which was called from
697somewhere else in the same library, called from line 326 of
698qpngio.cpp, and so on.
699
700<p>Valgrind tries to establish what the illegal address might relate
701to, since that's often useful. So, if it points into a block of
702memory which has already been freed, you'll be informed of this, and
sewardjc7529c32002-04-16 01:55:18 +0000[diff] [blame]703also where the block was free'd at. Likewise, if it should turn out
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]704to be just off the end of a malloc'd block, a common result of
705off-by-one-errors in array subscripting, you'll be informed of this
706fact, and also where the block was malloc'd.
707
708<p>In this example, Valgrind can't identify the address. Actually the
709address is on the stack, but, for some reason, this is not a valid
710stack address -- it is below the stack pointer, %esp, and that isn't
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]711allowed. In this particular case it's probably caused by gcc
712generating invalid code, a known bug in various flavours of gcc.
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]713
714<p>Note that Valgrind only tells you that your program is about to
715access memory at an illegal address. It can't stop the access from
716happening. So, if your program makes an access which normally would
717result in a segmentation fault, you program will still suffer the same
718fate -- but you will get a message from Valgrind immediately prior to
719this. In this particular example, reading junk on the stack is
720non-fatal, and the program stays alive.
721
722
723<h4>2.6.2&nbsp; Use of uninitialised values</h4>
724For example:
725<pre>
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]726 Conditional jump or move depends on uninitialised value(s)
727 at 0x402DFA94: _IO_vfprintf (_itoa.h:49)
728 by 0x402E8476: _IO_printf (printf.c:36)
729 by 0x8048472: main (tests/manuel1.c:8)
730 by 0x402A6E5E: __libc_start_main (libc-start.c:129)
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]731</pre>
732
733<p>An uninitialised-value use error is reported when your program uses
734a value which hasn't been initialised -- in other words, is undefined.
735Here, the undefined value is used somewhere inside the printf()
736machinery of the C library. This error was reported when running the
737following small program:
738<pre>
739 int main()
740 {
741 int x;
742 printf ("x = %d\n", x);
743 }
744</pre>
745
746<p>It is important to understand that your program can copy around
747junk (uninitialised) data to its heart's content. Valgrind observes
748this and keeps track of the data, but does not complain. A complaint
749is issued only when your program attempts to make use of uninitialised
750data. In this example, x is uninitialised. Valgrind observes the
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]751value being passed to _IO_printf and thence to _IO_vfprintf, but makes
752no comment. However, _IO_vfprintf has to examine the value of x so it
753can turn it into the corresponding ASCII string, and it is at this
754point that Valgrind complains.
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]755
756<p>Sources of uninitialised data tend to be:
757<ul>
758 <li>Local variables in procedures which have not been initialised,
759 as in the example above.</li><br><p>
760
761 <li>The contents of malloc'd blocks, before you write something
762 there. In C++, the new operator is a wrapper round malloc, so
763 if you create an object with new, its fields will be
764 uninitialised until you fill them in, which is only Right and
765 Proper.</li>
766</ul>
767
768
769
770<h4>2.6.3&nbsp; Illegal frees</h4>
771For example:
772<pre>
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]773 Invalid free()
774 at 0x4004FFDF: free (ut_clientmalloc.c:577)
775 by 0x80484C7: main (tests/doublefree.c:10)
776 by 0x402A6E5E: __libc_start_main (libc-start.c:129)
777 by 0x80483B1: (within tests/doublefree)
778 Address 0x3807F7B4 is 0 bytes inside a block of size 177 free'd
779 at 0x4004FFDF: free (ut_clientmalloc.c:577)
780 by 0x80484C7: main (tests/doublefree.c:10)
781 by 0x402A6E5E: __libc_start_main (libc-start.c:129)
782 by 0x80483B1: (within tests/doublefree)
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]783</pre>
784<p>Valgrind keeps track of the blocks allocated by your program with
785malloc/new, so it can know exactly whether or not the argument to
786free/delete is legitimate or not. Here, this test program has
787freed the same block twice. As with the illegal read/write errors,
788Valgrind attempts to make sense of the address free'd. If, as
789here, the address is one which has previously been freed, you wil
790be told that -- making duplicate frees of the same block easy to spot.
791
792
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]793<h4>2.6.4&nbsp; When a block is freed with an inappropriate
794deallocation function</h4>
795For example:
796<pre>
797 Mismatched free() / delete / delete []
798 at 0x40303847: DeviceContextImpl::~DeviceContextImpl(void)
799 by 0x45149BCB: nsDeviceContextGTK::~nsDeviceContextGTK(void)
800 by 0x4030341A: DeviceContextImpl::Release(void)
801 by 0x460C0CAC: nsBaseWidget::OnDestroy(void)
802 Address 0x41C11A7C is 0 bytes inside a block of size 120 alloc'd
803 at 0x40040BEC: malloc (vg_clientfuncs.c:100)
804 by 0x4516DAAC: ??? (../../gcc-2.95.3/gcc/cp/new1.cc:78)
805 by 0x4515FA11: nsDeviceContextGTKConstructor(nsISupports *, ...
806 by 0x40553ABB: nsGenericFactory::CreateInstance(nsISupports *, ...
807</pre>
808The following was told to me be the KDE 3 developers. I didn't know
809any of it myself. They also implemented the check itself.
810<p>
811In C++ it's important to deallocate memory in a way compatible with
812how it was allocated. The deal is:
813<ul>
814<li>If allocated with <code>malloc</code>, <code>calloc</code>,
815 <code>realloc</code>, <code>valloc</code> or
816 <code>memalign</code>, you must deallocate with <code>free</code>.
817<li>If allocated with <code>new []</code>, you must deallocate with
818 <code>delete []</code>.
819<li>If allocated with <code>new</code>, you must deallocate with
820 <code>delete</code>.
821</ul>
822The worst thing is that on Linux apparently it doesn't matter if you
823do muddle these up, and it all seems to work ok, but the same program
824may then crash on a different platform, Solaris for example. So it's
825best to fix it properly. According to the KDE folks "it's amazing how
826many C++ programmers don't know this".
827
828
829
830<h4>2.6.5&nbsp; Passing system call parameters with inadequate
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]831read/write permissions</h4>
832
833Valgrind checks all parameters to system calls. If a system call
834needs to read from a buffer provided by your program, Valgrind checks
835that the entire buffer is addressible and has valid data, ie, it is
836readable. And if the system call needs to write to a user-supplied
837buffer, Valgrind checks that the buffer is addressible. After the
838system call, Valgrind updates its administrative information to
839precisely reflect any changes in memory permissions caused by the
840system call.
841
842<p>Here's an example of a system call with an invalid parameter:
843<pre>
844 #include &lt;stdlib.h>
845 #include &lt;unistd.h>
846 int main( void )
847 {
848 char* arr = malloc(10);
849 (void) write( 1 /* stdout */, arr, 10 );
850 return 0;
851 }
852</pre>
853
854<p>You get this complaint ...
855<pre>
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]856 Syscall param write(buf) contains uninitialised or unaddressable byte(s)
857 at 0x4035E072: __libc_write
858 by 0x402A6E5E: __libc_start_main (libc-start.c:129)
859 by 0x80483B1: (within tests/badwrite)
860 by &lt;bogus frame pointer> ???
861 Address 0x3807E6D0 is 0 bytes inside a block of size 10 alloc'd
862 at 0x4004FEE6: malloc (ut_clientmalloc.c:539)
863 by 0x80484A0: main (tests/badwrite.c:6)
864 by 0x402A6E5E: __libc_start_main (libc-start.c:129)
865 by 0x80483B1: (within tests/badwrite)
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]866</pre>
867
868<p>... because the program has tried to write uninitialised junk from
869the malloc'd block to the standard output.
870
871
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]872<h4>2.6.6&nbsp; Warning messages you might see</h4>
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]873
874Most of these only appear if you run in verbose mode (enabled by
875<code>-v</code>):
876<ul>
877<li> <code>More than 50 errors detected. Subsequent errors
878 will still be recorded, but in less detail than before.</code>
879 <br>
880 After 50 different errors have been shown, Valgrind becomes
881 more conservative about collecting them. It then requires only
882 the program counters in the top two stack frames to match when
883 deciding whether or not two errors are really the same one.
884 Prior to this point, the PCs in the top four frames are required
885 to match. This hack has the effect of slowing down the
886 appearance of new errors after the first 50. The 50 constant can
887 be changed by recompiling Valgrind.
888<p>
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]889<li> <code>More than 300 errors detected. I'm not reporting any more.
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]890 Final error counts may be inaccurate. Go fix your
891 program!</code>
892 <br>
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]893 After 300 different errors have been detected, Valgrind ignores
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]894 any more. It seems unlikely that collecting even more different
895 ones would be of practical help to anybody, and it avoids the
896 danger that Valgrind spends more and more of its time comparing
897 new errors against an ever-growing collection. As above, the 500
898 number is a compile-time constant.
899<p>
900<li> <code>Warning: client exiting by calling exit(&lt;number>).
901 Bye!</code>
902 <br>
903 Your program has called the <code>exit</code> system call, which
904 will immediately terminate the process. You'll get no exit-time
905 error summaries or leak checks. Note that this is not the same
906 as your program calling the ANSI C function <code>exit()</code>
907 -- that causes a normal, controlled shutdown of Valgrind.
908<p>
909<li> <code>Warning: client switching stacks?</code>
910 <br>
911 Valgrind spotted such a large change in the stack pointer, %esp,
912 that it guesses the client is switching to a different stack.
913 At this point it makes a kludgey guess where the base of the new
914 stack is, and sets memory permissions accordingly. You may get
915 many bogus error messages following this, if Valgrind guesses
916 wrong. At the moment "large change" is defined as a change of
917 more that 2000000 in the value of the %esp (stack pointer)
918 register.
919<p>
920<li> <code>Warning: client attempted to close Valgrind's logfile fd &lt;number>
921 </code>
922 <br>
923 Valgrind doesn't allow the client
924 to close the logfile, because you'd never see any diagnostic
925 information after that point. If you see this message,
926 you may want to use the <code>--logfile-fd=&lt;number></code>
927 option to specify a different logfile file-descriptor number.
928<p>
929<li> <code>Warning: noted but unhandled ioctl &lt;number></code>
930 <br>
931 Valgrind observed a call to one of the vast family of
932 <code>ioctl</code> system calls, but did not modify its
933 memory status info (because I have not yet got round to it).
934 The call will still have gone through, but you may get spurious
935 errors after this as a result of the non-update of the memory info.
936<p>
937<li> <code>Warning: unblocking signal &lt;number> due to
938 sigprocmask</code>
939 <br>
940 Really just a diagnostic from the signal simulation machinery.
941 This message will appear if your program handles a signal by
942 first <code>longjmp</code>ing out of the signal handler,
943 and then unblocking the signal with <code>sigprocmask</code>
944 -- a standard signal-handling idiom.
945<p>
946<li> <code>Warning: bad signal number &lt;number> in __NR_sigaction.</code>
947 <br>
948 Probably indicates a bug in the signal simulation machinery.
949<p>
950<li> <code>Warning: set address range perms: large range &lt;number></code>
951 <br>
952 Diagnostic message, mostly for my benefit, to do with memory
953 permissions.
954</ul>
955
956
957<a name="suppfiles"></a>
958<h3>2.7&nbsp; Writing suppressions files</h3>
959
960A suppression file describes a bunch of errors which, for one reason
961or another, you don't want Valgrind to tell you about. Usually the
962reason is that the system libraries are buggy but unfixable, at least
963within the scope of the current debugging session. Multiple
964suppresions files are allowed. By default, Valgrind uses
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]965<code>$PREFIX/lib/valgrind/default.supp</code>.
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]966
967<p>
968You can ask to add suppressions from another file, by specifying
969<code>--suppressions=/path/to/file.supp</code>.
970
971<p>Each suppression has the following components:<br>
972<ul>
973
974 <li>Its name. This merely gives a handy name to the suppression, by
975 which it is referred to in the summary of used suppressions
976 printed out when a program finishes. It's not important what
977 the name is; any identifying string will do.
978 <p>
979
980 <li>The nature of the error to suppress. Either:
981 <code>Value1</code>,
982 <code>Value2</code>,
sewardja7dc7952002-03-24 11:29:13 +0000[diff] [blame]983 <code>Value4</code> or
984 <code>Value8</code>,
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]985 meaning an uninitialised-value error when
sewardja7dc7952002-03-24 11:29:13 +0000[diff] [blame]986 using a value of 1, 2, 4 or 8 bytes.
987 Or
988 <code>Cond</code> (or its old name, <code>Value0</code>),
989 meaning use of an uninitialised CPU condition code. Or:
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]990 <code>Addr1</code>,
991 <code>Addr2</code>,
992 <code>Addr4</code> or
993 <code>Addr8</code>, meaning an invalid address during a
994 memory access of 1, 2, 4 or 8 bytes respectively. Or
995 <code>Param</code>,
996 meaning an invalid system call parameter error. Or
997 <code>Free</code>, meaning an invalid or mismatching free.</li><br>
998 <p>
999
1000 <li>The "immediate location" specification. For Value and Addr
1001 errors, is either the name of the function in which the error
1002 occurred, or, failing that, the full path the the .so file
1003 containing the error location. For Param errors, is the name of
1004 the offending system call parameter. For Free errors, is the
1005 name of the function doing the freeing (eg, <code>free</code>,
1006 <code>__builtin_vec_delete</code>, etc)</li><br>
1007 <p>
1008
1009 <li>The caller of the above "immediate location". Again, either a
1010 function or shared-object name.</li><br>
1011 <p>
1012
1013 <li>Optionally, one or two extra calling-function or object names,
1014 for greater precision.</li>
1015</ul>
1016
1017<p>
1018Locations may be either names of shared objects or wildcards matching
1019function names. They begin <code>obj:</code> and <code>fun:</code>
1020respectively. Function and object names to match against may use the
1021wildcard characters <code>*</code> and <code>?</code>.
1022
1023A suppression only suppresses an error when the error matches all the
1024details in the suppression. Here's an example:
1025<pre>
1026 {
1027 __gconv_transform_ascii_internal/__mbrtowc/mbtowc
1028 Value4
1029 fun:__gconv_transform_ascii_internal
1030 fun:__mbr*toc
1031 fun:mbtowc
1032 }
1033</pre>
1034
1035<p>What is means is: suppress a use-of-uninitialised-value error, when
1036the data size is 4, when it occurs in the function
1037<code>__gconv_transform_ascii_internal</code>, when that is called
1038from any function of name matching <code>__mbr*toc</code>,
1039when that is called from
1040<code>mbtowc</code>. It doesn't apply under any other circumstances.
1041The string by which this suppression is identified to the user is
1042__gconv_transform_ascii_internal/__mbrtowc/mbtowc.
1043
1044<p>Another example:
1045<pre>
1046 {
1047 libX11.so.6.2/libX11.so.6.2/libXaw.so.7.0
1048 Value4
1049 obj:/usr/X11R6/lib/libX11.so.6.2
1050 obj:/usr/X11R6/lib/libX11.so.6.2
1051 obj:/usr/X11R6/lib/libXaw.so.7.0
1052 }
1053</pre>
1054
1055<p>Suppress any size 4 uninitialised-value error which occurs anywhere
1056in <code>libX11.so.6.2</code>, when called from anywhere in the same
1057library, when called from anywhere in <code>libXaw.so.7.0</code>. The
1058inexact specification of locations is regrettable, but is about all
1059you can hope for, given that the X11 libraries shipped with Red Hat
10607.2 have had their symbol tables removed.
1061
1062<p>Note -- since the above two examples did not make it clear -- that
1063you can freely mix the <code>obj:</code> and <code>fun:</code>
1064styles of description within a single suppression record.
1065
1066
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]1067<a name="clientreq"></a>
1068<h3>2.8&nbsp; The Client Request mechanism</h3>
sewardjc7529c32002-04-16 01:55:18 +0000[diff] [blame]1069
1070Valgrind has a trapdoor mechanism via which the client program can
1071pass all manner of requests and queries to Valgrind. Internally, this
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]1072is used extensively to make malloc, free, signals, threads, etc, work,
1073although you don't see that.
sewardjc7529c32002-04-16 01:55:18 +0000[diff] [blame]1074<p>
1075For your convenience, a subset of these so-called client requests is
1076provided to allow you to tell Valgrind facts about the behaviour of
1077your program, and conversely to make queries. In particular, your
1078program can tell Valgrind about changes in memory range permissions
1079that Valgrind would not otherwise know about, and so allows clients to
1080get Valgrind to do arbitrary custom checks.
1081<p>
1082Clients need to include the header file <code>valgrind.h</code> to
1083make this work. The macros therein have the magical property that
1084they generate code in-line which Valgrind can spot. However, the code
1085does nothing when not run on Valgrind, so you are not forced to run
1086your program on Valgrind just because you use the macros in this file.
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]1087Also, you are not required to link your program with any extra
1088supporting libraries.
sewardjc7529c32002-04-16 01:55:18 +0000[diff] [blame]1089<p>
1090A brief description of the available macros:
1091<ul>
1092<li><code>VALGRIND_MAKE_NOACCESS</code>,
1093 <code>VALGRIND_MAKE_WRITABLE</code> and
1094 <code>VALGRIND_MAKE_READABLE</code>. These mark address
1095 ranges as completely inaccessible, accessible but containing
1096 undefined data, and accessible and containing defined data,
1097 respectively. Subsequent errors may have their faulting
1098 addresses described in terms of these blocks. Returns a
1099 "block handle". Returns zero when not run on Valgrind.
1100<p>
1101<li><code>VALGRIND_DISCARD</code>: At some point you may want
1102 Valgrind to stop reporting errors in terms of the blocks
1103 defined by the previous three macros. To do this, the above
1104 macros return a small-integer "block handle". You can pass
1105 this block handle to <code>VALGRIND_DISCARD</code>. After
1106 doing so, Valgrind will no longer be able to relate
1107 addressing errors to the user-defined block associated with
1108 the handle. The permissions settings associated with the
1109 handle remain in place; this just affects how errors are
1110 reported, not whether they are reported. Returns 1 for an
1111 invalid handle and 0 for a valid handle (although passing
1112 invalid handles is harmless). Always returns 0 when not run
1113 on Valgrind.
1114<p>
1115<li><code>VALGRIND_CHECK_NOACCESS</code>,
1116 <code>VALGRIND_CHECK_WRITABLE</code> and
1117 <code>VALGRIND_CHECK_READABLE</code>: check immediately
1118 whether or not the given address range has the relevant
1119 property, and if not, print an error message. Also, for the
1120 convenience of the client, returns zero if the relevant
1121 property holds; otherwise, the returned value is the address
1122 of the first byte for which the property is not true.
1123 Always returns 0 when not run on Valgrind.
1124<p>
1125<li><code>VALGRIND_CHECK_NOACCESS</code>: a quick and easy way
1126 to find out whether Valgrind thinks a particular variable
1127 (lvalue, to be precise) is addressible and defined. Prints
1128 an error message if not. Returns no value.
1129<p>
1130<li><code>VALGRIND_MAKE_NOACCESS_STACK</code>: a highly
1131 experimental feature. Similarly to
1132 <code>VALGRIND_MAKE_NOACCESS</code>, this marks an address
1133 range as inaccessible, so that subsequent accesses to an
1134 address in the range gives an error. However, this macro
1135 does not return a block handle. Instead, all annotations
1136 created like this are reviewed at each client
1137 <code>ret</code> (subroutine return) instruction, and those
1138 which now define an address range block the client's stack
1139 pointer register (<code>%esp</code>) are automatically
1140 deleted.
1141 <p>
1142 In other words, this macro allows the client to tell
1143 Valgrind about red-zones on its own stack. Valgrind
1144 automatically discards this information when the stack
1145 retreats past such blocks. Beware: hacky and flaky, and
1146 probably interacts badly with the new pthread support.
sewardjc7529c32002-04-16 01:55:18 +0000[diff] [blame]1147<p>
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]1148<li><code>RUNNING_ON_VALGRIND</code>: returns 1 if running on
1149 Valgrind, 0 if running on the real CPU.
1150<p>
1151<li><code>VALGRIND_DO_LEAK_CHECK</code>: run the memory leak detector
1152 right now. Returns no value. I guess this could be used to
1153 incrementally check for leaks between arbitrary places in the
1154 program's execution. Warning: not properly tested!
1155</ul>
1156<p>
1157
1158
1159<a name="pthreads"></a>
1160<h3>2.9&nbsp; Support for POSIX Pthreads</h3>
1161
1162As of late April 02, Valgrind supports programs which use POSIX
1163pthreads. Doing this has proved technically challenging and is still
1164in progress, but it works well enough, as of 1 May 02, for significant
1165threaded applications to work.
1166<p>
1167It works as follows: threaded apps are (dynamically) linked against
1168<code>libpthread.so</code>. Usually this is the one installed with
1169your Linux distribution. Valgrind, however, supplies its own
1170<code>libpthread.so</code> and automatically connects your program to
1171it instead.
1172<p>
1173The fake <code>libpthread.so</code> and Valgrind cooperate to
1174implement a user-space pthreads package. This approach avoids the
1175horrible implementation problems of implementing a truly
1176multiprocessor version of Valgrind, but it does mean that threaded
1177apps run only on one CPU, even if you have a multiprocessor machine.
1178<p>
1179Valgrind schedules your threads in a round-robin fashion, with all
1180threads having equal priority. It switches threads every 20000 basic
1181blocks (typically around 120000 x86 instructions), which means you'll
1182get a much finer interleaving of thread executions than when run
1183natively. This in itself may cause your program to behave differently
1184if you have some kind of concurrency, critical race, locking, or
1185similar, bugs.
1186<p>
1187The current (1 May 02) state of pthread support is as follows. Please
1188note that things are advancing rapidly, so the situation may have
1189improved by the time you read this -- check the web site for further
1190updates.
1191<ul>
1192<li>Mutexes, condition variables, thread-specific data and
1193 <code>pthread_once</code> currently work.
1194<p>
1195<li>Various attribute-like calls are handled but ignored.
1196 You get a warning message.
1197<p>
1198<li>The main big omission is proper cleanup support for cancellation.
1199 <code>pthread_cancel</code> works, but instantly nukes the target
1200 thread without giving it any chance to clean up. Also, when a
1201 thread exits, it does not run any cleanup handlers.
1202<p>
1203<li>Currently the following syscalls are thread-safe (nonblocking):
1204 <code>write</code> <code>read</code> <code>nanosleep</code>
1205 <code>sleep</code> <code>select</code> and <code>poll</code>.
1206<p>
1207<li>The POSIX requirement that each thread have its own
1208 signal-blocking mask is not done; the signal handling mechanism is
1209 thread-unaware and all signals are delivered to the main thread,
1210 antidisirregardless.
1211</ul>
1212
1213
1214As of 1 May 02, the following programs now work fine on my RedHat 7.2
1215box: Opera 6.0Beta2, KNode in KDE 3.0, Mozilla-0.9.2.1 and
1216Galeon-0.11.3, both as supplied with RedHat 7.2.
1217<p>
1218Mozilla 1.0RC1 crashes because it jumps to location zero: <code>Jump
1219to the invalid address stated on the next line</code>. Other people
1220have reported the same thing. Despite considerable effort in tracking
1221this down, I cannot figure out what's going on. If you have a program
1222which does this, is small enough that I have half a hope of making
1223sense of it, and is open-source (or at least you'd be happy for me to
1224look at), I'd be very grateful to have it.
1225<p>
1226On the other hand, I have received mail from at least one person
1227who appears to be successful in running CVS builds of Mozilla on
1228Valgrind.
1229
1230
1231
1232<a name="install"></a>
1233<h3>2.10&nbsp; Building and installing</h3>
1234
1235We now use the standard Unix <code>./configure</code>,
1236<code>make</code>, <code>make install</code> mechanism, and I have
1237attempted to ensure that it works on machines with kernel 2.2 or 2.4
1238and glibc 2.1.X or 2.2.X. I don't think there is much else to say.
1239There are no options apart from the usual <code>--prefix</code> that
1240you should give to <code>./configure</code>.
1241<p>
1242Let me know if you have build problems.
sewardjc7529c32002-04-16 01:55:18 +0000[diff] [blame]1243
1244
1245
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]1246<a name="problems"></a>
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]1247<h3>2.11&nbsp; If you have problems</h3>
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]1248Mail me (<a href="mailto:jseward@acm.org">jseward@acm.org</a>).
1249
1250<p>See <a href="#limits">Section 4</a> for the known limitations of
1251Valgrind, and for a list of programs which are known not to work on
1252it.
1253
1254<p>The translator/instrumentor has a lot of assertions in it. They
1255are permanently enabled, and I have no plans to disable them. If one
1256of these breaks, please mail me!
1257
1258<p>If you get an assertion failure on the expression
1259<code>chunkSane(ch)</code> in <code>vg_free()</code> in
1260<code>vg_malloc.c</code>, this may have happened because your program
1261wrote off the end of a malloc'd block, or before its beginning.
1262Valgrind should have emitted a proper message to that effect before
1263dying in this way. This is a known problem which I should fix.
1264<p>
1265
1266<hr width="100%">
1267
1268<a name="machine"></a>
1269<h2>3&nbsp; Details of the checking machinery</h2>
1270
1271Read this section if you want to know, in detail, exactly what and how
1272Valgrind is checking.
1273
1274<a name="vvalue"></a>
1275<h3>3.1&nbsp; Valid-value (V) bits</h3>
1276
1277It is simplest to think of Valgrind implementing a synthetic Intel x86
1278CPU which is identical to a real CPU, except for one crucial detail.
1279Every bit (literally) of data processed, stored and handled by the
1280real CPU has, in the synthetic CPU, an associated "valid-value" bit,
1281which says whether or not the accompanying bit has a legitimate value.
1282In the discussions which follow, this bit is referred to as the V
1283(valid-value) bit.
1284
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]1285<p>Each byte in the system therefore has a 8 V bits which follow
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]1286it wherever it goes. For example, when the CPU loads a word-size item
1287(4 bytes) from memory, it also loads the corresponding 32 V bits from
1288a bitmap which stores the V bits for the process' entire address
1289space. If the CPU should later write the whole or some part of that
1290value to memory at a different address, the relevant V bits will be
1291stored back in the V-bit bitmap.
1292
1293<p>In short, each bit in the system has an associated V bit, which
1294follows it around everywhere, even inside the CPU. Yes, the CPU's
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]1295(integer and <code>%eflags</code>) registers have their own V bit
1296vectors.
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]1297
1298<p>Copying values around does not cause Valgrind to check for, or
1299report on, errors. However, when a value is used in a way which might
1300conceivably affect the outcome of your program's computation, the
1301associated V bits are immediately checked. If any of these indicate
1302that the value is undefined, an error is reported.
1303
1304<p>Here's an (admittedly nonsensical) example:
1305<pre>
1306 int i, j;
1307 int a[10], b[10];
1308 for (i = 0; i &lt; 10; i++) {
1309 j = a[i];
1310 b[i] = j;
1311 }
1312</pre>
1313
1314<p>Valgrind emits no complaints about this, since it merely copies
1315uninitialised values from <code>a[]</code> into <code>b[]</code>, and
1316doesn't use them in any way. However, if the loop is changed to
1317<pre>
1318 for (i = 0; i &lt; 10; i++) {
1319 j += a[i];
1320 }
1321 if (j == 77)
1322 printf("hello there\n");
1323</pre>
1324then Valgrind will complain, at the <code>if</code>, that the
1325condition depends on uninitialised values.
1326
1327<p>Most low level operations, such as adds, cause Valgrind to
1328use the V bits for the operands to calculate the V bits for the
1329result. Even if the result is partially or wholly undefined,
1330it does not complain.
1331
1332<p>Checks on definedness only occur in two places: when a value is
1333used to generate a memory address, and where control flow decision
1334needs to be made. Also, when a system call is detected, valgrind
1335checks definedness of parameters as required.
1336
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]1337<p>If a check should detect undefinedness, an error message is
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]1338issued. The resulting value is subsequently regarded as well-defined.
1339To do otherwise would give long chains of error messages. In effect,
1340we say that undefined values are non-infectious.
1341
1342<p>This sounds overcomplicated. Why not just check all reads from
1343memory, and complain if an undefined value is loaded into a CPU register?
1344Well, that doesn't work well, because perfectly legitimate C programs routinely
1345copy uninitialised values around in memory, and we don't want endless complaints
1346about that. Here's the canonical example. Consider a struct
1347like this:
1348<pre>
1349 struct S { int x; char c; };
1350 struct S s1, s2;
1351 s1.x = 42;
1352 s1.c = 'z';
1353 s2 = s1;
1354</pre>
1355
1356<p>The question to ask is: how large is <code>struct S</code>, in
1357bytes? An int is 4 bytes and a char one byte, so perhaps a struct S
1358occupies 5 bytes? Wrong. All (non-toy) compilers I know of will
1359round the size of <code>struct S</code> up to a whole number of words,
1360in this case 8 bytes. Not doing this forces compilers to generate
1361truly appalling code for subscripting arrays of <code>struct
1362S</code>'s.
1363
1364<p>So s1 occupies 8 bytes, yet only 5 of them will be initialised.
1365For the assignment <code>s2 = s1</code>, gcc generates code to copy
1366all 8 bytes wholesale into <code>s2</code> without regard for their
1367meaning. If Valgrind simply checked values as they came out of
1368memory, it would yelp every time a structure assignment like this
1369happened. So the more complicated semantics described above is
1370necessary. This allows gcc to copy <code>s1</code> into
1371<code>s2</code> any way it likes, and a warning will only be emitted
1372if the uninitialised values are later used.
1373
1374<p>One final twist to this story. The above scheme allows garbage to
1375pass through the CPU's integer registers without complaint. It does
1376this by giving the integer registers V tags, passing these around in
1377the expected way. This complicated and computationally expensive to
1378do, but is necessary. Valgrind is more simplistic about
1379floating-point loads and stores. In particular, V bits for data read
1380as a result of floating-point loads are checked at the load
1381instruction. So if your program uses the floating-point registers to
1382do memory-to-memory copies, you will get complaints about
1383uninitialised values. Fortunately, I have not yet encountered a
1384program which (ab)uses the floating-point registers in this way.
1385
1386<a name="vaddress"></a>
1387<h3>3.2&nbsp; Valid-address (A) bits</h3>
1388
1389Notice that the previous section describes how the validity of values
1390is established and maintained without having to say whether the
1391program does or does not have the right to access any particular
1392memory location. We now consider the latter issue.
1393
1394<p>As described above, every bit in memory or in the CPU has an
1395associated valid-value (V) bit. In addition, all bytes in memory, but
1396not in the CPU, have an associated valid-address (A) bit. This
1397indicates whether or not the program can legitimately read or write
1398that location. It does not give any indication of the validity or the
1399data at that location -- that's the job of the V bits -- only whether
1400or not the location may be accessed.
1401
1402<p>Every time your program reads or writes memory, Valgrind checks the
1403A bits associated with the address. If any of them indicate an
1404invalid address, an error is emitted. Note that the reads and writes
1405themselves do not change the A bits, only consult them.
1406
1407<p>So how do the A bits get set/cleared? Like this:
1408
1409<ul>
1410 <li>When the program starts, all the global data areas are marked as
1411 accessible.</li><br>
1412 <p>
1413
1414 <li>When the program does malloc/new, the A bits for the exactly the
1415 area allocated, and not a byte more, are marked as accessible.
1416 Upon freeing the area the A bits are changed to indicate
1417 inaccessibility.</li><br>
1418 <p>
1419
1420 <li>When the stack pointer register (%esp) moves up or down, A bits
1421 are set. The rule is that the area from %esp up to the base of
1422 the stack is marked as accessible, and below %esp is
1423 inaccessible. (If that sounds illogical, bear in mind that the
1424 stack grows down, not up, on almost all Unix systems, including
1425 GNU/Linux.) Tracking %esp like this has the useful side-effect
1426 that the section of stack used by a function for local variables
1427 etc is automatically marked accessible on function entry and
1428 inaccessible on exit.</li><br>
1429 <p>
1430
1431 <li>When doing system calls, A bits are changed appropriately. For
1432 example, mmap() magically makes files appear in the process's
1433 address space, so the A bits must be updated if mmap()
1434 succeeds.</li><br>
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]1435 <p>
1436
1437 <li>Optionally, your program can tell Valgrind about such changes
1438 explicitly, using the client request mechanism described above.
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]1439</ul>
1440
1441
1442<a name="together"></a>
1443<h3>3.3&nbsp; Putting it all together</h3>
1444Valgrind's checking machinery can be summarised as follows:
1445
1446<ul>
1447 <li>Each byte in memory has 8 associated V (valid-value) bits,
1448 saying whether or not the byte has a defined value, and a single
1449 A (valid-address) bit, saying whether or not the program
1450 currently has the right to read/write that address.</li><br>
1451 <p>
1452
1453 <li>When memory is read or written, the relevant A bits are
1454 consulted. If they indicate an invalid address, Valgrind emits
1455 an Invalid read or Invalid write error.</li><br>
1456 <p>
1457
1458 <li>When memory is read into the CPU's integer registers, the
1459 relevant V bits are fetched from memory and stored in the
1460 simulated CPU. They are not consulted.</li><br>
1461 <p>
1462
1463 <li>When an integer register is written out to memory, the V bits
1464 for that register are written back to memory too.</li><br>
1465 <p>
1466
1467 <li>When memory is read into the CPU's floating point registers, the
1468 relevant V bits are read from memory and they are immediately
1469 checked. If any are invalid, an uninitialised value error is
1470 emitted. This precludes using the floating-point registers to
1471 copy possibly-uninitialised memory, but simplifies Valgrind in
1472 that it does not have to track the validity status of the
1473 floating-point registers.</li><br>
1474 <p>
1475
1476 <li>As a result, when a floating-point register is written to
1477 memory, the associated V bits are set to indicate a valid
1478 value.</li><br>
1479 <p>
1480
1481 <li>When values in integer CPU registers are used to generate a
1482 memory address, or to determine the outcome of a conditional
1483 branch, the V bits for those values are checked, and an error
1484 emitted if any of them are undefined.</li><br>
1485 <p>
1486
1487 <li>When values in integer CPU registers are used for any other
1488 purpose, Valgrind computes the V bits for the result, but does
1489 not check them.</li><br>
1490 <p>
1491
1492 <li>One the V bits for a value in the CPU have been checked, they
1493 are then set to indicate validity. This avoids long chains of
1494 errors.</li><br>
1495 <p>
1496
1497 <li>When values are loaded from memory, valgrind checks the A bits
1498 for that location and issues an illegal-address warning if
1499 needed. In that case, the V bits loaded are forced to indicate
1500 Valid, despite the location being invalid.
1501 <p>
1502 This apparently strange choice reduces the amount of confusing
1503 information presented to the user. It avoids the
1504 unpleasant phenomenon in which memory is read from a place which
1505 is both unaddressible and contains invalid values, and, as a
1506 result, you get not only an invalid-address (read/write) error,
1507 but also a potentially large set of uninitialised-value errors,
1508 one for every time the value is used.
1509 <p>
1510 There is a hazy boundary case to do with multi-byte loads from
1511 addresses which are partially valid and partially invalid. See
1512 details of the flag <code>--partial-loads-ok</code> for details.
1513 </li><br>
1514</ul>
1515
1516Valgrind intercepts calls to malloc, calloc, realloc, valloc,
1517memalign, free, new and delete. The behaviour you get is:
1518
1519<ul>
1520
1521 <li>malloc/new: the returned memory is marked as addressible but not
1522 having valid values. This means you have to write on it before
1523 you can read it.</li><br>
1524 <p>
1525
1526 <li>calloc: returned memory is marked both addressible and valid,
1527 since calloc() clears the area to zero.</li><br>
1528 <p>
1529
1530 <li>realloc: if the new size is larger than the old, the new section
1531 is addressible but invalid, as with malloc.</li><br>
1532 <p>
1533
1534 <li>If the new size is smaller, the dropped-off section is marked as
1535 unaddressible. You may only pass to realloc a pointer
1536 previously issued to you by malloc/calloc/new/realloc.</li><br>
1537 <p>
1538
1539 <li>free/delete: you may only pass to free a pointer previously
1540 issued to you by malloc/calloc/new/realloc, or the value
1541 NULL. Otherwise, Valgrind complains. If the pointer is indeed
1542 valid, Valgrind marks the entire area it points at as
1543 unaddressible, and places the block in the freed-blocks-queue.
1544 The aim is to defer as long as possible reallocation of this
1545 block. Until that happens, all attempts to access it will
1546 elicit an invalid-address error, as you would hope.</li><br>
1547</ul>
1548
1549
1550
1551<a name="signals"></a>
1552<h3>3.4&nbsp; Signals</h3>
1553
1554Valgrind provides suitable handling of signals, so, provided you stick
1555to POSIX stuff, you should be ok. Basic sigaction() and sigprocmask()
1556are handled. Signal handlers may return in the normal way or do
1557longjmp(); both should work ok. As specified by POSIX, a signal is
1558blocked in its own handler. Default actions for signals should work
1559as before. Etc, etc.
1560
1561<p>Under the hood, dealing with signals is a real pain, and Valgrind's
1562simulation leaves much to be desired. If your program does
1563way-strange stuff with signals, bad things may happen. If so, let me
1564know. I don't promise to fix it, but I'd at least like to be aware of
1565it.
1566
1567
1568<a name="leaks"><a/>
1569<h3>3.5&nbsp; Memory leak detection</h3>
1570
1571Valgrind keeps track of all memory blocks issued in response to calls
1572to malloc/calloc/realloc/new. So when the program exits, it knows
1573which blocks are still outstanding -- have not been returned, in other
1574words. Ideally, you want your program to have no blocks still in use
1575at exit. But many programs do.
1576
1577<p>For each such block, Valgrind scans the entire address space of the
1578process, looking for pointers to the block. One of three situations
1579may result:
1580
1581<ul>
1582 <li>A pointer to the start of the block is found. This usually
1583 indicates programming sloppiness; since the block is still
1584 pointed at, the programmer could, at least in principle, free'd
1585 it before program exit.</li><br>
1586 <p>
1587
1588 <li>A pointer to the interior of the block is found. The pointer
1589 might originally have pointed to the start and have been moved
1590 along, or it might be entirely unrelated. Valgrind deems such a
1591 block as "dubious", that is, possibly leaked,
1592 because it's unclear whether or
1593 not a pointer to it still exists.</li><br>
1594 <p>
1595
1596 <li>The worst outcome is that no pointer to the block can be found.
1597 The block is classified as "leaked", because the
1598 programmer could not possibly have free'd it at program exit,
1599 since no pointer to it exists. This might be a symptom of
1600 having lost the pointer at some earlier point in the
1601 program.</li>
1602</ul>
1603
1604Valgrind reports summaries about leaked and dubious blocks.
1605For each such block, it will also tell you where the block was
1606allocated. This should help you figure out why the pointer to it has
1607been lost. In general, you should attempt to ensure your programs do
1608not have any leaked or dubious blocks at exit.
1609
1610<p>The precise area of memory in which Valgrind searches for pointers
1611is: all naturally-aligned 4-byte words for which all A bits indicate
1612addressibility and all V bits indicated that the stored value is
1613actually valid.
1614
1615<p><hr width="100%">
1616
1617
1618<a name="limits"></a>
1619<h2>4&nbsp; Limitations</h2>
1620
1621The following list of limitations seems depressingly long. However,
1622most programs actually work fine.
1623
1624<p>Valgrind will run x86-GNU/Linux ELF dynamically linked binaries, on
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]1625a kernel 2.2.X or 2.4.X system, subject to the following constraints:
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]1626
1627<ul>
1628 <li>No MMX, SSE, SSE2, 3DNow instructions. If the translator
1629 encounters these, Valgrind will simply give up. It may be
1630 possible to add support for them at a later time. Intel added a
1631 few instructions such as "cmov" to the integer instruction set
1632 on Pentium and later processors, and these are supported.
1633 Nevertheless it's safest to think of Valgrind as implementing
1634 the 486 instruction set.</li><br>
1635 <p>
1636
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]1637 <li>Pthreads support is improving, but there are still significant
1638 limitations in that department. See the section above on
1639 Pthreads. Note that your program must be dynamically linked
1640 against <code>libpthread.so</code>, so that Valgrind can
1641 substitute its own implementation at program startup time. If
1642 you're statically linked against it, things will fail
1643 badly.</li><br>
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]1644 <p>
1645
1646 <li>Valgrind assumes that the floating point registers are not used
1647 as intermediaries in memory-to-memory copies, so it immediately
1648 checks V bits in floating-point loads/stores. If you want to
1649 write code which copies around possibly-uninitialised values,
1650 you must ensure these travel through the integer registers, not
1651 the FPU.</li><br>
1652 <p>
1653
1654 <li>If your program does its own memory management, rather than
1655 using malloc/new/free/delete, it should still work, but
1656 Valgrind's error checking won't be so effective.</li><br>
1657 <p>
1658
1659 <li>Valgrind's signal simulation is not as robust as it could be.
1660 Basic POSIX-compliant sigaction and sigprocmask functionality is
1661 supplied, but it's conceivable that things could go badly awry
1662 if you do wierd things with signals. Workaround: don't.
1663 Programs that do non-POSIX signal tricks are in any case
1664 inherently unportable, so should be avoided if
1665 possible.</li><br>
1666 <p>
1667
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]1668 <li>Programs which try to handle signals on
1669 an alternate stack (sigaltstack) are not supported, although
1670 they could be, with a bit of effort.</li><br>
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]1671 <p>
1672
1673 <li>Programs which switch stacks are not well handled. Valgrind
1674 does have support for this, but I don't have great faith in it.
1675 It's difficult -- there's no cast-iron way to decide whether a
1676 large change in %esp is as a result of the program switching
1677 stacks, or merely allocating a large object temporarily on the
1678 current stack -- yet Valgrind needs to handle the two situations
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]1679 differently. 1 May 02: this probably interacts badly with the
1680 new pthread support. I haven't checked properly.</li><br>
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]1681 <p>
1682
1683 <li>x86 instructions, and system calls, have been implemented on
1684 demand. So it's possible, although unlikely, that a program
1685 will fall over with a message to that effect. If this happens,
1686 please mail me ALL the details printed out, so I can try and
1687 implement the missing feature.</li><br>
1688 <p>
1689
1690 <li>x86 floating point works correctly, but floating-point code may
1691 run even more slowly than integer code, due to my simplistic
1692 approach to FPU emulation.</li><br>
1693 <p>
1694
1695 <li>You can't Valgrind-ize statically linked binaries. Valgrind
1696 relies on the dynamic-link mechanism to gain control at
1697 startup.</li><br>
1698 <p>
1699
1700 <li>Memory consumption of your program is majorly increased whilst
1701 running under Valgrind. This is due to the large amount of
1702 adminstrative information maintained behind the scenes. Another
1703 cause is that Valgrind dynamically translates the original
1704 executable and never throws any translation away, except in
1705 those rare cases where self-modifying code is detected.
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]1706 Translated, instrumented code is 12-14 times larger than the
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]1707 original (!) so you can easily end up with 15+ MB of
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]1708 translations when running (eg) a web browser.
1709 </li>
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]1710</ul>
1711
1712
1713Programs which are known not to work are:
1714
1715<ul>
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]1716 <li>emacs starts up but immediately concludes it is out of memory
1717 and aborts. Emacs has it's own memory-management scheme, but I
1718 don't understand why this should interact so badly with
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]1719 Valgrind. Emacs works fine if you build it to use the standard
1720 malloc/free routines.</li><br>
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]1721 <p>
sewardjab1d9d12002-05-01 12:38:06 +0000[diff] [blame^]1722 <li>Mozilla 1.0RC1 crashes because it jumps to location zero:
1723 <code>Jump to the invalid address stated on the next
1724 line</code>. Other people have reported the same thing.
1725 Despite considerable effort in tracking this down, I cannot
1726 figure out what's going on. If you have a program which does
1727 this, is small enough that I have half a hope of making sense of
1728 it, and is open-source (or at least you'd be happy for me to
1729 look at), I'd be very grateful to have it.
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]1730</ul>
1731
1732
1733<p><hr width="100%">
1734
1735
1736<a name="howitworks"></a>
1737<h2>5&nbsp; How it works -- a rough overview</h2>
1738Some gory details, for those with a passion for gory details. You
1739don't need to read this section if all you want to do is use Valgrind.
1740
1741<a name="startb"></a>
1742<h3>5.1&nbsp; Getting started</h3>
1743
1744Valgrind is compiled into a shared object, valgrind.so. The shell
1745script valgrind sets the LD_PRELOAD environment variable to point to
1746valgrind.so. This causes the .so to be loaded as an extra library to
1747any subsequently executed dynamically-linked ELF binary, viz, the
1748program you want to debug.
1749
1750<p>The dynamic linker allows each .so in the process image to have an
1751initialisation function which is run before main(). It also allows
1752each .so to have a finalisation function run after main() exits.
1753
1754<p>When valgrind.so's initialisation function is called by the dynamic
1755linker, the synthetic CPU to starts up. The real CPU remains locked
1756in valgrind.so for the entire rest of the program, but the synthetic
1757CPU returns from the initialisation function. Startup of the program
1758now continues as usual -- the dynamic linker calls all the other .so's
1759initialisation routines, and eventually runs main(). This all runs on
1760the synthetic CPU, not the real one, but the client program cannot
1761tell the difference.
1762
1763<p>Eventually main() exits, so the synthetic CPU calls valgrind.so's
1764finalisation function. Valgrind detects this, and uses it as its cue
1765to exit. It prints summaries of all errors detected, possibly checks
1766for memory leaks, and then exits the finalisation routine, but now on
1767the real CPU. The synthetic CPU has now lost control -- permanently
1768-- so the program exits back to the OS on the real CPU, just as it
1769would have done anyway.
1770
1771<p>On entry, Valgrind switches stacks, so it runs on its own stack.
1772On exit, it switches back. This means that the client program
1773continues to run on its own stack, so we can switch back and forth
1774between running it on the simulated and real CPUs without difficulty.
1775This was an important design decision, because it makes it easy (well,
1776significantly less difficult) to debug the synthetic CPU.
1777
1778
1779<a name="engine"></a>
1780<h3>5.2&nbsp; The translation/instrumentation engine</h3>
1781
1782Valgrind does not directly run any of the original program's code. Only
1783instrumented translations are run. Valgrind maintains a translation
1784table, which allows it to find the translation quickly for any branch
1785target (code address). If no translation has yet been made, the
1786translator - a just-in-time translator - is summoned. This makes an
1787instrumented translation, which is added to the collection of
1788translations. Subsequent jumps to that address will use this
1789translation.
1790
1791<p>Valgrind can optionally check writes made by the application, to
1792see if they are writing an address contained within code which has
1793been translated. Such a write invalidates translations of code
1794bracketing the written address. Valgrind will discard the relevant
1795translations, which causes them to be re-made, if they are needed
1796again, reflecting the new updated data stored there. In this way,
1797self modifying code is supported. In practice I have not found any
1798Linux applications which use self-modifying-code.
1799
1800<p>The JITter translates basic blocks -- blocks of straight-line-code
1801-- as single entities. To minimise the considerable difficulties of
1802dealing with the x86 instruction set, x86 instructions are first
1803translated to a RISC-like intermediate code, similar to sparc code,
1804but with an infinite number of virtual integer registers. Initially
1805each insn is translated seperately, and there is no attempt at
1806instrumentation.
1807
1808<p>The intermediate code is improved, mostly so as to try and cache
1809the simulated machine's registers in the real machine's registers over
1810several simulated instructions. This is often very effective. Also,
1811we try to remove redundant updates of the simulated machines's
1812condition-code register.
1813
1814<p>The intermediate code is then instrumented, giving more
1815intermediate code. There are a few extra intermediate-code operations
1816to support instrumentation; it is all refreshingly simple. After
1817instrumentation there is a cleanup pass to remove redundant value
1818checks.
1819
1820<p>This gives instrumented intermediate code which mentions arbitrary
1821numbers of virtual registers. A linear-scan register allocator is
1822used to assign real registers and possibly generate spill code. All
1823of this is still phrased in terms of the intermediate code. This
1824machinery is inspired by the work of Reuben Thomas (MITE).
1825
1826<p>Then, and only then, is the final x86 code emitted. The
1827intermediate code is carefully designed so that x86 code can be
1828generated from it without need for spare registers or other
1829inconveniences.
1830
1831<p>The translations are managed using a traditional LRU-based caching
1832scheme. The translation cache has a default size of about 14MB.
1833
1834<a name="track"></a>
1835
1836<h3>5.3&nbsp; Tracking the status of memory</h3> Each byte in the
1837process' address space has nine bits associated with it: one A bit and
1838eight V bits. The A and V bits for each byte are stored using a
1839sparse array, which flexibly and efficiently covers arbitrary parts of
1840the 32-bit address space without imposing significant space or
1841performance overheads for the parts of the address space never
1842visited. The scheme used, and speedup hacks, are described in detail
1843at the top of the source file vg_memory.c, so you should read that for
1844the gory details.
1845
1846<a name="sys_calls"></a>
1847
1848<h3>5.4 System calls</h3>
1849All system calls are intercepted. The memory status map is consulted
1850before and updated after each call. It's all rather tiresome. See
1851vg_syscall_mem.c for details.
1852
1853<a name="sys_signals"></a>
1854
1855<h3>5.5&nbsp; Signals</h3>
1856All system calls to sigaction() and sigprocmask() are intercepted. If
1857the client program is trying to set a signal handler, Valgrind makes a
1858note of the handler address and which signal it is for. Valgrind then
1859arranges for the same signal to be delivered to its own handler.
1860
1861<p>When such a signal arrives, Valgrind's own handler catches it, and
1862notes the fact. At a convenient safe point in execution, Valgrind
1863builds a signal delivery frame on the client's stack and runs its
1864handler. If the handler longjmp()s, there is nothing more to be said.
1865If the handler returns, Valgrind notices this, zaps the delivery
1866frame, and carries on where it left off before delivering the signal.
1867
1868<p>The purpose of this nonsense is that setting signal handlers
1869essentially amounts to giving callback addresses to the Linux kernel.
1870We can't allow this to happen, because if it did, signal handlers
1871would run on the real CPU, not the simulated one. This means the
1872checking machinery would not operate during the handler run, and,
1873worse, memory permissions maps would not be updated, which could cause
1874spurious error reports once the handler had returned.
1875
1876<p>An even worse thing would happen if the signal handler longjmp'd
1877rather than returned: Valgrind would completely lose control of the
1878client program.
1879
1880<p>Upshot: we can't allow the client to install signal handlers
1881directly. Instead, Valgrind must catch, on behalf of the client, any
1882signal the client asks to catch, and must delivery it to the client on
1883the simulated CPU, not the real one. This involves considerable
1884gruesome fakery; see vg_signals.c for details.
1885<p>
1886
1887<hr width="100%">
1888
1889<a name="example"></a>
1890<h2>6&nbsp; Example</h2>
1891This is the log for a run of a small program. The program is in fact
1892correct, and the reported error is as the result of a potentially serious
1893code generation bug in GNU g++ (snapshot 20010527).
1894<pre>
1895sewardj@phoenix:~/newmat10$
1896~/Valgrind-6/valgrind -v ./bogon
1897==25832== Valgrind 0.10, a memory error detector for x86 RedHat 7.1.
1898==25832== Copyright (C) 2000-2001, and GNU GPL'd, by Julian Seward.
1899==25832== Startup, with flags:
1900==25832== --suppressions=/home/sewardj/Valgrind/redhat71.supp
1901==25832== reading syms from /lib/ld-linux.so.2
1902==25832== reading syms from /lib/libc.so.6
1903==25832== reading syms from /mnt/pima/jrs/Inst/lib/libgcc_s.so.0
1904==25832== reading syms from /lib/libm.so.6
1905==25832== reading syms from /mnt/pima/jrs/Inst/lib/libstdc++.so.3
1906==25832== reading syms from /home/sewardj/Valgrind/valgrind.so
1907==25832== reading syms from /proc/self/exe
1908==25832== loaded 5950 symbols, 142333 line number locations
1909==25832==
1910==25832== Invalid read of size 4
1911==25832== at 0x8048724: _ZN10BandMatrix6ReSizeEiii (bogon.cpp:45)
1912==25832== by 0x80487AF: main (bogon.cpp:66)
1913==25832== by 0x40371E5E: __libc_start_main (libc-start.c:129)
1914==25832== by 0x80485D1: (within /home/sewardj/newmat10/bogon)
1915==25832== Address 0xBFFFF74C is not stack'd, malloc'd or free'd
1916==25832==
1917==25832== ERROR SUMMARY: 1 errors from 1 contexts (suppressed: 0 from 0)
1918==25832== malloc/free: in use at exit: 0 bytes in 0 blocks.
1919==25832== malloc/free: 0 allocs, 0 frees, 0 bytes allocated.
1920==25832== For a detailed leak analysis, rerun with: --leak-check=yes
1921==25832==
1922==25832== exiting, did 1881 basic blocks, 0 misses.
1923==25832== 223 translations, 3626 bytes in, 56801 bytes out.
1924</pre>
1925<p>The GCC folks fixed this about a week before gcc-3.0 shipped.
1926<hr width="100%">
1927<p>
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]1928
1929
1930
1931<a name="cache"></a>
1932<h2>7&nbsp; Cache profiling</h2>
1933As well as memory debugging, Valgrind also allows you to do cache simulations
1934and annotate your source line-by-line with the number of cache misses. In
1935particular, it records:
1936<ul>
1937 <li>L1 instruction cache reads and misses;
1938 <li>L1 data cache reads and read misses, writes and write misses;
1939 <li>L2 unified cache reads and read misses, writes and writes misses.
1940</ul>
1941On a modern x86 machine, an L1 miss will typically cost around 10 cycles,
1942and an L2 miss can cost as much as 200 cycles. Detailed cache profiling can be
1943very useful for improving the performance of your program.
1944
1945Please note that this is an experimental feature. Any feedback, bug-fixes,
1946suggestions, etc, welcome.
1947
1948
1949<h3>7.1&nbsp; Overview</h3>
1950First off, as for normal Valgrind use, you probably want to turn on debugging
1951info (the <code>-g</code> flag). But by contrast with normal Valgrind use, you
1952probably <b>do</b> want to turn optimisation on, since you should profile your
1953program as it will be normally run.
1954
1955The three steps are:
1956<ol>
sewardj434f57f2002-05-01 01:24:52 +0000[diff] [blame]1957 <li>Generate a cache simulator for your machine's cache
1958 configuration with the supplied <code>vg_cachegen</code>
1959 program, and recompile Valgrind with <code>make install</code>.
1960 <p>
1961 The default settings are for an AMD Athlon, and you will get
1962 useful information with the defaults, so you can skip this step
1963 if you want. Nevertheless, for accurate cache profiles you will
1964 need use <code>vg_cachegen</code> to customise
1965 <code>cachegrind</code> for your system.
1966 <p>
1967 This step only needs to be done once, unless you are interested
1968 in simulating different cache configurations (eg. first
1969 concentrating on instruction cache misses, then on data cache
1970 misses).
1971 </li>
1972 <p>
1973 <li>Run your program with <code>cachegrind</code> in front of the
1974 normal command line invocation. When the program finishes,
1975 Valgrind will print summary cache statistics. It also collects
1976 line-by-line information in a file <code>cachegrind.out</code>.
1977 <p>
1978 This step should be done every time you want to collect
1979 information about a new program, a changed program, or about the
1980 same program with different input.
1981 </li>
1982 <p>
1983 <li>Generate a function-by-function summary, and possibly annotate
1984 source files with 'vg_annotate'. Source files to annotate can be
1985 specified manually, or manually on the command line, or
1986 "interesting" source files can be annotated automatically with
1987 the <code>--auto=yes</code> option. You can annotate C/C++
1988 files or assembly language files equally easily.</li>
1989 <p>
1990 This step can be performed as many times as you like for each
1991 Step 2. You may want to do multiple annotations showing
1992 different information each time.<p>
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]1993</ol>
1994
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]1995The steps are described in detail in the following sections.<p>
1996
1997
1998<a name="generate"></a>
1999<h3>7.3&nbsp; Generating a cache simulator</h3>
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2000
sewardj434f57f2002-05-01 01:24:52 +0000[diff] [blame]2001Although Valgrind comes with a pre-generated cache simulator, it most
2002likely won't match the cache configuration of your machine, so you
2003should generate a new simulator.<p>
2004
2005You need to generate three files, one for each of the I1, D1 and L2
2006caches. For each cache, you need to know the:
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2007<ul>
2008 <li>Cache size (bytes);
2009 <li>Line size (bytes);
2010 <li>Associativity.
2011</ul>
2012
2013vg_cachegen takes three options:
2014<ul>
2015 <li><code>--I1=size,line_size,associativity</code>
2016 <li><code>--D1=size,line_size,associativity</code>
2017 <li><code>--L2=size,line_size,associativity</code>
2018</ul>
2019
sewardj434f57f2002-05-01 01:24:52 +0000[diff] [blame]2020You can specify one, two or all three caches per invocation of
2021vg_cachegen. It checks that the configuration is sensible before
2022generating the simulators; to see the allowed values, run
2023<code>vg_cachegen -h</code>.<p>
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2024
2025An example invocation would be:
2026
2027<blockquote><code>
2028 vg_cachegen --I1=65536,64,2 --D1=65536,64,2 --L2=262144,64,8
2029</code></blockquote>
2030
sewardj434f57f2002-05-01 01:24:52 +0000[diff] [blame]2031This simulates a machine with a 128KB split L1 2-way associative
2032cache, and a 256KB unified 8-way associative L2 cache. Both caches
2033have 64B lines.<p>
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2034
sewardj434f57f2002-05-01 01:24:52 +0000[diff] [blame]2035If you don't know your cache configuration, you'll have to find it
2036out. (Ideally <code>vg_cachegen</code> could auto-identify your cache
2037configuration using the CPUID instruction, which could be done
2038automatically during installation, and this whole step could be
2039skipped.)<p>
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2040
2041
2042<h3>7.4&nbsp; Cache simulation specifics</h3>
sewardj434f57f2002-05-01 01:24:52 +0000[diff] [blame]2043
2044<code>vg_cachegen</code> only generates simulations for a machine with
2045a split L1 cache and a unified L2 cache. This configuration is used
2046for all (modern) x86-based machines we are aware of. Old Cyrix CPUs
2047had a unified I and D L1 cache, but they are ancient history now.<p>
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2048
2049The more specific characteristics of the simulation are as follows.
2050
2051<ul>
sewardj434f57f2002-05-01 01:24:52 +0000[diff] [blame]2052 <li>Write-allocate: when a write miss occurs, the block written to
2053 is brought into the D1 cache. Most modern caches have this
2054 property.</li><p>
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2055
sewardj434f57f2002-05-01 01:24:52 +0000[diff] [blame]2056 <li>Bit-selection hash function: the line(s) in the cache to which a
2057 memory block maps is chosen by the middle bits M--(M+N-1) of the
2058 byte address, where:
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2059 <ul>
2060 <li>&nbsp;line size = 2^M bytes&nbsp;</li>
2061 <li>(cache size / line size) = 2^N bytes</li>
2062 </ul> </li><p>
2063
sewardj434f57f2002-05-01 01:24:52 +0000[diff] [blame]2064 <li>Inclusive L2 cache: the L2 cache replicates all the entries of
2065 the L1 cache. This is standard on Pentium chips, but AMD
2066 Athlons use an exclusive L2 cache that only holds blocks evicted
2067 from L1. Ditto AMD Durons and most modern VIAs.</li><p>
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2068</ul>
2069
2070Other noteworthy behaviour:
2071
2072<ul>
2073 <li>References that straddle two cache lines are treated as follows:</li>
2074 <ul>
2075 <li>If both blocks hit --&gt; counted as one hit</li>
2076 <li>If one block hits, the other misses --&gt; counted as one miss</li>
2077 <li>If both blocks miss --&gt; counted as one miss (not two)</li>
2078 </ul><p>
2079
2080 <li>Instructions that modify a memory location (eg. <code>inc</code> and
2081 <code>dec</code>) are counted as doing just a read, ie. a single data
2082 reference. This may seem strange, but since the write can never cause a
2083 miss (the read guarantees the block is in the cache) it's not very
2084 interesting.<p>
2085
2086 Thus it measures not the number of times the data cache is accessed, but
2087 the number of times a data cache miss could occur.<p>
2088 </li>
2089</ul>
2090
2091If you are interested in simulating a cache with different properties, it is
2092not particularly hard to write your own cache simulator, or to modify existing
2093ones in <code>vg_cachesim_I1.c</code>, <code>vg_cachesim_I1.c</code> and
2094<code>vg_cachesim_I1.c</code>. We'd be interested to hear from anyone who
2095does.
2096
2097
2098<a name="profile"></a>
2099<h3>7.5&nbsp; Profiling programs</h3>
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2100
sewardj434f57f2002-05-01 01:24:52 +0000[diff] [blame]2101Cache profiling is enabled by using the <code>--cachesim=yes</code>
2102option to the <code>valgrind</code> shell script. Alternatively, it
2103is probably more convenient to use the <code>cachegrind</code> script.
2104This automatically turns off Valgrind's memory checking functions,
2105since the cache simulation is slow enough already, and you probably
2106don't want to do both at once.
2107<p>
2108To gather cache profiling information about the program <code>ls
2109-l<code, type:
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2110
sewardj434f57f2002-05-01 01:24:52 +0000[diff] [blame]2111<blockquote><code>cachegrind ls -l</code></blockquote>
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2112
2113The program will execute (slowly). Upon completion, summary statistics
2114that look like this will be printed:
2115
2116<pre>
2117==31751== I refs: 27,742,716
2118==31751== I1 misses: 276
2119==31751== L2 misses: 275
2120==31751== I1 miss rate: 0.0%
2121==31751== L2i miss rate: 0.0%
2122==31751==
2123==31751== D refs: 15,430,290 (10,955,517 rd + 4,474,773 wr)
2124==31751== D1 misses: 41,185 ( 21,905 rd + 19,280 wr)
2125==31751== L2 misses: 23,085 ( 3,987 rd + 19,098 wr)
2126==31751== D1 miss rate: 0.2% ( 0.1% + 0.4%)
2127==31751== L2d miss rate: 0.1% ( 0.0% + 0.4%)
2128==31751==
2129==31751== L2 misses: 23,360 ( 4,262 rd + 19,098 wr)
2130==31751== L2 miss rate: 0.0% ( 0.0% + 0.4%)
2131</pre>
2132
2133Cache accesses for instruction fetches are summarised first, giving the
2134number of fetches made (this is the number of instructions executed, which
2135can be useful to know in its own right), the number of I1 misses, and the
2136number of L2 instruction (<code>L2i</code>) misses.<p>
2137
2138Cache accesses for data follow. The information is similar to that of the
2139instruction fetches, except that the values are also shown split between reads
2140and writes (note each row's <code>rd</code> and <code>wr</code> values add up
2141to the row's total).<p>
2142
2143Combined instruction and data figures for the L2 cache follow that.<p>
2144
2145
2146<h3>7.6&nbsp; Output file</h3>
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2147
sewardj434f57f2002-05-01 01:24:52 +0000[diff] [blame]2148As well as printing summary information, Cachegrind also writes
2149line-by-line cache profiling information to a file named
2150<code>cachegrind.out</code>. This file is human-readable, but is best
2151interpreted by the accompanying program <code>vg_annotate</code>,
2152described in the next section.
2153<p>
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2154Things to note about the <code>cachegrind.out</code> file:
2155<ul>
sewardj434f57f2002-05-01 01:24:52 +0000[diff] [blame]2156 <li>It is written every time <code>valgrind --cachesim=yes</code> or
2157 <code>cachegrind</code> is run, and will overwrite any existing
2158 <code>cachegrind.out</code> in the current directory.</li>
2159 <p>
2160 <li>It can be huge: <code>ls -l</code> generates a file of about
2161 350KB. Browsing a few files and web pages with a Konqueror
2162 built with full debugging information generates a file
2163 of around 15 MB.</li>
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2164</ul>
2165
2166
2167<a name="annotate"></a>
2168<h3>7.7&nbsp; Annotating C/C++ programs</h3>
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2169
sewardj434f57f2002-05-01 01:24:52 +0000[diff] [blame]2170Before using <code>vg_annotate</code>, it is worth widening your
2171window to be at least 120-characters wide if possible, as the output
2172lines can be quite long.
2173<p>
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2174To get a function-by-function summary, run <code>vg_annotate</code> in
sewardj434f57f2002-05-01 01:24:52 +0000[diff] [blame]2175directory containing a <code>cachegrind.out</code> file. The output
2176looks like this:
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2177
2178<pre>
2179--------------------------------------------------------------------------------
2180I1 cache: 65536 B, 64 B, 2-way associative
2181D1 cache: 65536 B, 64 B, 2-way associative
2182L2 cache: 262144 B, 64 B, 8-way associative
2183Command: concord vg_to_ucode.c
2184Events recorded: Ir I1mr I2mr Dr D1mr D2mr Dw D1mw D2mw
2185Events shown: Ir I1mr I2mr Dr D1mr D2mr Dw D1mw D2mw
2186Event sort order: Ir I1mr I2mr Dr D1mr D2mr Dw D1mw D2mw
2187Threshold: 99%
2188Chosen for annotation:
2189Auto-annotation: on
2190
2191--------------------------------------------------------------------------------
2192Ir I1mr I2mr Dr D1mr D2mr Dw D1mw D2mw
2193--------------------------------------------------------------------------------
219427,742,716 276 275 10,955,517 21,905 3,987 4,474,773 19,280 19,098 PROGRAM TOTALS
2195
2196--------------------------------------------------------------------------------
2197Ir I1mr I2mr Dr D1mr D2mr Dw D1mw D2mw file:function
2198--------------------------------------------------------------------------------
21998,821,482 5 5 2,242,702 1,621 73 1,794,230 0 0 getc.c:_IO_getc
22005,222,023 4 4 2,276,334 16 12 875,959 1 1 concord.c:get_word
22012,649,248 2 2 1,344,810 7,326 1,385 . . . vg_main.c:strcmp
22022,521,927 2 2 591,215 0 0 179,398 0 0 concord.c:hash
22032,242,740 2 2 1,046,612 568 22 448,548 0 0 ctype.c:tolower
22041,496,937 4 4 630,874 9,000 1,400 279,388 0 0 concord.c:insert
2205 897,991 51 51 897,831 95 30 62 1 1 ???:???
2206 598,068 1 1 299,034 0 0 149,517 0 0 ../sysdeps/generic/lockfile.c:__flockfile
2207 598,068 0 0 299,034 0 0 149,517 0 0 ../sysdeps/generic/lockfile.c:__funlockfile
2208 598,024 4 4 213,580 35 16 149,506 0 0 vg_clientmalloc.c:malloc
2209 446,587 1 1 215,973 2,167 430 129,948 14,057 13,957 concord.c:add_existing
2210 341,760 2 2 128,160 0 0 128,160 0 0 vg_clientmalloc.c:vg_trap_here_WRAPPER
2211 320,782 4 4 150,711 276 0 56,027 53 53 concord.c:init_hash_table
2212 298,998 1 1 106,785 0 0 64,071 1 1 concord.c:create
2213 149,518 0 0 149,516 0 0 1 0 0 ???:tolower@@GLIBC_2.0
2214 149,518 0 0 149,516 0 0 1 0 0 ???:fgetc@@GLIBC_2.0
2215 95,983 4 4 38,031 0 0 34,409 3,152 3,150 concord.c:new_word_node
2216 85,440 0 0 42,720 0 0 21,360 0 0 vg_clientmalloc.c:vg_bogus_epilogue
2217</pre>
2218
2219First up is a summary of the annotation options:
2220
2221<ul>
2222 <li>I1 cache, D1 cache, L2 cache: cache configuration. So you know the
2223 configuration with which these results were obtained.</li><p>
2224
2225 <li>Command: the command line invocation of the program under
2226 examination.</li><p>
2227
2228 <li>Events recorded: event abbreviations are:<p>
2229 <ul>
2230 <li><code>Ir </code>: I cache reads (ie. instructions executed)</li>
2231 <li><code>I1mr</code>: I1 cache read misses</li>
2232 <li><code>I2mr</code>: L2 cache instruction read misses</li>
2233 <li><code>Dr </code>: D cache reads (ie. memory reads)</li>
2234 <li><code>D1mr</code>: D1 cache read misses</li>
2235 <li><code>D2mr</code>: L2 cache data read misses</li>
2236 <li><code>Dw </code>: D cache writes (ie. memory writes)</li>
2237 <li><code>D1mw</code>: D1 cache write misses</li>
2238 <li><code>D2mw</code>: L2 cache data write misses</li>
2239 </ul><p>
2240 Note that D1 total accesses is given by <code>D1mr</code> +
2241 <code>D1mw</code>, and that L2 total accesses is given by
2242 <code>I2mr</code> + <code>D2mr</code> + <code>D2mw</code>.</li><p>
2243
2244 <li>Events shown: the events shown (a subset of events gathered). This can
2245 be adjusted with the <code>--show</code> option.</li><p>
2246
2247 <li>Event sort order: the sort order in which functions are shown. For
2248 example, in this case the functions are sorted from highest
2249 <code>Ir</code> counts to lowest. If two functions have identical
2250 <code>Ir</code> counts, they will then be sorted by <code>I1mr</code>
2251 counts, and so on. This order can be adjusted with the
2252 <code>--sort</code> option.<p>
2253
2254 Note that this dictates the order the functions appear. It is <b>not</b>
2255 the order in which the columns appear; that is dictated by the "events
2256 shown" line (and can be changed with the <code>--sort</code> option).
2257 </li><p>
2258
sewardj434f57f2002-05-01 01:24:52 +0000[diff] [blame]2259 <li>Threshold: <code>vg_annotate</code> by default omits functions
2260 that cause very low numbers of misses to avoid drowning you in
2261 information. In this case, vg_annotate shows summaries the
2262 functions that account for 99% of the <code>Ir</code> counts;
2263 <code>Ir</code> is chosen as the threshold event since it is the
2264 primary sort event. The threshold can be adjusted with the
2265 <code>--threshold</code> option.</li><p>
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2266
2267 <li>Chosen for annotation: names of files specified manually for annotation;
2268 in this case none.</li><p>
2269
2270 <li>Auto-annotation: whether auto-annotation was requested via the
2271 <code>--auto=yes</code> option. In this case no.</li><p>
2272</ul>
2273
2274Then follows summary statistics for the whole program. These are similar
2275to the summary provided when running <code>valgrind --cachesim=yes</code>.<p>
2276
sewardj434f57f2002-05-01 01:24:52 +0000[diff] [blame]2277Then follows function-by-function statistics. Each function is
2278identified by a <code>file_name:function_name</code> pair. If a column
2279contains only a dot it means the function never performs
2280that event (eg. the third row shows that <code>strcmp()</code>
2281contains no instructions that write to memory). The name
2282<code>???</code> is used if the the file name and/or function name
2283could not be determined from debugging information. If most of the
2284entries have the form <code>???:???</code> the program probably wasn't
2285compiled with <code>-g</code>. <p>
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2286
2287It is worth noting that functions will come from three types of source files:
2288<ol>
2289 <li> From the profiled program (<code>concord.c</code> in this example).</li>
2290 <li>From libraries (eg. <code>getc.c</code>)</li>
2291 <li>From Valgrind's implementation of some libc functions (eg.
2292 <code>vg_clientmalloc.c:malloc</code>). These are recognisable because
2293 the filename begins with <code>vg_</code>, and is probably one of
2294 <code>vg_main.c</code>, <code>vg_clientmalloc.c</code> or
2295 <code>vg_mylibc.c</code>.
2296 </li>
2297</ol>
2298
sewardj434f57f2002-05-01 01:24:52 +0000[diff] [blame]2299There are two ways to annotate source files -- by choosing them
2300manually, or with the <code>--auto=yes</code> option. To do it
2301manually, just specify the filenames as arguments to
2302<code>vg_annotate</code>. For example, the output from running
2303<code>vg_annotate concord.c</code> for our example produces the same
2304output as above followed by an annotated version of
2305<code>concord.c</code>, a section of which looks like:
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2306
2307<pre>
2308--------------------------------------------------------------------------------
2309-- User-annotated source: concord.c
2310--------------------------------------------------------------------------------
2311Ir I1mr I2mr Dr D1mr D2mr Dw D1mw D2mw
2312
2313[snip]
2314
2315 . . . . . . . . . void init_hash_table(char *file_name, Word_Node *table[])
2316 3 1 1 . . . 1 0 0 {
2317 . . . . . . . . . FILE *file_ptr;
2318 . . . . . . . . . Word_Info *data;
2319 1 0 0 . . . 1 1 1 int line = 1, i;
2320 . . . . . . . . .
2321 5 0 0 . . . 3 0 0 data = (Word_Info *) create(sizeof(Word_Info));
2322 . . . . . . . . .
2323 4,991 0 0 1,995 0 0 998 0 0 for (i = 0; i < TABLE_SIZE; i++)
2324 3,988 1 1 1,994 0 0 997 53 52 table[i] = NULL;
2325 . . . . . . . . .
2326 . . . . . . . . . /* Open file, check it. */
2327 6 0 0 1 0 0 4 0 0 file_ptr = fopen(file_name, "r");
2328 2 0 0 1 0 0 . . . if (!(file_ptr)) {
2329 . . . . . . . . . fprintf(stderr, "Couldn't open '%s'.\n", file_name);
2330 1 1 1 . . . . . . exit(EXIT_FAILURE);
2331 . . . . . . . . . }
2332 . . . . . . . . .
2333 165,062 1 1 73,360 0 0 91,700 0 0 while ((line = get_word(data, line, file_ptr)) != EOF)
2334 146,712 0 0 73,356 0 0 73,356 0 0 insert(data->;word, data->line, table);
2335 . . . . . . . . .
2336 4 0 0 1 0 0 2 0 0 free(data);
2337 4 0 0 1 0 0 2 0 0 fclose(file_ptr);
2338 3 0 0 2 0 0 . . . }
2339</pre>
2340
2341(Although column widths are automatically minimised, a wide terminal is clearly
2342useful.)<p>
2343
2344Each source file is clearly marked (<code>User-annotated source</code>) as
2345having been chosen manually for annotation. If the file was found in one of
2346the directories specified with the <code>-I</code>/<code>--include</code>
2347option, the directory and file are both given.<p>
2348
2349Each line is annotated with its event counts. Events not applicable for a line
2350are represented by a `.'; this is useful for distinguishing between an event
2351which cannot happen, and one which can but did not.<p>
2352
2353Sometimes only a small section of a source file is executed. To minimise
2354uninteresting output, Valgrind only shows annotated lines and lines within a
2355small distance of annotated lines. Gaps are marked with the line numbers so
2356you know which part of a file the shown code comes from, eg:
2357
2358<pre>
2359(figures and code for line 704)
2360-- line 704 ----------------------------------------
2361-- line 878 ----------------------------------------
2362(figures and code for line 878)
2363</pre>
2364
2365The amount of context to show around annotated lines is controlled by the
2366<code>--context</code> option.<p>
2367
2368To get automatic annotation, run <code>vg_annotate --auto=yes</code>.
2369vg_annotate will automatically annotate every source file it can find that is
2370mentioned in the function-by-function summary. Therefore, the files chosen for
2371auto-annotation are affected by the <code>--sort</code> and
2372<code>--threshold</code> options. Each source file is clearly marked
2373(<code>Auto-annotated source</code>) as being chosen automatically. Any files
2374that could not be found are mentioned at the end of the output, eg:
2375
2376<pre>
2377--------------------------------------------------------------------------------
2378The following files chosen for auto-annotation could not be found:
2379--------------------------------------------------------------------------------
2380 getc.c
2381 ctype.c
2382 ../sysdeps/generic/lockfile.c
2383</pre>
2384
2385This is quite common for library files, since libraries are usually compiled
2386with debugging information, but the source files are often not present on a
2387system. If a file is chosen for annotation <b>both</b> manually and
2388automatically, it is marked as <code>User-annotated source</code>.
2389
2390Use the <code>-I/--include</code> option to tell Valgrind where to look for
2391source files if the filenames found from the debugging information aren't
2392specific enough.
2393
2394Beware that vg_annotate can take some time to digest large
2395<code>cachegrind.out</code> files, eg. 30 seconds or more. Also beware that
2396auto-annotation can produce a lot of output if your program is large!
2397
2398
2399<h3>7.8&nbsp; Annotating assembler programs</h3>
sewardj434f57f2002-05-01 01:24:52 +0000[diff] [blame]2400
2401Valgrind can annotate assembler programs too, or annotate the
2402assembler generated for your C program. Sometimes this is useful for
2403understanding what is really happening when an interesting line of C
2404code is translated into multiple instructions.<p>
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2405
2406To do this, you just need to assemble your <code>.s</code> files with
sewardj434f57f2002-05-01 01:24:52 +0000[diff] [blame]2407assembler-level debug information. gcc doesn't do this, but you can
2408use the GNU assembler with the <code>--gstabs</code> option to
2409generate object files with this information, eg:
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2410
2411<blockquote><code>as --gstabs foo.s</code></blockquote>
2412
2413You can then profile and annotate source files in the same way as for C/C++
2414programs.
2415
2416
sewardj434f57f2002-05-01 01:24:52 +0000[diff] [blame]2417<h3>7.9&nbsp; <code>vg_annotate</code> options</h3>
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2418<ul>
2419 <li><code>-h, --help</code></li><p>
2420 <li><code>-v, --version</code><p>
2421
2422 Help and version, as usual.</li>
2423
2424 <li><code>--sort=A,B,C</code> [default: order in
2425 <code>cachegrind.out</code>]<p>
2426 Specifies the events upon which the sorting of the function-by-function
2427 entries will be based. Useful if you want to concentrate on eg. I cache
2428 misses (<code>--sort=I1mr,I2mr</code>), or D cache misses
2429 (<code>--sort=D1mr,D2mr</code>), or L2 misses
2430 (<code>--sort=D2mr,I2mr</code>).</li><p>
2431
2432 <li><code>--show=A,B,C</code> [default: all, using order in
2433 <code>cachegrind.out</code>]<p>
2434 Specifies which events to show (and the column order). Default is to use
2435 all present in the <code>cachegrind.out</code> file (and use the order in
2436 the file).</li><p>
2437
2438 <li><code>--threshold=X</code> [default: 99%] <p>
2439 Sets the threshold for the function-by-function summary. Functions are
2440 shown that account for more than X% of all the primary sort events. If
2441 auto-annotating, also affects which files are annotated.</li><p>
2442
2443 <li><code>--auto=no</code> [default]<br>
2444 <code>--auto=yes</code> <p>
2445 When enabled, automatically annotates every file that is mentioned in the
2446 function-by-function summary that can be found. Also gives a list of
2447 those that couldn't be found.
2448
2449 <li><code>--context=N</code> [default: 8]<p>
2450 Print N lines of context before and after each annotated line. Avoids
2451 printing large sections of source files that were not executed. Use a
2452 large number (eg. 10,000) to show all source lines.
2453 </li><p>
2454
2455 <li><code>-I=&lt;dir&gt;, --include=&lt;dir&gt;</code>
2456 [default: empty string]<p>
2457 Adds a directory to the list in which to search for files. Multiple
2458 -I/--include options can be given to add multiple directories.
2459</ul>
2460
2461
2462<h3>7.10&nbsp; Warnings</h3>
2463There are a couple of situations in which vg_annotate issues warnings.
2464
2465<ul>
2466 <li>If a source file is more recent than the <code>cachegrind.out</code>
2467 file. This is because the information in <code>cachegrind.out</code> is
2468 only recorded with line numbers, so if the line numbers change at all in
2469 the source (eg. lines added, deleted, swapped), any annotations will be
2470 incorrect.<p>
2471
2472 <li>If information is recorded about line numbers past the end of a file.
2473 This can be caused by the above problem, ie. shortening the source file
2474 while using an old <code>cachegrind.out</code> file. If this happens,
2475 the figures for the bogus lines are printed anyway (clearly marked as
2476 bogus) in case they are important.</li><p>
2477</ul>
2478
2479
2480<h3>7.10&nbsp; Things to watch out for</h3>
2481Some odd things that can occur during annotation:
2482
2483<ul>
2484 <li>If annotating at the assembler level, you might see something like this:
2485
2486 <pre>
2487 1 0 0 . . . . . . leal -12(%ebp),%eax
2488 1 0 0 . . . 1 0 0 movl %eax,84(%ebx)
2489 2 0 0 0 0 0 1 0 0 movl $1,-20(%ebp)
2490 . . . . . . . . . .align 4,0x90
2491 1 0 0 . . . . . . movl $.LnrB,%eax
2492 1 0 0 . . . 1 0 0 movl %eax,-16(%ebp)
2493 </pre>
2494
2495 How can the third instruction be executed twice when the others are
2496 executed only once? As it turns out, it isn't. Here's a dump of the
2497 executable, from objdump:
2498
2499 <pre>
2500 8048f25: 8d 45 f4 lea 0xfffffff4(%ebp),%eax
2501 8048f28: 89 43 54 mov %eax,0x54(%ebx)
2502 8048f2b: c7 45 ec 01 00 00 00 movl $0x1,0xffffffec(%ebp)
2503 8048f32: 89 f6 mov %esi,%esi
2504 8048f34: b8 08 8b 07 08 mov $0x8078b08,%eax
2505 8048f39: 89 45 f0 mov %eax,0xfffffff0(%ebp)
2506 </pre>
2507
2508 Notice the extra <code>mov %esi,%esi</code> instruction. Where did this
2509 come from? The GNU assembler inserted it to serve as the two bytes of
2510 padding needed to align the <code>movl $.LnrB,%eax</code> instruction on
2511 a four-byte boundary, but pretended it didn't exist when adding debug
2512 information. Thus when Valgrind reads the debug info it thinks that the
2513 <code>movl $0x1,0xffffffec(%ebp)</code> instruction covers the address
2514 range 0x8048f2b--0x804833 by itself, and attributes the counts for the
2515 <code>mov %esi,%esi</code> to it.<p>
2516 </li>
2517
2518 <li>
2519 Inlined functions can cause strange results in the function-by-function
2520 summary. If a function <code>inline_me()</code> is defined in
2521 <code>foo.h</code> and inlined in the functions <code>f1()</code>,
2522 <code>f2()</code> and <code>f3()</code> in <code>bar.c</code>, there will
2523 not be a <code>foo.h:inline_me()</code> function entry. Instead, there
2524 will be separate function entries for each inlining site, ie.
2525 <code>foo.h:f1()</code>, <code>foo.h:f2()</code> and
2526 <code>foo.h:f3()</code>. To find the total counts for
2527 <code>foo.h:inline_me()</code>, add up the counts from each entry.<p>
2528
2529 The reason for this is that although the debug info output by gcc
2530 indicates the switch from <code>bar.c</code> to <code>foo.h</code>, it
2531 doesn't indicate the name of the function in <code>foo.h</code>, so
2532 Valgrind keeps using the old one.<p>
2533
2534 <li>
2535 Sometimes, the same filename might be represented with a relative name
2536 and with an absolute name in different parts of the debug info, eg:
2537 <code>/home/user/proj/proj.h</code> and <code>../proj.h</code>. In this
2538 case, if you use auto-annotation, the file will be annotated twice with
2539 the counts split between the two.<p>
2540 </li>
2541</ul>
2542
2543Note: stabs is not an easy format to read. If you come across bizarre
2544annotations that look like might be caused by a bug in the stabs reader,
2545please let us know.
2546
2547
2548<h3>7.11&nbsp; Accuracy</h3>
2549Valgrind's cache profiling has a number of shortcomings:
2550
2551<ul>
2552 <li>It doesn't account for kernel activity -- the effect of system calls on
2553 the cache contents is ignored.</li><p>
2554
2555 <li>It doesn't account for other process activity (although this is probably
2556 desirable when considering a single program).</li><p>
2557
2558 <li>It doesn't account for virtual-to-physical address mappings; hence the
2559 entire simulation is not a true representation of what's happening in the
2560 cache.</li><p>
2561
2562 <li>It doesn't account for cache misses not visible at the instruction level,
2563 eg. those arising from TLB misses, or speculative execution.</li><p>
njndb75e4d2002-04-30 12:46:22 +0000[diff] [blame]2564
2565 <li>The instructions <code>bts</code>, <code>btr</code> and <code>btc</code>
2566 will incorrectly be counted as doing a data read if both the arguments
2567 are registers, eg:
2568
2569 <blockquote><code>btsl %eax, %edx</code></blockquote>
2570
2571 This should only happen rarely.
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2572</ul>
2573
2574Another thing worth nothing is that results are very sensitive. Changing the
2575size of the <code>valgrind.so</code> file, the size of the program being
2576profiled, or even the length of its name can perturb the results. Variations
2577will be small, but don't expect perfectly repeatable results if your program
2578changes at all.<p>
2579
2580While these factors mean you shouldn't trust the results to be super-accurate,
2581hopefully they should be close enough to be useful.<p>
2582
2583
2584<h3>7.12&nbsp; Todo</h3>
2585<ul>
2586 <li>Use CPUID instruction to auto-identify cache configuration during
2587 installation. This would save the user from having to know their cache
sewardj434f57f2002-05-01 01:24:52 +0000[diff] [blame]2588 configuration and using vg_cachegen.</li>
2589 <p>
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2590 <li>Program start-up/shut-down calls a lot of functions that aren't
2591 interesting and just complicate the output. Would be nice to exclude
sewardj434f57f2002-05-01 01:24:52 +0000[diff] [blame]2592 these somehow.</li>
2593 <p>
2594 <li>Handle files with more than 65535 lines.</li><p>
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2595</ul>
2596<hr width="100%">
sewardjde4a1d02002-03-22 01:27:54 +0000[diff] [blame]2597</body>
2598</html>
njn4f9c9342002-04-29 16:03:24 +0000[diff] [blame]2599