| <?xml version="1.0"?> <!-- -*- sgml -*- --> |
| <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> |
| |
| <chapter id="manual-intro" xreflabel="Introduction"> |
| <title>Introduction</title> |
| |
| <sect1 id="manual-intro.overview" xreflabel="An Overview of Valgrind"> |
| <title>An Overview of Valgrind</title> |
| |
| <para>Valgrind is a flexible system for debugging and profiling |
| Linux executables. The system consists of a core, which |
| provides a synthetic CPU in software, and a series of tools, |
| each of which performs some kind of debugging, profiling, or |
| similar task. The architecture is modular, so that new tools can |
| be created easily and without disturbing the existing |
| structure.</para> |
| |
| <para>A number of useful tools are supplied as standard. In |
| summary, these are:</para> |
| |
| <orderedlist> |
| |
| <listitem> |
| <para><command>Memcheck</command> detects memory-management |
| problems in your programs. All reads and writes of memory |
| are checked, and calls to malloc/new/free/delete are |
| intercepted. As a result, Memcheck can detect the following |
| problems:</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para>Use of uninitialised memory</para> |
| </listitem> |
| <listitem> |
| <para>Reading/writing memory after it has been |
| free'd</para> |
| </listitem> |
| <listitem> |
| <para>Reading/writing off the end of malloc'd |
| blocks</para> |
| </listitem> |
| <listitem> |
| <para>Reading/writing inappropriate areas on the |
| stack</para> |
| </listitem> |
| <listitem> |
| <para>Memory leaks -- where pointers to malloc'd |
| blocks are lost forever</para> |
| </listitem> |
| <listitem> |
| <para>Mismatched use of malloc/new/new [] vs |
| free/delete/delete []</para> |
| </listitem> |
| <listitem> |
| <para>Overlapping <computeroutput>src</computeroutput> and |
| <computeroutput>dst</computeroutput> pointers in |
| <computeroutput>memcpy()</computeroutput> and related |
| functions</para></listitem> <listitem><para>Some misuses of |
| the POSIX pthreads API</para> |
| </listitem> |
| </itemizedlist> |
| |
| <para>Problems like these can be difficult to find by other |
| means, often lying undetected for long periods, then causing |
| occasional, difficult-to-diagnose crashes.</para> |
| </listitem> |
| |
| <listitem> |
| <para><command>Addrcheck</command> is a lightweight version |
| of Memcheck. It is identical to Memcheck except for the |
| single detail that it does not do any uninitialised-value |
| checks. All of the other checks -- primarily the |
| fine-grained address checking -- are still done. The |
| downside of this is that you don't catch the |
| uninitialised-value errors that Memcheck can find.</para> |
| |
| <para>But the upside is significant: programs run about twice |
| as fast as they do on Memcheck, and a lot less memory is |
| used. It still finds reads/writes of freed memory, memory |
| off the end of blocks and in other invalid places, bugs which |
| you really want to find before release!</para> |
| |
| <para>Because Addrcheck is lighter and faster than Memcheck, |
| you can run more programs for longer, and so you may be able |
| to cover more test scenarios. Addrcheck was created because |
| one of us (Julian) wanted to be able to run a complete KDE |
| desktop session with checking. As of early November 2002, we |
| have been able to run KDE-3.0.3 on a 1.7 GHz P4 with 512 MB |
| of memory, using Addrcheck. Although the result is not |
| stellar, it's quite usable, and it seems plausible to run KDE |
| for long periods at a time like this, collecting up all the |
| addressing errors that appear.</para> |
| </listitem> |
| |
| <listitem> |
| <para><command>Cachegrind</command> is a cache profiler. It |
| performs detailed simulation of the I1, D1 and L2 caches in |
| your CPU and so can accurately pinpoint the sources of cache |
| misses in your code. If you desire, it will show the number |
| of cache misses, memory references and instructions accruing |
| to each line of source code, with per-function, per-module |
| and whole-program summaries. If you ask really nicely it |
| will even show counts for each individual machine |
| instruction.</para> |
| |
| <para>On x86 and AMD64, Cachegrind auto-detects your machine's cache |
| configuration using the |
| <computeroutput>CPUID</computeroutput> instruction, and so |
| needs no further configuration info, in most cases.</para> |
| |
| <para>Cachegrind is nicely complemented by Josef |
| Weidendorfer's amazing KCacheGrind visualisation tool |
| (<ulink url="http://kcachegrind.sourceforge.net">http://kcachegrind.sourceforge.net</ulink>), |
| a KDE application which presents these profiling results in a |
| graphical and easier-to-understand form.</para> |
| </listitem> |
| |
| <listitem> |
| <para><command>Helgrind</command> finds data races in |
| multithreaded programs. Helgrind looks for memory locations |
| which are accessed by more than one (POSIX p-)thread, but for |
| which no consistently used (pthread_mutex_)lock can be found. |
| Such locations are indicative of missing synchronisation |
| between threads, and could cause hard-to-find |
| timing-dependent problems.</para> |
| |
| <para>Helgrind ("Hell's Gate", in Norse mythology) implements |
| the so-called "Eraser" data-race-detection algorithm, along |
| with various refinements (thread-segment lifetimes) which |
| reduce the number of false errors it reports. It is as yet |
| somewhat of an experimental tool, so your feedback is |
| especially welcomed here.</para> |
| |
| <para>Helgrind has been hacked on extensively by Jeremy |
| Fitzhardinge, and we have him to thank for getting it to a |
| releasable state.</para> |
| </listitem> |
| |
| </orderedlist> |
| |
| |
| <para>A number of minor tools (<command>Corecheck</command>, |
| <command>Lackey</command> and <command>Nulgrind</command>) are |
| also supplied. These aren't particularly useful -- they exist to |
| illustrate how to create simple tools and to help the valgrind |
| developers in various ways.</para> |
| |
| <para>Valgrind is closely tied to details of the CPU and operating |
| system, and to a lesser extent, the compiler and basic C libraries. |
| Nonetheless, as of version 3.0.0 it supports several platforms: x86/Linux |
| (mature), AMD64/Linux (immature but works well), and PPC32/Linux (very |
| preliminary). Valgrind uses the standard Unix |
| <computeroutput>./configure</computeroutput>, |
| <computeroutput>make</computeroutput>, <computeroutput>make |
| install</computeroutput> mechanism, and we have attempted to |
| ensure that it works on machines with kernel 2.4 or 2.6 and glibc |
| 2.2.X--2.4.X.</para> |
| |
| <para>Valgrind is licensed under the <xref linkend="license.gpl"/>, |
| version 2. The <computeroutput>valgrind/*.h</computeroutput> headers that |
| you may wish to include in your code (eg. |
| <computeroutput>valgrind.h</computeroutput>, |
| <computeroutput>memcheck.h</computeroutput>) are |
| distributed under a BSD-style license, so you may include them in your code |
| without worrying about license conflicts. Some of the PThreads test cases, |
| <computeroutput>pth_*.c</computeroutput>, are taken from |
| "Pthreads Programming" by Bradford Nichols, Dick Buttlar & |
| Jacqueline Proulx Farrell, ISBN 1-56592-115-1, published by |
| O'Reilly & Associates, Inc.</para> |
| |
| </sect1> |
| |
| |
| <sect1 id="manual-intro.navigation" xreflabel="How to navigate this manual"> |
| <title>How to navigate this manual</title> |
| |
| <para>The Valgrind distribution consists of the Valgrind core, |
| upon which are built Valgrind tools, which do different kinds of |
| debugging and profiling. This manual is structured |
| similarly.</para> |
| |
| <para>First, we describe the Valgrind core, how to use it, and |
| the flags it supports. Then, each tool has its own chapter in |
| this manual. You only need to read the documentation for the |
| core and for the tool(s) you actually use, although you may find |
| it helpful to be at least a little bit familar with what all |
| tools do. If you're new to all this, you probably want to run |
| the Memcheck tool. If you want to write a new tool, read |
| <xref linkend="writing-tools"/>.</para> |
| |
| <para>Be aware that the core understands some command line flags, |
| and the tools have their own flags which they know about. This |
| means there is no central place describing all the flags that are |
| accepted -- you have to read the flags documentation both for |
| <xref linkend="manual-core"/> and for the tool you want to |
| use.</para> |
| |
| </sect1> |
| |
| </chapter> |