mirror of
https://github.com/Zenithsiz/ftmemsim-valgrind.git
synced 2026-02-04 02:18:37 +00:00
169 lines
7.0 KiB
XML
169 lines
7.0 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, ppc32 and ppc64).
|
|
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 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>
|
|
|
|
</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.2.0 it supports several platforms:
|
|
x86/Linux (mature), amd64/Linux (maturing), ppc32/Linux and
|
|
ppc64/Linux (less mature but work 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 Linux kernel 2.4.X or 2.6.X and glibc
|
|
2.2.X to 2.5.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. 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>
|
|
|
|
</sect1>
|
|
|
|
</chapter>
|