mirror of
https://github.com/Zenithsiz/ftmemsim-valgrind.git
synced 2026-02-04 02:18:37 +00:00
e53a6fba14
*.xml docs. No more groffly/nroffly editing. How cool is docbook ? git-svn-id: svn://svn.valgrind.org/valgrind/trunk@5276
201 lines
8.8 KiB
XML
201 lines
8.8 KiB
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 & 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>
|