src/third_party/tcmalloc/vendor/doc/cpuprofile-fileformat.html

   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
  22 Google CPU Profiler.  For information about using the CPU Profiler,
  23 see <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
  41 large enough to hold the program's pointer type, i.e., for 32-bit
  42 programs they are 4 bytes in size, and for 64-bit programs they are 8
  43 bytes.  They are stored in the profile data file in the native byte
  44 order (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
  50 profiler, along with requirements currently enforced by the analysis
  51 tools, 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
 127 words in the profile data file.  The slot contents for 32-bit and
 128 64-bit headers are identical.  For 32-bit profiles, the 4-byte word
 129 view matches the slot view.  For 64-bit profiles, each (8-byte) slot
 130 is shown as two 4-byte words, ordered as they would appear in the
 131 file.
 132
 133 <p>The profiling tools examine the contents of the file and use the
 134 expected locations and values of the header words field to detect
 135 whether 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
 169 having an identical call chain.  In that case, analysis tools should
 170 sum 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
 174 having the address 0.  (This is similar to the binary trailer.)
 175
 176 <h3>Example</h3>
 177
 178 This 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
 193 function had been called by the function containing 0xc0000, which had
 194 been 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
 200 values, 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
 227 record with sample count = 0, num_pcs = 1, and a one-element call
 228 chain 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
 234 mapped objects.  This list consists of lines of text separated by
 235 newline 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
 253 other than underscore or alphanumeric characters), should be replaced
 254 by 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 -->
 260 Last modified: Mon Aug 27 12:18:26 PDT 2007  (cgd)
 261 <!-- hhmts end -->
 262 </address>
 263 </BODY>
 264 </HTML>