Blame - coregrind/docs/manual.html - platform/external/valgrind

blob: 03b7ede29230788b6d2d4ba0712390233db9cda9 [file] [log] [blame]

sewardj	de4a1d0	2002-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"> </a>
sewardj	a7dc795	2002-03-24 11:29:13 +0000	[diff] [blame]	27	<h1 align=center>Valgrind, snapshot 20020324</h1>
sewardj	c7529c3	2002-04-16 01:55:18 +0000	[diff] [blame^]	28	<center>This manual was minimally updated on 20020415</center>
				29	<p>
sewardj	de4a1d0	2002-03-22 01:27:54 +0000	[diff] [blame]	30
				31	<center>
				32	<a href="mailto:jseward@acm.org">jseward@acm.org<br>
				33	<a href="http://www.muraroa.demon.co.uk">http://www.muraroa.demon.co.uk</a><br>
				34	Copyright © 2000-2002 Julian Seward
				35	<p>
				36	Valgrind is licensed under the GNU General Public License,
				37	version 2<br>
				38	An open-source tool for finding memory-management problems in
				39	Linux-x86 executables.
				40	</center>
				41
				42	<p>
				43
				44	<hr width="100%">
				45	<a name="contents"></a>
				46	<h2>Contents of this manual</h2>
				47
				48	<h4>1  <a href="#intro">Introduction</a></h4>
				49	1.1  <a href="#whatfor">What Valgrind is for</a><br>
				50	1.2  <a href="#whatdoes">What it does with your program</a>
				51
				52	<h4>2  <a href="#howtouse">How to use it, and how to make sense
				53	of the results</a></h4>
				54	2.1  <a href="#starta">Getting started</a><br>
				55	2.2  <a href="#comment">The commentary</a><br>
				56	2.3  <a href="#report">Reporting of errors</a><br>
				57	2.4  <a href="#suppress">Suppressing errors</a><br>
				58	2.5  <a href="#flags">Command-line flags</a><br>
				59	2.6  <a href="#errormsgs">Explaination of error messages</a><br>
				60	2.7  <a href="#suppfiles">Writing suppressions files</a><br>
				61	2.8  <a href="#install">Building and installing</a><br>
				62	2.9  <a href="#problems">If you have problems</a><br>
				63
				64	<h4>3  <a href="#machine">Details of the checking machinery</a></h4>
				65	3.1  <a href="#vvalue">Valid-value (V) bits</a><br>
				66	3.2  <a href="#vaddress">Valid-address (A) bits</a><br>
				67	3.3  <a href="#together">Putting it all together</a><br>
				68	3.4  <a href="#signals">Signals</a><br>
				69	3.5  <a href="#leaks">Memory leak detection</a><br>
				70
				71	<h4>4  <a href="#limits">Limitations</a></h4>
				72
				73	<h4>5  <a href="#howitworks">How it works -- a rough overview</a></h4>
				74	5.1  <a href="#startb">Getting started</a><br>
				75	5.2  <a href="#engine">The translation/instrumentation engine</a><br>
				76	5.3  <a href="#track">Tracking the status of memory</a><br>
				77	5.4  <a href="#sys_calls">System calls</a><br>
				78	5.5  <a href="#sys_signals">Signals</a><br>
				79
				80	<h4>6  <a href="#example">An example</a></h4>
				81
				82	<h4>7  <a href="techdocs.html">The design and implementation of Valgrind</a></h4>
				83
				84	<hr width="100%">
				85
				86	<a name="intro"></a>
				87	<h2>1  Introduction</h2>
				88
				89	<a name="whatfor"></a>
				90	<h3>1.1  What Valgrind is for</h3>
				91
				92	Valgrind is a tool to help you find memory-management problems in your
				93	programs. When a program is run under Valgrind's supervision, all
				94	reads and writes of memory are checked, and calls to
				95	malloc/new/free/delete are intercepted. As a result, Valgrind can
				96	detect problems such as:
				97	<ul>
				98	<li>Use of uninitialised memory</li>
				99	<li>Reading/writing memory after it has been free'd</li>
				100	<li>Reading/writing off the end of malloc'd blocks</li>
				101	<li>Reading/writing inappropriate areas on the stack</li>
				102	<li>Memory leaks -- where pointers to malloc'd blocks are lost forever</li>
				103	</ul>
				104
				105	Problems like these can be difficult to find by other means, often
				106	lying undetected for long periods, then causing occasional,
				107	difficult-to-diagnose crashes.
				108
				109	<p>
				110	Valgrind is closely tied to details of the CPU, operating system and
				111	to a less extent, compiler and basic C libraries. This makes it
				112	difficult to make it portable, so I have chosen at the outset to
				113	concentrate on what I believe to be a widely used platform: Red Hat
				114	Linux 7.2, on x86s. I believe that it will work without significant
				115	difficulty on other x86 GNU/Linux systems which use the 2.4 kernel and
				116	GNU libc 2.2.X, for example SuSE 7.1 and Mandrake 8.0. Red Hat 6.2 is
				117	also supported. It has worked in the past, and probably still does,
				118	on RedHat 7.1 and 6.2. Note that I haven't compiled it on RedHat 7.1
				119	and 6.2 for a while, so they may no longer work now.
				120	<p>
				121	(Early Feb 02: after feedback from the KDE people it also works better
				122	on other Linuxes).
				123	<p>
				124	At some point in the past, Valgrind has also worked on Red Hat 6.2
				125	(x86), thanks to the efforts of Rob Noble.
				126
				127	<p>
				128	Valgrind is licensed under the GNU General Public License, version
				129	2. Read the file LICENSE in the source distribution for details.
				130
				131	<a name="whatdoes">
				132	<h3>1.2  What it does with your program</h3>
				133
				134	Valgrind is designed to be as non-intrusive as possible. It works
				135	directly with existing executables. You don't need to recompile,
				136	relink, or otherwise modify, the program to be checked. Simply place
				137	the word <code>valgrind</code> at the start of the command line
				138	normally used to run the program. So, for example, if you want to run
				139	the command <code>ls -l</code> on Valgrind, simply issue the
				140	command: <code>valgrind ls -l</code>.
				141
				142	<p>Valgrind takes control of your program before it starts. Debugging
				143	information is read from the executable and associated libraries, so
				144	that error messages can be phrased in terms of source code
				145	locations. Your program is then run on a synthetic x86 CPU which
				146	checks every memory access. All detected errors are written to a
				147	log. When the program finishes, Valgrind searches for and reports on
				148	leaked memory.
				149
				150	<p>You can run pretty much any dynamically linked ELF x86 executable using
				151	Valgrind. Programs run 25 to 50 times slower, and take a lot more
				152	memory, than they usually would. It works well enough to run large
				153	programs. For example, the Konqueror web browser from the KDE Desktop
				154	Environment, version 2.1.1, runs slowly but usably on Valgrind.
				155
				156	<p>Valgrind simulates every single instruction your program executes.
				157	Because of this, it finds errors not only in your application but also
				158	in all supporting dynamically-linked (.so-format) libraries, including
				159	the GNU C library, the X client libraries, Qt, if you work with KDE, and
				160	so on. That often includes libraries, for example the GNU C library,
				161	which contain memory access violations, but which you cannot or do not
				162	want to fix.
				163
				164	<p>Rather than swamping you with errors in which you are not
				165	interested, Valgrind allows you to selectively suppress errors, by
				166	recording them in a suppressions file which is read when Valgrind
				167	starts up. As supplied, Valgrind comes with a suppressions file
				168	designed to give reasonable behaviour on Red Hat 7.2 (also 7.1 and
				169	6.2) when running text-only and simple X applications.
				170
				171	<p><a href="#example">Section 6</a> shows an example of use.
				172	<p>
				173	<hr width="100%">
				174
				175	<a name="howtouse"></a>
				176	<h2>2  How to use it, and how to make sense of the results</h2>
				177
				178	<a name="starta"></a>
				179	<h3>2.1  Getting started</h3>
				180
				181	First off, consider whether it might be beneficial to recompile your
				182	application and supporting libraries with optimisation disabled and
				183	debugging info enabled (the <code>-g</code> flag). You don't have to
				184	do this, but doing so helps Valgrind produce more accurate and less
				185	confusing error reports. Chances are you're set up like this already,
				186	if you intended to debug your program with GNU gdb, or some other
				187	debugger.
				188
				189	<p>Then just run your application, but place the word
				190	<code>valgrind</code> in front of your usual command-line invokation.
				191	Note that you should run the real (machine-code) executable here. If
				192	your application is started by, for example, a shell or perl script,
				193	you'll need to modify it to invoke Valgrind on the real executables.
				194	Running such scripts directly under Valgrind will result in you
				195	getting error reports pertaining to <code>/bin/sh</code>,
				196	<code>/usr/bin/perl</code>, or whatever interpreter you're using.
				197	This almost certainly isn't what you want and can be hugely confusing.
				198
				199	<a name="comment"></a>
				200	<h3>2.2  The commentary</h3>
				201
				202	Valgrind writes a commentary, detailing error reports and other
				203	significant events. The commentary goes to standard output by
				204	default. This may interfere with your program, so you can ask for it
				205	to be directed elsewhere.
				206
				207	<p>All lines in the commentary are of the following form:<br>
				208	<pre>
				209	==12345== some-message-from-Valgrind
				210	</pre>
				211	<p>The <code>12345</code> is the process ID. This scheme makes it easy
				212	to distinguish program output from Valgrind commentary, and also easy
				213	to differentiate commentaries from different processes which have
				214	become merged together, for whatever reason.
				215
				216	<p>By default, Valgrind writes only essential messages to the commentary,
				217	so as to avoid flooding you with information of secondary importance.
				218	If you want more information about what is happening, re-run, passing
				219	the <code>-v</code> flag to Valgrind.
				220
				221
				222	<a name="report"></a>
				223	<h3>2.3  Reporting of errors</h3>
				224
				225	When Valgrind detects something bad happening in the program, an error
				226	message is written to the commentary. For example:<br>
				227	<pre>
				228	==25832== Invalid read of size 4
				229	==25832== at 0x8048724: BandMatrix::ReSize(int, int, int) (bogon.cpp:45)
				230	==25832== by 0x80487AF: main (bogon.cpp:66)
				231	==25832== by 0x40371E5E: __libc_start_main (libc-start.c:129)
				232	==25832== by 0x80485D1: (within /home/sewardj/newmat10/bogon)
				233	==25832== Address 0xBFFFF74C is not stack'd, malloc'd or free'd
				234	</pre>
				235
				236	<p>This message says that the program did an illegal 4-byte read of
				237	address 0xBFFFF74C, which, as far as it can tell, is not a valid stack
				238	address, nor corresponds to any currently malloc'd or free'd blocks.
				239	The read is happening at line 45 of <code>bogon.cpp</code>, called
				240	from line 66 of the same file, etc. For errors associated with an
				241	identified malloc'd/free'd block, for example reading free'd memory,
				242	Valgrind reports not only the location where the error happened, but
				243	also where the associated block was malloc'd/free'd.
				244
				245	<p>Valgrind remembers all error reports. When an error is detected,
				246	it is compared against old reports, to see if it is a duplicate. If
				247	so, the error is noted, but no further commentary is emitted. This
				248	avoids you being swamped with bazillions of duplicate error reports.
				249
				250	<p>If you want to know how many times each error occurred, run with
				251	the <code>-v</code> option. When execution finishes, all the reports
				252	are printed out, along with, and sorted by, their occurrence counts.
				253	This makes it easy to see which errors have occurred most frequently.
				254
				255	<p>Errors are reported before the associated operation actually
				256	happens. For example, if you program decides to read from address
				257	zero, Valgrind will emit a message to this effect, and the program
				258	will then duly die with a segmentation fault.
				259
				260	<p>In general, you should try and fix errors in the order that they
				261	are reported. Not doing so can be confusing. For example, a program
				262	which copies uninitialised values to several memory locations, and
				263	later uses them, will generate several error messages. The first such
				264	error message may well give the most direct clue to the root cause of
				265	the problem.
				266
				267	<a name="suppress"></a>
				268	<h3>2.4  Suppressing errors</h3>
				269
				270	Valgrind detects numerous problems in the base libraries, such as the
				271	GNU C library, and the XFree86 client libraries, which come
				272	pre-installed on your GNU/Linux system. You can't easily fix these,
				273	but you don't want to see these errors (and yes, there are many!) So
				274	Valgrind reads a list of errors to suppress at startup. By default
				275	this file is <code>redhat72.supp</code>, located in the Valgrind
				276	installation directory.
				277
				278	<p>You can modify and add to the suppressions file at your leisure, or
				279	write your own. Multiple suppression files are allowed. This is
				280	useful if part of your project contains errors you can't or don't want
				281	to fix, yet you don't want to continuously be reminded of them.
				282
				283	<p>Each error to be suppressed is described very specifically, to
				284	minimise the possibility that a suppression-directive inadvertantly
				285	suppresses a bunch of similar errors which you did want to see. The
				286	suppression mechanism is designed to allow precise yet flexible
				287	specification of errors to suppress.
				288
				289	<p>If you use the <code>-v</code> flag, at the end of execution, Valgrind
				290	prints out one line for each used suppression, giving its name and the
				291	number of times it got used. Here's the suppressions used by a run of
				292	<code>ls -l</code>:
				293	<pre>
				294	--27579-- supp: 1 socketcall.connect(serv_addr)/__libc_connect/__nscd_getgrgid_r
				295	--27579-- supp: 1 socketcall.connect(serv_addr)/__libc_connect/__nscd_getpwuid_r
				296	--27579-- supp: 6 strrchr/_dl_map_object_from_fd/_dl_map_object
				297	</pre>
				298
				299	<a name="flags"></a>
				300	<h3>2.5  Command-line flags</h3>
				301
				302	You invoke Valgrind like this:
				303	<pre>
				304	valgrind [options-for-Valgrind] your-prog [options for your-prog]
				305	</pre>
				306
				307	<p>Valgrind's default settings succeed in giving reasonable behaviour
				308	in most cases. Available options, in no particular order, are as
				309	follows:
				310	<ul>
				311	<li><code>--help</code></li><br>
				312
				313	<li><code>--version</code><br>
				314	<p>The usual deal.</li><br><p>
				315
				316	<li><code>-v --verbose</code><br>
				317	<p>Be more verbose. Gives extra information on various aspects
				318	of your program, such as: the shared objects loaded, the
				319	suppressions used, the progress of the instrumentation engine,
				320	and warnings about unusual behaviour.
				321	</li><br><p>
				322
				323	<li><code>-q --quiet</code><br>
				324	<p>Run silently, and only print error messages. Useful if you
				325	are running regression tests or have some other automated test
				326	machinery.
				327	</li><br><p>
				328
				329	<li><code>--demangle=no</code><br>
				330	<code>--demangle=yes</code> [the default]
				331	<p>Disable/enable automatic demangling (decoding) of C++ names.
				332	Enabled by default. When enabled, Valgrind will attempt to
				333	translate encoded C++ procedure names back to something
				334	approaching the original. The demangler handles symbols mangled
				335	by g++ versions 2.X and 3.X.
				336
				337	<p>An important fact about demangling is that function
				338	names mentioned in suppressions files should be in their mangled
				339	form. Valgrind does not demangle function names when searching
				340	for applicable suppressions, because to do otherwise would make
				341	suppressions file contents dependent on the state of Valgrind's
				342	demangling machinery, and would also be slow and pointless.
				343	</li><br><p>
				344
				345	<li><code>--num-callers=<number></code> [default=4]<br>
				346	<p>By default, Valgrind shows four levels of function call names
				347	to help you identify program locations. You can change that
				348	number with this option. This can help in determining the
				349	program's location in deeply-nested call chains. Note that errors
				350	are commoned up using only the top three function locations (the
				351	place in the current function, and that of its two immediate
				352	callers). So this doesn't affect the total number of errors
				353	reported.
				354	<p>
				355	The maximum value for this is 50. Note that higher settings
				356	will make Valgrind run a bit more slowly and take a bit more
				357	memory, but can be useful when working with programs with
				358	deeply-nested call chains.
				359	</li><br><p>
				360
				361	<li><code>--gdb-attach=no</code> [the default]<br>
				362	<code>--gdb-attach=yes</code>
				363	<p>When enabled, Valgrind will pause after every error shown,
				364	and print the line
				365	<br>
				366	<code>---- Attach to GDB ? --- [Return/N/n/Y/y/C/c] ----</code>
				367	<p>
				368	Pressing <code>Ret</code>, or <code>N</code> <code>Ret</code>
				369	or <code>n</code> <code>Ret</code>, causes Valgrind not to
				370	start GDB for this error.
				371	<p>
				372	<code>Y</code> <code>Ret</code>
				373	or <code>y</code> <code>Ret</code> causes Valgrind to
				374	start GDB, for the program at this point. When you have
				375	finished with GDB, quit from it, and the program will continue.
				376	Trying to continue from inside GDB doesn't work.
				377	<p>
				378	<code>C</code> <code>Ret</code>
				379	or <code>c</code> <code>Ret</code> causes Valgrind not to
				380	start GDB, and not to ask again.
				381	<p>
				382	<code>--gdb-attach=yes</code> conflicts with
				383	<code>--trace-children=yes</code>. You can't use them
				384	together. Valgrind refuses to start up in this situation.
				385	</li><br><p>
				386
				387	<li><code>--partial-loads-ok=yes</code> [the default]<br>
				388	<code>--partial-loads-ok=no</code>
				389	<p>Controls how Valgrind handles word (4-byte) loads from
				390	addresses for which some bytes are addressible and others
				391	are not. When <code>yes</code> (the default), such loads
				392	do not elicit an address error. Instead, the loaded V bytes
				393	corresponding to the illegal addresses indicate undefined, and
				394	those corresponding to legal addresses are loaded from shadow
				395	memory, as usual.
				396	<p>
				397	When <code>no</code>, loads from partially
				398	invalid addresses are treated the same as loads from completely
				399	invalid addresses: an illegal-address error is issued,
				400	and the resulting V bytes indicate valid data.
				401	</li><br><p>
				402
				403	<li><code>--sloppy-malloc=no</code> [the default]<br>
				404	<code>--sloppy-malloc=yes</code>
				405	<p>When enabled, all requests for malloc/calloc are rounded up
				406	to a whole number of machine words -- in other words, made
				407	divisible by 4. For example, a request for 17 bytes of space
				408	would result in a 20-byte area being made available. This works
				409	around bugs in sloppy libraries which assume that they can
				410	safely rely on malloc/calloc requests being rounded up in this
				411	fashion. Without the workaround, these libraries tend to
				412	generate large numbers of errors when they access the ends of
				413	these areas. Valgrind snapshots dated 17 Feb 2002 and later are
				414	cleverer about this problem, and you should no longer need to
				415	use this flag.
				416	</li><br><p>
				417
				418	<li><code>--trace-children=no</code> [the default]</br>
				419	<code>--trace-children=yes</code>
				420	<p>When enabled, Valgrind will trace into child processes. This
				421	is confusing and usually not what you want, so is disabled by
				422	default.</li><br><p>
				423
				424	<li><code>--freelist-vol=<number></code> [default: 1000000]
				425	<p>When the client program releases memory using free (in C) or
				426	delete (C++), that memory is not immediately made available for
				427	re-allocation. Instead it is marked inaccessible and placed in
				428	a queue of freed blocks. The purpose is to delay the point at
				429	which freed-up memory comes back into circulation. This
				430	increases the chance that Valgrind will be able to detect
				431	invalid accesses to blocks for some significant period of time
				432	after they have been freed.
				433	<p>
				434	This flag specifies the maximum total size, in bytes, of the
				435	blocks in the queue. The default value is one million bytes.
				436	Increasing this increases the total amount of memory used by
				437	Valgrind but may detect invalid uses of freed blocks which would
				438	otherwise go undetected.</li><br><p>
				439
				440	<li><code>--logfile-fd=<number></code> [default: 2, stderr]
				441	<p>Specifies the file descriptor on which Valgrind communicates
				442	all of its messages. The default, 2, is the standard error
				443	channel. This may interfere with the client's own use of
				444	stderr. To dump Valgrind's commentary in a file without using
				445	stderr, something like the following works well (sh/bash
				446	syntax):<br>
				447	<code>
				448	valgrind --logfile-fd=9 my_prog 9> logfile</code><br>
				449	That is: tell Valgrind to send all output to file descriptor 9,
				450	and ask the shell to route file descriptor 9 to "logfile".
				451	</li><br><p>
				452
				453	<li><code>--suppressions=<filename></code> [default:
				454	/installation/directory/redhat72.supp] <p>Specifies an extra
				455	file from which to read descriptions of errors to suppress. You
				456	may use as many extra suppressions files as you
				457	like.</li><br><p>
				458
				459	<li><code>--leak-check=no</code> [default]<br>
				460	<code>--leak-check=yes</code>
				461	<p>When enabled, search for memory leaks when the client program
				462	finishes. A memory leak means a malloc'd block, which has not
				463	yet been free'd, but to which no pointer can be found. Such a
				464	block can never be free'd by the program, since no pointer to it
				465	exists. Leak checking is disabled by default
				466	because it tends to generate dozens of error messages.
				467	</li><br><p>
				468
				469	<li><code>--show-reachable=no</code> [default]<br>
				470	<code>--show-reachable=yes</code> <p>When disabled, the memory
				471	leak detector only shows blocks for which it cannot find a
				472	pointer to at all, or it can only find a pointer to the middle
				473	of. These blocks are prime candidates for memory leaks. When
				474	enabled, the leak detector also reports on blocks which it could
				475	find a pointer to. Your program could, at least in principle,
				476	have freed such blocks before exit. Contrast this to blocks for
				477	which no pointer, or only an interior pointer could be found:
				478	they are more likely to indicate memory leaks, because
				479	you do not actually have a pointer to the start of the block
				480	which you can hand to free(), even if you wanted to.
				481	</li><br><p>
				482
				483	<li><code>--leak-resolution=low</code> [default]<br>
				484	<code>--leak-resolution=med</code> <br>
				485	<code>--leak-resolution=high</code>
				486	<p>When doing leak checking, determines how willing Valgrind is
				487	to consider different backtraces the same. When set to
				488	<code>low</code>, the default, only the first two entries need
				489	match. When <code>med</code>, four entries have to match. When
				490	<code>high</code>, all entries need to match.
				491	<p>
				492	For hardcore leak debugging, you probably want to use
				493	<code>--leak-resolution=high</code> together with
				494	<code>--num-callers=40</code> or some such large number. Note
				495	however that this can give an overwhelming amount of
				496	information, which is why the defaults are 4 callers and
				497	low-resolution matching.
				498	<p>
				499	Note that the <code>--leak-resolution=</code> setting does not
				500	affect Valgrind's ability to find leaks. It only changes how
				501	the results are presented to you.
				502	</li><br><p>
				503
				504	<li><code>--workaround-gcc296-bugs=no</code> [default]<br>
				505	<code>--workaround-gcc296-bugs=yes</code> <p>When enabled,
				506	assume that reads and writes some small distance below the stack
				507	pointer <code>%esp</code> are due to bugs in gcc 2.96, and does
				508	not report them. The "small distance" is 256 bytes by default.
				509	Note that gcc 2.96 is the default compiler on some popular Linux
				510	distributions (RedHat 7.X, Mandrake) and so you may well need to
				511	use this flag. Do not use it if you do not have to, as it can
				512	cause real errors to be overlooked. A better option is to use a
				513	gcc/g++ which works properly; 2.95.3 seems to be a good choice.
				514	<p>
				515	Unfortunately (27 Feb 02) it looks like g++ 3.0.4 is similarly
				516	buggy, so you may need to issue this flag if you use 3.0.4.
				517	</li><br><p>
				518
