blob: e7c716cbf0eb77d2fd7cd72b69757b0b0b227e00 [file] [log] [blame]
njn3e986b22004-11-30 10:43:45 +00001<?xml version="1.0"?> <!-- -*- sgml -*- -->
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5<chapter id="manual-intro" xreflabel="Introduction">
6<title>Introduction</title>
7
8<sect1 id="manual-intro.overview" xreflabel="An Overview of Valgrind">
9<title>An Overview of Valgrind</title>
10
sewardj053fe982005-11-15 19:51:04 +000011<para>Valgrind is a suite of simulation-based debugging and
12profiling tools for programs running on Linux (x86, amd64 and ppc32).
13The system consists of a core, which
njn779a2d62005-07-25 00:12:19 +000014provides a synthetic CPU in software, and a series of tools,
njn3e986b22004-11-30 10:43:45 +000015each of which performs some kind of debugging, profiling, or
16similar task. The architecture is modular, so that new tools can
17be created easily and without disturbing the existing
18structure.</para>
19
20<para>A number of useful tools are supplied as standard. In
21summary, these are:</para>
22
23<orderedlist>
24
25 <listitem>
26 <para><command>Memcheck</command> detects memory-management
27 problems in your programs. All reads and writes of memory
28 are checked, and calls to malloc/new/free/delete are
29 intercepted. As a result, Memcheck can detect the following
30 problems:</para>
31
32 <itemizedlist>
33 <listitem>
34 <para>Use of uninitialised memory</para>
35 </listitem>
36 <listitem>
37 <para>Reading/writing memory after it has been
38 free'd</para>
39 </listitem>
40 <listitem>
41 <para>Reading/writing off the end of malloc'd
42 blocks</para>
43 </listitem>
44 <listitem>
45 <para>Reading/writing inappropriate areas on the
46 stack</para>
47 </listitem>
48 <listitem>
49 <para>Memory leaks -- where pointers to malloc'd
50 blocks are lost forever</para>
51 </listitem>
52 <listitem>
53 <para>Mismatched use of malloc/new/new [] vs
54 free/delete/delete []</para>
55 </listitem>
56 <listitem>
57 <para>Overlapping <computeroutput>src</computeroutput> and
58 <computeroutput>dst</computeroutput> pointers in
59 <computeroutput>memcpy()</computeroutput> and related
sewardj053fe982005-11-15 19:51:04 +000060 functions</para></listitem>
njn3e986b22004-11-30 10:43:45 +000061 </itemizedlist>
62
63 <para>Problems like these can be difficult to find by other
64 means, often lying undetected for long periods, then causing
65 occasional, difficult-to-diagnose crashes.</para>
66 </listitem>
67
68 <listitem>
69 <para><command>Addrcheck</command> is a lightweight version
70 of Memcheck. It is identical to Memcheck except for the
71 single detail that it does not do any uninitialised-value
72 checks. All of the other checks -- primarily the
73 fine-grained address checking -- are still done. The
74 downside of this is that you don't catch the
75 uninitialised-value errors that Memcheck can find.</para>
76
77 <para>But the upside is significant: programs run about twice
78 as fast as they do on Memcheck, and a lot less memory is
79 used. It still finds reads/writes of freed memory, memory
80 off the end of blocks and in other invalid places, bugs which
81 you really want to find before release!</para>
82
83 <para>Because Addrcheck is lighter and faster than Memcheck,
84 you can run more programs for longer, and so you may be able
85 to cover more test scenarios. Addrcheck was created because
86 one of us (Julian) wanted to be able to run a complete KDE
87 desktop session with checking. As of early November 2002, we
88 have been able to run KDE-3.0.3 on a 1.7 GHz P4 with 512 MB
89 of memory, using Addrcheck. Although the result is not
90 stellar, it's quite usable, and it seems plausible to run KDE
91 for long periods at a time like this, collecting up all the
92 addressing errors that appear.</para>
sewardj053fe982005-11-15 19:51:04 +000093
94 <para>NOTE: Addrcheck is not available in Valgrind 3.1.X. We hope
95 to reinstate its functionality in later releases. For now, use
96 Memcheck instead.</para>
njn3e986b22004-11-30 10:43:45 +000097 </listitem>
98
99 <listitem>
100 <para><command>Cachegrind</command> is a cache profiler. It
101 performs detailed simulation of the I1, D1 and L2 caches in
102 your CPU and so can accurately pinpoint the sources of cache
103 misses in your code. If you desire, it will show the number
104 of cache misses, memory references and instructions accruing
105 to each line of source code, with per-function, per-module
106 and whole-program summaries. If you ask really nicely it
njn779a2d62005-07-25 00:12:19 +0000107 will even show counts for each individual machine
njn3e986b22004-11-30 10:43:45 +0000108 instruction.</para>
109
njn779a2d62005-07-25 00:12:19 +0000110 <para>On x86 and AMD64, Cachegrind auto-detects your machine's cache
njn3e986b22004-11-30 10:43:45 +0000111 configuration using the
112 <computeroutput>CPUID</computeroutput> instruction, and so
113 needs no further configuration info, in most cases.</para>
114
115 <para>Cachegrind is nicely complemented by Josef
116 Weidendorfer's amazing KCacheGrind visualisation tool
117 (<ulink url="http://kcachegrind.sourceforge.net">http://kcachegrind.sourceforge.net</ulink>),
118 a KDE application which presents these profiling results in a
119 graphical and easier-to-understand form.</para>
120 </listitem>
121
122 <listitem>
123 <para><command>Helgrind</command> finds data races in
124 multithreaded programs. Helgrind looks for memory locations
125 which are accessed by more than one (POSIX p-)thread, but for
126 which no consistently used (pthread_mutex_)lock can be found.
127 Such locations are indicative of missing synchronisation
128 between threads, and could cause hard-to-find
129 timing-dependent problems.</para>
130
131 <para>Helgrind ("Hell's Gate", in Norse mythology) implements
132 the so-called "Eraser" data-race-detection algorithm, along
133 with various refinements (thread-segment lifetimes) which
134 reduce the number of false errors it reports. It is as yet
135 somewhat of an experimental tool, so your feedback is
136 especially welcomed here.</para>
137
138 <para>Helgrind has been hacked on extensively by Jeremy
139 Fitzhardinge, and we have him to thank for getting it to a
140 releasable state.</para>
sewardj053fe982005-11-15 19:51:04 +0000141
142 <para>NOTE: Helgrind is, unfortunately, not available in Valgrind 3.1.X,
143 as a result of threading changes that happened in the 2.4.0 release.
144 We hope to reinstate its functionality in a future 3.2.0 release.</para>
njn3e986b22004-11-30 10:43:45 +0000145 </listitem>
146
147</orderedlist>
148
149
sewardj053fe982005-11-15 19:51:04 +0000150<para>A couple of minor tools (<command>Lackey</command>
151and <command>Nulgrind</command>) are
njn3e986b22004-11-30 10:43:45 +0000152also supplied. These aren't particularly useful -- they exist to
153illustrate how to create simple tools and to help the valgrind
sewardj053fe982005-11-15 19:51:04 +0000154developers in various ways. Nulgrind is the null tool -- it adds
155no instrumentation. Lackey is a simple example tool
156which counts instructions, memory accesses, and the number of
157integer and floating point operations your program does.</para>
njn3e986b22004-11-30 10:43:45 +0000158
njn779a2d62005-07-25 00:12:19 +0000159<para>Valgrind is closely tied to details of the CPU and operating
160system, and to a lesser extent, the compiler and basic C libraries.
sewardj053fe982005-11-15 19:51:04 +0000161Nonetheless, as of version 3.1.0 it supports several platforms: x86/Linux
162(mature), AMD64/Linux (maturing), and PPC32/Linux (immature but works well).
163Valgrind uses the standard Unix
njn3e986b22004-11-30 10:43:45 +0000164<computeroutput>./configure</computeroutput>,
165<computeroutput>make</computeroutput>, <computeroutput>make
166install</computeroutput> mechanism, and we have attempted to
njn21f91952005-03-12 22:14:42 +0000167ensure that it works on machines with kernel 2.4 or 2.6 and glibc
sewardj053fe982005-11-15 19:51:04 +00001682.2.X--2.3.X.</para>
njn3e986b22004-11-30 10:43:45 +0000169
170<para>Valgrind is licensed under the <xref linkend="license.gpl"/>,
njn779a2d62005-07-25 00:12:19 +0000171version 2. The <computeroutput>valgrind/*.h</computeroutput> headers that
172you may wish to include in your code (eg.
173<computeroutput>valgrind.h</computeroutput>,
174<computeroutput>memcheck.h</computeroutput>) are
njn21f91952005-03-12 22:14:42 +0000175distributed under a BSD-style license, so you may include them in your code
176without worrying about license conflicts. Some of the PThreads test cases,
njn3e986b22004-11-30 10:43:45 +0000177<computeroutput>pth_*.c</computeroutput>, are taken from
178"Pthreads Programming" by Bradford Nichols, Dick Buttlar &amp;
179Jacqueline Proulx Farrell, ISBN 1-56592-115-1, published by
180O'Reilly &amp; Associates, Inc.</para>
181
182</sect1>
183
184
185<sect1 id="manual-intro.navigation" xreflabel="How to navigate this manual">
186<title>How to navigate this manual</title>
187
188<para>The Valgrind distribution consists of the Valgrind core,
189upon which are built Valgrind tools, which do different kinds of
190debugging and profiling. This manual is structured
191similarly.</para>
192
193<para>First, we describe the Valgrind core, how to use it, and
194the flags it supports. Then, each tool has its own chapter in
195this manual. You only need to read the documentation for the
196core and for the tool(s) you actually use, although you may find
197it helpful to be at least a little bit familar with what all
198tools do. If you're new to all this, you probably want to run
199the Memcheck tool. If you want to write a new tool, read
200<xref linkend="writing-tools"/>.</para>
201
202<para>Be aware that the core understands some command line flags,
203and the tools have their own flags which they know about. This
204means there is no central place describing all the flags that are
205accepted -- you have to read the flags documentation both for
206<xref linkend="manual-core"/> and for the tool you want to
207use.</para>
208
209</sect1>
210
211</chapter>