ftmemsim-valgrind/coregrind/docs/coregrind_intro.html

<a name="intro"></a>
<h2>1&nbsp; Introduction</h2>

<a name="intro-overview"></a>
<h3>1.1&nbsp; An overview of Valgrind</h3>

Valgrind is a flexible tool for debugging and profiling Linux-x86
executables.  The tool consists of a core, which provides a synthetic
x86 CPU in software, and a series of "skins", each of which is a
debugging or profiling tool.  The architecture is modular, so that new
skins can be created easily and without disturbing the existing
structure.

<p>
A number of useful skins are supplied as standard.  In summary, these
are:

<ul>
<li>The <b>memcheck</b> skin detects memory-management problems in
    your programs.  It provides services identical to those supplied
    by the valgrind-1.0.X series.  Memcheck is essentially
    valgrind-1.0.X packaged up into a skin.
    <p>
    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:
    <ul>
        <li>Use of uninitialised memory</li>
        <li>Reading/writing memory after it has been free'd</li>
        <li>Reading/writing off the end of malloc'd blocks</li>
        <li>Reading/writing inappropriate areas on the stack</li>
        <li>Memory leaks -- where pointers to malloc'd blocks are lost
            forever</li>
        <li>Mismatched use of malloc/new/new [] vs free/delete/delete []</li>
        <li>Some misuses of the POSIX pthreads API</li>
    </ul>
    <p>
    Problems like these can be difficult to find by other means, often
    lying undetected for long periods, then causing occasional,
    difficult-to-diagnose crashes.
<p>
<li><b>cachegrind</b> is a packaging of Nick Nethercote's cache
    profiler from valgrind-1.0.X.  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.
    <p>
    Cachegrind auto-detects your machine's cache configuration
    using the <code>CPUID</code> instruction, and so needs no further
    configuration info, in most cases.
    <p>
    Cachegrind is nicely complemented by Josef Weidendorfer's
    amazing KCacheGrind visualisation tool (<A
    HREF="http://kcachegrind.sourceforge.net">
    http://kcachegrind.sourceforge.net</A>), a KDE application which
    presents these profiling results in a graphical and
    easier-to-understand form.
<p>
<li>The new <b>addrcheck</b> skin 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.
    <p>
    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!
    <p>
    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.
<p>
<li><b>helgrind</b> is a new debugging skin, designed to find data
    races in multithreaded programs.  What helgrind looks for
    is 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.
    <p>
    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 skin, so your feedback is especially welcomed here.
    <p>
    Helgrind has been hacked on extensively by Jeremy
    Fitzhardinge, and we have him to thank for getting it to a
    releasable state.
</ul>

A number of minor skins (<b>corecheck</b>, <b>lackey</b> and
<b>none</b>) are also supplied.  These aren't particularly useful --
they exist to illustrate how to create simple skins and to help the
valgrind developers in various ways.


<p>
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 <code>./configure</code>,
<code>make</code>, <code>make install</code> mechanism, and we have
attempted to ensure that it works on machines with kernel 2.2 or 2.4
and glibc 2.1.X, 2.2.X or 2.3.1.  This should cover the vast majority
of modern Linux installations.  Note that glibc-2.3.2+, with the
NPTL (next generation posix threads?) package won't work.  We hope to
be able to fix this, but it won't be easy.


<p>
Valgrind is licensed under the GNU General Public License, version
2. Read the file LICENSE in the source distribution for details.  Some
of the PThreads test cases, <code>pth_*.c</code>, 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.




<a name="intro-navigation"></a>
<h3>1.2&nbsp; How to navigate this manual</h3>

Valgrind is structured as a set of core services supporting a number
of profiling and debugging tools ("skins").  This manual is structured
similarly.  Below, we continue with a description of the valgrind
core, how to use it, and the flags it supports.

<p>
The skins each have their own chapters in this manual.  You only need
to read the documentation for the core services and for the skin(s)
you actually use, although you may find it helpful to be at least a
little bit familar with what all skins do.  If you want to write a new
skin, read <A HREF="coregrind_skins.html">this</A>.

<p>
If you're new to all this, you're most likely to be using the Memcheck
skin, since that's the one selected by default.  So, read the rest of
this page, and the section Memcheck.

<p>
Be aware that the core understands some command line flags, and the
skins 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 
<A HREF="coregrind_core.html#core">valgrind's core</A>
and for the skin you want to use.

<p>
<a name="intro-migrating"></a>
<h4>1.2.1&nbsp; For users migrating from valgrind-1.0.X</h4>
<p>
Valgrind-2.0.X is a major redesign of the 1.0.X series.  You should at
least be familiar with the concept of the new core/skin division,
as explained above in the Introduction.  Having said that, we've tried
to make the command line handling and behaviour as
backwards-compatible as we can.  In particular, just running
<code>valgrind [args-for-valgrind] my_prog [args-for-my-prog]</code>
should work pretty much as before.

<p>