diff options
Diffstat (limited to 'trunk/doc/cpuprofile-fileformat.html')
| -rw-r--r-- | trunk/doc/cpuprofile-fileformat.html | 264 |
1 files changed, 264 insertions, 0 deletions
diff --git a/trunk/doc/cpuprofile-fileformat.html b/trunk/doc/cpuprofile-fileformat.html new file mode 100644 index 0000000..3f90e6b --- /dev/null +++ b/trunk/doc/cpuprofile-fileformat.html @@ -0,0 +1,264 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML> + +<HEAD> + <link rel="stylesheet" href="designstyle.css"> + <title>Google CPU Profiler Binary Data File Format</title> +</HEAD> + +<BODY> + +<h1>Google CPU Profiler Binary Data File Format</h1> + +<p align=right> + <i>Last modified + <script type=text/javascript> + var lm = new Date(document.lastModified); + document.write(lm.toDateString()); + </script></i> +</p> + +<p>This file documents the binary data file format produced by the +Google CPU Profiler. For information about using the CPU Profiler, +see <a href="cpuprofile.html">its user guide</a>. + +<p>The profiler source code, which generates files using this format, is at +<code>src/profiler.cc</code></a>. + + +<h2>CPU Profile Data File Structure</h2> + +<p>CPU profile data files each consist of four parts, in order: + +<ul> + <li> Binary header + <li> Binary profile records + <li> Binary trailer + <li> Text list of mapped objects +</ul> + +<p>The binary data is expressed in terms of "slots." These are words +large enough to hold the program's pointer type, i.e., for 32-bit +programs they are 4 bytes in size, and for 64-bit programs they are 8 +bytes. They are stored in the profile data file in the native byte +order (i.e., little-endian for x86 and x86_64). + + +<h2>Binary Header</h2> + +<p>The binary header format is show below. Values written by the +profiler, along with requirements currently enforced by the analysis +tools, are shown in parentheses. + +<p> +<table summary="Header Format" + frame="box" rules="sides" cellpadding="5" width="50%"> + <tr> + <th width="30%">slot</th> + <th width="70%">data</th> + </tr> + + <tr> + <td>0</td> + <td>header count (0; must be 0)</td> + </tr> + + <tr> + <td>1</td> + <td>header slots after this one (3; must be >= 3)</td> + </tr> + + <tr> + <td>2</td> + <td>format version (0; must be 0)</td> + </tr> + + <tr> + <td>3</td> + <td>sampling period, in microseconds</td> + </tr> + + <tr> + <td>4</td> + <td>padding (0)</td> + </tr> +</table> + +<p>The headers currently generated for 32-bit and 64-bit little-endian +(x86 and x86_64) profiles are shown below, for comparison. + +<p> +<table summary="Header Example" frame="box" rules="sides" cellpadding="5"> + <tr> + <th></th> + <th>hdr count</th> + <th>hdr words</th> + <th>version</th> + <th>sampling period</th> + <th>pad</th> + </tr> + <tr> + <td>32-bit or 64-bit (slots)</td> + <td>0</td> + <td>3</td> + <td>0</td> + <td>10000</td> + <td>0</td> + </tr> + <tr> + <td>32-bit (4-byte words in file)</td> + <td><tt>0x00000</tt></td> + <td><tt>0x00003</tt></td> + <td><tt>0x00000</tt></td> + <td><tt>0x02710</tt></td> + <td><tt>0x00000</tt></td> + </tr> + <tr> + <td>64-bit LE (4-byte words in file)</td> + <td><tt>0x00000 0x00000</tt></td> + <td><tt>0x00003 0x00000</tt></td> + <td><tt>0x00000 0x00000</tt></td> + <td><tt>0x02710 0x00000</tt></td> + <td><tt>0x00000 0x00000</tt></td> + </tr> +</table> + +<p>The contents are shown in terms of slots, and in terms of 4-byte +words in the profile data file. The slot contents for 32-bit and +64-bit headers are identical. For 32-bit profiles, the 4-byte word +view matches the slot view. For 64-bit profiles, each (8-byte) slot +is shown as two 4-byte words, ordered as they would appear in the +file. + +<p>The profiling tools examine the contents of the file and use the +expected locations and values of the header words field to detect +whether the file is 32-bit or 64-bit. + + +<h2>Binary Profile Records</h2> + +<p>The binary profile record format is shown below. + +<p> +<table summary="Profile Record Format" + frame="box" rules="sides" cellpadding="5" width="50%"> + <tr> + <th width="30%">slot</th> + <th width="70%">data</th> + </tr> + + <tr> + <td>0</td> + <td>sample count, must be >= 1</td> + </tr> + + <tr> + <td>1</td> + <td>number of call chain PCs (num_pcs), must be >= 1</td> + </tr> + + <tr> + <td>2 .. (num_pcs + 1)</td> + <td>call chain PCs, most-recently-called function first. + </tr> +</table> + +<p>The total length of a given record is 2 + num_pcs. + +<p>Note that multiple profile records can be emitted by the profiler +having an identical call chain. In that case, analysis tools should +sum the counts of all records having identical call chains. + +<p><b>Note:</b> Some profile analysis tools terminate if they see +<em>any</em> profile record with a call chain with its first entry +having the address 0. (This is similar to the binary trailer.) + +<h3>Example</h3> + +This example shows the slots contained in a sample profile record. + +<p> +<table summary="Profile Record Example" + frame="box" rules="sides" cellpadding="5"> + <tr> + <td>5</td> + <td>3</td> + <td>0xa0000</td> + <td>0xc0000</td> + <td>0xe0000</td> + </tr> +</table> + +<p>In this example, 5 ticks were received at PC 0xa0000, whose +function had been called by the function containing 0xc0000, which had +been called from the function containing 0xe0000. + + +<h2>Binary Trailer</h2> + +<p>The binary trailer consists of three slots of data with fixed +values, shown below. + +<p> +<table summary="Trailer Format" + frame="box" rules="sides" cellpadding="5" width="50%"> + <tr> + <th width="30%">slot</th> + <th width="70%">value</th> + </tr> + + <tr> + <td>0</td> + <td>0</td> + </tr> + + <tr> + <td>1</td> + <td>1</td> + </tr> + + <tr> + <td>2</td> + <td>0</td> + </tr> +</table> + +<p>Note that this is the same data that would contained in a profile +record with sample count = 0, num_pcs = 1, and a one-element call +chain containing the address 0. + + +<h2>Text List of Mapped Objects</h2> + +<p>The binary data in the file is followed immediately by a list of +mapped objects. This list consists of lines of text separated by +newline characters. + +<p>Each line is one of the following types: + +<ul> + <li>Build specifier, starting with "<tt>build=</tt>". For example: + <pre> build=/path/to/binary</pre> + Leading spaces on the line are ignored. + + <li>Mapping line from ProcMapsIterator::FormatLine. For example: + <pre> 40000000-40015000 r-xp 00000000 03:01 12845071 /lib/ld-2.3.2.so</pre> + The first address must start at the beginning of the line. +</ul> + +<p>Unrecognized lines should be ignored by analysis tools. + +<p>When processing the paths see in mapping lines, occurrences of +<tt>$build</tt> followed by a non-word character (i.e., characters +other than underscore or alphanumeric characters), should be replaced +by the path given on the last build specifier line. + +<hr> +<address>Chris Demetriou<br> +<!-- Created: Mon Aug 27 12:18:26 PDT 2007 --> +<!-- hhmts start --> +Last modified: Mon Aug 27 12:18:26 PDT 2007 (cgd) +<!-- hhmts end --> +</address> +</BODY> +</HTML> |