sewardj	de4a1d0	2002-03-22 01:27:54 +0000	[diff] [blame]	519	</ul>
				520
				521	There are also some options for debugging Valgrind itself. You
				522	shouldn't need to use them in the normal run of things. Nevertheless:
				523
				524	<ul>
				525
				526	<li><code>--single-step=no</code> [default]<br>
				527	<code>--single-step=yes</code>
				528	<p>When enabled, each x86 insn is translated seperately into
				529	instrumented code. When disabled, translation is done on a
				530	per-basic-block basis, giving much better translations.</li><br>
				531	<p>
				532
				533	<li><code>--optimise=no</code><br>
				534	<code>--optimise=yes</code> [default]
				535	<p>When enabled, various improvements are applied to the
				536	intermediate code, mainly aimed at allowing the simulated CPU's
				537	registers to be cached in the real CPU's registers over several
				538	simulated instructions.</li><br>
				539	<p>
				540
				541	<li><code>--instrument=no</code><br>
				542	<code>--instrument=yes</code> [default]
				543	<p>When disabled, the translations don't actually contain any
				544	instrumentation.</li><br>
				545	<p>
				546
				547	<li><code>--cleanup=no</code><br>
				548	<code>--cleanup=yes</code> [default]
				549	<p>When enabled, various improvments are applied to the
				550	post-instrumented intermediate code, aimed at removing redundant
				551	value checks.</li><br>
				552	<p>
				553
				554	<li><code>--trace-syscalls=no</code> [default]<br>
				555	<code>--trace-syscalls=yes</code>
				556	<p>Enable/disable tracing of system call intercepts.</li><br>
				557	<p>
				558
				559	<li><code>--trace-signals=no</code> [default]<br>
				560	<code>--trace-signals=yes</code>
				561	<p>Enable/disable tracing of signal handling.</li><br>
				562	<p>
				563
