docs/xml/manual-intro.xml

<?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 suite of simulation-based debugging and profiling
tools for programs running on Linux (x86, amd64 and ppc32).  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> 
    </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>

    <para>NOTE: Addrcheck is not available in Valgrind 3.1.X.  We hope
    to reinstate its functionality in later releases.  For now, use
    Memcheck instead.</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/cgi-bin/show.cgi/KcacheGrindIndex">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>

    <para>NOTE: Helgrind is, unfortunately, not available in Valgrind
    3.1.X, as a result of threading changes that happened in the 2.4.0
    release.  We hope to reinstate its functionality in a future 3.2.0
    release.</para>
   </listitem>

</orderedlist>
  

<para>A couple of minor tools (<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.  Nulgrind is
the null tool -- it adds no instrumentation.  Lackey is a simple example
tool which counts instructions, memory accesses, and the number of
integer and floating point operations your program does.</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.1.0 it supports several platforms:
x86/Linux (mature), AMD64/Linux (maturing), and PPC32/Linux (immature
but works well).  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.3.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.
<filename>valgrind.h</filename>, <filename>memcheck.h</filename>) 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, <filename>pth_*.c</filename>, are taken from "Pthreads
Programming" by Bradford Nichols, Dick Buttlar &amp; Jacqueline Proulx
Farrell, ISBN 1-56592-115-1, published by O'Reilly &amp; 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>