weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame] | 1 | <?xml version="1.0"?> <!-- -*- sgml -*- --> |
| 2 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| 3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
njn | efd7ef7 | 2009-08-07 07:44:31 +0000 | [diff] [blame] | 4 | [ <!ENTITY % vg-entities SYSTEM "../../docs/xml/vg-entities.xml"> %vg-entities; ]> |
weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame] | 5 | |
| 6 | <chapter id="cl-format" xreflabel="Callgrind Format Specification"> |
| 7 | <title>Callgrind Format Specification</title> |
| 8 | |
| 9 | <para>This chapter describes the Callgrind Profile Format, Version 1.</para> |
| 10 | |
| 11 | <para>A synonymous name is "Calltree Profile Format". These names actually mean |
| 12 | the same since Callgrind was previously named Calltree.</para> |
| 13 | |
| 14 | <para>The format description is meant for the user to be able to understand the |
| 15 | file contents; but more important, it is given for authors of measurement or |
| 16 | visualization tools to be able to write and read this format.</para> |
| 17 | |
| 18 | <sect1 id="cl-format.overview" xreflabel="Overview"> |
| 19 | <title>Overview</title> |
| 20 | |
| 21 | <para>The profile data format is ASCII based. |
| 22 | It is written by Callgrind, and it is upwards compatible |
| 23 | to the format used by Cachegrind (ie. Cachegrind uses a subset). It can |
| 24 | be read by callgrind_annotate and KCachegrind.</para> |
| 25 | |
| 26 | <para>This chapter gives on overview of format features and examples. |
| 27 | For detailed syntax, look at the format reference.</para> |
| 28 | |
| 29 | <sect2 id="cl-format.overview.basics" xreflabel="Basic Structure"> |
| 30 | <title>Basic Structure</title> |
| 31 | |
| 32 | <para>Each file has a header part of an arbitrary number of lines of the |
| 33 | format "key: value". The lines with key "positions" and "events" define |
| 34 | the meaning of cost lines in the second part of the file: the value of |
| 35 | "positions" is a list of subpositions, and the value of "events" is a list |
| 36 | of event type names. Cost lines consist of subpositions followed by 64-bit |
| 37 | counters for the events, in the order specified by the "positions" and "events" |
| 38 | header line.</para> |
| 39 | |
| 40 | <para>The "events" header line is always required in contrast to the optional |
| 41 | line for "positions", which defaults to "line", i.e. a line number of some |
| 42 | source file. In addition, the second part of the file contains position |
| 43 | specifications of the form "spec=name". "spec" can be e.g. "fn" for a |
| 44 | function name or "fl" for a file name. Cost lines are always related to |
| 45 | the function/file specifications given directly before.</para> |
| 46 | |
| 47 | </sect2> |
| 48 | |
| 49 | <sect2 id="cl-format.overview.example1" xreflabel="Simple Example"> |
| 50 | <title>Simple Example</title> |
| 51 | |
weidendo | 362f783 | 2007-05-24 18:04:42 +0000 | [diff] [blame] | 52 | <para>The event names in the following example are quite arbitrary, and are not |
| 53 | related to event names used by Callgrind. Especially, cycle counts matching |
| 54 | real processors probably will never be generated by any Valgrind tools, as these |
| 55 | are bound to simulations of simple machine models for acceptable slowdown. |
| 56 | However, any profiling tool could use the format described in this chapter.</para> |
| 57 | |
weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame] | 58 | <para> |
| 59 | <screen>events: Cycles Instructions Flops |
| 60 | fl=file.f |
| 61 | fn=main |
| 62 | 15 90 14 2 |
| 63 | 16 20 12</screen></para> |
| 64 | |
| 65 | <para>The above example gives profile information for event types "Cycles", |
| 66 | "Instructions", and "Flops". Thus, cost lines give the number of CPU cycles |
| 67 | passed by, number of executed instructions, and number of floating point |
| 68 | operations executed while running code corresponding to some source |
| 69 | position. As there is no line specifying the value of "positions", it defaults |
| 70 | to "line", which means that the first number of a cost line is always a line |
| 71 | number.</para> |
| 72 | |
| 73 | <para>Thus, the first cost line specifies that in line 15 of source file |
njn | 92f99bb | 2009-08-07 05:40:26 +0000 | [diff] [blame] | 74 | <filename>file.f</filename> there is code belonging to function |
| 75 | <function>main</function>. While running, 90 CPU cycles passed by, and 2 of |
| 76 | the 14 instructions executed were floating point operations. Similarly, the |
| 77 | next line specifies that there were 12 instructions executed in the context |
| 78 | of function <function>main</function> which can be related to line 16 in |
| 79 | file <filename>file.f</filename>, taking 20 CPU cycles. If a cost line |
| 80 | specifies less event counts than given in the "events" line, the rest is |
| 81 | assumed to be zero. I.e. there was no floating point instruction executed |
| 82 | relating to line 16.</para> |
weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame] | 83 | |
| 84 | <para>Note that regular cost lines always give self (also called exclusive) |
| 85 | cost of code at a given position. If you specify multiple cost lines for the |
| 86 | same position, these will be summed up. On the other hand, in the example above |
njn | 92f99bb | 2009-08-07 05:40:26 +0000 | [diff] [blame] | 87 | there is no specification of how many times function |
| 88 | <function>main</function> actually was |
weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame] | 89 | called: profile data only contains sums.</para> |
| 90 | |
| 91 | </sect2> |
| 92 | |
| 93 | |
| 94 | <sect2 id="cl-format.overview.associations" xreflabel="Associations"> |
| 95 | <title>Associations</title> |
| 96 | |
| 97 | <para>The most important extension to the original format of Cachegrind is the |
| 98 | ability to specify call relationship among functions. More generally, you |
sewardj | 3387889 | 2007-11-17 09:43:25 +0000 | [diff] [blame] | 99 | specify associations among positions. For this, the second part of the |
| 100 | file also can contain association specifications. These look similar to |
weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame] | 101 | position specifications, but consist of 2 lines. For calls, the format |
| 102 | looks like |
| 103 | <screen> |
| 104 | calls=(Call Count) (Destination position) |
| 105 | (Source position) (Inclusive cost of call) |
| 106 | </screen></para> |
| 107 | |
| 108 | <para>The destination only specifies subpositions like line number. Therefore, |
| 109 | to be able to specify a call to another function in another source file, you |
| 110 | have to precede the above lines with a "cfn=" specification for the name of the |
| 111 | called function, and a "cfl=" specification if the function is in another |
| 112 | source file. The 2nd line looks like a regular cost line with the difference |
| 113 | that inclusive cost spent inside of the function call has to be specified.</para> |
| 114 | |
sewardj | 3387889 | 2007-11-17 09:43:25 +0000 | [diff] [blame] | 115 | <para>Other associations which or for example (conditional) jumps. See the |
weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame] | 116 | reference below for details.</para> |
| 117 | |
| 118 | </sect2> |
| 119 | |
| 120 | |
| 121 | <sect2 id="cl-format.overview.example2" xreflabel="Extended Example"> |
| 122 | <title>Extended Example</title> |
| 123 | |
njn | 92f99bb | 2009-08-07 05:40:26 +0000 | [diff] [blame] | 124 | <para>The following example shows 3 functions, <function>main</function>, |
| 125 | <function>func1</function>, and <function>func2</function>. Function |
| 126 | <function>main</function> calls <function>func1</function> once and |
| 127 | <function>func2</function> 3 times. <function>func1</function> calls |
| 128 | <function>func2</function> 2 times. |
weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame] | 129 | <screen>events: Instructions |
| 130 | |
| 131 | fl=file1.c |
| 132 | fn=main |
| 133 | 16 20 |
| 134 | cfn=func1 |
| 135 | calls=1 50 |
| 136 | 16 400 |
| 137 | cfl=file2.c |
| 138 | cfn=func2 |
| 139 | calls=3 20 |
| 140 | 16 400 |
| 141 | |
| 142 | fn=func1 |
| 143 | 51 100 |
| 144 | cfl=file2.c |
| 145 | cfn=func2 |
| 146 | calls=2 20 |
| 147 | 51 300 |
| 148 | |
| 149 | fl=file2.c |
| 150 | fn=func2 |
| 151 | 20 700</screen></para> |
| 152 | |
njn | 92f99bb | 2009-08-07 05:40:26 +0000 | [diff] [blame] | 153 | <para>One can see that in <function>main</function> only code from line 16 |
| 154 | is executed where also the other functions are called. Inclusive cost of |
| 155 | <function>main</function> is 820, which is the sum of self cost 20 and costs |
| 156 | spent in the calls: 400 for the single call to <function>func1</function> |
| 157 | and 400 as sum for the three calls to <function>func2</function>.</para> |
weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame] | 158 | |
njn | 92f99bb | 2009-08-07 05:40:26 +0000 | [diff] [blame] | 159 | <para>Function <function>func1</function> is located in |
| 160 | <filename>file1.c</filename>, the same as <function>main</function>. |
| 161 | Therefore, a "cfl=" specification for the call to <function>func1</function> |
| 162 | is not needed. The function <function>func1</function> only consists of code |
| 163 | at line 51 of <filename>file1.c</filename>, where <function>func2</function> |
| 164 | is called.</para> |
weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame] | 165 | |
| 166 | </sect2> |
| 167 | |
| 168 | |
| 169 | <sect2 id="cl-format.overview.compression1" xreflabel="Name Compression"> |
| 170 | <title>Name Compression</title> |
| 171 | |
| 172 | <para>With the introduction of association specifications like calls it is |
| 173 | needed to specify the same function or same file name multiple times. As |
| 174 | absolute filenames or symbol names in C++ can be quite long, it is advantageous |
weidendo | 52d4d1a | 2007-08-28 21:52:45 +0000 | [diff] [blame] | 175 | to be able to specify integer IDs for position specifications. |
| 176 | Here, the term "position" corresponds to a file name (source or object file) |
| 177 | or function name.</para> |
weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame] | 178 | |
| 179 | <para>To support name compression, a position specification can be not only of |
| 180 | the format "spec=name", but also "spec=(ID) name" to specify a mapping of an |
| 181 | integer ID to a name, and "spec=(ID)" to reference a previously defined ID |
| 182 | mapping. There is a separate ID mapping for each position specification, |
| 183 | i.e. you can use ID 1 for both a file name and a symbol name.</para> |
| 184 | |
| 185 | <para>With string compression, the example from 1.4 looks like this: |
| 186 | <screen>events: Instructions |
| 187 | |
| 188 | fl=(1) file1.c |
| 189 | fn=(1) main |
| 190 | 16 20 |
| 191 | cfn=(2) func1 |
| 192 | calls=1 50 |
| 193 | 16 400 |
| 194 | cfl=(2) file2.c |
| 195 | cfn=(3) func2 |
| 196 | calls=3 20 |
| 197 | 16 400 |
| 198 | |
| 199 | fn=(2) |
| 200 | 51 100 |
| 201 | cfl=(2) |
| 202 | cfn=(3) |
| 203 | calls=2 20 |
| 204 | 51 300 |
| 205 | |
| 206 | fl=(2) |
| 207 | fn=(3) |
| 208 | 20 700</screen></para> |
| 209 | |
sewardj | 3387889 | 2007-11-17 09:43:25 +0000 | [diff] [blame] | 210 | <para>As position specifications carry no information themselves, but only change |
weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame] | 211 | the meaning of subsequent cost lines or associations, they can appear |
| 212 | everywhere in the file without any negative consequence. Especially, you can |
| 213 | define name compression mappings directly after the header, and before any cost |
| 214 | lines. Thus, the above example can also be written as |
| 215 | <screen>events: Instructions |
| 216 | |
| 217 | # define file ID mapping |
| 218 | fl=(1) file1.c |
| 219 | fl=(2) file2.c |
| 220 | # define function ID mapping |
| 221 | fn=(1) main |
| 222 | fn=(2) func1 |
| 223 | fn=(3) func2 |
| 224 | |
| 225 | fl=(1) |
| 226 | fn=(1) |
| 227 | 16 20 |
| 228 | ...</screen></para> |
| 229 | |
| 230 | </sect2> |
| 231 | |
| 232 | |
| 233 | <sect2 id="cl-format.overview.compression2" xreflabel="Subposition Compression"> |
| 234 | <title>Subposition Compression</title> |
| 235 | |
weidendo | 52d4d1a | 2007-08-28 21:52:45 +0000 | [diff] [blame] | 236 | <para>If a Callgrind data file should hold costs for each assembler instruction |
sewardj | 3387889 | 2007-11-17 09:43:25 +0000 | [diff] [blame] | 237 | of a program, you specify subposition "instr" in the "positions:" header line, |
weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame] | 238 | and each cost line has to include the address of some instruction. Addresses |
njn | 92f99bb | 2009-08-07 05:40:26 +0000 | [diff] [blame] | 239 | are allowed to have a size of 64 bits to support 64-bit architectures. Thus, |
weidendo | 52d4d1a | 2007-08-28 21:52:45 +0000 | [diff] [blame] | 240 | repeating similar, long addresses for almost every line in the data file can |
| 241 | enlarge the file size quite significantly, and |
weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame] | 242 | motivates for subposition compression: instead of every cost line starting with |
weidendo | 52d4d1a | 2007-08-28 21:52:45 +0000 | [diff] [blame] | 243 | a 16 character long address, one is allowed to specify relative addresses. |
| 244 | This relative specification is not only allowed for instruction addresses, but |
| 245 | also for line numbers; both addresses and line numbers are called "subpositions".</para> |
weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame] | 246 | |
| 247 | <para>A relative subposition always is based on the corresponding subposition |
| 248 | of the last cost line, and starts with a "+" to specify a positive difference, |
| 249 | a "-" to specify a negative difference, or consists of "*" to specify the same |
weidendo | 52d4d1a | 2007-08-28 21:52:45 +0000 | [diff] [blame] | 250 | subposition. Because absolute subpositions always are positive (ie. never |
sewardj | 3387889 | 2007-11-17 09:43:25 +0000 | [diff] [blame] | 251 | prefixed by "-"), any relative specification is non-ambiguous; additionally, |
weidendo | 52d4d1a | 2007-08-28 21:52:45 +0000 | [diff] [blame] | 252 | absolute and relative subposition specifications can be mixed freely. |
| 253 | Assume the following example (subpositions can always be specified |
weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame] | 254 | as hexadecimal numbers, beginning with "0x"): |
| 255 | <screen>positions: instr line |
| 256 | events: ticks |
| 257 | |
| 258 | fn=func |
| 259 | 0x80001234 90 1 |
| 260 | 0x80001237 90 5 |
| 261 | 0x80001238 91 6</screen></para> |
| 262 | |
| 263 | <para>With subposition compression, this looks like |
| 264 | <screen>positions: instr line |
| 265 | events: ticks |
| 266 | |
| 267 | fn=func |
| 268 | 0x80001234 90 1 |
| 269 | +3 * 5 |
| 270 | +1 +1 6</screen></para> |
| 271 | |
| 272 | <para>Remark: For assembler annotation to work, instruction addresses have to |
| 273 | be corrected to correspond to addresses found in the original binary. I.e. for |
| 274 | relocatable shared objects, often a load offset has to be subtracted.</para> |
| 275 | |
| 276 | </sect2> |
| 277 | |
| 278 | |
| 279 | <sect2 id="cl-format.overview.misc" xreflabel="Miscellaneous"> |
| 280 | <title>Miscellaneous</title> |
| 281 | |
| 282 | <sect3 id="cl-format.overview.misc.summary" xreflabel="Cost Summary Information"> |
| 283 | <title>Cost Summary Information</title> |
| 284 | |
| 285 | <para>For the visualization to be able to show cost percentage, a sum of the |
| 286 | cost of the full run has to be known. Usually, it is assumed that this is the |
| 287 | sum of all cost lines in a file. But sometimes, this is not correct. Thus, you |
| 288 | can specify a "summary:" line in the header giving the full cost for the |
| 289 | profile run. This has another effect: a import filter can show a progress bar |
| 290 | while loading a large data file if he knows to cost sum in advance.</para> |
| 291 | |
| 292 | </sect3> |
| 293 | |
| 294 | <sect3 id="cl-format.overview.misc.events" xreflabel="Long Names for Event Types and inherited Types"> |
| 295 | <title>Long Names for Event Types and inherited Types</title> |
| 296 | |
| 297 | <para>Event types for cost lines are specified in the "events:" line with an |
| 298 | abbreviated name. For visualization, it makes sense to be able to specify some |
| 299 | longer, more descriptive name. For an event type "Ir" which means "Instruction |
| 300 | Fetches", this can be specified the header line |
| 301 | <screen>event: Ir : Instruction Fetches |
| 302 | events: Ir Dr</screen></para> |
| 303 | |
sewardj | 3387889 | 2007-11-17 09:43:25 +0000 | [diff] [blame] | 304 | <para>In this example, "Dr" itself has no long name associated. The order of |
weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame] | 305 | "event:" lines and the "events:" line is of no importance. Additionally, |
| 306 | inherited event types can be introduced for which no raw data is available, but |
| 307 | which are calculated from given types. Suppose the last example, you could add |
| 308 | <screen>event: Sum = Ir + Dr</screen> |
| 309 | to specify an additional event type "Sum", which is calculated by adding costs |
| 310 | for "Ir and "Dr".</para> |
| 311 | |
| 312 | </sect3> |
| 313 | |
| 314 | </sect2> |
| 315 | |
| 316 | </sect1> |
| 317 | |
| 318 | <sect1 id="cl-format.reference" xreflabel="Reference"> |
| 319 | <title>Reference</title> |
| 320 | |
| 321 | <sect2 id="cl-format.reference.grammar" xreflabel="Grammar"> |
| 322 | <title>Grammar</title> |
| 323 | |
| 324 | <para> |
| 325 | <screen>ProfileDataFile := FormatVersion? Creator? PartData*</screen> |
| 326 | <screen>FormatVersion := "version:" Space* Number "\n"</screen> |
| 327 | <screen>Creator := "creator:" NoNewLineChar* "\n"</screen> |
| 328 | <screen>PartData := (HeaderLine "\n")+ (BodyLine "\n")+</screen> |
| 329 | <screen>HeaderLine := (empty line) |
| 330 | | ('#' NoNewLineChar*) |
| 331 | | PartDetail |
| 332 | | Description |
| 333 | | EventSpecification |
| 334 | | CostLineDef</screen> |
| 335 | <screen>PartDetail := TargetCommand | TargetID</screen> |
| 336 | <screen>TargetCommand := "cmd:" Space* NoNewLineChar*</screen> |
| 337 | <screen>TargetID := ("pid"|"thread"|"part") ":" Space* Number</screen> |
| 338 | <screen>Description := "desc:" Space* Name Space* ":" NoNewLineChar*</screen> |
| 339 | <screen>EventSpecification := "event:" Space* Name InheritedDef? LongNameDef?</screen> |
| 340 | <screen>InheritedDef := "=" InheritedExpr</screen> |
| 341 | <screen>InheritedExpr := Name |
| 342 | | Number Space* ("*" Space*)? Name |
| 343 | | InheritedExpr Space* "+" Space* InheritedExpr</screen> |
| 344 | <screen>LongNameDef := ":" NoNewLineChar*</screen> |
| 345 | <screen>CostLineDef := "events:" Space* Name (Space+ Name)* |
| 346 | | "positions:" "instr"? (Space+ "line")?</screen> |
| 347 | <screen>BodyLine := (empty line) |
| 348 | | ('#' NoNewLineChar*) |
| 349 | | CostLine |
| 350 | | PositionSpecification |
sewardj | 3387889 | 2007-11-17 09:43:25 +0000 | [diff] [blame] | 351 | | AssociationSpecification</screen> |
weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame] | 352 | <screen>CostLine := SubPositionList Costs?</screen> |
| 353 | <screen>SubPositionList := (SubPosition+ Space+)+</screen> |
| 354 | <screen>SubPosition := Number | "+" Number | "-" Number | "*"</screen> |
| 355 | <screen>Costs := (Number Space+)+</screen> |
| 356 | <screen>PositionSpecification := Position "=" Space* PositionName</screen> |
| 357 | <screen>Position := CostPosition | CalledPosition</screen> |
| 358 | <screen>CostPosition := "ob" | "fl" | "fi" | "fe" | "fn"</screen> |
| 359 | <screen>CalledPosition := " "cob" | "cfl" | "cfn"</screen> |
| 360 | <screen>PositionName := ( "(" Number ")" )? (Space* NoNewLineChar* )?</screen> |
sewardj | 3387889 | 2007-11-17 09:43:25 +0000 | [diff] [blame] | 361 | <screen>AssociationSpecification := CallSpecification |
weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame] | 362 | | JumpSpecification</screen> |
| 363 | <screen>CallSpecification := CallLine "\n" CostLine</screen> |
| 364 | <screen>CallLine := "calls=" Space* Number Space+ SubPositionList</screen> |
| 365 | <screen>JumpSpecification := ...</screen> |
| 366 | <screen>Space := " " | "\t"</screen> |
| 367 | <screen>Number := HexNumber | (Digit)+</screen> |
| 368 | <screen>Digit := "0" | ... | "9"</screen> |
| 369 | <screen>HexNumber := "0x" (Digit | HexChar)+</screen> |
| 370 | <screen>HexChar := "a" | ... | "f" | "A" | ... | "F"</screen> |
| 371 | <screen>Name = Alpha (Digit | Alpha)*</screen> |
| 372 | <screen>Alpha = "a" | ... | "z" | "A" | ... | "Z"</screen> |
| 373 | <screen>NoNewLineChar := all characters without "\n"</screen> |
| 374 | </para> |
| 375 | |
| 376 | </sect2> |
| 377 | |
| 378 | <sect2 id="cl-format.reference.header" xreflabel="Description of Header Lines"> |
| 379 | <title>Description of Header Lines</title> |
| 380 | |
| 381 | <para>The header has an arbitrary number of lines of the format |
| 382 | "key: value". Possible <emphasis>key</emphasis> values for the header are:</para> |
| 383 | |
| 384 | <itemizedlist> |
| 385 | |
| 386 | <listitem> |
| 387 | <para><computeroutput>version: number</computeroutput> [Callgrind]</para> |
| 388 | <para>This is used to distinguish future profile data formats. A |
| 389 | major version of 0 or 1 is supposed to be upwards compatible with |
njn | 92f99bb | 2009-08-07 05:40:26 +0000 | [diff] [blame] | 390 | Cachegrind's format. It is optional; if not appearing, version 1 |
weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame] | 391 | is supposed. Otherwise, this has to be the first header line.</para> |
| 392 | </listitem> |
| 393 | |
| 394 | <listitem> |
| 395 | <para><computeroutput>pid: process id</computeroutput> [Callgrind]</para> |
| 396 | <para>This specifies the process ID of the supervised application |
| 397 | for which this profile was generated.</para> |
| 398 | </listitem> |
| 399 | |
| 400 | <listitem> |
| 401 | <para><computeroutput>cmd: program name + args</computeroutput> [Cachegrind]</para> |
| 402 | <para>This specifies the full command line of the supervised |
| 403 | application for which this profile was generated.</para> |
| 404 | </listitem> |
| 405 | |
| 406 | <listitem> |
| 407 | <para><computeroutput>part: number</computeroutput> [Callgrind]</para> |
| 408 | <para>This specifies a sequentially incremented number for each dump |
| 409 | generated, starting at 1.</para> |
| 410 | </listitem> |
| 411 | |
| 412 | <listitem> |
| 413 | <para><computeroutput>desc: type: value</computeroutput> [Cachegrind]</para> |
| 414 | <para>This specifies various information for this dump. For some |
| 415 | types, the semantic is defined, but any description type is allowed. |
| 416 | Unknown types should be ignored.</para> |
njn | 2d853a1 | 2010-10-06 22:46:31 +0000 | [diff] [blame^] | 417 | <para>There are the types "I1 cache", "D1 cache", "LL cache", which |
weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame] | 418 | specify parameters used for the cache simulator. These are the only |
| 419 | types originally used by Cachegrind. Additionally, Callgrind uses |
| 420 | the following types: "Timerange" gives a rough range of the basic |
| 421 | block counter, for which the cost of this dump was collected. |
| 422 | Type "Trigger" states the reason of why this trace was generated. |
| 423 | E.g. program termination or forced interactive dump.</para> |
| 424 | </listitem> |
| 425 | |
| 426 | <listitem> |
| 427 | <para><computeroutput>positions: [instr] [line]</computeroutput> [Callgrind]</para> |
| 428 | <para>For cost lines, this defines the semantic of the first numbers. |
| 429 | Any combination of "instr", "bb" and "line" is allowed, but has to be |
| 430 | in this order which corresponds to position numbers at the start of |
| 431 | the cost lines later in the file.</para> |
| 432 | <para>If "instr" is specified, the position is the address of an |
| 433 | instruction whose execution raised the events given later on the |
| 434 | line. This address is relative to the offset of the binary/shared |
| 435 | library file to not have to specify relocation info. For "line", |
| 436 | the position is the line number of a source file, which is |
| 437 | responsible for the events raised. Note that the mapping of "instr" |
| 438 | and "line" positions are given by the debugging line information |
| 439 | produced by the compiler.</para> |
| 440 | <para>This field is optional. If not specified, "line" is supposed |
| 441 | only.</para> |
| 442 | </listitem> |
| 443 | |
| 444 | <listitem> |
sewardj | 3387889 | 2007-11-17 09:43:25 +0000 | [diff] [blame] | 445 | <para><computeroutput>events: event type abbreviations</computeroutput> [Cachegrind]</para> |
weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame] | 446 | <para>A list of short names of the event types logged in this file. |
| 447 | The order is the same as in cost lines. The first event type is the |
| 448 | second or third number in a cost line, depending on the value of |
| 449 | "positions". Callgrind does not add additional cost types. Specify |
| 450 | exactly once.</para> |
| 451 | <para>Cost types from original Cachegrind are: |
| 452 | <itemizedlist> |
| 453 | <listitem> |
| 454 | <para><command>Ir</command>: Instruction read access</para> |
| 455 | </listitem> |
| 456 | <listitem> |
| 457 | <para><command>I1mr</command>: Instruction Level 1 read cache miss</para> |
| 458 | </listitem> |
| 459 | <listitem> |
njn | 2d853a1 | 2010-10-06 22:46:31 +0000 | [diff] [blame^] | 460 | <para><command>ILmr</command>: Instruction last-level read cache miss</para> |
weidendo | af0e723 | 2006-03-20 10:29:30 +0000 | [diff] [blame] | 461 | </listitem> |
| 462 | <listitem> |
| 463 | <para>...</para> |
| 464 | </listitem> |
| 465 | </itemizedlist> |
| 466 | </para> |
| 467 | </listitem> |
| 468 | |
| 469 | <listitem> |
| 470 | <para><computeroutput>summary: costs</computeroutput> [Callgrind]</para> |
| 471 | <para><computeroutput>totals: costs</computeroutput> [Cachegrind]</para> |
| 472 | <para>The value or the total number of events covered by this trace |
| 473 | file. Both keys have the same meaning, but the "totals:" line |
| 474 | happens to be at the end of the file, while "summary:" appears in |
| 475 | the header. This was added to allow postprocessing tools to know |
| 476 | in advance to total cost. The two lines always give the same cost |
| 477 | counts.</para> |
| 478 | </listitem> |
| 479 | |
| 480 | </itemizedlist> |
| 481 | |
| 482 | </sect2> |
| 483 | |
| 484 | <sect2 id="cl-format.reference.body" xreflabel="Description of Body Lines"> |
| 485 | <title>Description of Body Lines</title> |
| 486 | |
| 487 | <para>There exist lines |
| 488 | <computeroutput>spec=position</computeroutput>. The values for position |
| 489 | specifications are arbitrary strings. When starting with "(" and a |
| 490 | digit, it's a string in compressed format. Otherwise it's the real |
| 491 | position string. This allows for file and symbol names as position |
| 492 | strings, as these never start with "(" + <emphasis>digit</emphasis>. |
| 493 | The compressed format is either "(" <emphasis>number</emphasis> ")" |
| 494 | <emphasis>space</emphasis> <emphasis>position</emphasis> or only |
| 495 | "(" <emphasis>number</emphasis> ")". The first relates |
| 496 | <emphasis>position</emphasis> to <emphasis>number</emphasis> in the |
| 497 | context of the given format specification from this line to the end of |
| 498 | the file; it makes the (<emphasis>number</emphasis>) an alias for |
| 499 | <emphasis>position</emphasis>. Compressed format is always |
| 500 | optional.</para> |
| 501 | |
| 502 | <para>Position specifications allowed:</para> |
| 503 | <itemizedlist> |
| 504 | |
| 505 | <listitem> |
| 506 | <para><computeroutput>ob=</computeroutput> [Callgrind]</para> |
| 507 | <para>The ELF object where the cost of next cost lines happens.</para> |
| 508 | </listitem> |
| 509 | |
| 510 | <listitem> |
| 511 | <para><computeroutput>fl=</computeroutput> [Cachegrind]</para> |
| 512 | </listitem> |
| 513 | |
| 514 | <listitem> |
| 515 | <para><computeroutput>fi=</computeroutput> [Cachegrind]</para> |
| 516 | </listitem> |
| 517 | |
| 518 | <listitem> |
| 519 | <para><computeroutput>fe=</computeroutput> [Cachegrind]</para> |
| 520 | <para>The source file including the code which is responsible for |
| 521 | the cost of next cost lines. "fi="/"fe=" is used when the source |
| 522 | file changes inside of a function, i.e. for inlined code.</para> |
| 523 | </listitem> |
| 524 | |
| 525 | <listitem> |
| 526 | <para><computeroutput>fn=</computeroutput> [Cachegrind]</para> |
| 527 | <para>The name of the function where the cost of next cost lines |
| 528 | happens.</para> |
| 529 | </listitem> |
| 530 | |
| 531 | <listitem> |
| 532 | <para><computeroutput>cob=</computeroutput> [Callgrind]</para> |
| 533 | <para>The ELF object of the target of the next call cost lines.</para> |
| 534 | </listitem> |
| 535 | |
| 536 | <listitem> |
| 537 | <para><computeroutput>cfl=</computeroutput> [Callgrind]</para> |
| 538 | <para>The source file including the code of the target of the |
| 539 | next call cost lines.</para> |
| 540 | </listitem> |
| 541 | |
| 542 | <listitem> |
| 543 | <para><computeroutput>cfn=</computeroutput> [Callgrind]</para> |
| 544 | <para>The name of the target function of the next call cost |
| 545 | lines.</para> |
| 546 | </listitem> |
| 547 | |
| 548 | <listitem> |
| 549 | <para><computeroutput>calls=</computeroutput> [Callgrind]</para> |
| 550 | <para>The number of nonrecursive calls which are responsible for the |
| 551 | cost specified by the next call cost line. This is the cost spent |
| 552 | inside of the called function.</para> |
| 553 | <para>After "calls=" there MUST be a cost line. This is the cost |
| 554 | spent in the called function. The first number is the source line |
| 555 | from where the call happened.</para> |
| 556 | </listitem> |
| 557 | |
| 558 | <listitem> |
| 559 | <para><computeroutput>jump=count target position</computeroutput> [Callgrind]</para> |
| 560 | <para>Unconditional jump, executed count times, to the given target |
| 561 | position.</para> |
| 562 | </listitem> |
| 563 | |
| 564 | <listitem> |
| 565 | <para><computeroutput>jcnd=exe.count jumpcount target position</computeroutput> [Callgrind]</para> |
| 566 | <para>Conditional jump, executed exe.count times with jumpcount |
| 567 | jumps to the given target position.</para> |
| 568 | </listitem> |
| 569 | |
| 570 | </itemizedlist> |
| 571 | |
| 572 | </sect2> |
| 573 | |
| 574 | </sect1> |
| 575 | |
weidendo | 362f783 | 2007-05-24 18:04:42 +0000 | [diff] [blame] | 576 | </chapter> |