njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 1 | <?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 | |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame^] | 11 | <para>Valgrind is a suite of simulation-based debugging and |
| 12 | profiling tools for programs running on Linux (x86, amd64 and ppc32). |
| 13 | The system consists of a core, which |
njn | 779a2d6 | 2005-07-25 00:12:19 +0000 | [diff] [blame] | 14 | provides a synthetic CPU in software, and a series of tools, |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 15 | each of which performs some kind of debugging, profiling, or |
| 16 | similar task. The architecture is modular, so that new tools can |
| 17 | be created easily and without disturbing the existing |
| 18 | structure.</para> |
| 19 | |
| 20 | <para>A number of useful tools are supplied as standard. In |
| 21 | summary, 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 |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame^] | 60 | functions</para></listitem> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 61 | </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> |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame^] | 93 | |
| 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> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 97 | </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 |
njn | 779a2d6 | 2005-07-25 00:12:19 +0000 | [diff] [blame] | 107 | will even show counts for each individual machine |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 108 | instruction.</para> |
| 109 | |
njn | 779a2d6 | 2005-07-25 00:12:19 +0000 | [diff] [blame] | 110 | <para>On x86 and AMD64, Cachegrind auto-detects your machine's cache |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 111 | 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> |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame^] | 141 | |
| 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> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 145 | </listitem> |
| 146 | |
| 147 | </orderedlist> |
| 148 | |
| 149 | |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame^] | 150 | <para>A couple of minor tools (<command>Lackey</command> |
| 151 | and <command>Nulgrind</command>) are |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 152 | also supplied. These aren't particularly useful -- they exist to |
| 153 | illustrate how to create simple tools and to help the valgrind |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame^] | 154 | developers in various ways. Nulgrind is the null tool -- it adds |
| 155 | no instrumentation. Lackey is a simple example tool |
| 156 | which counts instructions, memory accesses, and the number of |
| 157 | integer and floating point operations your program does.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 158 | |
njn | 779a2d6 | 2005-07-25 00:12:19 +0000 | [diff] [blame] | 159 | <para>Valgrind is closely tied to details of the CPU and operating |
| 160 | system, and to a lesser extent, the compiler and basic C libraries. |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame^] | 161 | Nonetheless, as of version 3.1.0 it supports several platforms: x86/Linux |
| 162 | (mature), AMD64/Linux (maturing), and PPC32/Linux (immature but works well). |
| 163 | Valgrind uses the standard Unix |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 164 | <computeroutput>./configure</computeroutput>, |
| 165 | <computeroutput>make</computeroutput>, <computeroutput>make |
| 166 | install</computeroutput> mechanism, and we have attempted to |
njn | 21f9195 | 2005-03-12 22:14:42 +0000 | [diff] [blame] | 167 | ensure that it works on machines with kernel 2.4 or 2.6 and glibc |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame^] | 168 | 2.2.X--2.3.X.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 169 | |
| 170 | <para>Valgrind is licensed under the <xref linkend="license.gpl"/>, |
njn | 779a2d6 | 2005-07-25 00:12:19 +0000 | [diff] [blame] | 171 | version 2. The <computeroutput>valgrind/*.h</computeroutput> headers that |
| 172 | you may wish to include in your code (eg. |
| 173 | <computeroutput>valgrind.h</computeroutput>, |
| 174 | <computeroutput>memcheck.h</computeroutput>) are |
njn | 21f9195 | 2005-03-12 22:14:42 +0000 | [diff] [blame] | 175 | distributed under a BSD-style license, so you may include them in your code |
| 176 | without worrying about license conflicts. Some of the PThreads test cases, |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 177 | <computeroutput>pth_*.c</computeroutput>, are taken from |
| 178 | "Pthreads Programming" by Bradford Nichols, Dick Buttlar & |
| 179 | Jacqueline Proulx Farrell, ISBN 1-56592-115-1, published by |
| 180 | O'Reilly & 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, |
| 189 | upon which are built Valgrind tools, which do different kinds of |
| 190 | debugging and profiling. This manual is structured |
| 191 | similarly.</para> |
| 192 | |
| 193 | <para>First, we describe the Valgrind core, how to use it, and |
| 194 | the flags it supports. Then, each tool has its own chapter in |
| 195 | this manual. You only need to read the documentation for the |
| 196 | core and for the tool(s) you actually use, although you may find |
| 197 | it helpful to be at least a little bit familar with what all |
| 198 | tools do. If you're new to all this, you probably want to run |
| 199 | the 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, |
| 203 | and the tools have their own flags which they know about. This |
| 204 | means there is no central place describing all the flags that are |
| 205 | accepted -- you have to read the flags documentation both for |
| 206 | <xref linkend="manual-core"/> and for the tool you want to |
| 207 | use.</para> |
| 208 | |
| 209 | </sect1> |
| 210 | |
| 211 | </chapter> |