sewardj	c7529c3	2002-04-16 01:55:18 +0000	[diff] [blame^]	564	<li><code>--trace-sched=no</code> [default]<br>
				565	<code>--trace-sched=yes</code>
				566	<p>Enable/disable tracing of thread scheduling events.</li><br>
				567	<p>
				568
				569	<li><code>--trace-pthread=no</code> [default]<br>
				570	<code>--trace-pthread=yes</code>
				571	<p>Enable/disable tracing of pthread-related events.</li><br>
				572	<p>
				573
sewardj	de4a1d0	2002-03-22 01:27:54 +0000	[diff] [blame]	574	<li><code>--trace-symtab=no</code> [default]<br>
				575	<code>--trace-symtab=yes</code>
				576	<p>Enable/disable tracing of symbol table reading.</li><br>
				577	<p>
				578
				579	<li><code>--trace-malloc=no</code> [default]<br>
				580	<code>--trace-malloc=yes</code>
				581	<p>Enable/disable tracing of malloc/free (et al) intercepts.
				582	</li><br>
				583	<p>
				584
				585	<li><code>--stop-after=<number></code>
				586	[default: infinity, more or less]
				587	<p>After <number> basic blocks have been executed, shut down
				588	Valgrind and switch back to running the client on the real CPU.
				589	</li><br>
				590	<p>
				591
				592	<li><code>--dump-error=<number></code>
				593	[default: inactive]
				594	<p>After the program has exited, show gory details of the
				595	translation of the basic block containing the <number>'th
				596	error context. When used with <code>--single-step=yes</code>,
				597	can show the
				598	exact x86 instruction causing an error.</li><br>
				599	<p>
				600
				601	<li><code>--smc-check=none</code><br>
				602	<code>--smc-check=some</code> [default]<br>
				603	<code>--smc-check=all</code>
				604	<p>How carefully should Valgrind check for self-modifying code
				605	writes, so that translations can be discarded?  When
				606	"none", no writes are checked. When "some", only writes
				607	resulting from moves from integer registers to memory are
				608	checked. When "all", all memory writes are checked, even those
				609	with which are no sane program would generate code -- for
				610	example, floating-point writes.</li>
				611	</ul>
				612
				613
				614	<a name="errormsgs">
				615	<h3>2.6  Explaination of error messages</h3>
				616
				617	Despite considerable sophistication under the hood, Valgrind can only
				618	really detect two kinds of errors, use of illegal addresses, and use
				619	of undefined values. Nevertheless, this is enough to help you
				620	discover all sorts of memory-management nasties in your code. This
				621	section presents a quick summary of what error messages mean. The
				622	precise behaviour of the error-checking machinery is described in
				623	<a href="#machine">Section 4</a>.
				624
				625
				626	<h4>2.6.1  Illegal read / Illegal write errors</h4>
				627	For example:
				628	<pre>
				629	==30975== Invalid read of size 4
				630	==30975== at 0x40F6BBCC: (within /usr/lib/libpng.so.2.1.0.9)
				631	==30975== by 0x40F6B804: (within /usr/lib/libpng.so.2.1.0.9)
				632	==30975== by 0x40B07FF4: read_png_image__FP8QImageIO (kernel/qpngio.cpp:326)
				633	==30975== by 0x40AC751B: QImageIO::read() (kernel/qimage.cpp:3621)
				634	==30975== Address 0xBFFFF0E0 is not stack'd, malloc'd or free'd
				635	</pre>
				636
				637	<p>This happens when your program reads or writes memory at a place
				638	which Valgrind reckons it shouldn't. In this example, the program did
				639	a 4-byte read at address 0xBFFFF0E0, somewhere within the
				640	system-supplied library libpng.so.2.1.0.9, which was called from
				641	somewhere else in the same library, called from line 326 of
				642	qpngio.cpp, and so on.
				643
				644	<p>Valgrind tries to establish what the illegal address might relate
				645	to, since that's often useful. So, if it points into a block of
				646	memory which has already been freed, you'll be informed of this, and
sewardj	c7529c3	2002-04-16 01:55:18 +0000	[diff] [blame^]	647	also where the block was free'd at. Likewise, if it should turn out
sewardj	de4a1d0	2002-03-22 01:27:54 +0000	[diff] [blame]	648	to be just off the end of a malloc'd block, a common result of
				649	off-by-one-errors in array subscripting, you'll be informed of this
				650	fact, and also where the block was malloc'd.
				651
				652	<p>In this example, Valgrind can't identify the address. Actually the
				653	address is on the stack, but, for some reason, this is not a valid
				654	stack address -- it is below the stack pointer, %esp, and that isn't
				655	allowed.
				656
				657	<p>Note that Valgrind only tells you that your program is about to
				658	access memory at an illegal address. It can't stop the access from
				659	happening. So, if your program makes an access which normally would
				660	result in a segmentation fault, you program will still suffer the same
				661	fate -- but you will get a message from Valgrind immediately prior to
				662	this. In this particular example, reading junk on the stack is
				663	non-fatal, and the program stays alive.
				664
				665
				666	<h4>2.6.2  Use of uninitialised values</h4>
				667	For example:
				668	<pre>
