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 flexible system for debugging and profiling
Linux-x86 executables.  The system consists of a core, which
provides a synthetic x86 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 x86
    instruction.</para>

    <para>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, operating
system and to a less extent, compiler and basic C libraries. This
makes it difficult to make it portable, so we have chosen at the
outset to concentrate on what we believe to be a widely used
platform: Linux on x86s.  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.1.X--2.3.X.</para>

<para>Valgrind is licensed under the <xref linkend="license.gpl"/>,
version 2.  The <computeroutput>valgrind/*.h</computeroutput> headers 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 &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>