« back to all changes in this revision
Viewing changes to doc/vg-manual-cg.html
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Hai Zaar
- Date: 2009-05-06 14:48:00 UTC
- Revision ID: james.westby@ubuntu.com-20090506144800-vw617m4d4qa2pam3
Tags: upstream-1.4.0
Import upstream version 1.4.0
- files added:
- doc
- doc/images
- icons
- m4
- tests
- valkyrie
- valkyrie/core
- valkyrie/help
- valkyrie/options
- valkyrie/tool_utils
- valkyrie/tool_views
- vk_logmerge
- vk_logmerge/tests
added
removed
doc/vg-manual-cg.html
1
<html xmlns:cf="http://docbook.sourceforge.net/xmlns/chunkfast/1.0">
2
<head>
3
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4
<title>5.�Cachegrind: a cache profiler</title>
5
<link rel="stylesheet" href="vg_basic.css" type="text/css">
6
<meta name="generator" content="DocBook XSL Stylesheets V1.69.0">
7
<link rel="start" href="index.html" title="Valgrind Documentation">
8
<link rel="up" href="manual.html" title="Valgrind User Manual">
9
<link rel="prev" href="ac-manual.html" title="4.�Addrcheck: a lightweight memory checker">
10
<link rel="next" href="ms-manual.html" title="6.�Massif: a heap profiler">
11
</head>
12
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13
<div><table class="nav" width="100%" cellspacing="3" cellpadding="3" border="0" summary="Navigation header"><tr>
14
<td width="22px" align="center" valign="middle"><a accesskey="p" href="ac-manual.html"><img src="images/prev.png" width="18" height="21" border="0" alt="Prev"></a></td>
15
<td width="25px" align="center" valign="middle"><a accesskey="u" href="manual.html"><img src="images/up.png" width="21" height="18" border="0" alt="Up"></a></td>
16
<td width="31px" align="center" valign="middle"><a accesskey="h" href="index.html"><img src="images/home.png" width="27" height="20" border="0" alt="Up"></a></td>
17
<th align="center" valign="middle">Valgrind User Manual</th>
18
<td width="22px" align="center" valign="middle"><a accesskey="n" href="ms-manual.html"><img src="images/next.png" width="18" height="21" border="0" alt="Next"></a></td>
19
</tr></table></div>
20
<div class="chapter" lang="en">
21
<div class="titlepage"><div><div><h2 class="title">
22
<a name="cg-manual"></a>5.�Cachegrind: a cache profiler</h2></div></div></div>
23
<div class="toc">
24
<p><b>Table of Contents</b></p>
25
<dl>
26
<dt><span class="sect1"><a href="cg-manual.html#cg-manual.cache">5.1. Cache profiling</a></span></dt>
27
<dd><dl>
28
<dt><span class="sect2"><a href="cg-manual.html#cg-manual.overview">5.1.1. Overview</a></span></dt>
29
<dt><span class="sect2"><a href="cg-manual.html#cache-sim">5.1.2. Cache simulation specifics</a></span></dt>
30
</dl></dd>
31
<dt><span class="sect1"><a href="cg-manual.html#cg-manual.profile">5.2. Profiling programs</a></span></dt>
32
<dd><dl>
33
<dt><span class="sect2"><a href="cg-manual.html#cg-manual.outputfile">5.2.1. Output file</a></span></dt>
34
<dt><span class="sect2"><a href="cg-manual.html#cg-manual.cgopts">5.2.2. Cachegrind options</a></span></dt>
35
<dt><span class="sect2"><a href="cg-manual.html#cg-manual.annotate">5.2.3. Annotating C/C++ programs</a></span></dt>
36
<dt><span class="sect2"><a href="cg-manual.html#cg-manual.assembler">5.2.4. Annotating assembler programs</a></span></dt>
37
</dl></dd>
38
<dt><span class="sect1"><a href="cg-manual.html#cg-manual.annopts">5.3. <code class="computeroutput">cg_annotate</code> options</a></span></dt>
39
<dd><dl>
40
<dt><span class="sect2"><a href="cg-manual.html#id2596905">5.3.1. Warnings</a></span></dt>
41
<dt><span class="sect2"><a href="cg-manual.html#id2582002">5.3.2. Things to watch out for</a></span></dt>
42
<dt><span class="sect2"><a href="cg-manual.html#id2591706">5.3.3. Accuracy</a></span></dt>
43
<dt><span class="sect2"><a href="cg-manual.html#id2589064">5.3.4. Todo</a></span></dt>
44
</dl></dd>
45
</dl>
46
</div>
47
<p>Detailed technical documentation on how Cachegrind works is
48
available in <a href="cg-tech-docs.html">How Cachegrind works</a>. If you only want to know
49
how to <span><strong class="command">use</strong></span> it, this is the page you need to
50
read.</p>
51
<div class="sect1" lang="en">
52
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
53
<a name="cg-manual.cache"></a>5.1.�Cache profiling</h2></div></div></div>
54
<p>To use this tool, you must specify
55
<code class="computeroutput">--tool=cachegrind</code> on the
56
Valgrind command line.</p>
57
<p>Cachegrind is a tool for doing cache simulations and
58
annotating your source line-by-line with the number of cache
59
misses. In particular, it records:</p>
60
<div class="itemizedlist"><ul type="disc">
61
<li><p>L1 instruction cache reads and misses;</p></li>
62
<li><p>L1 data cache reads and read misses, writes and write
63
misses;</p></li>
64
<li><p>L2 unified cache reads and read misses, writes and
65
writes misses.</p></li>
66
</ul></div>
67
<p>On a modern machine, an L1 miss will typically cost
68
around 10 cycles, and an L2 miss can cost as much as 200
69
cycles. Detailed cache profiling can be very useful for improving
70
the performance of your program.</p>
71
<p>Also, since one instruction cache read is performed per
72
instruction executed, you can find out how many instructions are
73
executed per line, which can be useful for traditional profiling
74
and test coverage.</p>
75
<p>Any feedback, bug-fixes, suggestions, etc, welcome.</p>
76
<div class="sect2" lang="en">
77
<div class="titlepage"><div><div><h3 class="title">
78
<a name="cg-manual.overview"></a>5.1.1.�Overview</h3></div></div></div>
79
<p>First off, as for normal Valgrind use, you probably want to
80
compile with debugging info (the
81
<code class="computeroutput">-g</code> flag). But by contrast with
82
normal Valgrind use, you probably <span><strong class="command">do</strong></span> want to turn
83
optimisation on, since you should profile your program as it will
84
be normally run.</p>
85
<p>The two steps are:</p>
86
<div class="orderedlist"><ol type="1">
87
<li>
88
<p>Run your program with <code class="computeroutput">valgrind
89
--tool=cachegrind</code> in front of the normal
90
command line invocation. When the program finishes,
91
Cachegrind will print summary cache statistics. It also
92
collects line-by-line information in a file
93
<code class="computeroutput">cachegrind.out.pid</code>, where
94
<code class="computeroutput">pid</code> is the program's process
95
id.</p>
96
<p>This step should be done every time you want to collect
97
information about a new program, a changed program, or about
98
the same program with different input.</p>
99
</li>
100
<li>
101
<p>Generate a function-by-function summary, and possibly
102
annotate source files, using the supplied
103
<code class="computeroutput">cg_annotate</code> program. Source
104
files to annotate can be specified manually, or manually on
105
the command line, or "interesting" source files can be
106
annotated automatically with the
107
<code class="computeroutput">--auto=yes</code> option. You can
108
annotate C/C++ files or assembly language files equally
109
easily.</p>
110
<p>This step can be performed as many times as you like
111
for each Step 2. You may want to do multiple annotations
112
showing different information each time.</p>
113
</li>
114
</ol></div>
115
<p>The steps are described in detail in the following
116
sections.</p>
117
</div>
118
<div class="sect2" lang="en">
119
<div class="titlepage"><div><div><h3 class="title">
120
<a name="cache-sim"></a>5.1.2.�Cache simulation specifics</h3></div></div></div>
121
<p>Cachegrind uses a simulation for a machine with a split L1
122
cache and a unified L2 cache. This configuration is used for all
123
(modern) x86-based machines we are aware of. Old Cyrix CPUs had
124
a unified I and D L1 cache, but they are ancient history
125
now.</p>
126
<p>The more specific characteristics of the simulation are as
127
follows.</p>
128
<div class="itemizedlist"><ul type="disc">
129
<li><p>Write-allocate: when a write miss occurs, the block
130
written to is brought into the D1 cache. Most modern caches
131
have this property.</p></li>
132
<li>
133
<p>Bit-selection hash function: the line(s) in the cache
134
to which a memory block maps is chosen by the middle bits
135
M--(M+N-1) of the byte address, where:</p>
136
<div class="itemizedlist"><ul type="circle">
137
<li><p>line size = 2^M bytes</p></li>
138
<li><p>(cache size / line size) = 2^N bytes</p></li>
139
</ul></div>
140
</li>
141
<li><p>Inclusive L2 cache: the L2 cache replicates all the
142
entries of the L1 cache. This is standard on Pentium chips,
143
but AMD Athlons use an exclusive L2 cache that only holds
144
blocks evicted from L1. Ditto AMD Durons and most modern
145
VIAs.</p></li>
146
</ul></div>
147
<p>The cache configuration simulated (cache size,
148
associativity and line size) is determined automagically using
149
the CPUID instruction. If you have an old machine that (a)
150
doesn't support the CPUID instruction, or (b) supports it in an
151
early incarnation that doesn't give any cache information, then
152
Cachegrind will fall back to using a default configuration (that
153
of a model 3/4 Athlon). Cachegrind will tell you if this
154
happens. You can manually specify one, two or all three levels
155
(I1/D1/L2) of the cache from the command line using the
156
<code class="computeroutput">--I1</code>,
157
<code class="computeroutput">--D1</code> and
158
<code class="computeroutput">--L2</code> options.</p>
159
<p>Other noteworthy behaviour:</p>
160
<div class="itemizedlist"><ul type="disc">
161
<li>
162
<p>References that straddle two cache lines are treated as
163
follows:</p>
164
<div class="itemizedlist"><ul type="circle">
165
<li><p>If both blocks hit --> counted as one hit</p></li>
166
<li><p>If one block hits, the other misses --> counted
167
as one miss.</p></li>
168
<li><p>If both blocks miss --> counted as one miss (not
169
two)</p></li>
170
</ul></div>
171
</li>
172
<li>
173
<p>Instructions that modify a memory location
174
(eg. <code class="computeroutput">inc</code> and
175
<code class="computeroutput">dec</code>) are counted as doing
176
just a read, ie. a single data reference. This may seem
177
strange, but since the write can never cause a miss (the read
178
guarantees the block is in the cache) it's not very
179
interesting.</p>
180
<p>Thus it measures not the number of times the data cache
181
is accessed, but the number of times a data cache miss could
182
occur.</p>
183
</li>
184
</ul></div>
185
<p>If you are interested in simulating a cache with different
186
properties, it is not particularly hard to write your own cache
187
simulator, or to modify the existing ones in
188
<code class="computeroutput">vg_cachesim_I1.c</code>,
189
<code class="computeroutput">vg_cachesim_D1.c</code>,
190
<code class="computeroutput">vg_cachesim_L2.c</code> and
191
<code class="computeroutput">vg_cachesim_gen.c</code>. We'd be
192
interested to hear from anyone who does.</p>
193
</div>
194
</div>
195
<div class="sect1" lang="en">
196
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
197
<a name="cg-manual.profile"></a>5.2.�Profiling programs</h2></div></div></div>
198
<p>To gather cache profiling information about the program
199
<code class="computeroutput">ls -l</code>, invoke Cachegrind like
200
this:</p>
201
<pre class="programlisting">
202
valgrind --tool=cachegrind ls -l</pre>
203
<p>The program will execute (slowly). Upon completion,
204
summary statistics that look like this will be printed:</p>
205
<pre class="programlisting">
206
==31751== I refs: 27,742,716
207
==31751== I1 misses: 276
208
==31751== L2 misses: 275
209
==31751== I1 miss rate: 0.0%
210
==31751== L2i miss rate: 0.0%
211
==31751==
212
==31751== D refs: 15,430,290 (10,955,517 rd + 4,474,773 wr)
213
==31751== D1 misses: 41,185 ( 21,905 rd + 19,280 wr)
214
==31751== L2 misses: 23,085 ( 3,987 rd + 19,098 wr)
215
==31751== D1 miss rate: 0.2% ( 0.1% + 0.4%)
216
==31751== L2d miss rate: 0.1% ( 0.0% + 0.4%)
217
==31751==
218
==31751== L2 misses: 23,360 ( 4,262 rd + 19,098 wr)
219
==31751== L2 miss rate: 0.0% ( 0.0% + 0.4%)</pre>
220
<p>Cache accesses for instruction fetches are summarised
221
first, giving the number of fetches made (this is the number of
222
instructions executed, which can be useful to know in its own
223
right), the number of I1 misses, and the number of L2 instruction
224
(<code class="computeroutput">L2i</code>) misses.</p>
225
<p>Cache accesses for data follow. The information is similar
226
to that of the instruction fetches, except that the values are
227
also shown split between reads and writes (note each row's
228
<code class="computeroutput">rd</code> and
229
<code class="computeroutput">wr</code> values add up to the row's
230
total).</p>
231
<p>Combined instruction and data figures for the L2 cache
232
follow that.</p>
233
<div class="sect2" lang="en">
234
<div class="titlepage"><div><div><h3 class="title">
235
<a name="cg-manual.outputfile"></a>5.2.1.�Output file</h3></div></div></div>
236
<p>As well as printing summary information, Cachegrind also
237
writes line-by-line cache profiling information to a file named
238
<code class="computeroutput">cachegrind.out.pid</code>. This file
239
is human-readable, but is best interpreted by the accompanying
240
program <code class="computeroutput">cg_annotate</code>, described
241
in the next section.</p>
242
<p>Things to note about the
243
<code class="computeroutput">cachegrind.out.pid</code>
244
file:</p>
245
<div class="itemizedlist"><ul type="disc">
246
<li><p>It is written every time Cachegrind is run, and will
247
overwrite any existing
248
<code class="computeroutput">cachegrind.out.pid</code>
249
in the current directory (but that won't happen very often
250
because it takes some time for process ids to be
251
recycled).</p></li>
252
<li><p>It can be huge: <code class="computeroutput">ls -l</code>
253
generates a file of about 350KB. Browsing a few files and
254
web pages with a Konqueror built with full debugging
255
information generates a file of around 15 MB.</p></li>
256
</ul></div>
257
<p>The <code class="computeroutput">.pid</code> suffix
258
on the output file name serves two purposes. Firstly, it means you
259
don't have to rename old log files that you don't want to overwrite.
260
Secondly, and more importantly, it allows correct profiling with the
261
<code class="computeroutput">--trace-children=yes</code> option of
262
programs that spawn child processes.</p>
263
</div>
264
<div class="sect2" lang="en">
265
<div class="titlepage"><div><div><h3 class="title">
266
<a name="cg-manual.cgopts"></a>5.2.2.�Cachegrind options</h3></div></div></div>
267
<p>Cache-simulation specific options are:</p>
268
<pre class="screen">
269
--I1=<size>,<associativity>,<line_size>
270
--D1=<size>,<associativity>,<line_size>
271
--L2=<size>,<associativity>,<line_size>
272
273
[default: uses CPUID for automagic cache configuration]</pre>
274
<p>Manually specifies the I1/D1/L2 cache configuration, where
275
<code class="computeroutput">size</code> and
276
<code class="computeroutput">line_size</code> are measured in bytes.
277
The three items must be comma-separated, but with no spaces,
278
eg:</p>
279
<pre class="programlisting">
280
valgrind --tool=cachegrind --I1=65535,2,64</pre>
281
<p>You can specify one, two or three of the I1/D1/L2 caches.
282
Any level not manually specified will be simulated using the
283
configuration found in the normal way (via the CPUID instruction,
284
or failing that, via defaults).</p>
285
</div>
286
<div class="sect2" lang="en">
287
<div class="titlepage"><div><div><h3 class="title">
288
<a name="cg-manual.annotate"></a>5.2.3.�Annotating C/C++ programs</h3></div></div></div>
289
<p>Before using <code class="computeroutput">cg_annotate</code>,
290
it is worth widening your window to be at least 120-characters
291
wide if possible, as the output lines can be quite long.</p>
292
<p>To get a function-by-function summary, run
293
<code class="computeroutput">cg_annotate --pid</code> in a directory
294
containing a <code class="computeroutput">cachegrind.out.pid</code>
295
file. The <span class="emphasis"><em>--pid</em></span> is required so that
296
<code class="computeroutput">cg_annotate</code> knows which log file
297
to use when several are present.</p>
298
<p>The output looks like this:</p>
299
<pre class="programlisting">
300
--------------------------------------------------------------------------------
301
I1 cache: 65536 B, 64 B, 2-way associative
302
D1 cache: 65536 B, 64 B, 2-way associative
303
L2 cache: 262144 B, 64 B, 8-way associative
304
Command: concord vg_to_ucode.c
305
Events recorded: Ir I1mr I2mr Dr D1mr D2mr Dw D1mw D2mw
306
Events shown: Ir I1mr I2mr Dr D1mr D2mr Dw D1mw D2mw
307
Event sort order: Ir I1mr I2mr Dr D1mr D2mr Dw D1mw D2mw
308
Threshold: 99%
309
Chosen for annotation:
310
Auto-annotation: on
311
312
--------------------------------------------------------------------------------
313
Ir I1mr I2mr Dr D1mr D2mr Dw D1mw D2mw
314
--------------------------------------------------------------------------------
315
27,742,716 276 275 10,955,517 21,905 3,987 4,474,773 19,280 19,098 PROGRAM TOTALS
316
317
--------------------------------------------------------------------------------
318
Ir I1mr I2mr Dr D1mr D2mr Dw D1mw D2mw file:function
319
--------------------------------------------------------------------------------
320
8,821,482 5 5 2,242,702 1,621 73 1,794,230 0 0 getc.c:_IO_getc
321
5,222,023 4 4 2,276,334 16 12 875,959 1 1 concord.c:get_word
322
2,649,248 2 2 1,344,810 7,326 1,385 . . . vg_main.c:strcmp
323
2,521,927 2 2 591,215 0 0 179,398 0 0 concord.c:hash
324
2,242,740 2 2 1,046,612 568 22 448,548 0 0 ctype.c:tolower
325
1,496,937 4 4 630,874 9,000 1,400 279,388 0 0 concord.c:insert
326
897,991 51 51 897,831 95 30 62 1 1 ???:???
327
598,068 1 1 299,034 0 0 149,517 0 0 ../sysdeps/generic/lockfile.c:__flockfile
328
598,068 0 0 299,034 0 0 149,517 0 0 ../sysdeps/generic/lockfile.c:__funlockfile
329
598,024 4 4 213,580 35 16 149,506 0 0 vg_clientmalloc.c:malloc
330
446,587 1 1 215,973 2,167 430 129,948 14,057 13,957 concord.c:add_existing
331
341,760 2 2 128,160 0 0 128,160 0 0 vg_clientmalloc.c:vg_trap_here_WRAPPER
332
320,782 4 4 150,711 276 0 56,027 53 53 concord.c:init_hash_table
333
298,998 1 1 106,785 0 0 64,071 1 1 concord.c:create
334
149,518 0 0 149,516 0 0 1 0 0 ???:tolower@@GLIBC_2.0
335
149,518 0 0 149,516 0 0 1 0 0 ???:fgetc@@GLIBC_2.0
336
95,983 4 4 38,031 0 0 34,409 3,152 3,150 concord.c:new_word_node
337
85,440 0 0 42,720 0 0 21,360 0 0 vg_clientmalloc.c:vg_bogus_epilogue</pre>
338
<p>First up is a summary of the annotation options:</p>
339
<div class="itemizedlist"><ul type="disc">
340
<li><p>I1 cache, D1 cache, L2 cache: cache configuration. So
341
you know the configuration with which these results were
342
obtained.</p></li>
343
<li><p>Command: the command line invocation of the program
344
under examination.</p></li>
345
<li>
346
<p>Events recorded: event abbreviations are:</p>
347
<div class="itemizedlist"><ul type="circle">
348
<li><p><code class="computeroutput">Ir </code>: I cache reads
349
(ie. instructions executed)</p></li>
350
<li><p><code class="computeroutput">I1mr</code>: I1 cache read
351
misses</p></li>
352
<li><p><code class="computeroutput">I2mr</code>: L2 cache
353
instruction read misses</p></li>
354
<li><p><code class="computeroutput">Dr </code>: D cache reads
355
(ie. memory reads)</p></li>
356
<li><p><code class="computeroutput">D1mr</code>: D1 cache read
357
misses</p></li>
358
<li><p><code class="computeroutput">D2mr</code>: L2 cache data
359
read misses</p></li>
360
<li><p><code class="computeroutput">Dw </code>: D cache writes
361
(ie. memory writes)</p></li>
362
<li><p><code class="computeroutput">D1mw</code>: D1 cache write
363
misses</p></li>
364
<li><p><code class="computeroutput">D2mw</code>: L2 cache data
365
write misses</p></li>
366
</ul></div>
367
<p>Note that D1 total accesses is given by
368
<code class="computeroutput">D1mr</code> +
369
<code class="computeroutput">D1mw</code>, and that L2 total
370
accesses is given by <code class="computeroutput">I2mr</code> +
371
<code class="computeroutput">D2mr</code> +
372
<code class="computeroutput">D2mw</code>.</p>
373
</li>
374
<li><p>Events shown: the events shown (a subset of events
375
gathered). This can be adjusted with the
376
<code class="computeroutput">--show</code> option.</p></li>
377
<li>
378
<p>Event sort order: the sort order in which functions are
379
shown. For example, in this case the functions are sorted
380
from highest <code class="computeroutput">Ir</code> counts to
381
lowest. If two functions have identical
382
<code class="computeroutput">Ir</code> counts, they will then be
383
sorted by <code class="computeroutput">I1mr</code> counts, and
384
so on. This order can be adjusted with the
385
<code class="computeroutput">--sort</code> option.</p>
386
<p>Note that this dictates the order the functions appear.
387
It is <span><strong class="command">not</strong></span> the order in which the columns
388
appear; that is dictated by the "events shown" line (and can
389
be changed with the <code class="computeroutput">--show</code>
390
option).</p>
391
</li>
392
<li><p>Threshold: <code class="computeroutput">cg_annotate</code>
393
by default omits functions that cause very low numbers of
394
misses to avoid drowning you in information. In this case,
395
cg_annotate shows summaries the functions that account for
396
99% of the <code class="computeroutput">Ir</code> counts;
397
<code class="computeroutput">Ir</code> is chosen as the
398
threshold event since it is the primary sort event. The
399
threshold can be adjusted with the
400
<code class="computeroutput">--threshold</code>
401
option.</p></li>
402
<li><p>Chosen for annotation: names of files specified
403
manually for annotation; in this case none.</p></li>
404
<li><p>Auto-annotation: whether auto-annotation was requested
405
via the <code class="computeroutput">--auto=yes</code>
406
option. In this case no.</p></li>
407
</ul></div>
408
<p>Then follows summary statistics for the whole
409
program. These are similar to the summary provided when running
410
<code class="computeroutput">valgrind
411
--tool=cachegrind</code>.</p>
412
<p>Then follows function-by-function statistics. Each function
413
is identified by a
414
<code class="computeroutput">file_name:function_name</code> pair. If
415
a column contains only a dot it means the function never performs
416
that event (eg. the third row shows that
417
<code class="computeroutput">strcmp()</code> contains no
418
instructions that write to memory). The name
419
<code class="computeroutput">???</code> is used if the the file name
420
and/or function name could not be determined from debugging
421
information. If most of the entries have the form
422
<code class="computeroutput">???:???</code> the program probably
423
wasn't compiled with <code class="computeroutput">-g</code>. If any
424
code was invalidated (either due to self-modifying code or
425
unloading of shared objects) its counts are aggregated into a
426
single cost centre written as
427
<code class="computeroutput">(discarded):(discarded)</code>.</p>
428
<p>It is worth noting that functions will come from three
429
types of source files:</p>
430
<div class="orderedlist"><ol type="1">
431
<li><p>From the profiled program
432
(<code class="filename">concord.c</code> in this example).</p></li>
433
<li><p>From libraries (eg. <code class="filename">getc.c</code>)</p></li>
434
<li><p>From Valgrind's implementation of some libc functions
435
(eg. <code class="computeroutput">vg_clientmalloc.c:malloc</code>).
436
These are recognisable because the filename begins with
437
<code class="computeroutput">vg_</code>, and is probably one of
438
<code class="filename">vg_main.c</code>,
439
<code class="filename">vg_clientmalloc.c</code> or
440
<code class="filename">vg_mylibc.c</code>.</p></li>
441
</ol></div>
442
<p>There are two ways to annotate source files -- by choosing
443
them manually, or with the
444
<code class="computeroutput">--auto=yes</code> option. To do it
445
manually, just specify the filenames as arguments to
446
<code class="computeroutput">cg_annotate</code>. For example, the
447
output from running <code class="filename">cg_annotate concord.c</code>
448
for our example produces the same output as above followed by an
449
annotated version of <code class="filename">concord.c</code>, a section of
450
which looks like:</p>
451
<pre class="programlisting">
452
--------------------------------------------------------------------------------
453
-- User-annotated source: concord.c
454
--------------------------------------------------------------------------------
455
Ir I1mr I2mr Dr D1mr D2mr Dw D1mw D2mw
456
457
[snip]
458
459
. . . . . . . . . void init_hash_table(char *file_name, Word_Node *table[])
460
3 1 1 . . . 1 0 0 {
461
. . . . . . . . . FILE *file_ptr;
462
. . . . . . . . . Word_Info *data;
463
1 0 0 . . . 1 1 1 int line = 1, i;
464
. . . . . . . . .
465
5 0 0 . . . 3 0 0 data = (Word_Info *) create(sizeof(Word_Info));
466
. . . . . . . . .
467
4,991 0 0 1,995 0 0 998 0 0 for (i = 0; i < TABLE_SIZE; i++)
468
3,988 1 1 1,994 0 0 997 53 52 table[i] = NULL;
469
. . . . . . . . .
470
. . . . . . . . . /* Open file, check it. */
471
6 0 0 1 0 0 4 0 0 file_ptr = fopen(file_name, "r");
472
2 0 0 1 0 0 . . . if (!(file_ptr)) {
473
. . . . . . . . . fprintf(stderr, "Couldn't open '%s'.\n", file_name);
474
1 1 1 . . . . . . exit(EXIT_FAILURE);
475
. . . . . . . . . }
476
. . . . . . . . .
477
165,062 1 1 73,360 0 0 91,700 0 0 while ((line = get_word(data, line, file_ptr)) != EOF)
478
146,712 0 0 73,356 0 0 73,356 0 0 insert(data->;word, data->line, table);
479
. . . . . . . . .
480
4 0 0 1 0 0 2 0 0 free(data);
481
4 0 0 1 0 0 2 0 0 fclose(file_ptr);
482
3 0 0 2 0 0 . . . }</pre>
483
<p>(Although column widths are automatically minimised, a wide
484
terminal is clearly useful.)</p>
485
<p>Each source file is clearly marked
486
(<code class="computeroutput">User-annotated source</code>) as
487
having been chosen manually for annotation. If the file was
488
found in one of the directories specified with the
489
<code class="computeroutput">-I / --include</code> option, the directory
490
and file are both given.</p>
491
<p>Each line is annotated with its event counts. Events not
492
applicable for a line are represented by a `.'; this is useful
493
for distinguishing between an event which cannot happen, and one
494
which can but did not.</p>
495
<p>Sometimes only a small section of a source file is
496
executed. To minimise uninteresting output, Cachegrind only shows
497
annotated lines and lines within a small distance of annotated
498
lines. Gaps are marked with the line numbers so you know which
499
part of a file the shown code comes from, eg:</p>
500
<pre class="programlisting">
501
(figures and code for line 704)
502
-- line 704 ----------------------------------------
503
-- line 878 ----------------------------------------
504
(figures and code for line 878)</pre>
505
<p>The amount of context to show around annotated lines is
506
controlled by the <code class="computeroutput">--context</code>
507
option.</p>
508
<p>To get automatic annotation, run
509
<code class="computeroutput">cg_annotate --auto=yes</code>.
510
cg_annotate will automatically annotate every source file it can
511
find that is mentioned in the function-by-function summary.
512
Therefore, the files chosen for auto-annotation are affected by
513
the <code class="computeroutput">--sort</code> and
514
<code class="computeroutput">--threshold</code> options. Each
515
source file is clearly marked (<code class="computeroutput">Auto-annotated
516
source</code>) as being chosen automatically. Any
517
files that could not be found are mentioned at the end of the
518
output, eg:</p>
519
<pre class="programlisting">
520
------------------------------------------------------------------
521
The following files chosen for auto-annotation could not be found:
522
------------------------------------------------------------------
523
getc.c
524
ctype.c
525
../sysdeps/generic/lockfile.c</pre>
526
<p>This is quite common for library files, since libraries are
527
usually compiled with debugging information, but the source files
528
are often not present on a system. If a file is chosen for
529
annotation <span><strong class="command">both</strong></span> manually and automatically, it
530
is marked as <code class="computeroutput">User-annotated
531
source</code>. Use the <code class="computeroutput">-I /
532
--include</code> option to tell Valgrind where to look
533
for source files if the filenames found from the debugging
534
information aren't specific enough.</p>
535
<p>Beware that cg_annotate can take some time to digest large
536
<code class="computeroutput">cachegrind.out.pid</code> files,
537
e.g. 30 seconds or more. Also beware that auto-annotation can
538
produce a lot of output if your program is large!</p>
539
</div>
540
<div class="sect2" lang="en">
541
<div class="titlepage"><div><div><h3 class="title">
542
<a name="cg-manual.assembler"></a>5.2.4.�Annotating assembler programs</h3></div></div></div>
543
<p>Valgrind can annotate assembler programs too, or annotate
544
the assembler generated for your C program. Sometimes this is
545
useful for understanding what is really happening when an
546
interesting line of C code is translated into multiple
547
instructions.</p>
548
<p>To do this, you just need to assemble your
549
<code class="computeroutput">.s</code> files with assembler-level
550
debug information. gcc doesn't do this, but you can use the GNU
551
assembler with the <code class="computeroutput">--gstabs</code>
552
option to generate object files with this information, eg:</p>
553
<pre class="programlisting">
554
as --gstabs foo.s</pre>
555
<p>You can then profile and annotate source files in the same
556
way as for C/C++ programs.</p>
557
</div>
558
</div>
559
<div class="sect1" lang="en">
560
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
561
<a name="cg-manual.annopts"></a>5.3.�<code class="computeroutput">cg_annotate</code> options</h2></div></div></div>
562
<div class="itemizedlist"><ul type="disc">
563
<li>
564
<p><a name="pid"></a><code class="computeroutput">--pid</code></p>
565
<p>Indicates which
566
<code class="computeroutput">cachegrind.out.pid</code> file to
567
read. Not actually an option -- it is required.</p>
568
</li>
569
<li>
570
<p><code class="computeroutput">-h, --help</code></p>
571
<p><code class="computeroutput">-v, --version</code></p>
572
<p>Help and version, as usual.</p>
573
</li>
574
<li>
575
<p><a name="sort"></a><code class="computeroutput">--sort=A,B,C</code> [default:
576
order in
577
<code class="computeroutput">cachegrind.out.pid</code>]</p>
578
<p>Specifies the events upon which the sorting of the
579
function-by-function entries will be based. Useful if you
580
want to concentrate on eg. I cache misses
581
(<code class="computeroutput">--sort=I1mr,I2mr</code>), or D
582
cache misses
583
(<code class="computeroutput">--sort=D1mr,D2mr</code>), or L2
584
misses
585
(<code class="computeroutput">--sort=D2mr,I2mr</code>).</p>
586
</li>
587
<li>
588
<p><a name="show"></a><code class="computeroutput">--show=A,B,C</code> [default:
589
all, using order in
590
<code class="computeroutput">cachegrind.out.pid</code>]</p>
591
<p>Specifies which events to show (and the column
592
order). Default is to use all present in the
593
<code class="computeroutput">cachegrind.out.pid</code> file (and
594
use the order in the file).</p>
595
</li>
596
<li>
597
<p><a name="threshold"></a><code class="computeroutput">--threshold=X</code>
598
[default: 99%]</p>
599
<p>Sets the threshold for the function-by-function
600
summary. Functions are shown that account for more than X%
601
of the primary sort event. If auto-annotating, also affects
602
which files are annotated.</p>
603
<p>Note: thresholds can be set for more than one of the
604
events by appending any events for the
605
<code class="computeroutput">--sort</code> option with a colon
606
and a number (no spaces, though). E.g. if you want to see
607
the functions that cover 99% of L2 read misses and 99% of L2
608
write misses, use this option:</p>
609
<p><code class="computeroutput">--sort=D2mr:99,D2mw:99</code></p>
610
</li>
611
<li>
612
<p><a name="auto"></a><code class="computeroutput">--auto=no</code> [default]</p>
613
<p><code class="computeroutput">--auto=yes</code></p>
614
<p>When enabled, automatically annotates every file that
615
is mentioned in the function-by-function summary that can be
616
found. Also gives a list of those that couldn't be found.</p>
617
</li>
618
<li>
619
<p><a name="context"></a><code class="computeroutput">--context=N</code> [default:
620
8]</p>
621
<p>Print N lines of context before and after each
622
annotated line. Avoids printing large sections of source
623
files that were not executed. Use a large number
624
(eg. 10,000) to show all source lines.</p>
625
</li>
626
<li>
627
<p><a name="include"></a><code class="computeroutput">-I<dir>,
628
--include=<dir></code> [default: empty
629
string]</p>
630
<p>Adds a directory to the list in which to search for
631
files. Multiple -I/--include options can be given to add
632
multiple directories.</p>
633
</li>
634
</ul></div>
635
<div class="sect2" lang="en">
636
<div class="titlepage"><div><div><h3 class="title">
637
<a name="id2596905"></a>5.3.1.�Warnings</h3></div></div></div>
638
<p>There are a couple of situations in which
639
<code class="computeroutput">cg_annotate</code> issues
640
warnings.</p>
641
<div class="itemizedlist"><ul type="disc">
642
<li><p>If a source file is more recent than the
643
<code class="computeroutput">cachegrind.out.pid</code> file.
644
This is because the information in
645
<code class="computeroutput">cachegrind.out.pid</code> is only
646
recorded with line numbers, so if the line numbers change at
647
all in the source (eg. lines added, deleted, swapped), any
648
annotations will be incorrect.</p></li>
649
<li><p>If information is recorded about line numbers past the
650
end of a file. This can be caused by the above problem,
651
ie. shortening the source file while using an old
652
<code class="computeroutput">cachegrind.out.pid</code> file. If
653
this happens, the figures for the bogus lines are printed
654
anyway (clearly marked as bogus) in case they are
655
important.</p></li>
656
</ul></div>
657
</div>
658
<div class="sect2" lang="en">
659
<div class="titlepage"><div><div><h3 class="title">
660
<a name="id2582002"></a>5.3.2.�Things to watch out for</h3></div></div></div>
661
<p>Some odd things that can occur during annotation:</p>
662
<div class="itemizedlist"><ul type="disc">
663
<li>
664
<p>If annotating at the assembler level, you might see
665
something like this:</p>
666
<pre class="programlisting">
667
1 0 0 . . . . . . leal -12(%ebp),%eax
668
1 0 0 . . . 1 0 0 movl %eax,84(%ebx)
669
2 0 0 0 0 0 1 0 0 movl $1,-20(%ebp)
670
. . . . . . . . . .align 4,0x90
671
1 0 0 . . . . . . movl $.LnrB,%eax
672
1 0 0 . . . 1 0 0 movl %eax,-16(%ebp)</pre>
673
<p>How can the third instruction be executed twice when
674
the others are executed only once? As it turns out, it
675
isn't. Here's a dump of the executable, using
676
<code class="computeroutput">objdump -d</code>:</p>
677
<pre class="programlisting">
678
8048f25: 8d 45 f4 lea 0xfffffff4(%ebp),%eax
679
8048f28: 89 43 54 mov %eax,0x54(%ebx)
680
8048f2b: c7 45 ec 01 00 00 00 movl $0x1,0xffffffec(%ebp)
681
8048f32: 89 f6 mov %esi,%esi
682
8048f34: b8 08 8b 07 08 mov $0x8078b08,%eax
683
8048f39: 89 45 f0 mov %eax,0xfffffff0(%ebp)</pre>
684
<p>Notice the extra <code class="computeroutput">mov
685
%esi,%esi</code> instruction. Where did this come
686
from? The GNU assembler inserted it to serve as the two
687
bytes of padding needed to align the <code class="computeroutput">movl
688
$.LnrB,%eax</code> instruction on a four-byte
689
boundary, but pretended it didn't exist when adding debug
690
information. Thus when Valgrind reads the debug info it
691
thinks that the <code class="computeroutput">movl
692
$0x1,0xffffffec(%ebp)</code> instruction covers the
693
address range 0x8048f2b--0x804833 by itself, and attributes
694
the counts for the <code class="computeroutput">mov
695
%esi,%esi</code> to it.</p>
696
</li>
697
<li>
698
<p>Inlined functions can cause strange results in the
699
function-by-function summary. If a function
700
<code class="computeroutput">inline_me()</code> is defined in
701
<code class="filename">foo.h</code> and inlined in the functions
702
<code class="computeroutput">f1()</code>,
703
<code class="computeroutput">f2()</code> and
704
<code class="computeroutput">f3()</code> in
705
<code class="filename">bar.c</code>, there will not be a
706
<code class="computeroutput">foo.h:inline_me()</code> function
707
entry. Instead, there will be separate function entries for
708
each inlining site, ie.
709
<code class="computeroutput">foo.h:f1()</code>,
710
<code class="computeroutput">foo.h:f2()</code> and
711
<code class="computeroutput">foo.h:f3()</code>. To find the
712
total counts for
713
<code class="computeroutput">foo.h:inline_me()</code>, add up
714
the counts from each entry.</p>
715
<p>The reason for this is that although the debug info
716
output by gcc indicates the switch from
717
<code class="filename">bar.c</code> to <code class="filename">foo.h</code>, it
718
doesn't indicate the name of the function in
719
<code class="filename">foo.h</code>, so Valgrind keeps using the old
720
one.</p>
721
</li>
722
<li><p>Sometimes, the same filename might be represented with
723
a relative name and with an absolute name in different parts
724
of the debug info, eg:
725
<code class="filename">/home/user/proj/proj.h</code> and
726
<code class="filename">../proj.h</code>. In this case, if you use
727
auto-annotation, the file will be annotated twice with the
728
counts split between the two.</p></li>
729
<li><p>Files with more than 65,535 lines cause difficulties
730
for the stabs debug info reader. This is because the line
731
number in the <code class="computeroutput">struct nlist</code>
732
defined in <code class="filename">a.out.h</code> under Linux is only a
733
16-bit value. Valgrind can handle some files with more than
734
65,535 lines correctly by making some guesses to identify
735
line number overflows. But some cases are beyond it, in
736
which case you'll get a warning message explaining that
737
annotations for the file might be incorrect.</p></li>
738
<li><p>If you compile some files with
739
<code class="computeroutput">-g</code> and some without, some
740
events that take place in a file without debug info could be
741
attributed to the last line of a file with debug info
742
(whichever one gets placed before the non-debug-info file in
743
the executable).</p></li>
744
</ul></div>
745
<p>This list looks long, but these cases should be fairly
746
rare.</p>
747
<p><b>Note:�</b><code class="computeroutput">stabs</code> is not an easy
748
format to read. If you come across bizarre annotations that
749
look like might be caused by a bug in the stabs reader, please
750
let us know.</p>
751
</div>
752
<div class="sect2" lang="en">
753
<div class="titlepage"><div><div><h3 class="title">
754
<a name="id2591706"></a>5.3.3.�Accuracy</h3></div></div></div>
755
<p>Valgrind's cache profiling has a number of
756
shortcomings:</p>
757
<div class="itemizedlist"><ul type="disc">
758
<li><p>It doesn't account for kernel activity -- the effect of
759
system calls on the cache contents is ignored.</p></li>
760
<li><p>It doesn't account for other process activity (although
761
this is probably desirable when considering a single
762
program).</p></li>
763
<li><p>It doesn't account for virtual-to-physical address
764
mappings; hence the entire simulation is not a true
765
representation of what's happening in the
766
cache.</p></li>
767
<li><p>It doesn't account for cache misses not visible at the
768
instruction level, eg. those arising from TLB misses, or
769
speculative execution.</p></li>
770
<li><p>Valgrind will schedule
771
threads differently from how they would be when running natively.
772
This could warp the results for threaded programs.</p></li>
773
<li>
774
<p>The x86/amd64 instructions <code class="computeroutput">bts</code>,
775
<code class="computeroutput">btr</code> and
776
<code class="computeroutput">btc</code> will incorrectly be
777
counted as doing a data read if both the arguments are
778
registers, eg:</p>
779
<pre class="programlisting">
780
btsl %eax, %edx</pre>
781
<p>This should only happen rarely.</p>
782
</li>
783
<li><p>x86/amd64 FPU instructions with data sizes of 28 and 108 bytes
784
(e.g. <code class="computeroutput">fsave</code>) are treated as
785
though they only access 16 bytes. These instructions seem to
786
be rare so hopefully this won't affect accuracy much.</p></li>
787
</ul></div>
788
<p>Another thing worth nothing is that results are very
789
sensitive. Changing the size of the
790
<code class="filename">valgrind.so</code> file, the size of the program
791
being profiled, or even the length of its name can perturb the
792
results. Variations will be small, but don't expect perfectly
793
repeatable results if your program changes at all.</p>
794
<p>While these factors mean you shouldn't trust the results to
795
be super-accurate, hopefully they should be close enough to be
796
useful.</p>
797
</div>
798
<div class="sect2" lang="en">
799
<div class="titlepage"><div><div><h3 class="title">
800
<a name="id2589064"></a>5.3.4.�Todo</h3></div></div></div>
801
<div class="itemizedlist"><ul type="disc"><li><p>Program start-up/shut-down calls a lot of functions
802
that aren't interesting and just complicate the output.
803
Would be nice to exclude these somehow.</p></li></ul></div>
804
</div>
805
</div>
806
</div>
807
<div>
808
<br><table class="nav" width="100%" cellspacing="3" cellpadding="2" border="0" summary="Navigation footer">
809
<tr>
810
<td rowspan="2" width="40%" align="left">
811
<a accesskey="p" href="ac-manual.html"><<�4.�Addrcheck: a lightweight memory checker</a>�</td>
812
<td width="20%" align="center"><a accesskey="u" href="manual.html">Up</a></td>
813
<td rowspan="2" width="40%" align="right">�<a accesskey="n" href="ms-manual.html">6.�Massif: a heap profiler�>></a>
814
</td>
815
</tr>
816
<tr><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td></tr>
817
</table>
818
</div>
819
</body>
820
</html>
Loggerhead is a web-based interface for Breezy
Version: 2.0.1