1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 4<title>3.�Callgrind Format Specification</title> 5<link rel="stylesheet" type="text/css" href="vg_basic.css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="index.html" title="Valgrind Documentation"> 8<link rel="up" href="tech-docs.html" title="Valgrind Technical Documentation"> 9<link rel="prev" href="manual-writing-tools.html" title="2.�Writing a New Valgrind Tool"> 10<link rel="next" href="dist.html" title="Valgrind Distribution Documents"> 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="manual-writing-tools.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="tech-docs.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 Technical Documentation</th> 18<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> 19</tr></table></div> 20<div class="chapter"> 21<div class="titlepage"><div><div><h1 class="title"> 22<a name="cl-format"></a>3.�Callgrind Format Specification</h1></div></div></div> 23<div class="toc"> 24<p><b>Table of Contents</b></p> 25<dl class="toc"> 26<dt><span class="sect1"><a href="cl-format.html#cl-format.overview">3.1. Overview</a></span></dt> 27<dd><dl> 28<dt><span class="sect2"><a href="cl-format.html#cl-format.overview.basics">3.1.1. Basic Structure</a></span></dt> 29<dt><span class="sect2"><a href="cl-format.html#cl-format.overview.example1">3.1.2. Simple Example</a></span></dt> 30<dt><span class="sect2"><a href="cl-format.html#cl-format.overview.associations">3.1.3. Associations</a></span></dt> 31<dt><span class="sect2"><a href="cl-format.html#cl-format.overview.example2">3.1.4. Extended Example</a></span></dt> 32<dt><span class="sect2"><a href="cl-format.html#cl-format.overview.compression1">3.1.5. Name Compression</a></span></dt> 33<dt><span class="sect2"><a href="cl-format.html#cl-format.overview.compression2">3.1.6. Subposition Compression</a></span></dt> 34<dt><span class="sect2"><a href="cl-format.html#cl-format.overview.misc">3.1.7. Miscellaneous</a></span></dt> 35</dl></dd> 36<dt><span class="sect1"><a href="cl-format.html#cl-format.reference">3.2. Reference</a></span></dt> 37<dd><dl> 38<dt><span class="sect2"><a href="cl-format.html#cl-format.reference.grammar">3.2.1. Grammar</a></span></dt> 39<dt><span class="sect2"><a href="cl-format.html#cl-format.reference.header">3.2.2. Description of Header Lines</a></span></dt> 40<dt><span class="sect2"><a href="cl-format.html#cl-format.reference.body">3.2.3. Description of Body Lines</a></span></dt> 41</dl></dd> 42</dl> 43</div> 44<p>This chapter describes the Callgrind Format, Version 1.</p> 45<p>The format description is meant for the user to be able to understand the 46file contents; but more important, it is given for authors of measurement or 47visualization tools to be able to write and read this format.</p> 48<div class="sect1"> 49<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 50<a name="cl-format.overview"></a>3.1.�Overview</h2></div></div></div> 51<p>The profile data format is ASCII based. 52It is written by Callgrind, and it is upwards compatible 53to the format used by Cachegrind (ie. Cachegrind uses a subset). It can 54be read by callgrind_annotate and KCachegrind.</p> 55<p>This chapter gives on overview of format features and examples. 56For detailed syntax, look at the format reference.</p> 57<div class="sect2"> 58<div class="titlepage"><div><div><h3 class="title"> 59<a name="cl-format.overview.basics"></a>3.1.1.�Basic Structure</h3></div></div></div> 60<p>To uniquely specify that a file is a callgrind profile, it 61should add "# callgrind format" as first line. This is optional but 62recommended for easy format detection.</p> 63<p>Each file has a header part of an arbitrary number of lines of the 64format "key: value". After the header, lines specifying profile costs 65follow. Everywhere, comments on own lines starting with '#' are allowed. 66The header lines with keys "positions" and "events" define 67the meaning of cost lines in the second part of the file: the value of 68"positions" is a list of subpositions, and the value of "events" is a list 69of event type names. Cost lines consist of subpositions followed by 64-bit 70counters for the events, in the order specified by the "positions" and "events" 71header line.</p> 72<p>The "events" header line is always required in contrast to the optional 73line for "positions", which defaults to "line", i.e. a line number of some 74source file. In addition, the second part of the file contains position 75specifications of the form "spec=name". "spec" can be e.g. "fn" for a 76function name or "fl" for a file name. Cost lines are always related to 77the function/file specifications given directly before.</p> 78</div> 79<div class="sect2"> 80<div class="titlepage"><div><div><h3 class="title"> 81<a name="cl-format.overview.example1"></a>3.1.2.�Simple Example</h3></div></div></div> 82<p>The event names in the following example are quite arbitrary, and are not 83related to event names used by Callgrind. Especially, cycle counts matching 84real processors probably will never be generated by any Valgrind tools, as these 85are bound to simulations of simple machine models for acceptable slowdown. 86However, any profiling tool could use the format described in this chapter.</p> 87<p> 88</p> 89<pre class="screen"># callgrind format 90events: Cycles Instructions Flops 91fl=file.f 92fn=main 9315 90 14 2 9416 20 12</pre> 95<p>The above example gives profile information for event types "Cycles", 96"Instructions", and "Flops". Thus, cost lines give the number of CPU cycles 97passed by, number of executed instructions, and number of floating point 98operations executed while running code corresponding to some source 99position. As there is no line specifying the value of "positions", it defaults 100to "line", which means that the first number of a cost line is always a line 101number.</p> 102<p>Thus, the first cost line specifies that in line 15 of source file 103<code class="filename">file.f</code> there is code belonging to function 104<code class="function">main</code>. While running, 90 CPU cycles passed by, and 2 of 105the 14 instructions executed were floating point operations. Similarly, the 106next line specifies that there were 12 instructions executed in the context 107of function <code class="function">main</code> which can be related to line 16 in 108file <code class="filename">file.f</code>, taking 20 CPU cycles. If a cost line 109specifies less event counts than given in the "events" line, the rest is 110assumed to be zero. I.e. there was no floating point instruction executed 111relating to line 16.</p> 112<p>Note that regular cost lines always give self (also called exclusive) 113cost of code at a given position. If you specify multiple cost lines for the 114same position, these will be summed up. On the other hand, in the example above 115there is no specification of how many times function 116<code class="function">main</code> actually was 117called: profile data only contains sums.</p> 118</div> 119<div class="sect2"> 120<div class="titlepage"><div><div><h3 class="title"> 121<a name="cl-format.overview.associations"></a>3.1.3.�Associations</h3></div></div></div> 122<p>The most important extension to the original format of Cachegrind is the 123ability to specify call relationship among functions. More generally, you 124specify associations among positions. For this, the second part of the 125file also can contain association specifications. These look similar to 126position specifications, but consist of two lines. For calls, the format 127looks like 128</p> 129<pre class="screen"> 130 calls=(Call Count) (Target position) 131 (Source position) (Inclusive cost of call) 132</pre> 133<p>The destination only specifies subpositions like line number. Therefore, 134to be able to specify a call to another function in another source file, you 135have to precede the above lines with a "cfn=" specification for the name of the 136called function, and optionally a "cfi=" specification if the function is in 137another source file ("cfl=" is an alternative specification for "cfi=" because 138of historical reasons, and both should be supported by format readers). 139The second line looks like a regular cost line with the difference 140that inclusive cost spent inside of the function call has to be specified.</p> 141<p>Other associations are for example (conditional) jumps. See the 142reference below for details.</p> 143</div> 144<div class="sect2"> 145<div class="titlepage"><div><div><h3 class="title"> 146<a name="cl-format.overview.example2"></a>3.1.4.�Extended Example</h3></div></div></div> 147<p>The following example shows 3 functions, <code class="function">main</code>, 148<code class="function">func1</code>, and <code class="function">func2</code>. Function 149<code class="function">main</code> calls <code class="function">func1</code> once and 150<code class="function">func2</code> 3 times. <code class="function">func1</code> calls 151<code class="function">func2</code> 2 times. 152 153</p> 154<pre class="screen"># callgrind format 155events: Instructions 156 157fl=file1.c 158fn=main 15916 20 160cfn=func1 161calls=1 50 16216 400 163cfi=file2.c 164cfn=func2 165calls=3 20 16616 400 167 168fn=func1 16951 100 170cfi=file2.c 171cfn=func2 172calls=2 20 17351 300 174 175fl=file2.c 176fn=func2 17720 700</pre> 178<p>One can see that in <code class="function">main</code> only code from line 16 179is executed where also the other functions are called. Inclusive cost of 180<code class="function">main</code> is 820, which is the sum of self cost 20 and costs 181spent in the calls: 400 for the single call to <code class="function">func1</code> 182and 400 as sum for the three calls to <code class="function">func2</code>.</p> 183<p>Function <code class="function">func1</code> is located in 184<code class="filename">file1.c</code>, the same as <code class="function">main</code>. 185Therefore, a "cfi=" specification for the call to <code class="function">func1</code> 186is not needed. The function <code class="function">func1</code> only consists of code 187at line 51 of <code class="filename">file1.c</code>, where <code class="function">func2</code> 188is called.</p> 189</div> 190<div class="sect2"> 191<div class="titlepage"><div><div><h3 class="title"> 192<a name="cl-format.overview.compression1"></a>3.1.5.�Name Compression</h3></div></div></div> 193<p>With the introduction of association specifications like calls it is 194needed to specify the same function or same file name multiple times. As 195absolute filenames or symbol names in C++ can be quite long, it is advantageous 196to be able to specify integer IDs for position specifications. 197Here, the term "position" corresponds to a file name (source or object file) 198or function name.</p> 199<p>To support name compression, a position specification can be not only of 200the format "spec=name", but also "spec=(ID) name" to specify a mapping of an 201integer ID to a name, and "spec=(ID)" to reference a previously defined ID 202mapping. There is a separate ID mapping for each position specification, 203i.e. you can use ID 1 for both a file name and a symbol name.</p> 204<p>With string compression, the example from above looks like this: 205</p> 206<pre class="screen"># callgrind format 207events: Instructions 208 209fl=(1) file1.c 210fn=(1) main 21116 20 212cfn=(2) func1 213calls=1 50 21416 400 215cfi=(2) file2.c 216cfn=(3) func2 217calls=3 20 21816 400 219 220fn=(2) 22151 100 222cfi=(2) 223cfn=(3) 224calls=2 20 22551 300 226 227fl=(2) 228fn=(3) 22920 700</pre> 230<p>As position specifications carry no information themselves, but only change 231the meaning of subsequent cost lines or associations, they can appear 232everywhere in the file without any negative consequence. Especially, you can 233define name compression mappings directly after the header, and before any cost 234lines. Thus, the above example can also be written as 235</p> 236<pre class="screen"># callgrind format 237events: Instructions 238 239# define file ID mapping 240fl=(1) file1.c 241fl=(2) file2.c 242# define function ID mapping 243fn=(1) main 244fn=(2) func1 245fn=(3) func2 246 247fl=(1) 248fn=(1) 24916 20 250...</pre> 251</div> 252<div class="sect2"> 253<div class="titlepage"><div><div><h3 class="title"> 254<a name="cl-format.overview.compression2"></a>3.1.6.�Subposition Compression</h3></div></div></div> 255<p>If a Callgrind data file should hold costs for each assembler instruction 256of a program, you specify subposition "instr" in the "positions:" header line, 257and each cost line has to include the address of some instruction. Addresses 258are allowed to have a size of 64 bits to support 64-bit architectures. Thus, 259repeating similar, long addresses for almost every line in the data file can 260enlarge the file size quite significantly, and 261motivates for subposition compression: instead of every cost line starting with 262a 16 character long address, one is allowed to specify relative addresses. 263This relative specification is not only allowed for instruction addresses, but 264also for line numbers; both addresses and line numbers are called "subpositions".</p> 265<p>A relative subposition always is based on the corresponding subposition 266of the last cost line, and starts with a "+" to specify a positive difference, 267a "-" to specify a negative difference, or consists of "*" to specify the same 268subposition. Because absolute subpositions always are positive (ie. never 269prefixed by "-"), any relative specification is non-ambiguous; additionally, 270absolute and relative subposition specifications can be mixed freely. 271Assume the following example (subpositions can always be specified 272as hexadecimal numbers, beginning with "0x"): 273</p> 274<pre class="screen"># callgrind format 275positions: instr line 276events: ticks 277 278fn=func 2790x80001234 90 1 2800x80001237 90 5 2810x80001238 91 6</pre> 282<p>With subposition compression, this looks like 283</p> 284<pre class="screen"># callgrind format 285positions: instr line 286events: ticks 287 288fn=func 2890x80001234 90 1 290+3 * 5 291+1 +1 6</pre> 292<p>Remark: For assembler annotation to work, instruction addresses have to 293be corrected to correspond to addresses found in the original binary. I.e. for 294relocatable shared objects, often a load offset has to be subtracted.</p> 295</div> 296<div class="sect2"> 297<div class="titlepage"><div><div><h3 class="title"> 298<a name="cl-format.overview.misc"></a>3.1.7.�Miscellaneous</h3></div></div></div> 299<div class="sect3"> 300<div class="titlepage"><div><div><h4 class="title"> 301<a name="cl-format.overview.misc.summary"></a>3.1.7.1.�Cost Summary Information</h4></div></div></div> 302<p>For the visualization to be able to show cost percentage, a sum of the 303cost of the full run has to be known. Usually, it is assumed that this is the 304sum of all cost lines in a file. But sometimes, this is not correct. Thus, you 305can specify a "summary:" line in the header giving the full cost for the 306profile run. An import filter may use this to show a progress bar 307while loading a large data file.</p> 308</div> 309<div class="sect3"> 310<div class="titlepage"><div><div><h4 class="title"> 311<a name="cl-format.overview.misc.events"></a>3.1.7.2.�Long Names for Event Types and inherited Types</h4></div></div></div> 312<p>Event types for cost lines are specified in the "events:" line with an 313abbreviated name. For visualization, it makes sense to be able to specify some 314longer, more descriptive name. For an event type "Ir" which means "Instruction 315Fetches", this can be specified the header line 316</p> 317<pre class="screen">event: Ir : Instruction Fetches 318events: Ir Dr</pre> 319<p>In this example, "Dr" itself has no long name associated. The order of 320"event:" lines and the "events:" line is of no importance. Additionally, 321inherited event types can be introduced for which no raw data is available, but 322which are calculated from given types. Suppose the last example, you could add 323</p> 324<pre class="screen">event: Sum = Ir + Dr</pre> 325<p> 326to specify an additional event type "Sum", which is calculated by adding costs 327for "Ir and "Dr".</p> 328</div> 329</div> 330</div> 331<div class="sect1"> 332<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 333<a name="cl-format.reference"></a>3.2.�Reference</h2></div></div></div> 334<div class="sect2"> 335<div class="titlepage"><div><div><h3 class="title"> 336<a name="cl-format.reference.grammar"></a>3.2.1.�Grammar</h3></div></div></div> 337<p> 338</p> 339<pre class="screen">ProfileDataFile := FormatSpec? FormatVersion? Creator? PartData*</pre> 340<p> 341</p> 342<pre class="screen">FormatSpec := "# callgrind format\n"</pre> 343<p> 344</p> 345<pre class="screen">FormatVersion := "version: 1\n"</pre> 346<p> 347</p> 348<pre class="screen">Creator := "creator:" NoNewLineChar* "\n"</pre> 349<p> 350</p> 351<pre class="screen">PartData := (HeaderLine "\n")+ (BodyLine "\n")+</pre> 352<p> 353</p> 354<pre class="screen">HeaderLine := (empty line) 355 | ('#' NoNewLineChar*) 356 | PartDetail 357 | Description 358 | EventSpecification 359 | CostLineDef</pre> 360<p> 361</p> 362<pre class="screen">PartDetail := TargetCommand | TargetID</pre> 363<p> 364</p> 365<pre class="screen">TargetCommand := "cmd:" Space* NoNewLineChar*</pre> 366<p> 367</p> 368<pre class="screen">TargetID := ("pid"|"thread"|"part") ":" Space* Number</pre> 369<p> 370</p> 371<pre class="screen">Description := "desc:" Space* Name Space* ":" NoNewLineChar*</pre> 372<p> 373</p> 374<pre class="screen">EventSpecification := "event:" Space* Name InheritedDef? LongNameDef?</pre> 375<p> 376</p> 377<pre class="screen">InheritedDef := "=" InheritedExpr</pre> 378<p> 379</p> 380<pre class="screen">InheritedExpr := Name 381 | Number Space* ("*" Space*)? Name 382 | InheritedExpr Space* "+" Space* InheritedExpr</pre> 383<p> 384</p> 385<pre class="screen">LongNameDef := ":" NoNewLineChar*</pre> 386<p> 387</p> 388<pre class="screen">CostLineDef := "events:" Space* Name (Space+ Name)* 389 | "positions:" "instr"? (Space+ "line")?</pre> 390<p> 391</p> 392<pre class="screen">BodyLine := (empty line) 393 | ('#' NoNewLineChar*) 394 | CostLine 395 | PositionSpec 396 | CallSpec 397 | UncondJumpSpec 398 | CondJumpSpec</pre> 399<p> 400</p> 401<pre class="screen">CostLine := SubPositionList Costs?</pre> 402<p> 403</p> 404<pre class="screen">SubPositionList := (SubPosition+ Space+)+</pre> 405<p> 406</p> 407<pre class="screen">SubPosition := Number | "+" Number | "-" Number | "*"</pre> 408<p> 409</p> 410<pre class="screen">Costs := (Number Space+)+</pre> 411<p> 412</p> 413<pre class="screen">PositionSpec := Position "=" Space* PositionName</pre> 414<p> 415</p> 416<pre class="screen">Position := CostPosition | CalledPosition</pre> 417<p> 418</p> 419<pre class="screen">CostPosition := "ob" | "fl" | "fi" | "fe" | "fn"</pre> 420<p> 421</p> 422<pre class="screen">CalledPosition := " "cob" | "cfi" | "cfl" | "cfn"</pre> 423<p> 424</p> 425<pre class="screen">PositionName := ( "(" Number ")" )? (Space* NoNewLineChar* )?</pre> 426<p> 427</p> 428<pre class="screen">CallSpec := CallLine "\n" CostLine</pre> 429<p> 430</p> 431<pre class="screen">CallLine := "calls=" Space* Number Space+ SubPositionList</pre> 432<p> 433</p> 434<pre class="screen">UncondJumpSpec := "jump=" Space* Number Space+ SubPositionList</pre> 435<p> 436</p> 437<pre class="screen">CondJumpSpec := "jcnd=" Space* Number Space+ Number Space+ SubPositionList</pre> 438<p> 439</p> 440<pre class="screen">Space := " " | "\t"</pre> 441<p> 442</p> 443<pre class="screen">Number := HexNumber | (Digit)+</pre> 444<p> 445</p> 446<pre class="screen">Digit := "0" | ... | "9"</pre> 447<p> 448</p> 449<pre class="screen">HexNumber := "0x" (Digit | HexChar)+</pre> 450<p> 451</p> 452<pre class="screen">HexChar := "a" | ... | "f" | "A" | ... | "F"</pre> 453<p> 454</p> 455<pre class="screen">Name = Alpha (Digit | Alpha)*</pre> 456<p> 457</p> 458<pre class="screen">Alpha = "a" | ... | "z" | "A" | ... | "Z"</pre> 459<p> 460</p> 461<pre class="screen">NoNewLineChar := all characters without "\n"</pre> 462<p> 463</p> 464<p>A profile data file ("ProfileDataFile") starts with basic information 465 such as a format marker, the version and creator information, and then has a list of parts, where 466 each part has its own header and body. Parts typically are different threads 467 and/or time spans/phases within a profiled application run.</p> 468<p>Note that callgrind_annotate currently only supports profile data files with 469 one part. Callgrind may produce multiple parts for one profile run, but defaults 470 to one output file for each part.</p> 471</div> 472<div class="sect2"> 473<div class="titlepage"><div><div><h3 class="title"> 474<a name="cl-format.reference.header"></a>3.2.2.�Description of Header Lines</h3></div></div></div> 475<p>Basic information in the first lines of a profile data file:</p> 476<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 477<li class="listitem"> 478<p><code class="computeroutput"># callgrind format</code> [Callgrind]</p> 479<p>This line specifies that the file is a callgrind profile, 480 and it has to be the first line. It was added late to the 481 format (with Valgrind 3.13) and is optional, as all readers also 482 should work with older callgrind profiles not including this line. 483 However, generation of this line is recommended to allow desktop 484 environments and file managers to uniquely detect the format.</p> 485</li> 486<li class="listitem"> 487<p><code class="computeroutput">version: number</code> [Callgrind]</p> 488<p>This is used to distinguish future profile data formats. A 489 major version of 0 or 1 is supposed to be upwards compatible with 490 Cachegrind's format. It is optional; if not appearing, version 1 491 is assumed. Otherwise, it has to follow directly after the format 492 specification (i.e. be the first line if the optional format 493 specification is skipped).</p> 494</li> 495<li class="listitem"> 496<p><code class="computeroutput">creator: string</code> [Callgrind]</p> 497<p>This is an arbitrary string to denote the creator of this file. 498 Optional.</p> 499</li> 500</ul></div> 501<p>The header for each part has an arbitrary number of lines of the format 502"key: value". Possible <span class="emphasis"><em>key</em></span> values for the header are:</p> 503<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 504<li class="listitem"> 505<p><code class="computeroutput">pid: process id</code> [Callgrind]</p> 506<p>Optional. This specifies the process ID of the supervised application 507 for which this profile was generated.</p> 508</li> 509<li class="listitem"> 510<p><code class="computeroutput">cmd: program name + args</code> [Cachegrind]</p> 511<p>Optional. This specifies the full command line of the supervised 512 application for which this profile was generated.</p> 513</li> 514<li class="listitem"> 515<p><code class="computeroutput">part: number</code> [Callgrind]</p> 516<p>Optional. This specifies a sequentially incremented number for each dump 517 generated, starting at 1.</p> 518</li> 519<li class="listitem"> 520<p><code class="computeroutput">desc: type: value</code> [Cachegrind]</p> 521<p>This specifies various information for this dump. For some 522 types, the semantic is defined, but any description type is allowed. 523 Unknown types should be ignored.</p> 524<p>There are the types "I1 cache", "D1 cache", "LL cache", which 525 specify parameters used for the cache simulator. These are the only 526 types originally used by Cachegrind. Additionally, Callgrind uses 527 the following types: "Timerange" gives a rough range of the basic 528 block counter, for which the cost of this dump was collected. 529 Type "Trigger" states the reason of why this trace was generated. 530 E.g. program termination or forced interactive dump.</p> 531</li> 532<li class="listitem"> 533<p><code class="computeroutput">positions: [instr] [line]</code> [Callgrind]</p> 534<p>For cost lines, this defines the semantic of the first numbers. 535 Any combination of "instr", "bb" and "line" is allowed, but has to be 536 in this order which corresponds to position numbers at the start of 537 the cost lines later in the file.</p> 538<p>If "instr" is specified, the position is the address of an 539 instruction whose execution raised the events given later on the 540 line. This address is relative to the offset of the binary/shared 541 library file to not have to specify relocation info. For "line", 542 the position is the line number of a source file, which is 543 responsible for the events raised. Note that the mapping of "instr" 544 and "line" positions are given by the debugging line information 545 produced by the compiler.</p> 546<p>This header line is optional, defaulting to "positions: 547 line" if not specified.</p> 548</li> 549<li class="listitem"> 550<p><code class="computeroutput">events: event type abbreviations</code> [Cachegrind]</p> 551<p>A list of short names of the event types logged in cost 552 lines in this part of the profile data file. Arbitrary short 553 names are allowed. The order given specifies the required order 554 in cost lines. Thus, the first event type is the second or third 555 number in a cost line, depending on the value of "positions". 556 Required to appear for each header part exactly once.</p> 557</li> 558<li class="listitem"> 559<p><code class="computeroutput">summary: costs</code> [Callgrind]</p> 560<p>Optional. This header line specifies a summary cost, which should be 561 equal or larger than a total over all self costs. It may be larger as 562 the cost lines may not represent all cost of the program run.</p> 563</li> 564<li class="listitem"> 565<p><code class="computeroutput">totals: costs</code> [Cachegrind]</p> 566<p>Optional. Should appear at the end of the file (although 567 looking like a header line). Must give the total of all cost lines, 568 to allow for a consistency check.</p> 569</li> 570</ul></div> 571</div> 572<div class="sect2"> 573<div class="titlepage"><div><div><h3 class="title"> 574<a name="cl-format.reference.body"></a>3.2.3.�Description of Body Lines</h3></div></div></div> 575<p>The regular body line is a cost line consisting of one or two 576position numbers (depending on "positions:" header line, see above) 577and an array of cost numbers. A position number either is a 578line numbers into a source file or an instruction address within binary 579code, with source/binary file names specified as position names (see 580below). The cost numbers get mapped to event types in the same order 581as specified in the "events:" header line. If less numbers than event 582types are given, the costs default to zero for the remaining event 583types.</p> 584<p>Further, there exist lines 585<code class="computeroutput">spec=position name</code>. A position name 586is an arbitrary string. If it starts with "(" and a 587digit, it's a string in compressed format. Otherwise it's the real 588position string. This allows for file and symbol names as position 589strings, as these never start with "(" + <span class="emphasis"><em>digit</em></span>. 590The compressed format is either "(" <span class="emphasis"><em>number</em></span> ")" 591<span class="emphasis"><em>space</em></span> <span class="emphasis"><em>position</em></span> or only 592"(" <span class="emphasis"><em>number</em></span> ")". The first relates 593<span class="emphasis"><em>position</em></span> to <span class="emphasis"><em>number</em></span> in the 594context of the given format specification from this line to the end of 595the file; it makes the (<span class="emphasis"><em>number</em></span>) an alias for 596<span class="emphasis"><em>position</em></span>. Compressed format is always 597optional.</p> 598<p>Position specifications allowed:</p> 599<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 600<li class="listitem"> 601<p><code class="computeroutput">ob=</code> [Callgrind]</p> 602<p>The ELF object where the cost of next cost lines happens.</p> 603</li> 604<li class="listitem"><p><code class="computeroutput">fl=</code> [Cachegrind]</p></li> 605<li class="listitem"><p><code class="computeroutput">fi=</code> [Cachegrind]</p></li> 606<li class="listitem"> 607<p><code class="computeroutput">fe=</code> [Cachegrind]</p> 608<p>The source file including the code which is responsible for 609 the cost of next cost lines. "fi="/"fe=" is used when the source 610 file changes inside of a function, i.e. for inlined code.</p> 611</li> 612<li class="listitem"> 613<p><code class="computeroutput">fn=</code> [Cachegrind]</p> 614<p>The name of the function where the cost of next cost lines 615 happens.</p> 616</li> 617<li class="listitem"> 618<p><code class="computeroutput">cob=</code> [Callgrind]</p> 619<p>The ELF object of the target of the next call cost lines.</p> 620</li> 621<li class="listitem"> 622<p><code class="computeroutput">cfi=</code> [Callgrind]</p> 623<p>The source file including the code of the target of the 624 next call cost lines.</p> 625</li> 626<li class="listitem"> 627<p><code class="computeroutput">cfl=</code> [Callgrind]</p> 628<p>Alternative spelling for <code class="computeroutput">cfi=</code> 629 specification (because of historical reasons).</p> 630</li> 631<li class="listitem"> 632<p><code class="computeroutput">cfn=</code> [Callgrind]</p> 633<p>The name of the target function of the next call cost 634 lines.</p> 635</li> 636</ul></div> 637<p>The last type of body line provides specific costs not just 638related to one position as regular cost lines. It starts with specific 639strings similar to position name specifications.</p> 640<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 641<li class="listitem"> 642<p><code class="computeroutput">calls=count target-position</code> [Callgrind]</p> 643<p>Call executed "count" times to "target-position". 644 After a "calls=" line there MUST be a cost line. This provides the source position 645 of the call and the cost spent in the called function in total.</p> 646</li> 647<li class="listitem"> 648<p><code class="computeroutput">jump=count target-position</code> [Callgrind]</p> 649<p>Unconditional jump, executed "count" times, to "target-position".</p> 650</li> 651<li class="listitem"> 652<p><code class="computeroutput">jcnd=exe-count jump-count target-position</code> [Callgrind]</p> 653<p>Conditional jump, executed "exe-count" times with "jump-count" jumps 654 happening (rest is fall-through) to "target-position".</p> 655</li> 656</ul></div> 657</div> 658</div> 659</div> 660<div> 661<br><table class="nav" width="100%" cellspacing="3" cellpadding="2" border="0" summary="Navigation footer"> 662<tr> 663<td rowspan="2" width="40%" align="left"> 664<a accesskey="p" href="manual-writing-tools.html"><<�2.�Writing a New Valgrind Tool</a>�</td> 665<td width="20%" align="center"><a accesskey="u" href="tech-docs.html">Up</a></td> 666<td rowspan="2" width="40%" align="right">�<a accesskey="n" href="dist.html">Valgrind Distribution Documents�>></a> 667</td> 668</tr> 669<tr><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td></tr> 670</table> 671</div> 672</body> 673</html> 674
