Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / 3ca836a171b512094fe79820ec868f221fa92a64 / . / docs / BytecodeFormat.html
blob: 48b9f09e2a380246419a392eb273f8f7d8b48e6a [file] [log] [blame]
Reid Spencer50026612004-05-22 02:28:36 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<html>
4<head>
5 <title>LLVM Bytecode File Format</title>
6 <link rel="stylesheet" href="llvm.css" type="text/css">
7 <style>
8 table, tr, td { border: 2px solid gray }
9 th { border: 2px sold gray; font-weight: bold; }
10 table { border-collapse: collapse; margin-top: 1em margin-bottom: 1em }
11 </style>
12</head>
13<body>
14 <div class="doc_title"> LLVM Bytecode File Format </div>
15<ol>
16 <li><a href="#abstract">Abstract</a></li>
17 <li><a href="#general">General Concepts</a></li>
18 <ol>
19 <li><a href="#blocks">Blocks</a></li>
20 <li><a href="#lists">Lists</a></li>
21 <li><a href="#fields">Fields</a></li>
22 <li><a href="#align">Alignment</a></li>
23 </ol>
24 <li><a href="#details">Detailed Layout</a>
25 <ol>
26 <li><a href="#notation">Notation</a></li>
27 <li><a href="#blocktypes">Blocks Types</a></li>
28 <li><a href="#header">Header Block</a></li>
29 <li><a href="#typeool">Global Type Pool</a></li>
30 <li><a href="#modinfo">Module Info Block</a></li>
31 <li><a href="#constants">Global Constant Pool</a></li>
32 <li><a href="#functions">Function Blocks</a><li>
33 <li><a href="#symtab">Module Symbol Table</a><li>
34 </ol>
35 </li>
36</ol>
37<div class="doc_text">
38<p><b>Written by <a href="mailto:rspencer@x10sys.com">Reid Spencer</a>
39and <a href="mailto:sabre@nondot.org">Chris Lattner</a></b></p>
40<p> </p>
41</div>
42<!-- *********************************************************************** -->
43<div class="doc_section"> <a name="abstract">Abstract </a></div>
44<!-- *********************************************************************** -->
45<div class="doc_text">
46<p>This document is an (after the fact) specification of the LLVM bytecode
47file format. It documents the binary encoding rules of the bytecode file format
48so that equivalent systems can encode bytecode files correctly. The LLVM
49bytecode representation is used to store the intermediate representation on
50disk in compacted form.
51</p>
52</div>
53<!-- *********************************************************************** -->
54<div class="doc_section"> <a name="general">General Concepts</a> </div>
55<!-- *********************************************************************** -->
56<div class="doc_text">
57<p>This section describes the general concepts of the bytecode file format
58without getting into bit and byte level specifics.</p>
59</div>
60<!-- _______________________________________________________________________ -->
61<div class="doc_subsection"><a name="blocks">Blocks</a> </div>
62<div class="doc_text">
63<p>LLVM bytecode files consist simply of a sequence of blocks of bytes.
64Each block begins with an identification value that determines the type of
65the next block. The possible types of blocks are described below in the section
66<a href="#blockstypes">Block Types</a>. The block identifier is used because
67it is possible for entire blocks to be omitted from the file if they are
68empty. The block identifier helps the reader determine which kind of block is
69next in the file.</p>
Reid Spencer939290f2004-05-22 05:56:41 +0000[diff] [blame]70<p>The following block identifiers are currently in use
71(from llvm/Bytecode/Format.h):</p>
72<ol>
73 <li><b>Module (0x01)</b>.</li>
74 <li><b>Function (0x11)</b>.</li>
75 <li><b>ConstantPool (0x12)</b>.</li>
76 <li><b>SymbolTable (0x13)</b>.</li>
77 <li><b>ModuleGlobalInfo (0x14)</b>.</li>
78 <li><b>GlobalTypePlane (0x15)</b>.</li>
79 <li><b>BasicBlock (0x31)</b>.</li>
80 <li><b>InstructionList (0x32)</b>.</li>
81 <li><b>CompactionTable (0x33)</b>.</li>
82</ol>
83<p> Except for the <a href="#header">Header Block</a> all blocks are variable
84length. They consume just enough bytes to express their contents.</p>
Reid Spencer50026612004-05-22 02:28:36 +0000[diff] [blame]85</div>
86<!-- _______________________________________________________________________ -->
87<div class="doc_subsection"><a name="lists">Lists</a> </div>
88<div class="doc_text">
89<p>Most blocks are constructed of lists of information. Lists can be constructed
90of other lists, etc. This decomposition of information follows the containment
91hierarchy of the LLVM Intermediate Representation. For example, a function is
92composed of a list of basic blocks. Each basic block is composed of a set of
93instructions. This list of list nesting and hierarchy is maintained in the
94bytecode file.</p>
95<p>A list is encoded into the file simply by encoding the number of entries as
96an integer followed by each of the entries. The reader knows when the list is
97done because it will have filled the list with the required numbe of entries.
98</p>
99</div>
100<!-- _______________________________________________________________________ -->
101<div class="doc_subsection"><a name="fields">Fields</a> </div>
102<div class="doc_text">
103<p>Fields are units of information that LLVM knows how to write atomically.
104Most fields have a uniform length or some kind of length indication built into
105their encoding. For example, a constant string (array of SByte or UByte) is
106written simply as the length followed by the characters. Although this is
107similar to a list, constant strings are treated atomically and are thus
108fields.</p>
109<p>Fields use a condensed bit format specific to the type of information
110they must contain. As few bits as possible are written for each field. The
111sections that follow will provide the details on how these fields are
112written and how the bits are to be interpreted.</p>
113</div>
114<!-- _______________________________________________________________________ -->
115<div class="doc_subsection"><a name="align">Alignment</a> </div>
116<div class="doc_text">
117<p>To support cross-platform differences, the bytecode file is aligned on
118certain boundaries. This means that a small amount of padding (at most 3 bytes)
119will be added to ensure that the next entry is aligned to a 32-bit boundary.
120</p>
121</div>
122<!-- *********************************************************************** -->
123<div class="doc_section"> <a name="details">Detailed Layout</a> </div>
124<!-- *********************************************************************** -->
125<div class="doc_text">
126 <p>This section provides the detailed layout of the LLVM bytecode file format.
127 bit and byte level specifics.</p>
128</div>
129<!-- _______________________________________________________________________ -->
130<div class="doc_subsection"><a name="notation">Notation</a></div>
131<div class="doc_text">
132 <p>The descriptions of the bytecode format that follow describe the bit
133 fields in detail. These descriptions are provided in tabular form. Each table
134 has four columns that specify:</p>
135 <ol>
136 <li><b>Byte(s)</b>. The offset in bytes of the field from the start of
137 its container (block, list, other field).<li>
138 <li><b>Bit(s)</b>. The offset in bits of the field from the start of
139 the byte field. Bits are always little endian. That is, bit addresses with
140 smaller values have smaller address (i.e. 2^0 is at bit 0, 2^1 at 1, etc.)
141 </li>
142 <li><b>Align?</b> Indicates if this field is aligned to 32 bits or not.
143 This indicates where the <em>next</em> field starts, always on a 32 bit
144 boundary.</li>
Reid Spencer939290f2004-05-22 05:56:41 +0000[diff] [blame]145 <li><b>Type</b>. The basic type of information contained in the field.</li>
Reid Spencer50026612004-05-22 02:28:36 +0000[diff] [blame]146 <li><b>Description</b>. Descripts the contents of the field.</li>
147 </ol>
148</div>
149<!-- _______________________________________________________________________ -->
150<div class="doc_subsection"><a name="blocktypes">Block Types</a></div>
151<div class="doc_text">
152 <p>The bytecode format encodes the intermediate representation into groups
153 of bytes known as blocks. The blocks are written sequentially to the file in
154 the following order:</p>
155<ol>
156 <li><a href="#header">Header</a>. This block contains the file signature
157 (magic number), machine description and file format version (not LLVM
158 version).</li>
159 <li><a href="#gtypepool">Global Type Pool</a>. This block contains all the
160 global (module) level types.</li>
161 <li><a href="#modinfo">Module Info</a>. This block contains the types of the
162 global variables and functions in the module as well as the constant
163 initializers for the global variables</li>
164 <li><a href="#constants">Constants</a>. This block contains all the global
165 constants except function arguments, global values and constant strings.</li>
166 <li><a href="#functions">Functions</a>. One function block is written for
167 each function in the module. </li>
168 <li><a href="$symtab">Symbol Table</a>. The module level symbol table that
169 provides names for the various other entries in the file is the final block
170 written.</li>
171</ol>
172</div>
173<!-- _______________________________________________________________________ -->
174<div class="doc_subsection"><a name="header">Header Block</a> </div>
175<div class="doc_text">
176<p>The Header Block occurs in every LLVM bytecode file and is always first. It
177simply provides a few bytes of data to identify the file, its format, and the
178bytecode version. This block is fixed length and always eight bytes, as follows:
179<table class="doc_table" width="90%">
180 <tr>
181 <th><b>Byte(s)</b></th>
182 <th><b>Bit(s)</b></th>
183 <th><b>Align?</b></th>
Reid Spencer939290f2004-05-22 05:56:41 +0000[diff] [blame]184 <th><b>Type</b></th>
Reid Spencer50026612004-05-22 02:28:36 +0000[diff] [blame]185 <th align="left"><b>Field Description</b></th>
186 </tr>
187 <tr>
Reid Spencer939290f2004-05-22 05:56:41 +0000[diff] [blame]188 <td>00</td><td>00-07</td><td>No</td><td>Char</td>
189 <td align="left">Constant "l" (0x6C)</td>
Reid Spencer50026612004-05-22 02:28:36 +0000[diff] [blame]190 </tr>
191 <tr>
Reid Spencer939290f2004-05-22 05:56:41 +0000[diff] [blame]192 <td>01</td><td>00-07</td><td>No</td><td>Char</td>
193 <td align="left">Constant "l" (0x6C)</td>
Reid Spencer50026612004-05-22 02:28:36 +0000[diff] [blame]194 </tr>
195 <tr>
Reid Spencer939290f2004-05-22 05:56:41 +0000[diff] [blame]196 <td>02</td><td>00-07</td><td>No</td><td>Char</td>
197 <td align="left">Constant "v" (0x76)</td>
Reid Spencer50026612004-05-22 02:28:36 +0000[diff] [blame]198 </tr>
199 <tr>
Reid Spencer939290f2004-05-22 05:56:41 +0000[diff] [blame]200 <td>03</td><td>00-07</td><td>No</td><td>Char</td>
201 <td align="left">Constant "m" (0x6D)</td>
Reid Spencer50026612004-05-22 02:28:36 +0000[diff] [blame]202 </tr>
203 <tr>
Reid Spencer939290f2004-05-22 05:56:41 +0000[diff] [blame]204 <td>04-07</td><td>00</td><td>No</td><td>Bool</td>
205 <td align="left">Target is big endian?</td>
Reid Spencer50026612004-05-22 02:28:36 +0000[diff] [blame]206 </tr>
207 <tr>
Reid Spencer939290f2004-05-22 05:56:41 +0000[diff] [blame]208 <td>04-07</td><td>01</td><td>No</td><td>Bool</td>
209 <td align="left">Target has long pointers?</td>
Reid Spencer50026612004-05-22 02:28:36 +0000[diff] [blame]210 </tr>
211 <tr>
Reid Spencer939290f2004-05-22 05:56:41 +0000[diff] [blame]212 <td>04-07</td><td>02</td><td>No</td><td>Bool</td>
213 <td align="left">Target has no endianess?</td>
Reid Spencer50026612004-05-22 02:28:36 +0000[diff] [blame]214 </tr>
215 <tr>
Reid Spencer939290f2004-05-22 05:56:41 +0000[diff] [blame]216 <td>04-07</td><td>03</td><td>No</td><td>Bool</td>
217 <td align="left">Target has no pointer size?</td>
Reid Spencer50026612004-05-22 02:28:36 +0000[diff] [blame]218 </tr>
219 <tr>
Reid Spencer939290f2004-05-22 05:56:41 +0000[diff] [blame]220 <td>04-07</td><td>04-31</td><td>Yes</td><td>Unsigned</td>
Reid Spencer50026612004-05-22 02:28:36 +0000[diff] [blame]221 <td align="left">The LLVM bytecode format version number</td>
222 </tr>
223</table>
224</div>
225<!-- _______________________________________________________________________ -->
226<div class="doc_subsection"><a name="gtypepool">Global Type Pool</a> </div>
227<div class="doc_text">
228</div>
229<!-- _______________________________________________________________________ -->
230<div class="doc_subsection"><a name="modinfo">Module Info</a> </div>
231<div class="doc_text">
232</div>
233<!-- _______________________________________________________________________ -->
234<div class="doc_subsection"><a name="constants">Constants</a> </div>
235<div class="doc_text">
236</div>
237<!-- _______________________________________________________________________ -->
238<div class="doc_subsection"><a name="functions">Functions</a> </div>
239<div class="doc_text">
240</div>
241<!-- _______________________________________________________________________ -->
242<div class="doc_subsection"><a name="symtab">Module Symbol Table</a> </div>
243<div class="doc_text">
Reid Spencer939290f2004-05-22 05:56:41 +0000[diff] [blame]244<p>The module symbol table is a list of
Reid Spencer50026612004-05-22 02:28:36 +0000[diff] [blame]245</div>
246
247<!-- *********************************************************************** -->
248<hr>
249<address>
250 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
251 src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
252 <a href="http://validator.w3.org/check/referer"><img
253 src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
254
255 <a href="mailto:rspencer@x10sys.com">Reid Spencer</a> and
256 <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
257 <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br>
258 Last modified: $Date$
259</address>
260</body>
261</html>
262<!-- vim: sw=2
263-->