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

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