mirror of
https://github.com/Zenithsiz/ftmemsim-valgrind.git
synced 2026-02-03 10:05:29 +00:00
Started overhauling the documentation:
- There were detailed descriptions of all the tools in the Quick Start Guide, the Manual introduction, and the start of each tool chapter. To avoid duplication/overlap, I removed these altogether from the Quick Start Guide, and shortened them in the intro. - Improved the description of what errors Memcheck can find. - Made all tool chapters start with "Overview" section, for consistency. - Made the "run with --tool=XXX" bit consistent in each tool chapter. - Made all tool chapter titles match the description given when running them. - Added BBV to the User Manual intro. - Generally clarified, updated, and future-proofed various bits of text in the Quick Start Guide and User Manual introduction. Also: - Changed Nulgrind's start-up description to "the minimal Valgrind tool". - Fixed some punctuation in the usage message. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@10652
This commit is contained in:
Nicholas Nethercote
parent
d746713267
commit
78b2e5c83e
@ -4,27 +4,22 @@
|
||||
[ <!ENTITY % vg-entities SYSTEM "../../docs/xml/vg-entities.xml"> %vg-entities; ]>
|
||||
|
||||
|
||||
<chapter id="cg-manual" xreflabel="Cachegrind: a cache-miss profiler">
|
||||
<title>Cachegrind: a cache and branch profiler</title>
|
||||
|
||||
<sect1 id="cg-manual.cache" xreflabel="Cache profiling">
|
||||
<title>Cache and branch profiling</title>
|
||||
<chapter id="cg-manual" xreflabel="Cachegrind: a cache and branch-prediction profiler">
|
||||
<title>Cachegrind: a cache and branch-prediction profiler</title>
|
||||
|
||||
<para>To use this tool, you must specify
|
||||
<computeroutput>--tool=cachegrind</computeroutput> on the
|
||||
Valgrind command line.</para>
|
||||
|
||||
<para>Cachegrind is a tool for finding places where programs
|
||||
interact badly with typical modern superscalar processors
|
||||
and run slowly as a result.
|
||||
In particular, it will do a cache simulation of your program,
|
||||
and optionally a branch-predictor simulation, and can
|
||||
then annotate your source line-by-line with the number of cache
|
||||
misses and branch mispredictions. The following statistics are
|
||||
collected:</para>
|
||||
<sect1 id="cg-manual.overview" xreflabel="Overview">
|
||||
<title>Overview</title>
|
||||
|
||||
<para>Cachegrind simulates how your program interacts with a machine's cache
|
||||
hierarchy and (optionally) branch predictor. It gathers the following
|
||||
statistics:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>L1 instruction cache reads and misses;</para>
|
||||
<para>L1 instruction cache reads and read misses;</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>L1 data cache reads and read misses, writes and write
|
||||
@ -44,24 +39,28 @@ collected:</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>These statistics are presented for the entire program and for each
|
||||
function in the program. You can also annotate each line of source code in
|
||||
the program with the counts that were caused directly by it.</para>
|
||||
|
||||
<para>On a modern machine, an L1 miss will typically cost
|
||||
around 10 cycles, an L2 miss can cost as much as 200
|
||||
cycles, and a mispredicted branch costs in the region of 10
|
||||
to 30 cycles. Detailed cache and branch profiling can be very useful
|
||||
for improving the performance of your program.</para>
|
||||
for understanding how your program interacts with the machine and thus how
|
||||
to make it faster.</para>
|
||||
|
||||
<para>Also, since one instruction cache read is performed per
|
||||
instruction executed, you can find out how many instructions are
|
||||
executed per line, which can be useful for traditional profiling
|
||||
and test coverage.</para>
|
||||
executed per line, which can be useful for traditional profiling.</para>
|
||||
|
||||
<para>Branch profiling is not enabled by default. To use it, you must
|
||||
additionally specify <computeroutput>--branch-sim=yes</computeroutput>
|
||||
on the command line.</para>
|
||||
|
||||
|
||||
<sect2 id="cg-manual.overview" xreflabel="Overview">
|
||||
<title>Overview</title>
|
||||
<sect2 id="cg-manual.basics" xreflabel="Basics">
|
||||
<title>Basics</title>
|
||||
|
||||
<para>First off, as for normal Valgrind use, you probably want to
|
||||
compile with debugging info (the
|
||||
@ -169,7 +168,7 @@ follows:</para>
|
||||
|
||||
<para>The cache configuration simulated (cache size,
|
||||
associativity and line size) is determined automagically using
|
||||
the CPUID instruction. If you have an old machine that (a)
|
||||
the x86 CPUID instruction. If you have an machine that (a)
|
||||
doesn't support the CPUID instruction, or (b) supports it in an
|
||||
early incarnation that doesn't give any cache information, then
|
||||
Cachegrind will fall back to using a default configuration (that
|
||||
|
||||
@ -4,9 +4,13 @@
|
||||
[ <!ENTITY % cl-entities SYSTEM "cl-entities.xml"> %cl-entities; ]>
|
||||
|
||||
<chapter id="cl-manual" xreflabel="Callgrind Manual">
|
||||
<title>Callgrind: a call graph profiler</title>
|
||||
<title>Callgrind: a call-graph generating cache profiler</title>
|
||||
|
||||
|
||||
<para>To use this tool, you must specify
|
||||
<computeroutput>--tool=callgrind</computeroutput> on the
|
||||
Valgrind command line.</para>
|
||||
|
||||
<sect1 id="cl-manual.use" xreflabel="Overview">
|
||||
<title>Overview</title>
|
||||
|
||||
|
||||
@ -212,8 +212,8 @@ static void usage_NORETURN ( Bool debug_help )
|
||||
" Extra options read from ~/.valgrindrc, $VALGRIND_OPTS, ./.valgrindrc\n"
|
||||
"\n"
|
||||
" %s is %s\n"
|
||||
" Valgrind is Copyright (C) 2000-2009, and GNU GPL'd, by Julian Seward et al\n"
|
||||
" LibVEX is Copyright (C) 2004-2009, and GNU GPL'd, by OpenWorks LLP\n"
|
||||
" Valgrind is Copyright (C) 2000-2009, and GNU GPL'd, by Julian Seward et al.\n"
|
||||
" LibVEX is Copyright (C) 2004-2009, and GNU GPL'd, by OpenWorks LLP.\n"
|
||||
"\n"
|
||||
" Bug reports, feedback, admiration, abuse, etc, to: %s.\n"
|
||||
"\n";
|
||||
|
||||
@ -1,6 +1,7 @@
|
||||
<?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">
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
|
||||
[ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]>
|
||||
|
||||
<chapter id="manual-intro" xreflabel="Introduction">
|
||||
<title>Introduction</title>
|
||||
@ -8,163 +9,81 @@
|
||||
<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>Valgrind is an instrumentation framework for building dynamic analysis
|
||||
tools. It comes with a set of tools each of which performs some kind of
|
||||
debugging, profiling, or similar task that helps you improve your programs.
|
||||
Valgrind's architecture is modular, so 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>
|
||||
<para>A number of useful tools are supplied as standard.</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>
|
||||
<para><command>Memcheck</command> is a memory error detector. It helps
|
||||
you make your programs, particularly those written in C and C++, more
|
||||
correct.</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>
|
||||
<listitem>
|
||||
<para><command>Cachegrind</command> is a cache and branch-prediction
|
||||
profiler. It can help you make your programs run faster.</para>
|
||||
</listitem>
|
||||
|
||||
<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 call-graph generating cache
|
||||
profiler. It has some overlap with Cachegrind, but also gathers some
|
||||
information that Cachegrind does not.</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>Helgrind</command> is a thread error detector.
|
||||
It can help you make your multi-threaded programs more correct.
|
||||
</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>
|
||||
<listitem>
|
||||
<para><command>DRD</command> is also a thread error detector. It is
|
||||
similar to Helgrind but uses different analysis techniques and so may
|
||||
find different problems.</para>
|
||||
</listitem>
|
||||
|
||||
<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>
|
||||
<listitem>
|
||||
<para><command>Massif</command> is a heap profiler. It can help you
|
||||
make your programs use less memory.</para>
|
||||
</listitem>
|
||||
|
||||
<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>
|
||||
|
||||
<listitem>
|
||||
<para><command>DRD</command> is similar to Helgrind, but uses a
|
||||
different analysis technique and so may find different problems.
|
||||
</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>Ptrcheck</command> is an experimental pointer checking
|
||||
tool. Its functionality overlaps somewhat with Memcheck's, but it can
|
||||
find some problems that Memcheck would miss.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><command>Ptrcheck</command> is an experimental heap, stack and
|
||||
global array overrun detector. Its functionality overlaps somewhat
|
||||
with Memcheck's, but it can find some problems that Memcheck would
|
||||
miss.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><command>BBV</command> is an experimental SimPoint basic block
|
||||
vector generator. It is useful to people doing computer architecture
|
||||
research and development.</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>There are also a couple of minor tools that aren't useful to
|
||||
most users: <command>Lackey</command> is an example tool that illustrates
|
||||
some instrumentation basics; and <command>Nulgrind</command> is the minimal
|
||||
Valgrind tool that does no analysis or instrumentation, and is only useful
|
||||
for testing purposes.</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
|
||||
Nonetheless, it supports a number of widely-used platforms, listed in full
|
||||
at <ulink url="&vg-url;">&vg-url;</ulink>.</para>
|
||||
|
||||
<para>Valgrind is built via 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>
|
||||
install</computeroutput> process; full details are given in the
|
||||
README file in the distribution.</para>
|
||||
|
||||
<para>Valgrind is licensed under the <xref linkend="license.gpl"/>,
|
||||
version 2. The <computeroutput>valgrind/*.h</computeroutput> headers
|
||||
@ -182,7 +101,8 @@ Inc.</para>
|
||||
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>
|
||||
subdirectory, please also see the file VEX/HACKING.README in the
|
||||
distribution.</para>
|
||||
|
||||
|
||||
</sect1>
|
||||
@ -191,11 +111,8 @@ subdirectory, please also see VEX/HACKING.README.</para>
|
||||
<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
|
||||
<para>This manual's structure reflects the structure of Valgrind itself.
|
||||
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
|
||||
@ -209,9 +126,8 @@ 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>
|
||||
<para>The manual is quite big and complex. If you want to start using
|
||||
Valgrind more quickly, read <xref linkend="quick-start"/>.</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
@ -11,7 +11,7 @@
|
||||
<title>Introduction</title>
|
||||
|
||||
So you want to write a Valgrind tool? Here are some instructions that may
|
||||
help. They were last updated for Valgrind 3.2.2.
|
||||
help.
|
||||
|
||||
<sect2 id="writing-tools.tools" xreflabel="Tools">
|
||||
<title>Tools</title>
|
||||
|
||||
@ -26,71 +26,15 @@
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>The Valgrind tool suite provides a number of debugging and
|
||||
profiling tools. The most popular is
|
||||
Memcheck, a memory checking tool which can detect many common
|
||||
memory errors such as:</para>
|
||||
profiling tools that help you make your programs faster and more correct.
|
||||
The most popular of these tools is called Memcheck. It can detect many
|
||||
memory-related errors that are common in C and C++ programs and that can
|
||||
lead to crashes and unpredictable behaviour.</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>Touching memory you shouldn't (eg. overrunning heap block
|
||||
boundaries, or reading/writing freed memory).</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Using values before they have been initialized.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Incorrect freeing of memory, such as double-freeing heap
|
||||
blocks.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Memory leaks.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>Memcheck is only one of the tools in the Valgrind suite.
|
||||
Other tools you may find useful are:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>Cachegrind: a profiling tool which produces detailed data on
|
||||
cache (miss) and branch (misprediction) events. Statistics are
|
||||
gathered for the entire program, for each function, and for each
|
||||
line of code, if you need that level of detail.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Callgrind: a profiling tool that shows cost relationships
|
||||
across function calls, optionally with cache simulation similar to
|
||||
Cachegrind. Information gathered by Callgrind can be viewed
|
||||
either with an included command line tool, or by using the
|
||||
KCachegrind GUI. KCachegrind is not part of the Valgrind suite
|
||||
-- it is part of the KDE Desktop Environment.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Massif: a space profiling tool. It allows you to explore
|
||||
in detail which parts of your program allocate memory.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Helgrind: a debugging tool for threaded programs. Helgrind
|
||||
looks for various kinds of synchronisation errors in code that uses
|
||||
the POSIX PThreads API.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>In addition, there are a number of "experimental" tools in
|
||||
the codebase. They can be distinguished by the "exp-" prefix on
|
||||
their names. Experimental tools are not subject to the same
|
||||
quality control standards that apply to our production-grade tools
|
||||
(Memcheck, Cachegrind, Callgrind, Massif, Helgrind and DRD).</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>The rest of this guide discusses only the Memcheck tool. For
|
||||
full documentation on the other tools, and for Memcheck, see the
|
||||
Valgrind User Manual.</para>
|
||||
|
||||
<para>What follows is the minimum information you need to start
|
||||
detecting memory errors in your program with Memcheck. Note that this
|
||||
guide applies to Valgrind version 3.4.0 and later. Some of the
|
||||
information is not quite right for earlier versions.</para>
|
||||
<para>The rest of this guide gives the minimum information you need to start
|
||||
detecting memory errors in your program with Memcheck. For full
|
||||
documentation of Memcheck and the other tools, please read the User Manual.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
@ -103,9 +47,9 @@ information so that Memcheck's error messages include exact line
|
||||
numbers. Using <computeroutput>-O0</computeroutput> is also a good
|
||||
idea, if you can tolerate the slowdown. With
|
||||
<computeroutput>-O1</computeroutput> line numbers in error messages can
|
||||
be inaccurate, although generally speaking Memchecking code compiled at
|
||||
<computeroutput>-O1</computeroutput> works fairly well and is
|
||||
recommended. Use of
|
||||
be inaccurate, although generally speaking running Memcheck on code compiled
|
||||
at <computeroutput>-O1</computeroutput> works fairly well.
|
||||
Use of
|
||||
<computeroutput>-O2</computeroutput> and above is not recommended as
|
||||
Memcheck occasionally reports uninitialised-value errors which don't
|
||||
really exist.</para>
|
||||
@ -137,8 +81,8 @@ memory errors and leaks that it detects.</para>
|
||||
<sect1 id="quick-start.interpret"
|
||||
xreflabel="Interpreting Memcheck's output">
|
||||
<title>Interpreting Memcheck's output</title>
|
||||
<para>Here's an example C program with a memory error and a memory
|
||||
leak.</para>
|
||||
<para>Here's an example C program, in a file called a.c, with a memory error
|
||||
and a memory leak.</para>
|
||||
|
||||
<programlisting>
|
||||
#include <stdlib.h>
|
||||
@ -237,12 +181,13 @@ categories are:</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>It can be difficult to track down the root causes of
|
||||
uninitialised-value errors reported by Memcheck. Try using
|
||||
the <option>--track-origins=yes</option> to get extra information.
|
||||
This makes Memcheck run slower, but the extra information you get
|
||||
often saves a lot of time figuring out where the uninitialised values
|
||||
are coming from.</para>
|
||||
<para>Memcheck also reports uses of uninitialised values, most commonly with
|
||||
the message "Conditional jump or move depends on uninitialised
|
||||
value(s)". It can be difficult to determine the root cause of these errors.
|
||||
Try using the <option>--track-origins=yes</option> to get extra information.
|
||||
This makes Memcheck run slower, but the extra information you get often
|
||||
saves a lot of time figuring out where the uninitialised values are coming
|
||||
from.</para>
|
||||
|
||||
<para>If you don't understand an error message, please consult
|
||||
<xref linkend="mc-manual.errormsgs"/> in the <xref linkend="manual"/>
|
||||
@ -275,8 +220,8 @@ errors. Once you achieve this state, it is much easier to see when
|
||||
changes to the program cause Memcheck to report new errors.
|
||||
Experience from several years of Memcheck use shows that it is
|
||||
possible to make even huge programs run Memcheck-clean. For example,
|
||||
large parts of KDE 3.5.X, and recent versions of OpenOffice.org
|
||||
(2.3.0) are Memcheck-clean, or very close to it.</para>
|
||||
large parts of KDE, OpenOffice.org and Firefox are Memcheck-clean, or very
|
||||
close to it.</para>
|
||||
|
||||
|
||||
</sect1>
|
||||
|
||||
@ -13,7 +13,7 @@ on the Valgrind command line.</para>
|
||||
|
||||
|
||||
<sect1 id="drd-manual.overview" xreflabel="Overview">
|
||||
<title>Background</title>
|
||||
<title>Overview</title>
|
||||
|
||||
<para>
|
||||
DRD is a Valgrind tool for detecting errors in multithreaded C and C++
|
||||
|
||||
@ -3,14 +3,14 @@
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
||||
|
||||
<chapter id="bbv-manual" xreflabel="BBV">
|
||||
<title>BBV: a Basic Block Vector generation tool</title>
|
||||
<title>BBV: an experimental basic block vector generation tool</title>
|
||||
|
||||
<para>To use this tool, you must specify
|
||||
<computeroutput>--tool=exp-bbv</computeroutput> on the Valgrind
|
||||
command line.</para>
|
||||
|
||||
<sect1 id="bbv-manual.background" xreflabel="BBV Background">
|
||||
<title>Basic Block Profiling and SimPoint</title>
|
||||
<sect1 id="bbv-manual.overview" xreflabel="Overview">
|
||||
<title>Overview</title>
|
||||
|
||||
<para>
|
||||
A Basic Blocks Vector (BBV) is a list of all basic blocks entered
|
||||
@ -20,7 +20,7 @@ command line.</para>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This tool was written to generate basic block vectors
|
||||
BBV is tool that generates basic block vectors
|
||||
for use with the SimPoint analysis tool
|
||||
(http://www.cse.ucsd.edu/~calder/simpoint/).
|
||||
The SimPoint methodology enables speeding up architectural
|
||||
@ -39,14 +39,14 @@ command line.</para>
|
||||
In computer architecture research, running a
|
||||
benchmark on a cycle-accurate simulator can cause slowdowns on the order
|
||||
of 1000 times, making it take days, weeks, or even longer to run full
|
||||
benchmarks. By utilizing SimPoint this can be reduced significantly
|
||||
while still retaining reasonable accuracy, usually in the 5-10% range.
|
||||
benchmarks. By utilizing SimPoint this can be reduced significantly,
|
||||
usually by 90-95%, while still retaining reasonable accuracy.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A more complete introduction to how SimPoint works can be
|
||||
found in the paper "Automatically Characterizing Large Scale
|
||||
Program Behavior" by T. Sherwood, E Perelman, G. Hamerly, and
|
||||
Program Behavior" by T. Sherwood, E. Perelman, G. Hamerly, and
|
||||
B. Calder.
|
||||
</para>
|
||||
|
||||
|
||||
@ -5,8 +5,8 @@
|
||||
|
||||
|
||||
<chapter id="pc-manual"
|
||||
xreflabel="Ptrcheck: an (experimental) pointer checking tool">
|
||||
<title>Ptrcheck: an (experimental) pointer checking tool</title>
|
||||
xreflabel="Ptrcheck: an experimental heap, stack & global array overrun detector">
|
||||
<title>Ptrcheck: an experimental heap, stack & global array overrun detector</title>
|
||||
|
||||
<para>To use this tool, you must specify
|
||||
<computeroutput>--tool=exp-ptrcheck</computeroutput> on the Valgrind
|
||||
@ -18,7 +18,7 @@ command line.</para>
|
||||
<sect1 id="pc-manual.overview" xreflabel="Overview">
|
||||
<title>Overview</title>
|
||||
|
||||
<para>Ptrcheck is a Valgrind tool for finding overruns of heap, stack
|
||||
<para>Ptrcheck is a tool for finding overruns of heap, stack
|
||||
and global arrays. Its functionality overlaps somewhat with
|
||||
Memcheck's, but it is able to catch invalid accesses in a number of
|
||||
cases that Memcheck would miss. A detailed comparison against
|
||||
|
||||
@ -12,8 +12,6 @@
|
||||
command line.</para>
|
||||
|
||||
|
||||
|
||||
|
||||
<sect1 id="hg-manual.overview" xreflabel="Overview">
|
||||
<title>Overview</title>
|
||||
|
||||
@ -26,14 +24,6 @@ sharing a common address space, thread creation, thread joining,
|
||||
thread exit, mutexes (locks), condition variables (inter-thread event
|
||||
notifications), reader-writer locks, semaphores and barriers.</para>
|
||||
|
||||
<para>Helgrind is aware of all these abstractions and tracks their
|
||||
effects as accurately as it can. Currently it does not correctly
|
||||
handle pthread spinlocks, although it will not object if you use them.
|
||||
Adding support for spinlocks would be easy enough if the demand arises.
|
||||
On x86 and amd64 platforms, it understands and partially handles
|
||||
implicit locking arising from the use of the LOCK instruction prefix.
|
||||
</para>
|
||||
|
||||
<para>Helgrind can detect three classes of errors, which are discussed
|
||||
in detail in the next three sections:</para>
|
||||
|
||||
@ -58,6 +48,19 @@ in detail in the next three sections:</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
|
||||
<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>
|
||||
|
||||
<para>Helgrind is aware of all the pthread abstractions and tracks their
|
||||
effects as accurately as it can. Currently it does not correctly
|
||||
handle pthread spinlocks, although it will not object if you use them.
|
||||
Adding support for spinlocks would be easy enough if the demand arises.
|
||||
On x86 and amd64 platforms, it understands and partially handles
|
||||
implicit locking arising from the use of the LOCK instruction prefix.
|
||||
</para>
|
||||
|
||||
|
||||
<para>Following those is a section containing
|
||||
<link linkend="hg-manual.effective-use">
|
||||
hints and tips on how to get the best out of Helgrind.</link>
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
|
||||
<chapter id="lk-manual" xreflabel="Lackey">
|
||||
|
||||
<title>Lackey: a simple profiler and memory tracer</title>
|
||||
<title>Lackey: an example tool</title>
|
||||
|
||||
<para>To use this tool, you must specify
|
||||
<computeroutput>--tool=lackey</computeroutput> on the Valgrind
|
||||
|
||||
@ -7,21 +7,16 @@
|
||||
<chapter id="ms-manual" xreflabel="Massif: a heap profiler">
|
||||
<title>Massif: a heap profiler</title>
|
||||
|
||||
<emphasis>Please note that this documentation describes Massif version 3.3.0
|
||||
and later. Massif was significantly overhauled for 3.3.0; versions 3.2.3
|
||||
and earlier presented the profiling information an a quite different manner,
|
||||
and so this documentation only pertains to the later versions.</emphasis>
|
||||
|
||||
<para>To use this tool, you must specify
|
||||
<computeroutput>--tool=massif</computeroutput> on the Valgrind
|
||||
command line.</para>
|
||||
|
||||
<sect1 id="ms-manual.spaceprof" xreflabel="Heap profiling">
|
||||
<title>Heap profiling</title>
|
||||
<sect1 id="ms-manual.overview" xreflabel="Overview">
|
||||
<title>Overview</title>
|
||||
|
||||
<para>Massif is a heap profiler. It measures how much heap memory your
|
||||
program uses. This includes both the useful space, and the extra bytes
|
||||
allocated for book-keeping purposes and alignment purposes. It can also
|
||||
allocated for book-keeping and alignment purposes. It can also
|
||||
measure the size of your program's stack(s), although it does not do so by
|
||||
default.</para>
|
||||
|
||||
|
||||
@ -3,55 +3,56 @@
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
||||
|
||||
|
||||
<chapter id="mc-manual" xreflabel="Memcheck: a heavyweight memory checker">
|
||||
<title>Memcheck: a heavyweight memory checker</title>
|
||||
<chapter id="mc-manual" xreflabel="Memcheck: a memory error detector">
|
||||
<title>Memcheck: a memory error detector</title>
|
||||
|
||||
<para>To use this tool, you may specify <option>--tool=memcheck</option>
|
||||
on the Valgrind command line. You don't have to, though, since Memcheck
|
||||
is the default tool.</para>
|
||||
|
||||
|
||||
<sect1 id="mc-manual.bugs"
|
||||
xreflabel="Kinds of bugs that Memcheck can find">
|
||||
<title>Kinds of bugs that Memcheck can find</title>
|
||||
<sect1 id="mc-manual.overview" xreflabel="Overview">
|
||||
<title>Overview</title>
|
||||
|
||||
<para>Memcheck is Valgrind's heavyweight memory checking tool. All
|
||||
reads and writes of memory are checked, and calls to
|
||||
<function>malloc</function>/<computeroutput>new</computeroutput>/<function>free</function>/<computeroutput>delete</computeroutput>
|
||||
are intercepted. As a result, Memcheck can detect the following
|
||||
problems:</para>
|
||||
<para>Memcheck is a memory error detector. It can detect the following
|
||||
problems that are common in C and C++ programs.</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>Use of uninitialised memory</para>
|
||||
<para>Accessing memory you shouldn't, e.g. overrunning and underrunning
|
||||
heap blocks, overrunning the top of the stack, and accessing memory after
|
||||
it has been freed.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Reading/writing memory after it has been free'd</para>
|
||||
<para>Using undefined values, i.e. values that have not been initialised,
|
||||
or that have been derived from other undefined values.</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
|
||||
<para>Incorrect freeing of heap memory, such as double-freeing heap
|
||||
blocks, or mismatched use of
|
||||
<function>malloc</function>/<computeroutput>new</computeroutput>/<computeroutput>new[]</computeroutput>
|
||||
versus
|
||||
<function>free</function>/<computeroutput>delete</computeroutput>/<computeroutput>delete[]</computeroutput></para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Overlapping <computeroutput>src</computeroutput> and
|
||||
<computeroutput>dst</computeroutput> pointers in
|
||||
<function>memcpy()</function> and related
|
||||
functions</para>
|
||||
<computeroutput>memcpy()</computeroutput> and related
|
||||
functions.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Memory leaks.</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>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
|
||||
@ -5,18 +5,26 @@
|
||||
|
||||
<chapter id="nl-manual" xreflabel="Nulgrind">
|
||||
|
||||
<title>Nulgrind: the "null" tool</title>
|
||||
<subtitle>A tool that does not very much at all</subtitle>
|
||||
<title>Nulgrind: the minimal Valgrind tool</title>
|
||||
|
||||
<para>Nulgrind is the minimal tool for Valgrind. It does no
|
||||
initialisation or finalisation, and adds no instrumentation to
|
||||
the program's code. It is mainly of use for Valgrind's
|
||||
developers for debugging and regression testing.</para>
|
||||
<para>To use this tool, you must specify
|
||||
<computeroutput>--tool=none</computeroutput> on the Valgrind
|
||||
command line.</para>
|
||||
|
||||
<sect1 id="ms-manual.overview" xreflabel="Overview">
|
||||
<title>Overview</title>
|
||||
|
||||
<para>Nulgrind is the simplest possible Valgrind tool. It performs no
|
||||
instrumentation or analysis of a program, just runs it normally. It is
|
||||
mainly of use for Valgrind's developers for debugging and regression
|
||||
testing.</para>
|
||||
|
||||
<para>Nonetheless you can run programs with Nulgrind. They will run
|
||||
roughly 5 times more slowly than normal, for no useful effect. Note
|
||||
that you need to use the option <option>--tool=none</option> to run
|
||||
Nulgrind (ie. not <option>--tool=nulgrind</option>).</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
</chapter>
|
||||
|
||||
|
||||
@ -1,11 +1,11 @@
|
||||
|
||||
/*--------------------------------------------------------------------*/
|
||||
/*--- Nulgrind: The null tool. nl_main.c ---*/
|
||||
/*--- Nulgrind: The minimal Valgrind tool. nl_main.c ---*/
|
||||
/*--------------------------------------------------------------------*/
|
||||
|
||||
/*
|
||||
This file is part of Nulgrind, the simplest possible Valgrind tool,
|
||||
which does nothing.
|
||||
This file is part of Nulgrind, the minimal Valgrind tool,
|
||||
which does no instrumentation or analysis.
|
||||
|
||||
Copyright (C) 2002-2009 Nicholas Nethercote
|
||||
njn@valgrind.org
|
||||
@ -53,7 +53,7 @@ static void nl_pre_clo_init(void)
|
||||
{
|
||||
VG_(details_name) ("Nulgrind");
|
||||
VG_(details_version) (NULL);
|
||||
VG_(details_description) ("a binary JIT-compiler");
|
||||
VG_(details_description) ("the minimal Valgrind tool");
|
||||
VG_(details_copyright_author)(
|
||||
"Copyright (C) 2002-2009, and GNU GPL'd, by Nicholas Nethercote.");
|
||||
VG_(details_bug_reports_to) (VG_BUGS_TO);
|
||||
|
||||
@ -56,8 +56,8 @@ usage: valgrind [options] prog-and-args
|
||||
Extra options read from ~/.valgrindrc, $VALGRIND_OPTS, ./.valgrindrc
|
||||
|
||||
Nulgrind is Copyright (C) 2002-2009, and GNU GPL'd, by Nicholas Nethercote.
|
||||
Valgrind is Copyright (C) 2000-2009, and GNU GPL'd, by Julian Seward et al
|
||||
LibVEX is Copyright (C) 2004-2009, and GNU GPL'd, by OpenWorks LLP
|
||||
Valgrind is Copyright (C) 2000-2009, and GNU GPL'd, by Julian Seward et al.
|
||||
LibVEX is Copyright (C) 2004-2009, and GNU GPL'd, by OpenWorks LLP.
|
||||
|
||||
Bug reports, feedback, admiration, abuse, etc, to: www.valgrind.org.
|
||||
|
||||
|
||||
@ -101,8 +101,8 @@ usage: valgrind [options] prog-and-args
|
||||
Extra options read from ~/.valgrindrc, $VALGRIND_OPTS, ./.valgrindrc
|
||||
|
||||
Nulgrind is Copyright (C) 2002-2009, and GNU GPL'd, by Nicholas Nethercote.
|
||||
Valgrind is Copyright (C) 2000-2009, and GNU GPL'd, by Julian Seward et al
|
||||
LibVEX is Copyright (C) 2004-2009, and GNU GPL'd, by OpenWorks LLP
|
||||
Valgrind is Copyright (C) 2000-2009, and GNU GPL'd, by Julian Seward et al.
|
||||
LibVEX is Copyright (C) 2004-2009, and GNU GPL'd, by OpenWorks LLP.
|
||||
|
||||
Bug reports, feedback, admiration, abuse, etc, to: www.valgrind.org.
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ dir=`dirname $0`
|
||||
$dir/../../tests/filter_stderr_basic |
|
||||
|
||||
# Remove "Nulgrind, ..." line and the following copyright line.
|
||||
sed "/^Nulgrind, a binary JIT-compiler./ , /./ d" |
|
||||
sed "/^Nulgrind, the minimal Valgrind tool./ , /./ d" |
|
||||
|
||||
# Anonymise addresses
|
||||
$dir/../../tests/filter_addresses
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user