|
From: <sv...@va...> - 2013-11-01 11:05:06
|
Author: sewardj
Date: Fri Nov 1 11:04:53 2013
New Revision: 483
Log:
Documentation update for 3.9.0.
Modified:
trunk/docs/manual/FAQ.html
trunk/docs/manual/QuickStart.html
trunk/docs/manual/bbv-manual.html
trunk/docs/manual/cg-manual.html
trunk/docs/manual/cl-format.html
trunk/docs/manual/cl-manual.html
trunk/docs/manual/design-impl.html
trunk/docs/manual/dh-manual.html
trunk/docs/manual/dist.authors.html
trunk/docs/manual/dist.html
trunk/docs/manual/dist.news.html
trunk/docs/manual/dist.news.old.html
trunk/docs/manual/dist.readme-android.html
trunk/docs/manual/dist.readme-developers.html
trunk/docs/manual/dist.readme-missing.html
trunk/docs/manual/dist.readme-packagers.html
trunk/docs/manual/dist.readme-s390.html
trunk/docs/manual/dist.readme.html
trunk/docs/manual/drd-manual.html
trunk/docs/manual/faq.html
trunk/docs/manual/hg-manual.html
trunk/docs/manual/index.html
trunk/docs/manual/license.gfdl.html
trunk/docs/manual/license.gpl.html
trunk/docs/manual/licenses.html
trunk/docs/manual/lk-manual.html
trunk/docs/manual/manual-core-adv.html
trunk/docs/manual/manual-core.html
trunk/docs/manual/manual-intro.html
trunk/docs/manual/manual-writing-tools.html
trunk/docs/manual/manual.html
trunk/docs/manual/mc-manual.html
trunk/docs/manual/ms-manual.html
trunk/docs/manual/nl-manual.html
trunk/docs/manual/quick-start.html
trunk/docs/manual/sg-manual.html
trunk/docs/manual/tech-docs.html
trunk/docs/manual/valgrind_manual.html.tar.bz2
trunk/docs/manual/valgrind_manual.pdf
trunk/docs/manual/valgrind_manual.ps.bz2
Modified: trunk/docs/manual/FAQ.html
==============================================================================
--- trunk/docs/manual/FAQ.html (original)
+++ trunk/docs/manual/FAQ.html Fri Nov 1 11:04:53 2013
@@ -2,8 +2,8 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Valgrind FAQ</title>
-<link rel="stylesheet" href="vg_basic.css" type="text/css">
-<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
+<link rel="stylesheet" type="text/css" href="vg_basic.css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="index.html" title="Valgrind Documentation">
<link rel="up" href="index.html" title="Valgrind Documentation">
<link rel="prev" href="nl-manual.html" title="14. Nulgrind: the minimal Valgrind tool">
@@ -17,22 +17,22 @@
<th align="center" valign="middle">Valgrind Documentation</th>
<td width="22px" align="center" valign="middle"><a accesskey="n" href="faq.html"><img src="images/next.png" width="18" height="21" border="0" alt="Next"></a></td>
</tr></table></div>
-<div class="book" title="Valgrind FAQ">
+<div class="book">
<div class="titlepage">
<div>
<div><h1 class="title">
<a name="FAQ"></a>Valgrind FAQ</h1></div>
-<div><p class="releaseinfo">Release 3.8.0 10 August 2012</p></div>
-<div><p class="copyright">Copyright © 2000-2012 <a class="ulink" href="http://www.valgrind.org/info/developers.html" target="_top">Valgrind Developers</a></p></div>
-<div><div class="legalnotice" title="Legal Notice">
-<a name="id408979"></a><p>Email: <a class="ulink" href="mailto:val...@va..." target="_top">val...@va...</a></p>
+<div><p class="releaseinfo">Release 3.9.0 31 October 2013</p></div>
+<div><p class="copyright">Copyright © 2000-2013 <a class="ulink" href="http://www.valgrind.org/info/developers.html" target="_top">Valgrind Developers</a></p></div>
+<div><div class="legalnotice">
+<a name="idp9077856"></a><p>Email: <a class="ulink" href="mailto:val...@va..." target="_top">val...@va...</a></p>
</div></div>
</div>
<hr>
</div>
<div class="toc">
<p><b>Table of Contents</b></p>
-<dl><dt><span class="article"><a href="faq.html">Valgrind Frequently Asked Questions</a></span></dt></dl>
+<dl class="toc"><dt><span class="article"><a href="faq.html">Valgrind Frequently Asked Questions</a></span></dt></dl>
</div>
</div>
<div>
Modified: trunk/docs/manual/QuickStart.html
==============================================================================
--- trunk/docs/manual/QuickStart.html (original)
+++ trunk/docs/manual/QuickStart.html Fri Nov 1 11:04:53 2013
@@ -2,8 +2,8 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>The Valgrind Quick Start Guide</title>
-<link rel="stylesheet" href="vg_basic.css" type="text/css">
-<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
+<link rel="stylesheet" type="text/css" href="vg_basic.css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="index.html" title="Valgrind Documentation">
<link rel="up" href="index.html" title="Valgrind Documentation">
<link rel="prev" href="index.html" title="Valgrind Documentation">
@@ -17,22 +17,22 @@
<th align="center" valign="middle">Valgrind Documentation</th>
<td width="22px" align="center" valign="middle"><a accesskey="n" href="quick-start.html"><img src="images/next.png" width="18" height="21" border="0" alt="Next"></a></td>
</tr></table></div>
-<div class="book" title="The Valgrind Quick Start Guide">
+<div class="book">
<div class="titlepage">
<div>
<div><h1 class="title">
<a name="QuickStart"></a>The Valgrind Quick Start Guide</h1></div>
-<div><p class="releaseinfo">Release 3.8.0 10 August 2012</p></div>
-<div><p class="copyright">Copyright © 2000-2012 <a class="ulink" href="http://www.valgrind.org/info/developers.html" target="_top">Valgrind Developers</a></p></div>
-<div><div class="legalnotice" title="Legal Notice">
-<a name="id372819"></a><p>Email: <a class="ulink" href="mailto:val...@va..." target="_top">val...@va...</a></p>
+<div><p class="releaseinfo">Release 3.9.0 31 October 2013</p></div>
+<div><p class="copyright">Copyright © 2000-2013 <a class="ulink" href="http://www.valgrind.org/info/developers.html" target="_top">Valgrind Developers</a></p></div>
+<div><div class="legalnotice">
+<a name="idp7082176"></a><p>Email: <a class="ulink" href="mailto:val...@va..." target="_top">val...@va...</a></p>
</div></div>
</div>
<hr>
</div>
<div class="toc">
<p><b>Table of Contents</b></p>
-<dl>
+<dl class="toc">
<dt><span class="article"><a href="quick-start.html">The Valgrind Quick Start Guide</a></span></dt>
<dd><dl>
<dt><span class="sect1"><a href="quick-start.html#quick-start.intro">1. Introduction</a></span></dt>
Modified: trunk/docs/manual/bbv-manual.html
==============================================================================
--- trunk/docs/manual/bbv-manual.html (original)
+++ trunk/docs/manual/bbv-manual.html Fri Nov 1 11:04:53 2013
@@ -2,8 +2,8 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>12. BBV: an experimental basic block vector generation tool</title>
-<link rel="stylesheet" href="vg_basic.css" type="text/css">
-<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
+<link rel="stylesheet" type="text/css" href="vg_basic.css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="index.html" title="Valgrind Documentation">
<link rel="up" href="manual.html" title="Valgrind User Manual">
<link rel="prev" href="sg-manual.html" title="11. SGCheck: an experimental stack and global array overrun detector">
@@ -17,12 +17,12 @@
<th align="center" valign="middle">Valgrind User Manual</th>
<td width="22px" align="center" valign="middle"><a accesskey="n" href="lk-manual.html"><img src="images/next.png" width="18" height="21" border="0" alt="Next"></a></td>
</tr></table></div>
-<div class="chapter" title="12. BBV: an experimental basic block vector generation tool">
-<div class="titlepage"><div><div><h2 class="title">
-<a name="bbv-manual"></a>12. BBV: an experimental basic block vector generation tool</h2></div></div></div>
+<div class="chapter">
+<div class="titlepage"><div><div><h1 class="title">
+<a name="bbv-manual"></a>12. BBV: an experimental basic block vector generation tool</h1></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
-<dl>
+<dl class="toc">
<dt><span class="sect1"><a href="bbv-manual.html#bbv-manual.overview">12.1. Overview</a></span></dt>
<dt><span class="sect1"><a href="bbv-manual.html#bbv-manual.quickstart">12.2. Using Basic Block Vectors to create SimPoints</a></span></dt>
<dt><span class="sect1"><a href="bbv-manual.html#bbv-manual.usage">12.3. BBV Command-line Options</a></span></dt>
@@ -36,7 +36,7 @@
<p>To use this tool, you must specify
<code class="option">--tool=exp-bbv</code> on the Valgrind
command line.</p>
-<div class="sect1" title="12.1. Overview">
+<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="bbv-manual.overview"></a>12.1. Overview</h2></div></div></div>
<p>
@@ -74,7 +74,7 @@
B. Calder.
</p>
</div>
-<div class="sect1" title="12.2. Using Basic Block Vectors to create SimPoints">
+<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="bbv-manual.quickstart"></a>12.2. Using Basic Block Vectors to create SimPoints</h2></div></div></div>
<p>
@@ -131,12 +131,12 @@
calculate your results.
</p>
</div>
-<div class="sect1" title="12.3. BBV Command-line Options">
+<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="bbv-manual.usage"></a>12.3. BBV Command-line Options</h2></div></div></div>
<p> BBV-specific command-line options are:</p>
<div class="variablelist">
-<a name="bbv.opts.list"></a><dl>
+<a name="bbv.opts.list"></a><dl class="variablelist">
<dt>
<a name="opt.bb-out-file"></a><span class="term">
<code class="option">--bb-out-file=<name> [default: bb.out.%p] </code>
@@ -198,7 +198,7 @@
</dl>
</div>
</div>
-<div class="sect1" title="12.4. Basic Block Vector File Format">
+<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="bbv-manual.fileformat"></a>12.4. Basic Block Vector File Format</h2></div></div></div>
<p>
@@ -239,7 +239,7 @@
not generate these, as the SimPoint utility ignores them.
</p>
</div>
-<div class="sect1" title="12.5. Implementation">
+<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="bbv-manual.implementation"></a>12.5. Implementation</h2></div></div></div>
<p>
@@ -308,7 +308,7 @@
counters on Pentium 4 systems.
</p>
</div>
-<div class="sect1" title="12.6. Threaded Executable Support">
+<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="bbv-manual.threadsupport"></a>12.6. Threaded Executable Support</h2></div></div></div>
<p>
@@ -326,7 +326,7 @@
BBV.
</p>
</div>
-<div class="sect1" title="12.7. Validation">
+<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="bbv-manual.validation"></a>12.7. Validation</h2></div></div></div>
<p>
@@ -338,7 +338,7 @@
V.M. Weaver and S.A. McKee.
</p>
</div>
-<div class="sect1" title="12.8. Performance">
+<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="bbv-manual.performance"></a>12.8. Performance</h2></div></div></div>
<p>
Modified: trunk/docs/manual/cg-manual.html
==============================================================================
--- trunk/docs/manual/cg-manual.html (original)
+++ trunk/docs/manual/cg-manual.html Fri Nov 1 11:04:53 2013
@@ -2,8 +2,8 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>5. Cachegrind: a cache and branch-prediction profiler</title>
-<link rel="stylesheet" href="vg_basic.css" type="text/css">
-<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
+<link rel="stylesheet" type="text/css" href="vg_basic.css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="index.html" title="Valgrind Documentation">
<link rel="up" href="manual.html" title="Valgrind User Manual">
<link rel="prev" href="mc-manual.html" title="4. Memcheck: a memory error detector">
@@ -17,12 +17,12 @@
<th align="center" valign="middle">Valgrind User Manual</th>
<td width="22px" align="center" valign="middle"><a accesskey="n" href="cl-manual.html"><img src="images/next.png" width="18" height="21" border="0" alt="Next"></a></td>
</tr></table></div>
-<div class="chapter" title="5. Cachegrind: a cache and branch-prediction profiler">
-<div class="titlepage"><div><div><h2 class="title">
-<a name="cg-manual"></a>5. Cachegrind: a cache and branch-prediction profiler</h2></div></div></div>
+<div class="chapter">
+<div class="titlepage"><div><div><h1 class="title">
+<a name="cg-manual"></a>5. Cachegrind: a cache and branch-prediction profiler</h1></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
-<dl>
+<dl class="toc">
<dt><span class="sect1"><a href="cg-manual.html#cg-manual.overview">5.1. Overview</a></span></dt>
<dt><span class="sect1"><a href="cg-manual.html#cg-manual.profile">5.2. Using Cachegrind, cg_annotate and cg_merge</a></span></dt>
<dd><dl>
@@ -41,25 +41,26 @@
</dl></dd>
<dt><span class="sect1"><a href="cg-manual.html#cg-manual.cgopts">5.3. Cachegrind Command-line Options</a></span></dt>
<dt><span class="sect1"><a href="cg-manual.html#cg-manual.annopts">5.4. cg_annotate Command-line Options</a></span></dt>
-<dt><span class="sect1"><a href="cg-manual.html#cg-manual.diffopts">5.5. cg_diff Command-line Options</a></span></dt>
-<dt><span class="sect1"><a href="cg-manual.html#cg-manual.acting-on">5.6. Acting on Cachegrind's Information</a></span></dt>
-<dt><span class="sect1"><a href="cg-manual.html#cg-manual.sim-details">5.7. Simulation Details</a></span></dt>
+<dt><span class="sect1"><a href="cg-manual.html#cg-manual.mergeopts">5.5. cg_merge Command-line Options</a></span></dt>
+<dt><span class="sect1"><a href="cg-manual.html#cg-manual.diffopts">5.6. cg_diff Command-line Options</a></span></dt>
+<dt><span class="sect1"><a href="cg-manual.html#cg-manual.acting-on">5.7. Acting on Cachegrind's Information</a></span></dt>
+<dt><span class="sect1"><a href="cg-manual.html#cg-manual.sim-details">5.8. Simulation Details</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="cg-manual.html#cache-sim">5.7.1. Cache Simulation Specifics</a></span></dt>
-<dt><span class="sect2"><a href="cg-manual.html#branch-sim">5.7.2. Branch Simulation Specifics</a></span></dt>
-<dt><span class="sect2"><a href="cg-manual.html#cg-manual.annopts.accuracy">5.7.3. Accuracy</a></span></dt>
+<dt><span class="sect2"><a href="cg-manual.html#cache-sim">5.8.1. Cache Simulation Specifics</a></span></dt>
+<dt><span class="sect2"><a href="cg-manual.html#branch-sim">5.8.2. Branch Simulation Specifics</a></span></dt>
+<dt><span class="sect2"><a href="cg-manual.html#cg-manual.annopts.accuracy">5.8.3. Accuracy</a></span></dt>
</dl></dd>
-<dt><span class="sect1"><a href="cg-manual.html#cg-manual.impl-details">5.8. Implementation Details</a></span></dt>
+<dt><span class="sect1"><a href="cg-manual.html#cg-manual.impl-details">5.9. Implementation Details</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="cg-manual.html#cg-manual.impl-details.how-cg-works">5.8.1. How Cachegrind Works</a></span></dt>
-<dt><span class="sect2"><a href="cg-manual.html#cg-manual.impl-details.file-format">5.8.2. Cachegrind Output File Format</a></span></dt>
+<dt><span class="sect2"><a href="cg-manual.html#cg-manual.impl-details.how-cg-works">5.9.1. How Cachegrind Works</a></span></dt>
+<dt><span class="sect2"><a href="cg-manual.html#cg-manual.impl-details.file-format">5.9.2. Cachegrind Output File Format</a></span></dt>
</dl></dd>
</dl>
</div>
<p>To use this tool, you must specify
<code class="option">--tool=cachegrind</code> on the
Valgrind command line.</p>
-<div class="sect1" title="5.1. Overview">
+<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="cg-manual.overview"></a>5.1. Overview</h2></div></div></div>
<p>Cachegrind simulates how your program interacts with a machine's cache
@@ -67,10 +68,10 @@
independent first-level instruction and data caches (I1 and D1), backed by a
unified second-level cache (L2). This exactly matches the configuration of
many modern machines.</p>
-<p>However, some modern machines have three levels of cache. For these
+<p>However, some modern machines have three or four levels of cache. For these
machines (in the cases where Cachegrind can auto-detect the cache
-configuration) Cachegrind simulates the first-level and third-level caches.
-The reason for this choice is that the L3 cache has the most influence on
+configuration) Cachegrind simulates the first-level and last-level caches.
+The reason for this choice is that the last-level cache has the most influence on
runtime, as it masks accesses to main memory. Furthermore, the L1 caches
often have low associativity, so simulating them can detect cases where the
code interacts badly with this cache (eg. traversing a matrix column-wise
@@ -80,7 +81,7 @@
<p>
Cachegrind gathers the following statistics (abbreviations used for each statistic
is given in parentheses):</p>
-<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>I cache reads (<code class="computeroutput">Ir</code>,
which equals the number of instructions executed),
I1 cache read misses (<code class="computeroutput">I1mr</code>) and
@@ -123,7 +124,7 @@
instruction executed, you can find out how many instructions are
executed per line, which can be useful for traditional profiling.</p>
</div>
-<div class="sect1" title="5.2. Using Cachegrind, cg_annotate and cg_merge">
+<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="cg-manual.profile"></a>5.2. Using Cachegrind, cg_annotate and cg_merge</h2></div></div></div>
<p>First off, as for normal Valgrind use, you probably want to
@@ -137,9 +138,9 @@
information. As an optional intermediate step, you can use cg_merge to sum
together the outputs of multiple Cachegrind runs into a single file which
you then use as the input for cg_annotate. Alternatively, you can use
-cg_diff to difference the outputs of two Cachegrind runs into a signel file
+cg_diff to difference the outputs of two Cachegrind runs into a single file
which you then use as the input for cg_annotate.</p>
-<div class="sect2" title="5.2.1. Running Cachegrind">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cg-manual.running-cachegrind"></a>5.2.1. Running Cachegrind</h3></div></div></div>
<p>To run Cachegrind on a program <code class="filename">prog</code>, run:</p>
@@ -184,7 +185,7 @@
<p>Branch prediction statistics are not collected by default.
To do so, add the option <code class="option">--branch-sim=yes</code>.</p>
</div>
-<div class="sect2" title="5.2.2. Output File">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cg-manual.outputfile"></a>5.2.2. Output File</h3></div></div></div>
<p>As well as printing summary information, Cachegrind also writes
@@ -203,7 +204,7 @@
<p>The output file can be big, many megabytes for large applications
built with full debugging information.</p>
</div>
-<div class="sect2" title="5.2.3. Running cg_annotate">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cg-manual.running-cg_annotate"></a>5.2.3. Running cg_annotate</h3></div></div></div>
<p>Before using cg_annotate,
@@ -213,7 +214,7 @@
<pre class="screen">cg_annotate <filename></pre>
<p>on a Cachegrind output file.</p>
</div>
-<div class="sect2" title="5.2.4. The Output Preamble">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cg-manual.the-output-preamble"></a>5.2.4. The Output Preamble</h3></div></div></div>
<p>The first part of the output looks like this:</p>
@@ -231,7 +232,7 @@
Auto-annotation: off
</pre>
<p>This is a summary of the annotation options:</p>
-<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>I1 cache, D1 cache, LL cache: cache configuration. So
you know the configuration with which these results were
obtained.</p></li>
@@ -273,7 +274,7 @@
option. In this case no.</p></li>
</ul></div>
</div>
-<div class="sect2" title="5.2.5. The Global and Function-level Counts">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cg-manual.the-global"></a>5.2.5. The Global and Function-level Counts</h3></div></div></div>
<p>Then follows summary statistics for the whole
@@ -316,7 +317,7 @@
that event (e.g. the third row shows that
<code class="computeroutput">strcmp()</code> contains no
instructions that write to memory). The name
-<code class="computeroutput">???</code> is used if the the file name
+<code class="computeroutput">???</code> is used if the file name
and/or function name could not be determined from debugging
information. If most of the entries have the form
<code class="computeroutput">???:???</code> the program probably
@@ -325,7 +326,7 @@
the profiled program (e.g. <code class="filename">concord.c</code>)
and from libraries (e.g. <code class="filename">getc.c</code>)</p>
</div>
-<div class="sect2" title="5.2.6. Line-by-line Counts">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cg-manual.line-by-line"></a>5.2.6. Line-by-line Counts</h3></div></div></div>
<p>There are two ways to annotate source files -- by specifying them
@@ -420,7 +421,7 @@
e.g. 30 seconds or more. Also beware that auto-annotation can
produce a lot of output if your program is large!</p>
</div>
-<div class="sect2" title="5.2.7. Annotating Assembly Code Programs">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cg-manual.assembler"></a>5.2.7. Annotating Assembly Code Programs</h3></div></div></div>
<p>Valgrind can annotate assembly code programs too, or annotate
@@ -435,7 +436,7 @@
<code class="option">-g</code> to achieve this. You can then profile and annotate the
assembly code source files in the same way as C/C++ source files.</p>
</div>
-<div class="sect2" title="5.2.8. Forking Programs">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="ms-manual.forkingprograms"></a>5.2.8. Forking Programs</h3></div></div></div>
<p>If your program forks, the child will inherit all the profiling data that
@@ -446,12 +447,12 @@
output file, which will almost certainly make it unreadable by
cg_annotate.</p>
</div>
-<div class="sect2" title="5.2.9. cg_annotate Warnings">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cg-manual.annopts.warnings"></a>5.2.9. cg_annotate Warnings</h3></div></div></div>
<p>There are a couple of situations in which
cg_annotate issues warnings.</p>
-<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>If a source file is more recent than the
<code class="filename">cachegrind.out.<pid></code> file.
This is because the information in
@@ -468,11 +469,11 @@
important.</p></li>
</ul></div>
</div>
-<div class="sect2" title="5.2.10. Unusual Annotation Cases">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cg-manual.annopts.things-to-watch-out-for"></a>5.2.10. Unusual Annotation Cases</h3></div></div></div>
<p>Some odd things that can occur during annotation:</p>
-<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>If annotating at the assembler level, you might see
something like this:</p>
@@ -539,7 +540,7 @@
<p>This list looks long, but these cases should be fairly
rare.</p>
</div>
-<div class="sect2" title="5.2.11. Merging Profiles with cg_merge">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cg-manual.cg_merge"></a>5.2.11. Merging Profiles with cg_merge</h3></div></div></div>
<p>
@@ -585,7 +586,7 @@
attempt to print a helpful error message if any of the input files
fail these checks.</p>
</div>
-<div class="sect2" title="5.2.12. Differencing Profiles with cg_diff">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cg-manual.cg_diff"></a>5.2.12. Differencing Profiles with cg_diff</h3></div></div></div>
<p>
@@ -661,12 +662,12 @@
<code class="option">--mod-filename</code>.</p>
</div>
</div>
-<div class="sect1" title="5.3. Cachegrind Command-line Options">
+<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="cg-manual.cgopts"></a>5.3. Cachegrind Command-line Options</h2></div></div></div>
<p>Cachegrind-specific options are:</p>
<div class="variablelist">
-<a name="cg.opts.list"></a><dl>
+<a name="cg.opts.list"></a><dl class="variablelist">
<dt>
<a name="opt.I1"></a><span class="term">
<code class="option">--I1=<size>,<associativity>,<line size> </code>
@@ -724,11 +725,11 @@
</dl>
</div>
</div>
-<div class="sect1" title="5.4. cg_annotate Command-line Options">
+<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="cg-manual.annopts"></a>5.4. cg_annotate Command-line Options</h2></div></div></div>
<div class="variablelist">
-<a name="cg_annotate.opts.list"></a><dl>
+<a name="cg_annotate.opts.list"></a><dl class="variablelist">
<dt><span class="term">
<code class="option">-h --help </code>
</span></dt>
@@ -793,11 +794,25 @@
</dl>
</div>
</div>
-<div class="sect1" title="5.5. cg_diff Command-line Options">
+<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="cg-manual.diffopts"></a>5.5. cg_diff Command-line Options</h2></div></div></div>
+<a name="cg-manual.mergeopts"></a>5.5. cg_merge Command-line Options</h2></div></div></div>
<div class="variablelist">
-<a name="cg_diff.opts.list"></a><dl>
+<a name="cg_merge.opts.list"></a><dl class="variablelist">
+<dt><span class="term">
+ <code class="option">-o outfile</code>
+ </span></dt>
+<dd><p>Write the profile data to <code class="computeroutput">outfile</code>
+ rather than to standard output.
+ </p></dd>
+</dl>
+</div>
+</div>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="cg-manual.diffopts"></a>5.6. cg_diff Command-line Options</h2></div></div></div>
+<div class="variablelist">
+<a name="cg_diff.opts.list"></a><dl class="variablelist">
<dt><span class="term">
<code class="option">-h --help </code>
</span></dt>
@@ -822,9 +837,9 @@
</dl>
</div>
</div>
-<div class="sect1" title="5.6. Acting on Cachegrind's Information">
+<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="cg-manual.acting-on"></a>5.6. Acting on Cachegrind's Information</h2></div></div></div>
+<a name="cg-manual.acting-on"></a>5.7. Acting on Cachegrind's Information</h2></div></div></div>
<p>
Cachegrind gives you lots of information, but acting on that information
isn't always easy. Here are some rules of thumb that we have found to be
@@ -900,19 +915,19 @@
yourself. But at least you have the information!
</p>
</div>
-<div class="sect1" title="5.7. Simulation Details">
+<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="cg-manual.sim-details"></a>5.7. Simulation Details</h2></div></div></div>
+<a name="cg-manual.sim-details"></a>5.8. Simulation Details</h2></div></div></div>
<p>
This section talks about details you don't need to know about in order to
use Cachegrind, but may be of interest to some people.
</p>
-<div class="sect2" title="5.7.1. Cache Simulation Specifics">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="cache-sim"></a>5.7.1. Cache Simulation Specifics</h3></div></div></div>
+<a name="cache-sim"></a>5.8.1. Cache Simulation Specifics</h3></div></div></div>
<p>Specific characteristics of the cache simulation are as
follows:</p>
-<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>Write-allocate: when a write miss occurs, the block
written to is brought into the D1 cache. Most modern caches
have this property.</p></li>
@@ -920,7 +935,7 @@
<p>Bit-selection hash function: the set of line(s) in the cache
to which a memory block maps is chosen by the middle bits
M--(M+N-1) of the byte address, where:</p>
-<div class="itemizedlist"><ul class="itemizedlist" type="circle">
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; ">
<li class="listitem"><p>line size = 2^M bytes</p></li>
<li class="listitem"><p>(cache size / line size / associativity) = 2^N bytes</p></li>
</ul></div>
@@ -956,11 +971,11 @@
<code class="option">--D1</code> and
<code class="option">--LL</code> options.</p>
<p>Other noteworthy behaviour:</p>
-<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>References that straddle two cache lines are treated as
follows:</p>
-<div class="itemizedlist"><ul class="itemizedlist" type="circle">
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; ">
<li class="listitem"><p>If both blocks hit --> counted as one hit</p></li>
<li class="listitem"><p>If one block hits, the other misses --> counted
as one miss.</p></li>
@@ -987,9 +1002,9 @@
<code class="computeroutput">cg_sim.c</code>. We'd be
interested to hear from anyone who does.</p>
</div>
-<div class="sect2" title="5.7.2. Branch Simulation Specifics">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="branch-sim"></a>5.7.2. Branch Simulation Specifics</h3></div></div></div>
+<a name="branch-sim"></a>5.8.2. Branch Simulation Specifics</h3></div></div></div>
<p>Cachegrind simulates branch predictors intended to be
typical of mainstream desktop/server processors of around 2004.</p>
<p>Conditional branches are predicted using an array of 16384 2-bit
@@ -1021,12 +1036,12 @@
Architecture: A Quantitative Approach", 4th edition (2007), Section
2.3 (pages 80-89) for background on modern branch predictors.</p>
</div>
-<div class="sect2" title="5.7.3. Accuracy">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="cg-manual.annopts.accuracy"></a>5.7.3. Accuracy</h3></div></div></div>
+<a name="cg-manual.annopts.accuracy"></a>5.8.3. Accuracy</h3></div></div></div>
<p>Valgrind's cache profiling has a number of
shortcomings:</p>
-<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>It doesn't account for kernel activity -- the effect of system
calls on the cache and branch predictor contents is ignored.</p></li>
<li class="listitem"><p>It doesn't account for other process activity.
@@ -1059,7 +1074,7 @@
be rare so hopefully this won't affect accuracy much.</p></li>
</ul></div>
<p>Another thing worth noting is that results are very sensitive.
-Changing the size of the the executable being profiled, or the sizes
+Changing the size of the executable being profiled, or the sizes
of any of the shared libraries it uses, or even the length of their
file names, can perturb the results. Variations will be small, but
don't expect perfectly repeatable results if your program changes at
@@ -1072,24 +1087,24 @@
be super-accurate, they should be close enough to be useful.</p>
</div>
</div>
-<div class="sect1" title="5.8. Implementation Details">
+<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="cg-manual.impl-details"></a>5.8. Implementation Details</h2></div></div></div>
+<a name="cg-manual.impl-details"></a>5.9. Implementation Details</h2></div></div></div>
<p>
This section talks about details you don't need to know about in order to
use Cachegrind, but may be of interest to some people.
</p>
-<div class="sect2" title="5.8.1. How Cachegrind Works">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="cg-manual.impl-details.how-cg-works"></a>5.8.1. How Cachegrind Works</h3></div></div></div>
+<a name="cg-manual.impl-details.how-cg-works"></a>5.9.1. How Cachegrind Works</h3></div></div></div>
<p>The best reference for understanding how Cachegrind works is chapter 3 of
"Dynamic Binary Analysis and Instrumentation", by Nicholas Nethercote. It
is available on the <a class="ulink" href="http://www.valgrind.org/docs/pubs.html" target="_top">Valgrind publications
page</a>.</p>
</div>
-<div class="sect2" title="5.8.2. Cachegrind Output File Format">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="cg-manual.impl-details.file-format"></a>5.8.2. Cachegrind Output File Format</h3></div></div></div>
+<a name="cg-manual.impl-details.file-format"></a>5.9.2. Cachegrind Output File Format</h3></div></div></div>
<p>The file format is fairly straightforward, basically giving the
cost centre for every line, grouped by files and
functions. It's also totally generic and self-describing, in the sense that
@@ -1111,7 +1126,7 @@
summary_line ::= "summary:" ws? (count ws)+
count ::= num | "."</pre>
<p>Where:</p>
-<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p><code class="computeroutput">non_nl_string</code> is any
string not containing a newline.</p></li>
<li class="listitem"><p><code class="computeroutput">cmd</code> is a string holding the
Modified: trunk/docs/manual/cl-format.html
==============================================================================
--- trunk/docs/manual/cl-format.html (original)
+++ trunk/docs/manual/cl-format.html Fri Nov 1 11:04:53 2013
@@ -2,8 +2,8 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>3. Callgrind Format Specification</title>
-<link rel="stylesheet" href="vg_basic.css" type="text/css">
-<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
+<link rel="stylesheet" type="text/css" href="vg_basic.css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="index.html" title="Valgrind Documentation">
<link rel="up" href="tech-docs.html" title="Valgrind Technical Documentation">
<link rel="prev" href="manual-writing-tools.html" title="2. Writing a New Valgrind Tool">
@@ -17,12 +17,12 @@
<th align="center" valign="middle">Valgrind Technical Documentation</th>
<td width="22px" align="center" valign="middle"><a accesskey="n" href="dist.html"><img src="images/next.png" width="18" height="21" border="0" alt="Next"></a></td>
</tr></table></div>
-<div class="chapter" title="3. Callgrind Format Specification">
-<div class="titlepage"><div><div><h2 class="title">
-<a name="cl-format"></a>3. Callgrind Format Specification</h2></div></div></div>
+<div class="chapter">
+<div class="titlepage"><div><div><h1 class="title">
+<a name="cl-format"></a>3. Callgrind Format Specification</h1></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
-<dl>
+<dl class="toc">
<dt><span class="sect1"><a href="cl-format.html#cl-format.overview">3.1. Overview</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="cl-format.html#cl-format.overview.basics">3.1.1. Basic Structure</a></span></dt>
@@ -47,7 +47,7 @@
<p>The format description is meant for the user to be able to understand the
file contents; but more important, it is given for authors of measurement or
visualization tools to be able to write and read this format.</p>
-<div class="sect1" title="3.1. Overview">
+<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="cl-format.overview"></a>3.1. Overview</h2></div></div></div>
<p>The profile data format is ASCII based.
@@ -56,11 +56,13 @@
be read by callgrind_annotate and KCachegrind.</p>
<p>This chapter gives on overview of format features and examples.
For detailed syntax, look at the format reference.</p>
-<div class="sect2" title="3.1.1. Basic Structure">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cl-format.overview.basics"></a>3.1.1. Basic Structure</h3></div></div></div>
<p>Each file has a header part of an arbitrary number of lines of the
-format "key: value". The lines with key "positions" and "events" define
+format "key: value". After the header, lines specifying profile costs
+follow. Everywhere, comments on own lines starting with '#' are allowed.
+The header lines with keys "positions" and "events" define
the meaning of cost lines in the second part of the file: the value of
"positions" is a list of subpositions, and the value of "events" is a list
of event type names. Cost lines consist of subpositions followed by 64-bit
@@ -73,7 +75,7 @@
function name or "fl" for a file name. Cost lines are always related to
the function/file specifications given directly before.</p>
</div>
-<div class="sect2" title="3.1.2. Simple Example">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cl-format.overview.example1"></a>3.1.2. Simple Example</h3></div></div></div>
<p>The event names in the following example are quite arbitrary, and are not
@@ -112,15 +114,15 @@
<code class="function">main</code> actually was
called: profile data only contains sums.</p>
</div>
-<div class="sect2" title="3.1.3. Associations">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cl-format.overview.associations"></a>3.1.3. Associations</h3></div></div></div>
<p>The most important extension to the original format of Cachegrind is the
ability to specify call relationship among functions. More generally, you
specify associations among positions. For this, the second part of the
file also can contain association specifications. These look similar to
-position specifications, but consist of 2 lines. For calls, the format
-looks like
+position specifications, but consist of two lines. For calls, the format
+looks like
</p>
<pre class="screen">
calls=(Call Count) (Destination position)
@@ -129,13 +131,15 @@
<p>The destination only specifies subpositions like line number. Therefore,
to be able to specify a call to another function in another source file, you
have to precede the above lines with a "cfn=" specification for the name of the
-called function, and a "cfl=" specification if the function is in another
-source file. The 2nd line looks like a regular cost line with the difference
+called function, and optionally a "cfi=" specification if the function is in
+another source file ("cfl=" is an alternative specification for "cfi=" because
+of historical reasons, and both should be supported by format readers).
+The second line looks like a regular cost line with the difference
that inclusive cost spent inside of the function call has to be specified.</p>
<p>Other associations are for example (conditional) jumps. See the
reference below for details.</p>
</div>
-<div class="sect2" title="3.1.4. Extended Example">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cl-format.overview.example2"></a>3.1.4. Extended Example</h3></div></div></div>
<p>The following example shows 3 functions, <code class="function">main</code>,
@@ -152,14 +156,14 @@
cfn=func1
calls=1 50
16 400
-cfl=file2.c
+cfi=file2.c
cfn=func2
calls=3 20
16 400
fn=func1
51 100
-cfl=file2.c
+cfi=file2.c
cfn=func2
calls=2 20
51 300
@@ -174,12 +178,12 @@
and 400 as sum for the three calls to <code class="function">func2</code>.</p>
<p>Function <code class="function">func1</code> is located in
<code class="filename">file1.c</code>, the same as <code class="function">main</code>.
-Therefore, a "cfl=" specification for the call to <code class="function">func1</code>
+Therefore, a "cfi=" specification for the call to <code class="function">func1</code>
is not needed. The function <code class="function">func1</code> only consists of code
at line 51 of <code class="filename">file1.c</code>, where <code class="function">func2</code>
is called.</p>
</div>
-<div class="sect2" title="3.1.5. Name Compression">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cl-format.overview.compression1"></a>3.1.5. Name Compression</h3></div></div></div>
<p>With the introduction of association specifications like calls it is
@@ -203,14 +207,14 @@
cfn=(2) func1
calls=1 50
16 400
-cfl=(2) file2.c
+cfi=(2) file2.c
cfn=(3) func2
calls=3 20
16 400
fn=(2)
51 100
-cfl=(2)
+cfi=(2)
cfn=(3)
calls=2 20
51 300
@@ -239,7 +243,7 @@
16 20
...</pre>
</div>
-<div class="sect2" title="3.1.6. Subposition Compression">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cl-format.overview.compression2"></a>3.1.6. Subposition Compression</h3></div></div></div>
<p>If a Callgrind data file should hold costs for each assembler instruction
@@ -281,20 +285,20 @@
be corrected to correspond to addresses found in the original binary. I.e. for
relocatable shared objects, often a load offset has to be subtracted.</p>
</div>
-<div class="sect2" title="3.1.7. Miscellaneous">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cl-format.overview.misc"></a>3.1.7. Miscellaneous</h3></div></div></div>
-<div class="sect3" title="3.1.7.1. Cost Summary Information">
+<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="cl-format.overview.misc.summary"></a>3.1.7.1. Cost Summary Information</h4></div></div></div>
<p>For the visualization to be able to show cost percentage, a sum of the
cost of the full run has to be known. Usually, it is assumed that this is the
sum of all cost lines in a file. But sometimes, this is not correct. Thus, you
can specify a "summary:" line in the header giving the full cost for the
-profile run. This has another effect: a import filter can show a progress bar
-while loading a large data file if he knows to cost sum in advance.</p>
+profile run. An import filter may use this to show a progress bar
+while loading a large data file.</p>
</div>
-<div class="sect3" title="3.1.7.2. Long Names for Event Types and inherited Types">
+<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="cl-format.overview.misc.events"></a>3.1.7.2. Long Names for Event Types and inherited Types</h4></div></div></div>
<p>Event types for cost lines are specified in the "events:" line with an
@@ -316,10 +320,10 @@
</div>
</div>
</div>
-<div class="sect1" title="3.2. Reference">
+<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="cl-format.reference"></a>3.2. Reference</h2></div></div></div>
-<div class="sect2" title="3.2.1. Grammar">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cl-format.reference.grammar"></a>3.2.1. Grammar</h3></div></div></div>
<p>
@@ -402,7 +406,7 @@
<pre class="screen">CostPosition := "ob" | "fl" | "fi" | "fe" | "fn"</pre>
<p>
</p>
-<pre class="screen">CalledPosition := " "cob" | "cfl" | "cfn"</pre>
+<pre class="screen">CalledPosition := " "cob" | "cfi" | "cfl" | "cfn"</pre>
<p>
</p>
<pre class="screen">PositionName := ( "(" Number ")" )? (Space* NoNewLineChar* )?</pre>
@@ -446,32 +450,32 @@
<p>
</p>
</div>
-<div class="sect2" title="3.2.2. Description of Header Lines">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cl-format.reference.header"></a>3.2.2. Description of Header Lines</h3></div></div></div>
<p>The header has an arbitrary number of lines of the format
"key: value". Possible <span class="emphasis"><em>key</em></span> values for the header are:</p>
-<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><code class="computeroutput">version: number</code> [Callgrind]</p>
<p>This is used to distinguish future profile data formats. A
major version of 0 or 1 is supposed to be upwards compatible with
Cachegrind's format. It is optional; if not appearing, version 1
- is supposed. Otherwise, this has to be the first header line.</p>
+ is assumed. Otherwise, this has to be the first header line.</p>
</li>
<li class="listitem">
<p><code class="computeroutput">pid: process id</code> [Callgrind]</p>
-<p>This specifies the process ID of the supervised application
+<p>Optional. This specifies the process ID of the supervised application
for which this profile was generated.</p>
</li>
<li class="listitem">
<p><code class="computeroutput">cmd: program name + args</code> [Cachegrind]</p>
-<p>This specifies the full command line of the supervised
+<p>Optional. This specifies the full command line of the supervised
application for which this profile was generated.</p>
</li>
<li class="listitem">
<p><code class="computeroutput">part: number</code> [Callgrind]</p>
-<p>This specifies a sequentially incremented number for each dump
+<p>Optional. This specifies a sequentially incremented number for each dump
generated, starting at 1.</p>
</li>
<li class="listitem">
@@ -513,7 +517,7 @@
exactly once.</p>
<p>Cost types from original Cachegrind are:
</p>
-<div class="itemizedlist"><ul class="itemizedlist" type="circle">
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; ">
<li class="listitem"><p><span class="command"><strong>Ir</strong></span>: Instruction read access</p></li>
<li class="listitem"><p><span class="command"><strong>I1mr</strong></span>: Instruction Level 1 read cache miss</p></li>
<li class="listitem"><p><span class="command"><strong>ILmr</strong></span>: Instruction last-level read cache miss</p></li>
@@ -524,17 +528,19 @@
</li>
<li class="listitem">
<p><code class="computeroutput">summary: costs</code> [Callgrind]</p>
+<p>Optional. This header line specifies a summary cost, which should be
+ equal or larger than a total over all self costs. It may be larger as
+ the cost lines may not represent all cost of the program run.</p>
+</li>
+<li class="listitem">
<p><code class="computeroutput">totals: costs</code> [Cachegrind]</p>
-<p>The value or the total number of events covered by this trace
- file. Both keys have the same meaning, but the "totals:" line
- happens to be at the end of the file, while "summary:" appears in
- the header. This was added to allow postprocessing tools to know
- in advance to total cost. The two lines always give the same cost
- counts.</p>
+<p>Optional. Should appear at the end of the file (although
+ looking like a header line). Must give the total of all cost lines,
+ to allow for a consistency check.</p>
</li>
</ul></div>
</div>
-<div class="sect2" title="3.2.3. Description of Body Lines">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cl-format.reference.body"></a>3.2.3. Description of Body Lines</h3></div></div></div>
<p>There exist lines
@@ -552,7 +558,7 @@
<span class="emphasis"><em>position</em></span>. Compressed format is always
optional.</p>
<p>Position specifications allowed:</p>
-<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><code class="computeroutput">ob=</code> [Callgrind]</p>
<p>The ELF object where the cost of next cost lines happens.</p>
@@ -575,11 +581,16 @@
<p>The ELF object of the target of the next call cost lines.</p>
</li>
<li class="listitem">
-<p><code class="computeroutput">cfl=</code> [Callgrind]</p>
+<p><code class="computeroutput">cfi=</code> [Callgrind]</p>
<p>The source file including the code of the target of the
next call cost lines.</p>
</li>
<li class="listitem">
+<p><code class="computeroutput">cfl=</code> [Callgrind]</p>
+<p>Alternative spelling for <code class="computeroutput">cfi=</code>
+ specification (because of historical reasons).</p>
+</li>
+<li class="listitem">
<p><code class="computeroutput">cfn=</code> [Callgrind]</p>
<p>The name of the target function of the next call cost
lines.</p>
Modified: trunk/docs/manual/cl-manual.html
==============================================================================
--- trunk/docs/manual/cl-manual.html (original)
+++ trunk/docs/manual/cl-manual.html Fri Nov 1 11:04:53 2013
@@ -2,8 +2,8 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>6. Callgrind: a call-graph generating cache and branch prediction profiler</title>
-<link rel="stylesheet" href="vg_basic.css" type="text/css">
-<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
+<link rel="stylesheet" type="text/css" href="vg_basic.css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="index.html" title="Valgrind Documentation">
<link rel="up" href="manual.html" title="Valgrind User Manual">
<link rel="prev" href="cg-manual.html" title="5. Cachegrind: a cache and branch-prediction profiler">
@@ -17,12 +17,12 @@
<th align="center" valign="middle">Valgrind User Manual</th>
<td width="22px" align="center" valign="middle"><a accesskey="n" href="hg-manual.html"><img src="images/next.png" width="18" height="21" border="0" alt="Next"></a></td>
</tr></table></div>
-<div class="chapter" title="6. Callgrind: a call-graph generating cache and branch prediction profiler">
-<div class="titlepage"><div><div><h2 class="title">
-<a name="cl-manual"></a>6. Callgrind: a call-graph generating cache and branch prediction profiler</h2></div></div></div>
+<div class="chapter">
+<div class="titlepage"><div><div><h1 class="title">
+<a name="cl-manual"></a>6. Callgrind: a call-graph generating cache and branch prediction profiler</h1></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
-<dl>
+<dl class="toc">
<dt><span class="sect1"><a href="cl-manual.html#cl-manual.use">6.1. Overview</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="cl-manual.html#cl-manual.functionality">6.1.1. Functionality</a></span></dt>
@@ -54,7 +54,7 @@
<p>To use this tool, you must specify
<code class="option">--tool=callgrind</code> on the
Valgrind command line.</p>
-<div class="sect1" title="6.1. Overview">
+<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="cl-manual.use"></a>6.1. Overview</h2></div></div></div>
<p>Callgrind is a profiling tool that records the call history among
@@ -69,7 +69,7 @@
<p>The profile data is written out to a file at program
termination. For presentation of the data, and interactive control
of the profiling, two command line tools are provided:</p>
-<div class="variablelist"><dl>
+<div class="variablelist"><dl class="variablelist">
<dt><span class="term"><span class="command"><strong>callgrind_annotate</strong></span></span></dt>
<dd>
<p>This command reads in the profile data, and prints a
@@ -86,7 +86,7 @@
well as the current stack trace, and you can request zeroing of counters
or dumping of profile data.</p></dd>
</dl></div>
-<div class="sect2" title="6.1.1. Functionality">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cl-manual.functionality"></a>6.1.1. Functionality</h3></div></div></div>
<p>Cachegrind collects flat profile data: event counts (data reads,
@@ -126,7 +126,7 @@
call or return instructions in these instruction sets, so Callgrind
has to rely on heuristics to detect calls and returns.</p>
</div>
-<div class="sect2" title="6.1.2. Basic Usage">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cl-manual.basics"></a>6.1.2. Basic Usage</h3></div></div></div>
<p>As with Cachegrind, you probably want to compile with debugging info
@@ -164,7 +164,7 @@
are the ones that are shown.
Important for the additional features of Callgrind are
the following two options:</p>
-<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p><code class="option">--inclusive=yes</code>: Instead of using
exclusive cost of functions as sorting order, use and show
inclusive cost.</p></li>
@@ -220,10 +220,10 @@
<code class="option"><a class="xref" href="cl-manual.html#opt.collect-jumps">--collect-jumps</a>=yes</code>.</p>
</div>
</div>
-<div class="sect1" title="6.2. Advanced Usage">
+<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="cl-manual.usage"></a>6.2. Advanced Usage</h2></div></div></div>
-<div class="sect2" title="6.2.1. Multiple profiling dumps from one program run">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cl-manual.dumps"></a>6.2.1. Multiple profiling dumps from one program run</h3></div></div></div>
<p>Sometimes you are not interested in characteristics of a full
@@ -251,7 +251,7 @@
counters afterwards". To allow for zeroing cost counters without
dumping, there is a second action "zero all cost counters now".
The different methods are:</p>
-<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p><span class="command"><strong>Dump on program termination.</strong></span>
This method is the standard way and doesn't need any special
action on your part.</p></li>
@@ -306,7 +306,7 @@
of the currently running thread. With the other methods, you will get
multiple dumps (one for each thread) on a dump request.</p>
</div>
-<div class="sect2" title="6.2.2. Limiting the range of collected events">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cl-manual.limits"></a>6.2.2. Limiting the range of collected events</h3></div></div></div>
<p>For aggregating events (function enter/leave,
@@ -351,7 +351,7 @@
start event collection a few million instructions after you have enabled
instrumentation.</p>
</div>
-<div class="sect2" title="6.2.3. Counting global bus events">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cl-manual.busevents"></a>6.2.3. Counting global bus events</h3></div></div></div>
<p>For access to shared data among threads in a multithreaded
@@ -368,7 +368,7 @@
To count global bus events, use <code class="option"><a class="xref" href="cl-manual.html#clopt.collect-bus">--collect-bus</a>=yes</code>.
</p>
</div>
-<div class="sect2" title="6.2.4. Avoiding cycles">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cl-manual.cycles"></a>6.2.4. Avoiding cycles</h3></div></div></div>
<p>Informally speaking, a cycle is a group of functions which
@@ -457,7 +457,7 @@
dependency for all functions. Note that doing this will increase
the size of profile data files.</p>
</div>
-<div class="sect2" title="6.2.5. Forking Programs">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cl-manual.forkingprograms"></a>6.2.5. Forking Programs</h3></div></div></div>
<p>If your program forks, the child will inherit all the profiling
@@ -475,7 +475,7 @@
the parent via callgrind_control.</p>
</div>
</div>
-<div class="sect1" title="6.3. Callgrind Command-line Options">
+<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="cl-manual.options"></a>6.3. Callgrind Command-line Options</h2></div></div></div>
<p>
@@ -492,14 +492,14 @@
shell. This feature is important especially for C++, as without wildcard
usage, the function would have to be specified in full extent, including
parameter signature. </p>
-<div class="sect2" title="6.3.1. Dump creation options">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cl-manual.options.creation"></a>6.3.1. Dump creation options</h3></div></div></div>
<p>
These options influence the name and format of the profile data files.
</p>
<div class="variablelist">
-<a name="cl.opts.list.creation"></a><dl>
+<a name="cl.opts.list.creation"></a><dl class="variablelist">
<dt>
<a name="opt.callgrind-out-file"></a><span class="term">
<code class="option">--callgrind-out-file=<file> </code>
@@ -564,7 +564,7 @@
</dl>
</div>
</div>
-<div class="sect2" title="6.3.2. Activity options">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cl-manual.options.activity"></a>6.3.2. Activity options</h3></div></div></div>
<p>
@@ -572,7 +572,7 @@
be executed. For interactive control use callgrind_control.
</p>
<div class="variablelist">
-<a name="cl.opts.list.activity"></a><dl>
+<a name="cl.opts.list.activity"></a><dl class="variablelist">
<dt>
<a name="opt.dump-every-bb"></a><span class="term">
<code class="option">--dump-every-bb=<count> [default: 0, never] </code>
@@ -604,14 +604,14 @@
</dl>
</div>
</div>
-<div class="sect2" title="6.3.3. Data collection options">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cl-manual.options.collection"></a>6.3.3. Data collection options</h3></div></div></div>
<p>
These options specify when events are to be aggregated into event counts.
Also see <a class="xref" href="cl-manual.html#cl-manual.limits" title="6.2.2. Limiting the range of collected events">Limiting range of event collection</a>.</p>
<div class="variablelist">
-<a name="cl.opts.list.collection"></a><dl>
+<a name="cl.opts.list.collection"></a><dl class="variablelist">
<dt>
<a name="opt.instr-atstart"></a><span class="term">
<code class="option">--instr-atstart=<yes|no> [default: yes] </code>
@@ -707,7 +707,7 @@
</dl>
</div>
</div>
-<div class="sect2" title="6.3.4. Cost entity separation options">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cl-manual.options.separation"></a>6.3.4. Cost entity separation options</h3></div></div></div>
<p>
@@ -718,7 +718,7 @@
and whether the thread ID should be considered.
Also see <a class="xref" href="cl-manual.html#cl-manual.cycles" title="6.2.4. Avoiding cycles">Avoiding cycles</a>.</p>
<div class="variablelist">
-<a name="cmd-options.separation"></a><dl>
+<a name="cmd-options.separation"></a><dl class="variablelist">
<dt>
<a name="opt.separate-threads"></a><span class="term">
<code class="option">--separate-threads=<no|yes> [default: no] </code>
@@ -786,11 +786,11 @@
</dl>
</div>
</div>
-<div class="sect2" title="6.3.5. Simulation options">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cl-manual.options.simulation"></a>6.3.5. Simulation options</h3></div></div></div>
<div class="variablelist">
-<a name="cl.opts.list.simulation"></a><dl>
+<a name="cl.opts.list.simulation"></a><dl class="variablelist">
<dt>
<a name="clopt.cache-sim"></a><span class="term">
<code class="option">--cache-sim=<yes|no> [default: no] </code>
@@ -817,11 +817,11 @@
</dl>
</div>
</div>
-<div class="sect2" title="6.3.6. Cache simulation options">
+<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="cl-manual.options.cachesimulation"></a>6...
[truncated message content] |