cl-format.html
字号:
<html xmlns:cf="http://docbook.sourceforge.net/xmlns/chunkfast/1.0"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>3.燙allgrind Format Specification</title><link rel="stylesheet" href="vg_basic.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.69.0"><link rel="start" href="index.html" title="Valgrind Documentation"><link rel="up" href="tech-docs.html" title="Valgrind Technical Documentation"><link rel="prev" href="cg-tech-docs.html" title="2.燞ow Cachegrind works"><link rel="next" href="writing-tools.html" title="4.燱riting a New Valgrind Tool"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div><table class="nav" width="100%" cellspacing="3" cellpadding="3" border="0" summary="Navigation header"><tr><td width="22px" align="center" valign="middle"><a accesskey="p" href="cg-tech-docs.html"><img src="images/prev.png" width="18" height="21" border="0" alt="Prev"></a></td><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><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><th align="center" valign="middle">Valgrind Technical Documentation</th><td width="22px" align="center" valign="middle"><a accesskey="n" href="writing-tools.html"><img src="images/next.png" width="18" height="21" border="0" alt="Next"></a></td></tr></table></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="cl-format"></a>3.燙allgrind Format Specification</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="cl-format.html#cl-format.overview">3.1. Overview</a></span></dt><dd><dl><dt><span class="sect2"><a href="cl-format.html#cl-format.overview.basics">3.1.1. Basic Structure</a></span></dt><dt><span class="sect2"><a href="cl-format.html#cl-format.overview.example1">3.1.2. Simple Example</a></span></dt><dt><span class="sect2"><a href="cl-format.html#cl-format.overview.associations">3.1.3. Associations</a></span></dt><dt><span class="sect2"><a href="cl-format.html#cl-format.overview.example2">3.1.4. Extended Example</a></span></dt><dt><span class="sect2"><a href="cl-format.html#cl-format.overview.compression1">3.1.5. Name Compression</a></span></dt><dt><span class="sect2"><a href="cl-format.html#cl-format.overview.compression2">3.1.6. Subposition Compression</a></span></dt><dt><span class="sect2"><a href="cl-format.html#cl-format.overview.misc">3.1.7. Miscellaneous</a></span></dt></dl></dd><dt><span class="sect1"><a href="cl-format.html#cl-format.reference">3.2. Reference</a></span></dt><dd><dl><dt><span class="sect2"><a href="cl-format.html#cl-format.reference.grammar">3.2.1. Grammar</a></span></dt><dt><span class="sect2"><a href="cl-format.html#cl-format.reference.header">3.2.2. Description of Header Lines</a></span></dt><dt><span class="sect2"><a href="cl-format.html#cl-format.reference.body">3.2.3. Description of Body Lines</a></span></dt></dl></dd></dl></div><p>This chapter describes the Callgrind Profile Format, Version 1.</p><p>A synonymous name is "Calltree Profile Format". These names actually meanthe same since Callgrind was previously named Calltree.</p><p>The format description is meant for the user to be able to understand thefile contents; but more important, it is given for authors of measurement orvisualization tools to be able to write and read this format.</p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cl-format.overview"></a>3.1.燨verview</h2></div></div></div><p>The profile data format is ASCII based.It is written by Callgrind, and it is upwards compatibleto the format used by Cachegrind (ie. Cachegrind uses a subset). It canbe read by callgrind_annotate and KCachegrind.</p><p>This chapter gives on overview of format features and examples.For detailed syntax, look at the format reference.</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="cl-format.overview.basics"></a>3.1.1.燘asic Structure</h3></div></div></div><p>Each file has a header part of an arbitrary number of lines of theformat "key: value". The lines with key "positions" and "events" definethe meaning of cost lines in the second part of the file: the value of"positions" is a list of subpositions, and the value of "events" is a listof event type names. Cost lines consist of subpositions followed by 64-bitcounters for the events, in the order specified by the "positions" and "events"header line.</p><p>The "events" header line is always required in contrast to the optionalline for "positions", which defaults to "line", i.e. a line number of somesource file. In addition, the second part of the file contains positionspecifications of the form "spec=name". "spec" can be e.g. "fn" for afunction name or "fl" for a file name. Cost lines are always related tothe function/file specifications given directly before.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="cl-format.overview.example1"></a>3.1.2.燬imple Example</h3></div></div></div><p></p><pre class="screen">events: Cycles Instructions Flopsfl=file.ffn=main15 90 14 216 20 12</pre><p>The above example gives profile information for event types "Cycles","Instructions", and "Flops". Thus, cost lines give the number of CPU cyclespassed by, number of executed instructions, and number of floating pointoperations executed while running code corresponding to some sourceposition. As there is no line specifying the value of "positions", it defaultsto "line", which means that the first number of a cost line is always a linenumber.</p><p>Thus, the first cost line specifies that in line 15 of source file"file.f" there is code belonging to function "main". While running, 90 CPUcycles passed by, and 2 of the 14 instructions executed were floating pointoperations. Similarily, the next line specifies that there were 12 instructionsexecuted in the context of function "main" which can be related to line 16 infile "file.f", taking 20 CPU cycles. If a cost line specifies less event countsthan given in the "events" line, the rest is assumed to be zero. I.e., therewas no floating point instruction executed relating to line 16.</p><p>Note that regular cost lines always give self (also called exclusive)cost of code at a given position. If you specify multiple cost lines for thesame position, these will be summed up. On the other hand, in the example abovethere is no specification of how many times function "main" actually wascalled: profile data only contains sums.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="cl-format.overview.associations"></a>3.1.3.燗ssociations</h3></div></div></div><p>The most important extension to the original format of Cachegrind is theability to specify call relationship among functions. More generally, youspecify assoziations among positions. For this, the second part of thefile also can contain assoziation specifications. These look similar toposition specifications, but consist of 2 lines. For calls, the formatlooks like </p><pre class="screen"> calls=(Call Count) (Destination position) (Source position) (Inclusive cost of call)</pre><p>The destination only specifies subpositions like line number. Therefore,to be able to specify a call to another function in another source file, youhave to precede the above lines with a "cfn=" specification for the name of thecalled function, and a "cfl=" specification if the function is in anothersource file. The 2nd line looks like a regular cost line with the differencethat inclusive cost spent inside of the function call has to be specified.</p><p>Other assoziations which or for example (conditional) jumps. See thereference below for details.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="cl-format.overview.example2"></a>3.1.4.燛xtended Example</h3></div></div></div><p>The following example shows 3 functions, "main", "func1", and"func2". Function "main" calls "func1" once and "func2" 3 times. "func1" calls"func2" 2 times.</p><pre class="screen">events: Instructionsfl=file1.cfn=main16 20cfn=func1calls=1 5016 400cfl=file2.ccfn=func2calls=3 2016 400fn=func151 100cfl=file2.ccfn=func2calls=2 2051 300fl=file2.cfn=func220 700</pre><p>One can see that in "main" only code from line 16 is executed where alsothe other functions are called. Inclusive cost of "main" is 420, which is thesum of self cost 20 and costs spent in the calls.</p><p>Function "func1" is located in "file1.c", the same as "main". Therefore,a "cfl=" specification for the call to "func1" is not needed. The function"func1" only consists of code at line 51 of "file1.c", where "func2" is called.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="cl-format.overview.compression1"></a>3.1.5.燦ame Compression</h3></div></div></div><p>With the introduction of association specifications like calls it isneeded to specify the same function or same file name multiple times. Asabsolute filenames or symbol names in C++ can be quite long, it is advantageousto be able to specify integer IDs for position specifications.</p><p>To support name compression, a position specification can be not only ofthe format "spec=name", but also "spec=(ID) name" to specify a mapping of aninteger ID to a name, and "spec=(ID)" to reference a previously defined IDmapping. There is a separate ID mapping for each position specification,i.e. you can use ID 1 for both a file name and a symbol name.</p><p>With string compression, the example from 1.4 looks like this:</p><pre class="screen">events: Instructionsfl=(1) file1.cfn=(1) main16 20cfn=(2) func1calls=1 5016 400cfl=(2) file2.ccfn=(3) func2calls=3 2016 400fn=(2)51 100cfl=(2)cfn=(3)calls=2 2051 300fl=(2)fn=(3)20 700</pre><p>As position specifications carry no information themself, but only changethe meaning of subsequent cost lines or associations, they can appeareverywhere in the file without any negative consequence. Especially, you candefine name compression mappings directly after the header, and before any costlines. Thus, the above example can also be written as</p><pre class="screen">events: Instructions# define file ID mappingfl=(1) file1.cfl=(2) file2.c# define function ID mappingfn=(1) mainfn=(2) func1fn=(3) func2fl=(1)fn=(1)16 20...</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="cl-format.overview.compression2"></a>3.1.6.燬ubposition Compression</h3></div></div></div><p>If a Calltree data file should hold costs for each assembler instructionof a program, you specify subpostion "instr" in the "positions:" header line,and each cost line has to include the address of some instruction. Addressesare allowed to have a size of 64bit to support 64bit architectures. Thismotivates for subposition compression: instead of every cost line starting witha 16 character long address, one is allowed to specify relative subpositions.</p><p>A relative subposition always is based on the corresponding subpositionof the last cost line, and starts with a "+" to specify a positive difference,a "-" to specify a negative difference, or consists of "*" to specify the samesubposition. Assume the following example (subpositions can always be specifiedas hexadecimal numbers, beginning with "0x"):</p><pre class="screen">positions: instr lineevents: ticksfn=func0x80001234 90 10x80001237 90 50x80001238 91 6</pre><p>With subposition compression, this looks like</p><pre class="screen">positions: instr lineevents: ticksfn=func0x80001234 90 1+3 * 5+1 +1 6</pre><p>Remark: For assembler annotation to work, instruction addresses have tobe corrected to correspond to addresses found in the original binary. I.e. forrelocatable shared objects, often a load offset has to be subtracted.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="cl-format.overview.misc"></a>3.1.7.燤iscellaneous</h3></div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="cl-format.overview.misc.summary"></a>3.1.7.1.燙ost Summary Information</h4></div></div></div><p>For the visualization to be able to show cost percentage, a sum of thecost of the full run has to be known. Usually, it is assumed that this is thesum of all cost lines in a file. But sometimes, this is not correct. Thus, youcan specify a "summary:" line in the header giving the full cost for theprofile run. This has another effect: a import filter can show a progress barwhile loading a large data file if he knows to cost sum in advance.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="cl-format.overview.misc.events"></a>3.1.7.2.燣ong Names for Event Types and inherited Types</h4></div></div></div><p>Event types for cost lines are specified in the "events:" line with anabbreviated name. For visualization, it makes sense to be able to specify somelonger, more descriptive name. For an event type "Ir" which means "InstructionFetches", this can be specified the header line</p><pre class="screen">event: Ir : Instruction Fetchesevents: Ir Dr</pre><p>In this example, "Dr" itself has no long name assoziated. The order of"event:" lines and the "events:" line is of no importance. Additionally,inherited event types can be introduced for which no raw data is available, butwhich are calculated from given types. Suppose the last example, you could add</p><pre class="screen">event: Sum = Ir + Dr</pre><p>to specify an additional event type "Sum", which is calculated by adding costsfor "Ir and "Dr".</p></div></div></div><div class="sect1" lang="en">⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -