Elliott Hughes | a0664b9 | 2017-04-18 17:46:52 -0700 | [diff] [blame] | 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"> |
Elliott Hughes | ed39800 | 2017-06-21 14:41:24 -0700 | [diff] [blame] | 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> |
Elliott Hughes | a0664b9 | 2017-04-18 17:46:52 -0700 | [diff] [blame] | 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> |
Elliott Hughes | ed39800 | 2017-06-21 14:41:24 -0700 | [diff] [blame] | 44 | <p>This chapter describes the Callgrind Format, Version 1.</p> |
Elliott Hughes | a0664b9 | 2017-04-18 17:46:52 -0700 | [diff] [blame] | 45 | <p>The format description is meant for the user to be able to understand the |
| 46 | file contents; but more important, it is given for authors of measurement or |
| 47 | visualization 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. |
| 52 | It is written by Callgrind, and it is upwards compatible |
| 53 | to the format used by Cachegrind (ie. Cachegrind uses a subset). It can |
| 54 | be read by callgrind_annotate and KCachegrind.</p> |
| 55 | <p>This chapter gives on overview of format features and examples. |
| 56 | For 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> |
Elliott Hughes | ed39800 | 2017-06-21 14:41:24 -0700 | [diff] [blame] | 60 | <p>To uniquely specify that a file is a callgrind profile, it |
| 61 | should add "# callgrind format" as first line. This is optional but |
| 62 | recommended for easy format detection.</p> |
Elliott Hughes | a0664b9 | 2017-04-18 17:46:52 -0700 | [diff] [blame] | 63 | <p>Each file has a header part of an arbitrary number of lines of the |
| 64 | format "key: value". After the header, lines specifying profile costs |
| 65 | follow. Everywhere, comments on own lines starting with '#' are allowed. |
| 66 | The header lines with keys "positions" and "events" define |
| 67 | the 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 |
| 69 | of event type names. Cost lines consist of subpositions followed by 64-bit |
| 70 | counters for the events, in the order specified by the "positions" and "events" |
| 71 | header line.</p> |
| 72 | <p>The "events" header line is always required in contrast to the optional |
| 73 | line for "positions", which defaults to "line", i.e. a line number of some |
| 74 | source file. In addition, the second part of the file contains position |
| 75 | specifications of the form "spec=name". "spec" can be e.g. "fn" for a |
| 76 | function name or "fl" for a file name. Cost lines are always related to |
| 77 | the 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 |
| 83 | related to event names used by Callgrind. Especially, cycle counts matching |
| 84 | real processors probably will never be generated by any Valgrind tools, as these |
| 85 | are bound to simulations of simple machine models for acceptable slowdown. |
| 86 | However, any profiling tool could use the format described in this chapter.</p> |
| 87 | <p> |
| 88 | </p> |
Elliott Hughes | ed39800 | 2017-06-21 14:41:24 -0700 | [diff] [blame] | 89 | <pre class="screen"># callgrind format |
| 90 | events: Cycles Instructions Flops |
Elliott Hughes | a0664b9 | 2017-04-18 17:46:52 -0700 | [diff] [blame] | 91 | fl=file.f |
| 92 | fn=main |
| 93 | 15 90 14 2 |
| 94 | 16 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 |
| 97 | passed by, number of executed instructions, and number of floating point |
| 98 | operations executed while running code corresponding to some source |
| 99 | position. As there is no line specifying the value of "positions", it defaults |
| 100 | to "line", which means that the first number of a cost line is always a line |
| 101 | number.</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 |
| 105 | the 14 instructions executed were floating point operations. Similarly, the |
| 106 | next line specifies that there were 12 instructions executed in the context |
| 107 | of function <code class="function">main</code> which can be related to line 16 in |
| 108 | file <code class="filename">file.f</code>, taking 20 CPU cycles. If a cost line |
| 109 | specifies less event counts than given in the "events" line, the rest is |
| 110 | assumed to be zero. I.e. there was no floating point instruction executed |
| 111 | relating to line 16.</p> |
| 112 | <p>Note that regular cost lines always give self (also called exclusive) |
| 113 | cost of code at a given position. If you specify multiple cost lines for the |
| 114 | same position, these will be summed up. On the other hand, in the example above |
| 115 | there is no specification of how many times function |
| 116 | <code class="function">main</code> actually was |
| 117 | called: 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 |
| 123 | ability to specify call relationship among functions. More generally, you |
| 124 | specify associations among positions. For this, the second part of the |
| 125 | file also can contain association specifications. These look similar to |
| 126 | position specifications, but consist of two lines. For calls, the format |
| 127 | looks 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, |
| 134 | to be able to specify a call to another function in another source file, you |
| 135 | have to precede the above lines with a "cfn=" specification for the name of the |
| 136 | called function, and optionally a "cfi=" specification if the function is in |
| 137 | another source file ("cfl=" is an alternative specification for "cfi=" because |
| 138 | of historical reasons, and both should be supported by format readers). |
| 139 | The second line looks like a regular cost line with the difference |
| 140 | that inclusive cost spent inside of the function call has to be specified.</p> |
| 141 | <p>Other associations are for example (conditional) jumps. See the |
| 142 | reference 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. |
Elliott Hughes | ed39800 | 2017-06-21 14:41:24 -0700 | [diff] [blame] | 152 | |
Elliott Hughes | a0664b9 | 2017-04-18 17:46:52 -0700 | [diff] [blame] | 153 | </p> |
Elliott Hughes | ed39800 | 2017-06-21 14:41:24 -0700 | [diff] [blame] | 154 | <pre class="screen"># callgrind format |
| 155 | events: Instructions |
Elliott Hughes | a0664b9 | 2017-04-18 17:46:52 -0700 | [diff] [blame] | 156 | |
| 157 | fl=file1.c |
| 158 | fn=main |
| 159 | 16 20 |
| 160 | cfn=func1 |
| 161 | calls=1 50 |
| 162 | 16 400 |
| 163 | cfi=file2.c |
| 164 | cfn=func2 |
| 165 | calls=3 20 |
| 166 | 16 400 |
| 167 | |
| 168 | fn=func1 |
| 169 | 51 100 |
| 170 | cfi=file2.c |
| 171 | cfn=func2 |
| 172 | calls=2 20 |
| 173 | 51 300 |
| 174 | |
| 175 | fl=file2.c |
| 176 | fn=func2 |
| 177 | 20 700</pre> |
| 178 | <p>One can see that in <code class="function">main</code> only code from line 16 |
| 179 | is 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 |
| 181 | spent in the calls: 400 for the single call to <code class="function">func1</code> |
| 182 | and 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>. |
| 185 | Therefore, a "cfi=" specification for the call to <code class="function">func1</code> |
| 186 | is not needed. The function <code class="function">func1</code> only consists of code |
| 187 | at line 51 of <code class="filename">file1.c</code>, where <code class="function">func2</code> |
| 188 | is 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 |
| 194 | needed to specify the same function or same file name multiple times. As |
| 195 | absolute filenames or symbol names in C++ can be quite long, it is advantageous |
| 196 | to be able to specify integer IDs for position specifications. |
| 197 | Here, the term "position" corresponds to a file name (source or object file) |
| 198 | or function name.</p> |
| 199 | <p>To support name compression, a position specification can be not only of |
| 200 | the format "spec=name", but also "spec=(ID) name" to specify a mapping of an |
| 201 | integer ID to a name, and "spec=(ID)" to reference a previously defined ID |
| 202 | mapping. There is a separate ID mapping for each position specification, |
| 203 | i.e. you can use ID 1 for both a file name and a symbol name.</p> |
Elliott Hughes | ed39800 | 2017-06-21 14:41:24 -0700 | [diff] [blame] | 204 | <p>With string compression, the example from above looks like this: |
Elliott Hughes | a0664b9 | 2017-04-18 17:46:52 -0700 | [diff] [blame] | 205 | </p> |
Elliott Hughes | ed39800 | 2017-06-21 14:41:24 -0700 | [diff] [blame] | 206 | <pre class="screen"># callgrind format |
| 207 | events: Instructions |
Elliott Hughes | a0664b9 | 2017-04-18 17:46:52 -0700 | [diff] [blame] | 208 | |
| 209 | fl=(1) file1.c |
| 210 | fn=(1) main |
| 211 | 16 20 |
| 212 | cfn=(2) func1 |
| 213 | calls=1 50 |
| 214 | 16 400 |
| 215 | cfi=(2) file2.c |
| 216 | cfn=(3) func2 |
| 217 | calls=3 20 |
| 218 | 16 400 |
| 219 | |
| 220 | fn=(2) |
| 221 | 51 100 |
| 222 | cfi=(2) |
| 223 | cfn=(3) |
| 224 | calls=2 20 |
| 225 | 51 300 |
| 226 | |
| 227 | fl=(2) |
| 228 | fn=(3) |
| 229 | 20 700</pre> |
| 230 | <p>As position specifications carry no information themselves, but only change |
| 231 | the meaning of subsequent cost lines or associations, they can appear |
| 232 | everywhere in the file without any negative consequence. Especially, you can |
| 233 | define name compression mappings directly after the header, and before any cost |
| 234 | lines. Thus, the above example can also be written as |
| 235 | </p> |
Elliott Hughes | ed39800 | 2017-06-21 14:41:24 -0700 | [diff] [blame] | 236 | <pre class="screen"># callgrind format |
| 237 | events: Instructions |
Elliott Hughes | a0664b9 | 2017-04-18 17:46:52 -0700 | [diff] [blame] | 238 | |
| 239 | # define file ID mapping |
| 240 | fl=(1) file1.c |
| 241 | fl=(2) file2.c |
| 242 | # define function ID mapping |
| 243 | fn=(1) main |
| 244 | fn=(2) func1 |
| 245 | fn=(3) func2 |
| 246 | |
| 247 | fl=(1) |
| 248 | fn=(1) |
| 249 | 16 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 |
| 256 | of a program, you specify subposition "instr" in the "positions:" header line, |
| 257 | and each cost line has to include the address of some instruction. Addresses |
| 258 | are allowed to have a size of 64 bits to support 64-bit architectures. Thus, |
| 259 | repeating similar, long addresses for almost every line in the data file can |
| 260 | enlarge the file size quite significantly, and |
| 261 | motivates for subposition compression: instead of every cost line starting with |
| 262 | a 16 character long address, one is allowed to specify relative addresses. |
| 263 | This relative specification is not only allowed for instruction addresses, but |
| 264 | also for line numbers; both addresses and line numbers are called "subpositions".</p> |
| 265 | <p>A relative subposition always is based on the corresponding subposition |
| 266 | of the last cost line, and starts with a "+" to specify a positive difference, |
| 267 | a "-" to specify a negative difference, or consists of "*" to specify the same |
| 268 | subposition. Because absolute subpositions always are positive (ie. never |
| 269 | prefixed by "-"), any relative specification is non-ambiguous; additionally, |
| 270 | absolute and relative subposition specifications can be mixed freely. |
| 271 | Assume the following example (subpositions can always be specified |
| 272 | as hexadecimal numbers, beginning with "0x"): |
| 273 | </p> |
Elliott Hughes | ed39800 | 2017-06-21 14:41:24 -0700 | [diff] [blame] | 274 | <pre class="screen"># callgrind format |
| 275 | positions: instr line |
Elliott Hughes | a0664b9 | 2017-04-18 17:46:52 -0700 | [diff] [blame] | 276 | events: ticks |
| 277 | |
| 278 | fn=func |
| 279 | 0x80001234 90 1 |
| 280 | 0x80001237 90 5 |
| 281 | 0x80001238 91 6</pre> |
| 282 | <p>With subposition compression, this looks like |
| 283 | </p> |
Elliott Hughes | ed39800 | 2017-06-21 14:41:24 -0700 | [diff] [blame] | 284 | <pre class="screen"># callgrind format |
| 285 | positions: instr line |
Elliott Hughes | a0664b9 | 2017-04-18 17:46:52 -0700 | [diff] [blame] | 286 | events: ticks |
| 287 | |
| 288 | fn=func |
| 289 | 0x80001234 90 1 |
| 290 | +3 * 5 |
| 291 | +1 +1 6</pre> |
| 292 | <p>Remark: For assembler annotation to work, instruction addresses have to |
| 293 | be corrected to correspond to addresses found in the original binary. I.e. for |
| 294 | relocatable 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 |
| 303 | cost of the full run has to be known. Usually, it is assumed that this is the |
| 304 | sum of all cost lines in a file. But sometimes, this is not correct. Thus, you |
| 305 | can specify a "summary:" line in the header giving the full cost for the |
| 306 | profile run. An import filter may use this to show a progress bar |
| 307 | while 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 |
| 313 | abbreviated name. For visualization, it makes sense to be able to specify some |
| 314 | longer, more descriptive name. For an event type "Ir" which means "Instruction |
| 315 | Fetches", this can be specified the header line |
| 316 | </p> |
| 317 | <pre class="screen">event: Ir : Instruction Fetches |
| 318 | events: 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, |
| 321 | inherited event types can be introduced for which no raw data is available, but |
| 322 | which 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> |
| 326 | to specify an additional event type "Sum", which is calculated by adding costs |
| 327 | for "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> |
Elliott Hughes | ed39800 | 2017-06-21 14:41:24 -0700 | [diff] [blame] | 339 | <pre class="screen">ProfileDataFile := FormatSpec? FormatVersion? Creator? PartData*</pre> |
| 340 | <p> |
| 341 | </p> |
| 342 | <pre class="screen">FormatSpec := "# callgrind format\n"</pre> |
Elliott Hughes | a0664b9 | 2017-04-18 17:46:52 -0700 | [diff] [blame] | 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 |
Elliott Hughes | ed39800 | 2017-06-21 14:41:24 -0700 | [diff] [blame] | 465 | such as a format marker, the version and creator information, and then has a list of parts, where |
Elliott Hughes | a0664b9 | 2017-04-18 17:46:52 -0700 | [diff] [blame] | 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"> |
Elliott Hughes | ed39800 | 2017-06-21 14:41:24 -0700 | [diff] [blame] | 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"> |
Elliott Hughes | a0664b9 | 2017-04-18 17:46:52 -0700 | [diff] [blame] | 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 |
Elliott Hughes | ed39800 | 2017-06-21 14:41:24 -0700 | [diff] [blame] | 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> |
Elliott Hughes | a0664b9 | 2017-04-18 17:46:52 -0700 | [diff] [blame] | 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 |
| 576 | position numbers (depending on "positions:" header line, see above) |
| 577 | and an array of cost numbers. A position number either is a |
| 578 | line numbers into a source file or an instruction address within binary |
| 579 | code, with source/binary file names specified as position names (see |
| 580 | below). The cost numbers get mapped to event types in the same order |
| 581 | as specified in the "events:" header line. If less numbers than event |
| 582 | types are given, the costs default to zero for the remaining event |
| 583 | types.</p> |
| 584 | <p>Further, there exist lines |
| 585 | <code class="computeroutput">spec=position name</code>. A position name |
| 586 | is an arbitrary string. If it starts with "(" and a |
| 587 | digit, it's a string in compressed format. Otherwise it's the real |
| 588 | position string. This allows for file and symbol names as position |
| 589 | strings, as these never start with "(" + <span class="emphasis"><em>digit</em></span>. |
| 590 | The 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 |
| 594 | context of the given format specification from this line to the end of |
| 595 | the 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 |
| 597 | optional.</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 |
| 638 | related to one position as regular cost lines. It starts with specific |
| 639 | strings 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> |