sewardj	a7dc795	2002-03-24 11:29:13 +0000	[diff] [blame]	669	==19146== Conditional jump or move depends on uninitialised value(s)
sewardj	de4a1d0	2002-03-22 01:27:54 +0000	[diff] [blame]	670	==19146== at 0x402DFA94: _IO_vfprintf (_itoa.h:49)
				671	==19146== by 0x402E8476: _IO_printf (printf.c:36)
				672	==19146== by 0x8048472: main (tests/manuel1.c:8)
				673	==19146== by 0x402A6E5E: __libc_start_main (libc-start.c:129)
				674	</pre>
				675
				676	<p>An uninitialised-value use error is reported when your program uses
				677	a value which hasn't been initialised -- in other words, is undefined.
				678	Here, the undefined value is used somewhere inside the printf()
				679	machinery of the C library. This error was reported when running the
				680	following small program:
				681	<pre>
				682	int main()
				683	{
				684	int x;
				685	printf ("x = %d\n", x);
				686	}
				687	</pre>
				688
				689	<p>It is important to understand that your program can copy around
				690	junk (uninitialised) data to its heart's content. Valgrind observes
				691	this and keeps track of the data, but does not complain. A complaint
				692	is issued only when your program attempts to make use of uninitialised
				693	data. In this example, x is uninitialised. Valgrind observes the
				694	value being passed to _IO_printf and thence to
				695	_IO_vfprintf, but makes no comment. However,
				696	_IO_vfprintf has to examine the value of x
				697	so it can turn it into the corresponding ASCII string, and it is at
				698	this point that Valgrind complains.
				699
				700	<p>Sources of uninitialised data tend to be:
				701	<ul>
				702	<li>Local variables in procedures which have not been initialised,
				703	as in the example above.</li><br><p>
				704
				705	<li>The contents of malloc'd blocks, before you write something
				706	there. In C++, the new operator is a wrapper round malloc, so
				707	if you create an object with new, its fields will be
				708	uninitialised until you fill them in, which is only Right and
				709	Proper.</li>
				710	</ul>
				711
				712
				713
				714	<h4>2.6.3  Illegal frees</h4>
				715	For example:
				716	<pre>
				717	==7593== Invalid free()
				718	==7593== at 0x4004FFDF: free (ut_clientmalloc.c:577)
				719	==7593== by 0x80484C7: main (tests/doublefree.c:10)
				720	==7593== by 0x402A6E5E: __libc_start_main (libc-start.c:129)
				721	==7593== by 0x80483B1: (within tests/doublefree)
				722	==7593== Address 0x3807F7B4 is 0 bytes inside a block of size 177 free'd
				723	==7593== at 0x4004FFDF: free (ut_clientmalloc.c:577)
				724	==7593== by 0x80484C7: main (tests/doublefree.c:10)
				725	==7593== by 0x402A6E5E: __libc_start_main (libc-start.c:129)
				726	==7593== by 0x80483B1: (within tests/doublefree)
				727	</pre>
				728	<p>Valgrind keeps track of the blocks allocated by your program with
				729	malloc/new, so it can know exactly whether or not the argument to
				730	free/delete is legitimate or not. Here, this test program has
				731	freed the same block twice. As with the illegal read/write errors,
				732	Valgrind attempts to make sense of the address free'd. If, as
				733	here, the address is one which has previously been freed, you wil
				734	be told that -- making duplicate frees of the same block easy to spot.
				735
				736
				737	<h4>2.6.4  Passing system call parameters with inadequate
				738	read/write permissions</h4>
				739
				740	Valgrind checks all parameters to system calls. If a system call
				741	needs to read from a buffer provided by your program, Valgrind checks
				742	that the entire buffer is addressible and has valid data, ie, it is
				743	readable. And if the system call needs to write to a user-supplied
				744	buffer, Valgrind checks that the buffer is addressible. After the
				745	system call, Valgrind updates its administrative information to
				746	precisely reflect any changes in memory permissions caused by the
				747	system call.
				748
				749	<p>Here's an example of a system call with an invalid parameter:
				750	<pre>
				751	#include <stdlib.h>
				752	#include <unistd.h>
				753	int main( void )
				754	{
				755	char* arr = malloc(10);
				756	(void) write( 1 /* stdout */, arr, 10 );
				757	return 0;
				758	}
				759	</pre>
				760
				761	<p>You get this complaint ...
				762	<pre>
				763	==8230== Syscall param write(buf) lacks read permissions
				764	==8230== at 0x4035E072: __libc_write
				765	==8230== by 0x402A6E5E: __libc_start_main (libc-start.c:129)
				766	==8230== by 0x80483B1: (within tests/badwrite)
				767	==8230== by <bogus frame pointer> ???
				768	==8230== Address 0x3807E6D0 is 0 bytes inside a block of size 10 alloc'd
				769	==8230== at 0x4004FEE6: malloc (ut_clientmalloc.c:539)
				770	==8230== by 0x80484A0: main (tests/badwrite.c:6)
				771	==8230== by 0x402A6E5E: __libc_start_main (libc-start.c:129)
				772	==8230== by 0x80483B1: (within tests/badwrite)
				773	</pre>
				774
				775	<p>... because the program has tried to write uninitialised junk from
				776	the malloc'd block to the standard output.
				777
				778
				779	<h4>2.6.5  Warning messages you might see</h4>
				780
				781	Most of these only appear if you run in verbose mode (enabled by
				782	<code>-v</code>):
				783	<ul>
				784	<li> <code>More than 50 errors detected. Subsequent errors
				785	will still be recorded, but in less detail than before.</code>
				786	<br>
				787	After 50 different errors have been shown, Valgrind becomes
				788	more conservative about collecting them. It then requires only
				789	the program counters in the top two stack frames to match when
				790	deciding whether or not two errors are really the same one.
				791	Prior to this point, the PCs in the top four frames are required
				792	to match. This hack has the effect of slowing down the
				793	appearance of new errors after the first 50. The 50 constant can
				794	be changed by recompiling Valgrind.
				795	<p>
				796	<li> <code>More than 500 errors detected. I'm not reporting any more.
				797	Final error counts may be inaccurate. Go fix your
				798	program!</code>
				799	<br>
				800	After 500 different errors have been detected, Valgrind ignores
				801	any more. It seems unlikely that collecting even more different
				802	ones would be of practical help to anybody, and it avoids the
				803	danger that Valgrind spends more and more of its time comparing
				804	new errors against an ever-growing collection. As above, the 500
				805	number is a compile-time constant.
				806	<p>
				807	<li> <code>Warning: client exiting by calling exit(<number>).
				808	Bye!</code>
				809	<br>
				810	Your program has called the <code>exit</code> system call, which
				811	will immediately terminate the process. You'll get no exit-time
				812	error summaries or leak checks. Note that this is not the same
				813	as your program calling the ANSI C function <code>exit()</code>
				814	-- that causes a normal, controlled shutdown of Valgrind.
				815	<p>
				816	<li> <code>Warning: client switching stacks?</code>
				817	<br>
				818	Valgrind spotted such a large change in the stack pointer, %esp,
				819	that it guesses the client is switching to a different stack.
				820	At this point it makes a kludgey guess where the base of the new
				821	stack is, and sets memory permissions accordingly. You may get
				822	many bogus error messages following this, if Valgrind guesses
				823	wrong. At the moment "large change" is defined as a change of
				824	more that 2000000 in the value of the %esp (stack pointer)
				825	register.
				826	<p>
				827	<li> <code>Warning: client attempted to close Valgrind's logfile fd <number>
				828	</code>
				829	<br>
				830	Valgrind doesn't allow the client
				831	to close the logfile, because you'd never see any diagnostic
				832	information after that point. If you see this message,
				833	you may want to use the <code>--logfile-fd=<number></code>
				834	option to specify a different logfile file-descriptor number.
				835	<p>
				836	<li> <code>Warning: noted but unhandled ioctl <number></code>
				837	<br>
				838	Valgrind observed a call to one of the vast family of
				839	<code>ioctl</code> system calls, but did not modify its
				840	memory status info (because I have not yet got round to it).
				841	The call will still have gone through, but you may get spurious
				842	errors after this as a result of the non-update of the memory info.
				843	<p>
				844	<li> <code>Warning: unblocking signal <number> due to
				845	sigprocmask</code>
				846	<br>
				847	Really just a diagnostic from the signal simulation machinery.
				848	This message will appear if your program handles a signal by
				849	first <code>longjmp</code>ing out of the signal handler,
				850	and then unblocking the signal with <code>sigprocmask</code>
				851	-- a standard signal-handling idiom.
				852	<p>
				853	<li> <code>Warning: bad signal number <number> in __NR_sigaction.</code>
				854	<br>
				855	Probably indicates a bug in the signal simulation machinery.
				856	<p>
				857	<li> <code>Warning: set address range perms: large range <number></code>
				858	<br>
				859	Diagnostic message, mostly for my benefit, to do with memory
				860	permissions.
				861	</ul>
				862
				863
				864	<a name="suppfiles"></a>
				865	<h3>2.7  Writing suppressions files</h3>
				866
				867	A suppression file describes a bunch of errors which, for one reason
				868	or another, you don't want Valgrind to tell you about. Usually the
				869	reason is that the system libraries are buggy but unfixable, at least
				870	within the scope of the current debugging session. Multiple
				871	suppresions files are allowed. By default, Valgrind uses
				872	<code>linux24.supp</code> in the directory where it is installed.
				873
				874	<p>
				875	You can ask to add suppressions from another file, by specifying
				876	<code>--suppressions=/path/to/file.supp</code>.
				877
				878	<p>Each suppression has the following components:<br>
				879	<ul>
				880
				881	<li>Its name. This merely gives a handy name to the suppression, by
				882	which it is referred to in the summary of used suppressions
				883	printed out when a program finishes. It's not important what
				884	the name is; any identifying string will do.
				885	<p>
				886
				887	<li>The nature of the error to suppress. Either:
				888	<code>Value1</code>,
				889	<code>Value2</code>,
sewardj	a7dc795	2002-03-24 11:29:13 +0000	[diff] [blame]	890	<code>Value4</code> or
				891	<code>Value8</code>,
