Gitiles
Code Review Sign In
realtimeroboticsgroup.org / RealtimeRoboticsGroup / test / c44d0d7211e0912562eed939410d594b23b51a43 / . / third_party / gperftools / doc / cpuprofile-fileformat.html
blob: 3f90e6bc78e69ba5fcc28b32387614df123539e1 [file] [log] [blame]
Austin Schuh745610d2015-09-06 18:19:50 -0700[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<HTML>
3
4<HEAD>
5 <link rel="stylesheet" href="designstyle.css">
6 <title>Google CPU Profiler Binary Data File Format</title>
7</HEAD>
8
9<BODY>
10
11<h1>Google CPU Profiler Binary Data File Format</h1>
12
13<p align=right>
14 <i>Last modified
15 <script type=text/javascript>
16 var lm = new Date(document.lastModified);
17 document.write(lm.toDateString());
18 </script></i>
19</p>
20
21<p>This file documents the binary data file format produced by the
22Google CPU Profiler. For information about using the CPU Profiler,
23see <a href="cpuprofile.html">its user guide</a>.
24
25<p>The profiler source code, which generates files using this format, is at
26<code>src/profiler.cc</code></a>.
27
28
29<h2>CPU Profile Data File Structure</h2>
30
31<p>CPU profile data files each consist of four parts, in order:
32
33<ul>
34 <li> Binary header
35 <li> Binary profile records
36 <li> Binary trailer
37 <li> Text list of mapped objects
38</ul>
39
40<p>The binary data is expressed in terms of "slots." These are words
41large enough to hold the program's pointer type, i.e., for 32-bit
42programs they are 4 bytes in size, and for 64-bit programs they are 8
43bytes. They are stored in the profile data file in the native byte
44order (i.e., little-endian for x86 and x86_64).
45
46
47<h2>Binary Header</h2>
48
49<p>The binary header format is show below. Values written by the
50profiler, along with requirements currently enforced by the analysis
51tools, are shown in parentheses.
52
53<p>
54<table summary="Header Format"
55 frame="box" rules="sides" cellpadding="5" width="50%">
56 <tr>
57 <th width="30%">slot</th>
58 <th width="70%">data</th>
59 </tr>
60
61 <tr>
62 <td>0</td>
63 <td>header count (0; must be 0)</td>
64 </tr>
65
66 <tr>
67 <td>1</td>
68 <td>header slots after this one (3; must be &gt;= 3)</td>
69 </tr>
70
71 <tr>
72 <td>2</td>
73 <td>format version (0; must be 0)</td>
74 </tr>
75
76 <tr>
77 <td>3</td>
78 <td>sampling period, in microseconds</td>
79 </tr>
80
81 <tr>
82 <td>4</td>
83 <td>padding (0)</td>
84 </tr>
85</table>
86
87<p>The headers currently generated for 32-bit and 64-bit little-endian
88(x86 and x86_64) profiles are shown below, for comparison.
89
90<p>
91<table summary="Header Example" frame="box" rules="sides" cellpadding="5">
92 <tr>
93 <th></th>
94 <th>hdr count</th>
95 <th>hdr words</th>
96 <th>version</th>
97 <th>sampling period</th>
98 <th>pad</th>
99 </tr>
100 <tr>
101 <td>32-bit or 64-bit (slots)</td>
102 <td>0</td>
103 <td>3</td>
104 <td>0</td>
105 <td>10000</td>
106 <td>0</td>
107 </tr>
108 <tr>
109 <td>32-bit (4-byte words in file)</td>
110 <td><tt>0x00000</tt></td>
111 <td><tt>0x00003</tt></td>
112 <td><tt>0x00000</tt></td>
113 <td><tt>0x02710</tt></td>
114 <td><tt>0x00000</tt></td>
115 </tr>
116 <tr>
117 <td>64-bit LE (4-byte words in file)</td>
118 <td><tt>0x00000&nbsp;0x00000</tt></td>
119 <td><tt>0x00003&nbsp;0x00000</tt></td>
120 <td><tt>0x00000&nbsp;0x00000</tt></td>
121 <td><tt>0x02710&nbsp;0x00000</tt></td>
122 <td><tt>0x00000&nbsp;0x00000</tt></td>
123 </tr>
124</table>
125
126<p>The contents are shown in terms of slots, and in terms of 4-byte
127words in the profile data file. The slot contents for 32-bit and
12864-bit headers are identical. For 32-bit profiles, the 4-byte word
129view matches the slot view. For 64-bit profiles, each (8-byte) slot
130is shown as two 4-byte words, ordered as they would appear in the
131file.
132
133<p>The profiling tools examine the contents of the file and use the
134expected locations and values of the header words field to detect
135whether the file is 32-bit or 64-bit.
136
137
138<h2>Binary Profile Records</h2>
139
140<p>The binary profile record format is shown below.
141
142<p>
143<table summary="Profile Record Format"
144 frame="box" rules="sides" cellpadding="5" width="50%">
145 <tr>
146 <th width="30%">slot</th>
147 <th width="70%">data</th>
148 </tr>
149
150 <tr>
151 <td>0</td>
152 <td>sample count, must be &gt;= 1</td>
153 </tr>
154
155 <tr>
156 <td>1</td>
157 <td>number of call chain PCs (num_pcs), must be &gt;= 1</td>
158 </tr>
159
160 <tr>
161 <td>2 .. (num_pcs + 1)</td>
162 <td>call chain PCs, most-recently-called function first.
163 </tr>
164</table>
165
166<p>The total length of a given record is 2 + num_pcs.
167
168<p>Note that multiple profile records can be emitted by the profiler
169having an identical call chain. In that case, analysis tools should
170sum the counts of all records having identical call chains.
171
172<p><b>Note:</b> Some profile analysis tools terminate if they see
173<em>any</em> profile record with a call chain with its first entry
174having the address 0. (This is similar to the binary trailer.)
175
176<h3>Example</h3>
177
178This example shows the slots contained in a sample profile record.
179
180<p>
181<table summary="Profile Record Example"
182 frame="box" rules="sides" cellpadding="5">
183 <tr>
184 <td>5</td>
185 <td>3</td>
186 <td>0xa0000</td>
187 <td>0xc0000</td>
188 <td>0xe0000</td>
189 </tr>
190</table>
191
192<p>In this example, 5 ticks were received at PC 0xa0000, whose
193function had been called by the function containing 0xc0000, which had
194been called from the function containing 0xe0000.
195
196
197<h2>Binary Trailer</h2>
198
199<p>The binary trailer consists of three slots of data with fixed
200values, shown below.
201
202<p>
203<table summary="Trailer Format"
204 frame="box" rules="sides" cellpadding="5" width="50%">
205 <tr>
206 <th width="30%">slot</th>
207 <th width="70%">value</th>
208 </tr>
209
210 <tr>
211 <td>0</td>
212 <td>0</td>
213 </tr>
214
215 <tr>
216 <td>1</td>
217 <td>1</td>
218 </tr>
219
220 <tr>
221 <td>2</td>
222 <td>0</td>
223 </tr>
224</table>
225
226<p>Note that this is the same data that would contained in a profile
227record with sample count = 0, num_pcs = 1, and a one-element call
228chain containing the address 0.
229
230
231<h2>Text List of Mapped Objects</h2>
232
233<p>The binary data in the file is followed immediately by a list of
234mapped objects. This list consists of lines of text separated by
235newline characters.
236
237<p>Each line is one of the following types:
238
239<ul>
240 <li>Build specifier, starting with "<tt>build=</tt>". For example:
241 <pre> build=/path/to/binary</pre>
242 Leading spaces on the line are ignored.
243
244 <li>Mapping line from ProcMapsIterator::FormatLine. For example:
245 <pre> 40000000-40015000 r-xp 00000000 03:01 12845071 /lib/ld-2.3.2.so</pre>
246 The first address must start at the beginning of the line.
247</ul>
248
249<p>Unrecognized lines should be ignored by analysis tools.
250
251<p>When processing the paths see in mapping lines, occurrences of
252<tt>$build</tt> followed by a non-word character (i.e., characters
253other than underscore or alphanumeric characters), should be replaced
254by the path given on the last build specifier line.
255
256<hr>
257<address>Chris Demetriou<br>
258<!-- Created: Mon Aug 27 12:18:26 PDT 2007 -->
259<!-- hhmts start -->
260Last modified: Mon Aug 27 12:18:26 PDT 2007 (cgd)
261<!-- hhmts end -->
262</address>
263</BODY>
264</HTML>