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 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 11 | <para>Valgrind is a suite of simulation-based debugging and profiling |
sewardj | 3ecfaaa | 2007-03-26 02:11:17 +0000 | [diff] [blame] | 12 | tools for programs running on Linux (x86, amd64, ppc32 and ppc64). |
| 13 | The system consists of a core, which provides a synthetic CPU in |
| 14 | software, and a series of tools, each of which performs some kind of |
| 15 | debugging, profiling, or similar task. The architecture is modular, |
| 16 | so that new tools can be created easily and without disturbing the |
| 17 | existing structure.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 18 | |
| 19 | <para>A number of useful tools are supplied as standard. In |
| 20 | summary, these are:</para> |
| 21 | |
| 22 | <orderedlist> |
| 23 | |
| 24 | <listitem> |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 25 | <para><command>Memcheck</command> detects memory-management problems |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 26 | in programs. All reads and writes of memory are checked, and |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 27 | calls to malloc/new/free/delete are intercepted. As a result, |
| 28 | Memcheck can detect the following problems:</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 29 | |
| 30 | <itemizedlist> |
| 31 | <listitem> |
| 32 | <para>Use of uninitialised memory</para> |
| 33 | </listitem> |
| 34 | <listitem> |
| 35 | <para>Reading/writing memory after it has been |
| 36 | free'd</para> |
| 37 | </listitem> |
| 38 | <listitem> |
| 39 | <para>Reading/writing off the end of malloc'd |
| 40 | blocks</para> |
| 41 | </listitem> |
| 42 | <listitem> |
| 43 | <para>Reading/writing inappropriate areas on the |
| 44 | stack</para> |
| 45 | </listitem> |
| 46 | <listitem> |
| 47 | <para>Memory leaks -- where pointers to malloc'd |
| 48 | blocks are lost forever</para> |
| 49 | </listitem> |
| 50 | <listitem> |
| 51 | <para>Mismatched use of malloc/new/new [] vs |
| 52 | free/delete/delete []</para> |
| 53 | </listitem> |
| 54 | <listitem> |
| 55 | <para>Overlapping <computeroutput>src</computeroutput> and |
| 56 | <computeroutput>dst</computeroutput> pointers in |
| 57 | <computeroutput>memcpy()</computeroutput> and related |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame] | 58 | functions</para></listitem> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 59 | </itemizedlist> |
| 60 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 61 | <para>Problems like these can be difficult to find by other means, |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 62 | often remaining undetected for long periods, then causing occasional, |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 63 | difficult-to-diagnose crashes.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 64 | </listitem> |
| 65 | |
| 66 | <listitem> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 67 | <para><command>Cachegrind</command> is a cache profiler. It |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 68 | performs detailed simulation of the I1, D1 and L2 caches in your CPU |
| 69 | and so can accurately pinpoint the sources of cache misses in your |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 70 | code. It will show the number of cache misses, |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 71 | memory references and instructions accruing to each line of source |
| 72 | code, with per-function, per-module and whole-program summaries. If |
| 73 | you ask really nicely it will even show counts for each individual |
| 74 | machine instruction.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 75 | |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 76 | <para>On x86 and and64, Cachegrind auto-detects your machine's cache |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 77 | configuration using the <computeroutput>CPUID</computeroutput> |
| 78 | instruction, and so needs no further configuration info, in most |
| 79 | cases.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 80 | </listitem> |
| 81 | |
| 82 | <listitem> |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 83 | <para><command>Callgrind</command> is a profiler similar in |
| 84 | concept to Cachegrind, but which also tracks caller-callee |
| 85 | relationships. By doing so it is able to show how instruction, |
| 86 | memory reference and cache miss costs flow between callers and |
| 87 | callees. Callgrind collects a large amount of data which is best |
| 88 | navigated using Josef Weidendorfer's amazing KCachegrind |
| 89 | visualisation tool (<ulink |
| 90 | url="http://kcachegrind.sourceforge.net/cgi-bin/show.cgi/KcacheGrindIndex">http://kcachegrind.sourceforge.net</ulink>). |
| 91 | KCachegrind is a KDE application which presents |
| 92 | these profiling results in a |
| 93 | graphical and easy-to-understand form.</para> |
| 94 | </listitem> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 95 | |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 96 | <listitem> |
| 97 | <para><command>Massif</command> is a heap profiler. |
| 98 | It measures how much heap memory programs use. In particular, |
| 99 | it can give you information about heap blocks, heap |
| 100 | administration overheads, and stack sizes.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 101 | |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 102 | <para>Heap profiling can help you reduce the amount of |
| 103 | memory your program uses. On modern machines with virtual |
| 104 | memory, this reduces the chances that your program will run out |
| 105 | of memory, and may make it faster by reducing the amount of |
| 106 | paging needed.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 107 | </listitem> |
| 108 | |
| 109 | </orderedlist> |
| 110 | |
| 111 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 112 | <para>A couple of minor tools (<command>Lackey</command> and |
| 113 | <command>Nulgrind</command>) are also supplied. These aren't |
| 114 | particularly useful -- they exist to illustrate how to create simple |
| 115 | tools and to help the valgrind developers in various ways. Nulgrind is |
| 116 | the null tool -- it adds no instrumentation. Lackey is a simple example |
| 117 | tool which counts instructions, memory accesses, and the number of |
sewardj | 053fe98 | 2005-11-15 19:51:04 +0000 | [diff] [blame] | 118 | integer and floating point operations your program does.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 119 | |
njn | 779a2d6 | 2005-07-25 00:12:19 +0000 | [diff] [blame] | 120 | <para>Valgrind is closely tied to details of the CPU and operating |
| 121 | system, and to a lesser extent, the compiler and basic C libraries. |
sewardj | 3ecfaaa | 2007-03-26 02:11:17 +0000 | [diff] [blame] | 122 | Nonetheless, as of version 3.2.0 it supports several platforms: |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 123 | x86/Linux (mature), amd64/Linux (maturing), ppc32/Linux and |
| 124 | ppc64/Linux (less mature but work well). Valgrind uses the standard Unix |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 125 | <computeroutput>./configure</computeroutput>, |
| 126 | <computeroutput>make</computeroutput>, <computeroutput>make |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 127 | install</computeroutput> mechanism, and we have attempted to ensure that |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 128 | it works on machines with Linux kernel 2.4.X or 2.6.X and glibc |
sewardj | 3ecfaaa | 2007-03-26 02:11:17 +0000 | [diff] [blame] | 129 | 2.2.X to 2.5.X.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 130 | |
| 131 | <para>Valgrind is licensed under the <xref linkend="license.gpl"/>, |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 132 | version 2. The <computeroutput>valgrind/*.h</computeroutput> headers |
| 133 | that you may wish to include in your code (eg. |
| 134 | <filename>valgrind.h</filename>, <filename>memcheck.h</filename>) are |
| 135 | distributed under a BSD-style license, so you may include them in your |
| 136 | code without worrying about license conflicts. Some of the PThreads |
| 137 | test cases, <filename>pth_*.c</filename>, are taken from "Pthreads |
| 138 | Programming" by Bradford Nichols, Dick Buttlar & Jacqueline Proulx |
| 139 | Farrell, ISBN 1-56592-115-1, published by O'Reilly & Associates, |
| 140 | Inc.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 141 | |
| 142 | </sect1> |
| 143 | |
| 144 | |
| 145 | <sect1 id="manual-intro.navigation" xreflabel="How to navigate this manual"> |
| 146 | <title>How to navigate this manual</title> |
| 147 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 148 | <para>The Valgrind distribution consists of the Valgrind core, upon |
sewardj | 08e31e2 | 2007-05-23 21:58:33 +0000 | [diff] [blame] | 149 | which are built Valgrind tools. The tools do different kinds of debugging |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 150 | and profiling. This manual is structured similarly.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 151 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 152 | <para>First, we describe the Valgrind core, how to use it, and the flags |
| 153 | it supports. Then, each tool has its own chapter in this manual. You |
| 154 | only need to read the documentation for the core and for the tool(s) you |
| 155 | actually use, although you may find it helpful to be at least a little |
sewardj | 3387889 | 2007-11-17 09:43:25 +0000 | [diff] [blame^] | 156 | bit familiar with what all tools do. If you're new to all this, you probably |
njn | e5eaf3a | 2006-10-23 21:21:48 +0000 | [diff] [blame] | 157 | want to run the Memcheck tool. The final chapter explains how to write a |
| 158 | new tool.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 159 | |
de | bad57fc | 2005-12-03 22:33:29 +0000 | [diff] [blame] | 160 | <para>Be aware that the core understands some command line flags, and |
| 161 | the tools have their own flags which they know about. This means there |
| 162 | is no central place describing all the flags that are accepted -- you |
| 163 | have to read the flags documentation both for |
| 164 | <xref linkend="manual-core"/> and for the tool you want to use.</para> |
njn | 3e986b2 | 2004-11-30 10:43:45 +0000 | [diff] [blame] | 165 | |
| 166 | </sect1> |
| 167 | |
| 168 | </chapter> |