sewardj	de4a1d0	2002-03-22 01:27:54 +0000	[diff] [blame]	892	meaning an uninitialised-value error when
sewardj	a7dc795	2002-03-24 11:29:13 +0000	[diff] [blame]	893	using a value of 1, 2, 4 or 8 bytes.
				894	Or
				895	<code>Cond</code> (or its old name, <code>Value0</code>),
				896	meaning use of an uninitialised CPU condition code. Or:
sewardj	de4a1d0	2002-03-22 01:27:54 +0000	[diff] [blame]	897	<code>Addr1</code>,
				898	<code>Addr2</code>,
				899	<code>Addr4</code> or
				900	<code>Addr8</code>, meaning an invalid address during a
				901	memory access of 1, 2, 4 or 8 bytes respectively. Or
				902	<code>Param</code>,
				903	meaning an invalid system call parameter error. Or
				904	<code>Free</code>, meaning an invalid or mismatching free.</li><br>
				905	<p>
				906
				907	<li>The "immediate location" specification. For Value and Addr
				908	errors, is either the name of the function in which the error
				909	occurred, or, failing that, the full path the the .so file
				910	containing the error location. For Param errors, is the name of
				911	the offending system call parameter. For Free errors, is the
				912	name of the function doing the freeing (eg, <code>free</code>,
				913	<code>__builtin_vec_delete</code>, etc)</li><br>
				914	<p>
				915
				916	<li>The caller of the above "immediate location". Again, either a
				917	function or shared-object name.</li><br>
				918	<p>
				919
				920	<li>Optionally, one or two extra calling-function or object names,
				921	for greater precision.</li>
				922	</ul>
				923
				924	<p>
				925	Locations may be either names of shared objects or wildcards matching
				926	function names. They begin <code>obj:</code> and <code>fun:</code>
				927	respectively. Function and object names to match against may use the
				928	wildcard characters <code>*</code> and <code>?</code>.
				929
				930	A suppression only suppresses an error when the error matches all the
				931	details in the suppression. Here's an example:
				932	<pre>
				933	{
				934	__gconv_transform_ascii_internal/__mbrtowc/mbtowc
				935	Value4
				936	fun:__gconv_transform_ascii_internal
				937	fun:__mbr*toc
				938	fun:mbtowc
				939	}
				940	</pre>
				941
				942	<p>What is means is: suppress a use-of-uninitialised-value error, when
				943	the data size is 4, when it occurs in the function
				944	<code>__gconv_transform_ascii_internal</code>, when that is called
				945	from any function of name matching <code>__mbr*toc</code>,
				946	when that is called from
				947	<code>mbtowc</code>. It doesn't apply under any other circumstances.
				948	The string by which this suppression is identified to the user is
				949	__gconv_transform_ascii_internal/__mbrtowc/mbtowc.
				950
				951	<p>Another example:
				952	<pre>
				953	{
				954	libX11.so.6.2/libX11.so.6.2/libXaw.so.7.0
				955	Value4
				956	obj:/usr/X11R6/lib/libX11.so.6.2
				957	obj:/usr/X11R6/lib/libX11.so.6.2
				958	obj:/usr/X11R6/lib/libXaw.so.7.0
				959	}
				960	</pre>
				961
				962	<p>Suppress any size 4 uninitialised-value error which occurs anywhere
				963	in <code>libX11.so.6.2</code>, when called from anywhere in the same
				964	library, when called from anywhere in <code>libXaw.so.7.0</code>. The
				965	inexact specification of locations is regrettable, but is about all
				966	you can hope for, given that the X11 libraries shipped with Red Hat
				967	7.2 have had their symbol tables removed.
				968
				969	<p>Note -- since the above two examples did not make it clear -- that
				970	you can freely mix the <code>obj:</code> and <code>fun:</code>
				971	styles of description within a single suppression record.
				972
				973
				974	<a name="install"></a>
				975	<h3>2.8  Building and installing</h3>
				976	At the moment, very rudimentary.
				977
				978	<p>The tarball is set up for a standard Red Hat 7.1 (6.2) machine. To
				979	build, just do "make". No configure script, no autoconf, no nothing.
				980
				981	<p>The files needed for installation are: valgrind.so, valgring.so,
				982	valgrind, VERSION, redhat72.supp (or redhat62.supp). You can copy
				983	these to any directory you like. However, you then need to edit the
				984	shell script "valgrind". On line 4, set the environment variable
				985	<code>VALGRIND</code> to point to the directory you have copied the
				986	installation into.
				987
				988
sewardj	c7529c3	2002-04-16 01:55:18 +0000	[diff] [blame^]	989	<a name="install"></a>
				990	<h3>2.9  The Client Request mechanism</h3>
				991
				992	Valgrind has a trapdoor mechanism via which the client program can
				993	pass all manner of requests and queries to Valgrind. Internally, this
				994	is used extensively to make malloc, free, signals, etc, work, although
				995	you don't see that.
				996	<p>
				997	For your convenience, a subset of these so-called client requests is
				998	provided to allow you to tell Valgrind facts about the behaviour of
				999	your program, and conversely to make queries. In particular, your
				1000	program can tell Valgrind about changes in memory range permissions
				1001	that Valgrind would not otherwise know about, and so allows clients to
				1002	get Valgrind to do arbitrary custom checks.
				1003	<p>
				1004	Clients need to include the header file <code>valgrind.h</code> to
				1005	make this work. The macros therein have the magical property that
				1006	they generate code in-line which Valgrind can spot. However, the code
				1007	does nothing when not run on Valgrind, so you are not forced to run
				1008	your program on Valgrind just because you use the macros in this file.
				1009	<p>
				1010	A brief description of the available macros:
				1011	<ul>
				1012	<li><code>VALGRIND_MAKE_NOACCESS</code>,
				1013	<code>VALGRIND_MAKE_WRITABLE</code> and
				1014	<code>VALGRIND_MAKE_READABLE</code>. These mark address
				1015	ranges as completely inaccessible, accessible but containing
				1016	undefined data, and accessible and containing defined data,
				1017	respectively. Subsequent errors may have their faulting
				1018	addresses described in terms of these blocks. Returns a
				1019	"block handle". Returns zero when not run on Valgrind.
				1020	<p>
				1021	<li><code>VALGRIND_DISCARD</code>: At some point you may want
				1022	Valgrind to stop reporting errors in terms of the blocks
				1023	defined by the previous three macros. To do this, the above
				1024	macros return a small-integer "block handle". You can pass
				1025	this block handle to <code>VALGRIND_DISCARD</code>. After
				1026	doing so, Valgrind will no longer be able to relate
				1027	addressing errors to the user-defined block associated with
				1028	the handle. The permissions settings associated with the
				1029	handle remain in place; this just affects how errors are
				1030	reported, not whether they are reported. Returns 1 for an
				1031	invalid handle and 0 for a valid handle (although passing
				1032	invalid handles is harmless). Always returns 0 when not run
				1033	on Valgrind.
				1034	<p>
				1035	<li><code>VALGRIND_CHECK_NOACCESS</code>,
				1036	<code>VALGRIND_CHECK_WRITABLE</code> and
				1037	<code>VALGRIND_CHECK_READABLE</code>: check immediately
				1038	whether or not the given address range has the relevant
				1039	property, and if not, print an error message. Also, for the
				1040	convenience of the client, returns zero if the relevant
				1041	property holds; otherwise, the returned value is the address
				1042	of the first byte for which the property is not true.
				1043	Always returns 0 when not run on Valgrind.
				1044	<p>
				1045	<li><code>VALGRIND_CHECK_NOACCESS</code>: a quick and easy way
				1046	to find out whether Valgrind thinks a particular variable
				1047	(lvalue, to be precise) is addressible and defined. Prints
				1048	an error message if not. Returns no value.
				1049	<p>
				1050	<li><code>VALGRIND_MAKE_NOACCESS_STACK</code>: a highly
				1051	experimental feature. Similarly to
				1052	<code>VALGRIND_MAKE_NOACCESS</code>, this marks an address
				1053	range as inaccessible, so that subsequent accesses to an
				1054	address in the range gives an error. However, this macro
				1055	does not return a block handle. Instead, all annotations
				1056	created like this are reviewed at each client
				1057	<code>ret</code> (subroutine return) instruction, and those
				1058	which now define an address range block the client's stack
				1059	pointer register (<code>%esp</code>) are automatically
				1060	deleted.
				1061	<p>
				1062	In other words, this macro allows the client to tell
				1063	Valgrind about red-zones on its own stack. Valgrind
				1064	automatically discards this information when the stack
				1065	retreats past such blocks. Beware: hacky and flaky, and
				1066	probably interacts badly with the new pthread support.
				1067	</ul>
				1068	</li>
				1069	<p>
				1070
				1071
				1072
