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, ppc32 and ppc64).
The system consists of a core, which provides a synthetic CPU in
software, and a set 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 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 remaining undetected for long periods, then causing occasional,
    difficult-to-diagnose crashes.</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.  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 and64, 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>
   </listitem>

   <listitem>
     <para><command>Callgrind</command> is a profiler similar in
     concept to Cachegrind, but which also tracks caller-callee
     relationships.  By doing so it is able to show how instruction,
     memory reference and cache miss costs flow between callers and
     callees.  Callgrind collects a large amount of data which is best
     navigated using Josef Weidendorfer's amazing KCachegrind
     visualisation tool (<ulink
     url="http://kcachegrind.sourceforge.net/cgi-bin/show.cgi/KcacheGrindIndex">http://kcachegrind.sourceforge.net</ulink>).
     KCachegrind is a KDE application which presents 
     these profiling results in a
     graphical and easy-to-understand form.</para>
   </listitem>

   <listitem>
     <para><command>Massif</command> is a heap profiler.
     It measures how much heap memory programs use.  In particular,
     it can give you information about heap blocks, heap 
     administration overheads, and stack sizes.</para>

     <para>Heap profiling can help you reduce the amount of
     memory your program uses.  On modern machines with virtual
     memory, this reduces the chances that your program will run out
     of memory, and may make it faster by reducing the amount of
     paging needed.</para>
   </listitem>

   <listitem>
     <para><command>Helgrind</command> detects synchronisation errors
     in programs that use the POSIX pthreads threading primitives.  It
     detects the following three classes of errors:</para>

     <itemizedlist>
      <listitem>
        <para>Misuses of the POSIX pthreads API.</para>
      </listitem>
      <listitem>
        <para>Potential deadlocks arising from lock ordering
        problems.</para>
      </listitem>
      <listitem>
       <para>Data races -- accessing memory without adequate locking.</para>
      </listitem>
    </itemizedlist>

    <para>Problems like these often result in unreproducible,
    timing-dependent crashes, deadlocks and other misbehaviour, and
    can be difficult to find by other means.</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.3.0 it supports several platforms:
x86/Linux (mature), amd64/Linux (maturing), ppc32/Linux and
ppc64/Linux (less mature but work well).  There is also experimental
support for ppc32/AIX5 and ppc64/AIX5 (AIX 5.2 and 5.3 only).
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 Linux kernel 2.4.X or 2.6.X and glibc
2.2.X to 2.7.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>,
<filename>helgrind.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>

<para>If you contribute code to Valgrind, please ensure your
contributions are licensed as "GPLv2, or (at your option) any later
version."  This is so as to allow the possibility of easily upgrading
the license to GPLv3 in future.  If you want to modify code in the VEX
subdirectory, please also see VEX/HACKING.README.</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.  The tools 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 familiar with what all tools do.  If you're new to all this, you probably
want to run the Memcheck tool.  The final chapter explains how to write a
new tool.</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>

<para>The manual is quite big and complex.  If you are looking for a
quick getting-started guide, have a look at
<xref linkend="quick-start"/>.</para>

</sect1>

</chapter>