sewardj	de4a1d0	2002-03-22 01:27:54 +0000	[diff] [blame]	1073	<a name="problems"></a>
sewardj	c7529c3	2002-04-16 01:55:18 +0000	[diff] [blame^]	1074	<h3>2.10  If you have problems</h3>
sewardj	de4a1d0	2002-03-22 01:27:54 +0000	[diff] [blame]	1075	Mail me (<a href="mailto:jseward@acm.org">jseward@acm.org</a>).
				1076
				1077	<p>See <a href="#limits">Section 4</a> for the known limitations of
				1078	Valgrind, and for a list of programs which are known not to work on
				1079	it.
				1080
				1081	<p>The translator/instrumentor has a lot of assertions in it. They
				1082	are permanently enabled, and I have no plans to disable them. If one
				1083	of these breaks, please mail me!
				1084
				1085	<p>If you get an assertion failure on the expression
				1086	<code>chunkSane(ch)</code> in <code>vg_free()</code> in
				1087	<code>vg_malloc.c</code>, this may have happened because your program
				1088	wrote off the end of a malloc'd block, or before its beginning.
				1089	Valgrind should have emitted a proper message to that effect before
				1090	dying in this way. This is a known problem which I should fix.
				1091	<p>
				1092
				1093	<hr width="100%">
				1094
				1095	<a name="machine"></a>
				1096	<h2>3  Details of the checking machinery</h2>
				1097
				1098	Read this section if you want to know, in detail, exactly what and how
				1099	Valgrind is checking.
				1100
				1101	<a name="vvalue"></a>
				1102	<h3>3.1  Valid-value (V) bits</h3>
				1103
				1104	It is simplest to think of Valgrind implementing a synthetic Intel x86
				1105	CPU which is identical to a real CPU, except for one crucial detail.
				1106	Every bit (literally) of data processed, stored and handled by the
				1107	real CPU has, in the synthetic CPU, an associated "valid-value" bit,
				1108	which says whether or not the accompanying bit has a legitimate value.
				1109	In the discussions which follow, this bit is referred to as the V
				1110	(valid-value) bit.
				1111
				1112	<p>Each byte in the system therefore has a 8 V bits which accompanies
				1113	it wherever it goes. For example, when the CPU loads a word-size item
				1114	(4 bytes) from memory, it also loads the corresponding 32 V bits from
				1115	a bitmap which stores the V bits for the process' entire address
				1116	space. If the CPU should later write the whole or some part of that
				1117	value to memory at a different address, the relevant V bits will be
				1118	stored back in the V-bit bitmap.
				1119
				1120	<p>In short, each bit in the system has an associated V bit, which
				1121	follows it around everywhere, even inside the CPU. Yes, the CPU's
				1122	(integer) registers have their own V bit vectors.
				1123
				1124	<p>Copying values around does not cause Valgrind to check for, or
				1125	report on, errors. However, when a value is used in a way which might
				1126	conceivably affect the outcome of your program's computation, the
				1127	associated V bits are immediately checked. If any of these indicate
				1128	that the value is undefined, an error is reported.
				1129
				1130	<p>Here's an (admittedly nonsensical) example:
				1131	<pre>
				1132	int i, j;
				1133	int a[10], b[10];
				1134	for (i = 0; i < 10; i++) {
				1135	j = a[i];
				1136	b[i] = j;
				1137	}
				1138	</pre>
				1139
				1140	<p>Valgrind emits no complaints about this, since it merely copies
				1141	uninitialised values from <code>a[]</code> into <code>b[]</code>, and
				1142	doesn't use them in any way. However, if the loop is changed to
				1143	<pre>
				1144	for (i = 0; i < 10; i++) {
				1145	j += a[i];
				1146	}
				1147	if (j == 77)
				1148	printf("hello there\n");
				1149	</pre>
				1150	then Valgrind will complain, at the <code>if</code>, that the
				1151	condition depends on uninitialised values.
				1152
				1153	<p>Most low level operations, such as adds, cause Valgrind to
				1154	use the V bits for the operands to calculate the V bits for the
				1155	result. Even if the result is partially or wholly undefined,
				1156	it does not complain.
				1157
				1158	<p>Checks on definedness only occur in two places: when a value is
				1159	used to generate a memory address, and where control flow decision
				1160	needs to be made. Also, when a system call is detected, valgrind
				1161	checks definedness of parameters as required.
				1162
				1163	<p>If a check should detect undefinedness, and error message is
				1164	issued. The resulting value is subsequently regarded as well-defined.
				1165	To do otherwise would give long chains of error messages. In effect,
				1166	we say that undefined values are non-infectious.
				1167
				1168	<p>This sounds overcomplicated. Why not just check all reads from
				1169	memory, and complain if an undefined value is loaded into a CPU register?
				1170	Well, that doesn't work well, because perfectly legitimate C programs routinely
				1171	copy uninitialised values around in memory, and we don't want endless complaints
				1172	about that. Here's the canonical example. Consider a struct
				1173	like this:
				1174	<pre>
				1175	struct S { int x; char c; };
				1176	struct S s1, s2;
				1177	s1.x = 42;
				1178	s1.c = 'z';
				1179	s2 = s1;
				1180	</pre>
				1181
				1182	<p>The question to ask is: how large is <code>struct S</code>, in
				1183	bytes? An int is 4 bytes and a char one byte, so perhaps a struct S
				1184	occupies 5 bytes? Wrong. All (non-toy) compilers I know of will
				1185	round the size of <code>struct S</code> up to a whole number of words,
				1186	in this case 8 bytes. Not doing this forces compilers to generate
				1187	truly appalling code for subscripting arrays of <code>struct
				1188	S</code>'s.
				1189
				1190	<p>So s1 occupies 8 bytes, yet only 5 of them will be initialised.
				1191	For the assignment <code>s2 = s1</code>, gcc generates code to copy
				1192	all 8 bytes wholesale into <code>s2</code> without regard for their
				1193	meaning. If Valgrind simply checked values as they came out of
				1194	memory, it would yelp every time a structure assignment like this
				1195	happened. So the more complicated semantics described above is
				1196	necessary. This allows gcc to copy <code>s1</code> into
				1197	<code>s2</code> any way it likes, and a warning will only be emitted
				1198	if the uninitialised values are later used.
				1199
				1200	<p>One final twist to this story. The above scheme allows garbage to
				1201	pass through the CPU's integer registers without complaint. It does
				1202	this by giving the integer registers V tags, passing these around in
				1203	the expected way. This complicated and computationally expensive to
				1204	do, but is necessary. Valgrind is more simplistic about
				1205	floating-point loads and stores. In particular, V bits for data read
				1206	as a result of floating-point loads are checked at the load
				1207	instruction. So if your program uses the floating-point registers to
				1208	do memory-to-memory copies, you will get complaints about
				1209	uninitialised values. Fortunately, I have not yet encountered a
				1210	program which (ab)uses the floating-point registers in this way.
				1211
				1212	<a name="vaddress"></a>
				1213	<h3>3.2  Valid-address (A) bits</h3>
				1214
				1215	Notice that the previous section describes how the validity of values
				1216	is established and maintained without having to say whether the
				1217	program does or does not have the right to access any particular
				1218	memory location. We now consider the latter issue.
				1219
				1220	<p>As described above, every bit in memory or in the CPU has an
				1221	associated valid-value (V) bit. In addition, all bytes in memory, but
				1222	not in the CPU, have an associated valid-address (A) bit. This
				1223	indicates whether or not the program can legitimately read or write
				1224	that location. It does not give any indication of the validity or the
				1225	data at that location -- that's the job of the V bits -- only whether
				1226	or not the location may be accessed.
				1227
				1228	<p>Every time your program reads or writes memory, Valgrind checks the
				1229	A bits associated with the address. If any of them indicate an
				1230	invalid address, an error is emitted. Note that the reads and writes
				1231	themselves do not change the A bits, only consult them.
				1232
				1233	<p>So how do the A bits get set/cleared? Like this:
				1234
				1235	<ul>
				1236	<li>When the program starts, all the global data areas are marked as
				1237	accessible.</li><br>
				1238	<p>
				1239
				1240	<li>When the program does malloc/new, the A bits for the exactly the
				1241	area allocated, and not a byte more, are marked as accessible.
				1242	Upon freeing the area the A bits are changed to indicate
				1243	inaccessibility.</li><br>
				1244	<p>
				1245
				1246	<li>When the stack pointer register (%esp) moves up or down, A bits
				1247	are set. The rule is that the area from %esp up to the base of
				1248	the stack is marked as accessible, and below %esp is
				1249	inaccessible. (If that sounds illogical, bear in mind that the
				1250	stack grows down, not up, on almost all Unix systems, including
				1251	GNU/Linux.) Tracking %esp like this has the useful side-effect
				1252	that the section of stack used by a function for local variables
				1253	etc is automatically marked accessible on function entry and
				1254	inaccessible on exit.</li><br>
				1255	<p>
				1256
				1257	<li>When doing system calls, A bits are changed appropriately. For
				1258	example, mmap() magically makes files appear in the process's
				1259	address space, so the A bits must be updated if mmap()
				1260	succeeds.</li><br>
				1261	</ul>
				1262
				1263
				1264	<a name="together"></a>
				1265	<h3>3.3  Putting it all together</h3>
				1266	Valgrind's checking machinery can be summarised as follows:
				1267
				1268	<ul>
				1269	<li>Each byte in memory has 8 associated V (valid-value) bits,
				1270	saying whether or not the byte has a defined value, and a single
				1271	A (valid-address) bit, saying whether or not the program
				1272	currently has the right to read/write that address.</li><br>
				1273	<p>
				1274
				1275	<li>When memory is read or written, the relevant A bits are
				1276	consulted. If they indicate an invalid address, Valgrind emits
				1277	an Invalid read or Invalid write error.</li><br>
				1278	<p>
				1279
				1280	<li>When memory is read into the CPU's integer registers, the
				1281	relevant V bits are fetched from memory and stored in the
				1282	simulated CPU. They are not consulted.</li><br>
				1283	<p>
				1284
				1285	<li>When an integer register is written out to memory, the V bits
				1286	for that register are written back to memory too.</li><br>
				1287	<p>
				1288
				1289	<li>When memory is read into the CPU's floating point registers, the
				1290	relevant V bits are read from memory and they are immediately
				1291	checked. If any are invalid, an uninitialised value error is
				1292	emitted. This precludes using the floating-point registers to
				1293	copy possibly-uninitialised memory, but simplifies Valgrind in
				1294	that it does not have to track the validity status of the
				1295	floating-point registers.</li><br>
				1296	<p>
				1297
				1298	<li>As a result, when a floating-point register is written to
				1299	memory, the associated V bits are set to indicate a valid
				1300	value.</li><br>
				1301	<p>
				1302
				1303	<li>When values in integer CPU registers are used to generate a
				1304	memory address, or to determine the outcome of a conditional
				1305	branch, the V bits for those values are checked, and an error
				1306	emitted if any of them are undefined.</li><br>
				1307	<p>
				1308
				1309	<li>When values in integer CPU registers are used for any other
				1310	purpose, Valgrind computes the V bits for the result, but does
				1311	not check them.</li><br>
				1312	<p>
				1313
				1314	<li>One the V bits for a value in the CPU have been checked, they
				1315	are then set to indicate validity. This avoids long chains of
				1316	errors.</li><br>
				1317	<p>
				1318
				1319	<li>When values are loaded from memory, valgrind checks the A bits
				1320	for that location and issues an illegal-address warning if
				1321	needed. In that case, the V bits loaded are forced to indicate
				1322	Valid, despite the location being invalid.
				1323	<p>
				1324	This apparently strange choice reduces the amount of confusing
				1325	information presented to the user. It avoids the
				1326	unpleasant phenomenon in which memory is read from a place which
				1327	is both unaddressible and contains invalid values, and, as a
				1328	result, you get not only an invalid-address (read/write) error,
				1329	but also a potentially large set of uninitialised-value errors,
				1330	one for every time the value is used.
				1331	<p>
				1332	There is a hazy boundary case to do with multi-byte loads from
				1333	addresses which are partially valid and partially invalid. See
				1334	details of the flag <code>--partial-loads-ok</code> for details.
				1335	</li><br>
				1336	</ul>
				1337
				1338	Valgrind intercepts calls to malloc, calloc, realloc, valloc,
				1339	memalign, free, new and delete. The behaviour you get is:
				1340
				1341	<ul>
				1342
				1343	<li>malloc/new: the returned memory is marked as addressible but not
				1344	having valid values. This means you have to write on it before
				1345	you can read it.</li><br>
				1346	<p>
				1347
				1348	<li>calloc: returned memory is marked both addressible and valid,
				1349	since calloc() clears the area to zero.</li><br>
				1350	<p>
				1351
				1352	<li>realloc: if the new size is larger than the old, the new section
				1353	is addressible but invalid, as with malloc.</li><br>
				1354	<p>
				1355
				1356	<li>If the new size is smaller, the dropped-off section is marked as
				1357	unaddressible. You may only pass to realloc a pointer
				1358	previously issued to you by malloc/calloc/new/realloc.</li><br>
				1359	<p>
				1360
				1361	<li>free/delete: you may only pass to free a pointer previously
				1362	issued to you by malloc/calloc/new/realloc, or the value
				1363	NULL. Otherwise, Valgrind complains. If the pointer is indeed
				1364	valid, Valgrind marks the entire area it points at as
				1365	unaddressible, and places the block in the freed-blocks-queue.
				1366	The aim is to defer as long as possible reallocation of this
				1367	block. Until that happens, all attempts to access it will
				1368	elicit an invalid-address error, as you would hope.</li><br>
				1369	</ul>
				1370
				1371
				1372
				1373	<a name="signals"></a>
				1374	<h3>3.4  Signals</h3>
				1375
				1376	Valgrind provides suitable handling of signals, so, provided you stick
				1377	to POSIX stuff, you should be ok. Basic sigaction() and sigprocmask()
				1378	are handled. Signal handlers may return in the normal way or do
				1379	longjmp(); both should work ok. As specified by POSIX, a signal is
				1380	blocked in its own handler. Default actions for signals should work
				1381	as before. Etc, etc.
				1382
				1383	<p>Under the hood, dealing with signals is a real pain, and Valgrind's
				1384	simulation leaves much to be desired. If your program does
				1385	way-strange stuff with signals, bad things may happen. If so, let me
				1386	know. I don't promise to fix it, but I'd at least like to be aware of
				1387	it.
				1388
				1389
				1390	<a name="leaks"><a/>
				1391	<h3>3.5  Memory leak detection</h3>
				1392
				1393	Valgrind keeps track of all memory blocks issued in response to calls
				1394	to malloc/calloc/realloc/new. So when the program exits, it knows
				1395	which blocks are still outstanding -- have not been returned, in other
				1396	words. Ideally, you want your program to have no blocks still in use
				1397	at exit. But many programs do.
				1398
				1399	<p>For each such block, Valgrind scans the entire address space of the
				1400	process, looking for pointers to the block. One of three situations
				1401	may result:
				1402
				1403	<ul>
				1404	<li>A pointer to the start of the block is found. This usually
				1405	indicates programming sloppiness; since the block is still
				1406	pointed at, the programmer could, at least in principle, free'd
				1407	it before program exit.</li><br>
				1408	<p>
				1409
				1410	<li>A pointer to the interior of the block is found. The pointer
				1411	might originally have pointed to the start and have been moved
				1412	along, or it might be entirely unrelated. Valgrind deems such a
				1413	block as "dubious", that is, possibly leaked,
				1414	because it's unclear whether or
				1415	not a pointer to it still exists.</li><br>
				1416	<p>
				1417
				1418	<li>The worst outcome is that no pointer to the block can be found.
				1419	The block is classified as "leaked", because the
				1420	programmer could not possibly have free'd it at program exit,
				1421	since no pointer to it exists. This might be a symptom of
				1422	having lost the pointer at some earlier point in the
				1423	program.</li>
				1424	</ul>
				1425
				1426	Valgrind reports summaries about leaked and dubious blocks.
				1427	For each such block, it will also tell you where the block was
				1428	allocated. This should help you figure out why the pointer to it has
				1429	been lost. In general, you should attempt to ensure your programs do
				1430	not have any leaked or dubious blocks at exit.
				1431
				1432	<p>The precise area of memory in which Valgrind searches for pointers
				1433	is: all naturally-aligned 4-byte words for which all A bits indicate
				1434	addressibility and all V bits indicated that the stored value is
				1435	actually valid.
				1436
				1437	<p><hr width="100%">
				1438
				1439
				1440	<a name="limits"></a>
				1441	<h2>4  Limitations</h2>
				1442
				1443	The following list of limitations seems depressingly long. However,
				1444	most programs actually work fine.
				1445
				1446	<p>Valgrind will run x86-GNU/Linux ELF dynamically linked binaries, on
				1447	a kernel 2.4.X system, subject to the following constraints:
				1448
				1449	<ul>
				1450	<li>No MMX, SSE, SSE2, 3DNow instructions. If the translator
				1451	encounters these, Valgrind will simply give up. It may be
				1452	possible to add support for them at a later time. Intel added a
				1453	few instructions such as "cmov" to the integer instruction set
				1454	on Pentium and later processors, and these are supported.
				1455	Nevertheless it's safest to think of Valgrind as implementing
				1456	the 486 instruction set.</li><br>
				1457	<p>
				1458
				1459	<li>Multithreaded programs are not supported, since I haven't yet
				1460	figured out how to do this. To be more specific, it is the
				1461	"clone" system call which is not supported. A program calls
				1462	"clone" to create threads. Valgrind will abort if this
				1463	happens.</li><nr>
				1464	<p>
				1465
				1466	<li>Valgrind assumes that the floating point registers are not used
				1467	as intermediaries in memory-to-memory copies, so it immediately
				1468	checks V bits in floating-point loads/stores. If you want to
				1469	write code which copies around possibly-uninitialised values,
				1470	you must ensure these travel through the integer registers, not
				1471	the FPU.</li><br>
				1472	<p>
				1473
				1474	<li>If your program does its own memory management, rather than
				1475	using malloc/new/free/delete, it should still work, but
				1476	Valgrind's error checking won't be so effective.</li><br>
				1477	<p>
				1478
				1479	<li>Valgrind's signal simulation is not as robust as it could be.
				1480	Basic POSIX-compliant sigaction and sigprocmask functionality is
				1481	supplied, but it's conceivable that things could go badly awry
				1482	if you do wierd things with signals. Workaround: don't.
				1483	Programs that do non-POSIX signal tricks are in any case
				1484	inherently unportable, so should be avoided if
				1485	possible.</li><br>
				1486	<p>
				1487
				1488	<li>I have no idea what happens if programs try to handle signals on
				1489	an alternate stack (sigaltstack). YMMV.</li><br>
				1490	<p>
				1491
				1492	<li>Programs which switch stacks are not well handled. Valgrind
				1493	does have support for this, but I don't have great faith in it.
				1494	It's difficult -- there's no cast-iron way to decide whether a
				1495	large change in %esp is as a result of the program switching
				1496	stacks, or merely allocating a large object temporarily on the
				1497	current stack -- yet Valgrind needs to handle the two situations
				1498	differently.</li><br>
				1499	<p>
				1500
				1501	<li>x86 instructions, and system calls, have been implemented on
				1502	demand. So it's possible, although unlikely, that a program
				1503	will fall over with a message to that effect. If this happens,
				1504	please mail me ALL the details printed out, so I can try and
				1505	implement the missing feature.</li><br>
				1506	<p>
				1507
				1508	<li>x86 floating point works correctly, but floating-point code may
				1509	run even more slowly than integer code, due to my simplistic
				1510	approach to FPU emulation.</li><br>
				1511	<p>
				1512
				1513	<li>You can't Valgrind-ize statically linked binaries. Valgrind
				1514	relies on the dynamic-link mechanism to gain control at
				1515	startup.</li><br>
				1516	<p>
				1517
				1518	<li>Memory consumption of your program is majorly increased whilst
				1519	running under Valgrind. This is due to the large amount of
				1520	adminstrative information maintained behind the scenes. Another
				1521	cause is that Valgrind dynamically translates the original
				1522	executable and never throws any translation away, except in
				1523	those rare cases where self-modifying code is detected.
				1524	Translated, instrumented code is 8-12 times larger than the
				1525	original (!) so you can easily end up with 15+ MB of
				1526	translations when running (eg) a web browser. There's not a lot
				1527	you can do about this -- use Valgrind on a fast machine with a lot
				1528	of memory and swap space. At some point I may implement a LRU
				1529	caching scheme for translations, so as to bound the maximum
				1530	amount of memory devoted to them, to say 8 or 16 MB.</li>
				1531	</ul>
				1532
				1533
				1534	Programs which are known not to work are:
				1535
				1536	<ul>
				1537	<li>Netscape 4.76 works pretty well on some platforms -- quite
				1538	nicely on my AMD K6-III (400 MHz). I can surf, do mail, etc, no
				1539	problem. On other platforms is has been observed to crash
				1540	during startup. Despite much investigation I can't figure out
				1541	why.</li><br>
				1542	<p>
				1543
				1544	<li>kpackage (a KDE front end to rpm) dies because the CPUID
				1545	instruction is unimplemented. Easy to fix.</li><br>
				1546	<p>
				1547
				1548	<li>knode (a KDE newsreader) tries to do multithreaded things, and
				1549	fails.</li><br>
				1550	<p>
				1551
				1552	<li>emacs starts up but immediately concludes it is out of memory
				1553	and aborts. Emacs has it's own memory-management scheme, but I
				1554	don't understand why this should interact so badly with
				1555	Valgrind.</li><br>
				1556	<p>
				1557
				1558	<li>Gimp and Gnome and GTK-based apps die early on because
				1559	of unimplemented system call wrappers. (I'm a KDE user :)
				1560	This wouldn't be hard to fix.
				1561	</li><br>
				1562	<p>
				1563
				1564	<li>As a consequence of me being a KDE user, almost all KDE apps
				1565	work ok -- except those which are multithreaded.
				1566	</li><br>
				1567	<p>
				1568	</ul>
				1569
				1570
				1571	<p><hr width="100%">
				1572
				1573
				1574	<a name="howitworks"></a>
				1575	<h2>5  How it works -- a rough overview</h2>
				1576	Some gory details, for those with a passion for gory details. You
				1577	don't need to read this section if all you want to do is use Valgrind.
				1578
				1579	<a name="startb"></a>
				1580	<h3>5.1  Getting started</h3>
				1581
				1582	Valgrind is compiled into a shared object, valgrind.so. The shell
				1583	script valgrind sets the LD_PRELOAD environment variable to point to
				1584	valgrind.so. This causes the .so to be loaded as an extra library to
				1585	any subsequently executed dynamically-linked ELF binary, viz, the
				1586	program you want to debug.
				1587
				1588	<p>The dynamic linker allows each .so in the process image to have an
				1589	initialisation function which is run before main(). It also allows
				1590	each .so to have a finalisation function run after main() exits.
				1591
				1592	<p>When valgrind.so's initialisation function is called by the dynamic
				1593	linker, the synthetic CPU to starts up. The real CPU remains locked
				1594	in valgrind.so for the entire rest of the program, but the synthetic
				1595	CPU returns from the initialisation function. Startup of the program
				1596	now continues as usual -- the dynamic linker calls all the other .so's
				1597	initialisation routines, and eventually runs main(). This all runs on
				1598	the synthetic CPU, not the real one, but the client program cannot
				1599	tell the difference.
				1600
				1601	<p>Eventually main() exits, so the synthetic CPU calls valgrind.so's
				1602	finalisation function. Valgrind detects this, and uses it as its cue
				1603	to exit. It prints summaries of all errors detected, possibly checks
				1604	for memory leaks, and then exits the finalisation routine, but now on
				1605	the real CPU. The synthetic CPU has now lost control -- permanently
				1606	-- so the program exits back to the OS on the real CPU, just as it
				1607	would have done anyway.
				1608
				1609	<p>On entry, Valgrind switches stacks, so it runs on its own stack.
				1610	On exit, it switches back. This means that the client program
				1611	continues to run on its own stack, so we can switch back and forth
				1612	between running it on the simulated and real CPUs without difficulty.
				1613	This was an important design decision, because it makes it easy (well,
				1614	significantly less difficult) to debug the synthetic CPU.
				1615
				1616
				1617	<a name="engine"></a>
				1618	<h3>5.2  The translation/instrumentation engine</h3>
				1619
				1620	Valgrind does not directly run any of the original program's code. Only
				1621	instrumented translations are run. Valgrind maintains a translation
				1622	table, which allows it to find the translation quickly for any branch
				1623	target (code address). If no translation has yet been made, the
				1624	translator - a just-in-time translator - is summoned. This makes an
				1625	instrumented translation, which is added to the collection of
				1626	translations. Subsequent jumps to that address will use this
				1627	translation.
				1628
				1629	<p>Valgrind can optionally check writes made by the application, to
				1630	see if they are writing an address contained within code which has
				1631	been translated. Such a write invalidates translations of code
				1632	bracketing the written address. Valgrind will discard the relevant
				1633	translations, which causes them to be re-made, if they are needed
				1634	again, reflecting the new updated data stored there. In this way,
				1635	self modifying code is supported. In practice I have not found any
				1636	Linux applications which use self-modifying-code.
				1637
				1638	<p>The JITter translates basic blocks -- blocks of straight-line-code
				1639	-- as single entities. To minimise the considerable difficulties of
				1640	dealing with the x86 instruction set, x86 instructions are first
				1641	translated to a RISC-like intermediate code, similar to sparc code,
				1642	but with an infinite number of virtual integer registers. Initially
				1643	each insn is translated seperately, and there is no attempt at
				1644	instrumentation.
				1645
				1646	<p>The intermediate code is improved, mostly so as to try and cache
				1647	the simulated machine's registers in the real machine's registers over
				1648	several simulated instructions. This is often very effective. Also,
				1649	we try to remove redundant updates of the simulated machines's
				1650	condition-code register.
				1651
				1652	<p>The intermediate code is then instrumented, giving more
				1653	intermediate code. There are a few extra intermediate-code operations
				1654	to support instrumentation; it is all refreshingly simple. After
				1655	instrumentation there is a cleanup pass to remove redundant value
				1656	checks.
				1657
				1658	<p>This gives instrumented intermediate code which mentions arbitrary
				1659	numbers of virtual registers. A linear-scan register allocator is
				1660	used to assign real registers and possibly generate spill code. All
				1661	of this is still phrased in terms of the intermediate code. This
				1662	machinery is inspired by the work of Reuben Thomas (MITE).
				1663
				1664	<p>Then, and only then, is the final x86 code emitted. The
				1665	intermediate code is carefully designed so that x86 code can be
				1666	generated from it without need for spare registers or other
				1667	inconveniences.
				1668
				1669	<p>The translations are managed using a traditional LRU-based caching
				1670	scheme. The translation cache has a default size of about 14MB.
				1671
				1672	<a name="track"></a>
				1673
				1674	<h3>5.3  Tracking the status of memory</h3> Each byte in the
				1675	process' address space has nine bits associated with it: one A bit and
				1676	eight V bits. The A and V bits for each byte are stored using a
				1677	sparse array, which flexibly and efficiently covers arbitrary parts of
				1678	the 32-bit address space without imposing significant space or
				1679	performance overheads for the parts of the address space never
				1680	visited. The scheme used, and speedup hacks, are described in detail
				1681	at the top of the source file vg_memory.c, so you should read that for
				1682	the gory details.
				1683
				1684	<a name="sys_calls"></a>
				1685
				1686	<h3>5.4 System calls</h3>
				1687	All system calls are intercepted. The memory status map is consulted
				1688	before and updated after each call. It's all rather tiresome. See
				1689	vg_syscall_mem.c for details.
				1690
				1691	<a name="sys_signals"></a>
				1692
				1693	<h3>5.5  Signals</h3>
				1694	All system calls to sigaction() and sigprocmask() are intercepted. If
				1695	the client program is trying to set a signal handler, Valgrind makes a
				1696	note of the handler address and which signal it is for. Valgrind then
				1697	arranges for the same signal to be delivered to its own handler.
				1698
				1699	<p>When such a signal arrives, Valgrind's own handler catches it, and
				1700	notes the fact. At a convenient safe point in execution, Valgrind
				1701	builds a signal delivery frame on the client's stack and runs its
				1702	handler. If the handler longjmp()s, there is nothing more to be said.
				1703	If the handler returns, Valgrind notices this, zaps the delivery
				1704	frame, and carries on where it left off before delivering the signal.
				1705
				1706	<p>The purpose of this nonsense is that setting signal handlers
				1707	essentially amounts to giving callback addresses to the Linux kernel.
				1708	We can't allow this to happen, because if it did, signal handlers
				1709	would run on the real CPU, not the simulated one. This means the
				1710	checking machinery would not operate during the handler run, and,
				1711	worse, memory permissions maps would not be updated, which could cause
				1712	spurious error reports once the handler had returned.
				1713
				1714	<p>An even worse thing would happen if the signal handler longjmp'd
				1715	rather than returned: Valgrind would completely lose control of the
				1716	client program.
				1717
				1718	<p>Upshot: we can't allow the client to install signal handlers
				1719	directly. Instead, Valgrind must catch, on behalf of the client, any
				1720	signal the client asks to catch, and must delivery it to the client on
				1721	the simulated CPU, not the real one. This involves considerable
				1722	gruesome fakery; see vg_signals.c for details.
				1723	<p>
				1724
				1725	<hr width="100%">
				1726
				1727	<a name="example"></a>
				1728	<h2>6  Example</h2>
				1729	This is the log for a run of a small program. The program is in fact
				1730	correct, and the reported error is as the result of a potentially serious
				1731	code generation bug in GNU g++ (snapshot 20010527).
				1732	<pre>
				1733	sewardj@phoenix:~/newmat10$
				1734	~/Valgrind-6/valgrind -v ./bogon
				1735	==25832== Valgrind 0.10, a memory error detector for x86 RedHat 7.1.
				1736	==25832== Copyright (C) 2000-2001, and GNU GPL'd, by Julian Seward.
				1737	==25832== Startup, with flags:
				1738	==25832== --suppressions=/home/sewardj/Valgrind/redhat71.supp
				1739	==25832== reading syms from /lib/ld-linux.so.2
				1740	==25832== reading syms from /lib/libc.so.6
				1741	==25832== reading syms from /mnt/pima/jrs/Inst/lib/libgcc_s.so.0
				1742	==25832== reading syms from /lib/libm.so.6
				1743	==25832== reading syms from /mnt/pima/jrs/Inst/lib/libstdc++.so.3
				1744	==25832== reading syms from /home/sewardj/Valgrind/valgrind.so
				1745	==25832== reading syms from /proc/self/exe
				1746	==25832== loaded 5950 symbols, 142333 line number locations
				1747	==25832==
				1748	==25832== Invalid read of size 4
				1749	==25832== at 0x8048724: _ZN10BandMatrix6ReSizeEiii (bogon.cpp:45)
				1750	==25832== by 0x80487AF: main (bogon.cpp:66)
				1751	==25832== by 0x40371E5E: __libc_start_main (libc-start.c:129)
				1752	==25832== by 0x80485D1: (within /home/sewardj/newmat10/bogon)
				1753	==25832== Address 0xBFFFF74C is not stack'd, malloc'd or free'd
				1754	==25832==
				1755	==25832== ERROR SUMMARY: 1 errors from 1 contexts (suppressed: 0 from 0)
				1756	==25832== malloc/free: in use at exit: 0 bytes in 0 blocks.
				1757	==25832== malloc/free: 0 allocs, 0 frees, 0 bytes allocated.
				1758	==25832== For a detailed leak analysis, rerun with: --leak-check=yes
				1759	==25832==
				1760	==25832== exiting, did 1881 basic blocks, 0 misses.
				1761	==25832== 223 translations, 3626 bytes in, 56801 bytes out.
				1762	</pre>
				1763	<p>The GCC folks fixed this about a week before gcc-3.0 shipped.
				1764	<hr width="100%">
				1765	<p>
				1766	</body>
				1767	</html>