Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / 8addca2f3aa82b9087602c902722ca5d7c8c944c / . / docs / BitCodeFormat.html
blob: f1ddefdea9afefe7664c6a7433234a1364dde6e8 [file] [log] [blame]
Chris Lattner3a1716d2007-05-12 05:37:42 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
Reid Spencer2c1ce4f2007-01-20 23:21:08 +0000[diff] [blame]3<html>
4<head>
5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6 <title>LLVM Bitcode File Format</title>
7 <link rel="stylesheet" href="llvm.css" type="text/css">
Reid Spencer2c1ce4f2007-01-20 23:21:08 +0000[diff] [blame]8</head>
9<body>
10<div class="doc_title"> LLVM Bitcode File Format </div>
11<ol>
12 <li><a href="#abstract">Abstract</a></li>
Chris Lattnere9ef4572007-05-12 03:23:40 +0000[diff] [blame]13 <li><a href="#overview">Overview</a></li>
14 <li><a href="#bitstream">Bitstream Format</a>
15 <ol>
16 <li><a href="#magic">Magic Numbers</a></li>
Chris Lattner3a1716d2007-05-12 05:37:42 +0000[diff] [blame]17 <li><a href="#primitives">Primitives</a></li>
18 <li><a href="#abbrevid">Abbreviation IDs</a></li>
19 <li><a href="#blocks">Blocks</a></li>
20 <li><a href="#datarecord">Data Records</a></li>
Chris Lattnerdaeb63c2007-05-12 07:49:15 +0000[diff] [blame]21 <li><a href="#abbreviations">Abbreviations</a></li>
Chris Lattner7300af52007-05-13 00:59:52 +0000[diff] [blame]22 <li><a href="#stdblocks">Standard Blocks</a></li>
Chris Lattnere9ef4572007-05-12 03:23:40 +0000[diff] [blame]23 </ol>
24 </li>
Chris Lattner6fa6a322008-07-09 05:14:23 +0000[diff] [blame]25 <li><a href="#wrapper">Bitcode Wrapper Format</a>
26 </li>
Chris Lattner69b3e402007-05-13 01:39:44 +0000[diff] [blame]27 <li><a href="#llvmir">LLVM IR Encoding</a>
28 <ol>
29 <li><a href="#basics">Basics</a></li>
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]30 <li><a href="#MODULE_BLOCK">MODULE_BLOCK Contents</a></li>
31 <li><a href="#PARAMATTR_BLOCK">PARAMATTR_BLOCK Contents</a></li>
32 <li><a href="#TYPE_BLOCK">TYPE_BLOCK Contents</a></li>
33 <li><a href="#CONSTANTS_BLOCK">CONSTANTS_BLOCK Contents</a></li>
34 <li><a href="#FUNCTION_BLOCK">FUNCTION_BLOCK Contents</a></li>
35 <li><a href="#TYPE_SYMTAB_BLOCK">TYPE_SYMTAB_BLOCK Contents</a></li>
36 <li><a href="#VALUE_SYMTAB_BLOCK">VALUE_SYMTAB_BLOCK Contents</a></li>
37 <li><a href="#METADATA_BLOCK">METADATA_BLOCK Contents</a></li>
38 <li><a href="#METADATA_ATTACHMENT">METADATA_ATTACHMENT Contents</a></li>
Chris Lattner69b3e402007-05-13 01:39:44 +0000[diff] [blame]39 </ol>
40 </li>
Reid Spencer2c1ce4f2007-01-20 23:21:08 +0000[diff] [blame]41</ol>
42<div class="doc_author">
Chris Lattnerf19b8e42007-10-08 18:42:45 +0000[diff] [blame]43 <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>
44 and <a href="http://www.reverberate.org">Joshua Haberman</a>.
Reid Spencer2c1ce4f2007-01-20 23:21:08 +0000[diff] [blame]45</p>
46</div>
Chris Lattnere9ef4572007-05-12 03:23:40 +0000[diff] [blame]47
Reid Spencer2c1ce4f2007-01-20 23:21:08 +0000[diff] [blame]48<!-- *********************************************************************** -->
Chris Lattnere9ef4572007-05-12 03:23:40 +0000[diff] [blame]49<div class="doc_section"> <a name="abstract">Abstract</a></div>
Reid Spencer2c1ce4f2007-01-20 23:21:08 +0000[diff] [blame]50<!-- *********************************************************************** -->
Chris Lattnere9ef4572007-05-12 03:23:40 +0000[diff] [blame]51
Reid Spencer2c1ce4f2007-01-20 23:21:08 +0000[diff] [blame]52<div class="doc_text">
Chris Lattnere9ef4572007-05-12 03:23:40 +0000[diff] [blame]53
54<p>This document describes the LLVM bitstream file format and the encoding of
55the LLVM IR into it.</p>
56
Reid Spencer2c1ce4f2007-01-20 23:21:08 +0000[diff] [blame]57</div>
Chris Lattnere9ef4572007-05-12 03:23:40 +0000[diff] [blame]58
Reid Spencer2c1ce4f2007-01-20 23:21:08 +0000[diff] [blame]59<!-- *********************************************************************** -->
Chris Lattnere9ef4572007-05-12 03:23:40 +0000[diff] [blame]60<div class="doc_section"> <a name="overview">Overview</a></div>
Reid Spencer2c1ce4f2007-01-20 23:21:08 +0000[diff] [blame]61<!-- *********************************************************************** -->
Chris Lattnere9ef4572007-05-12 03:23:40 +0000[diff] [blame]62
Reid Spencer2c1ce4f2007-01-20 23:21:08 +0000[diff] [blame]63<div class="doc_text">
Chris Lattnere9ef4572007-05-12 03:23:40 +0000[diff] [blame]64
65<p>
66What is commonly known as the LLVM bitcode file format (also, sometimes
67anachronistically known as bytecode) is actually two things: a <a
68href="#bitstream">bitstream container format</a>
69and an <a href="#llvmir">encoding of LLVM IR</a> into the container format.</p>
70
71<p>
Reid Spencer58d05472007-05-12 08:01:52 +0000[diff] [blame]72The bitstream format is an abstract encoding of structured data, very
Chris Lattnere9ef4572007-05-12 03:23:40 +0000[diff] [blame]73similar to XML in some ways. Like XML, bitstream files contain tags, and nested
74structures, and you can parse the file without having to understand the tags.
75Unlike XML, the bitstream format is a binary encoding, and unlike XML it
76provides a mechanism for the file to self-describe "abbreviations", which are
77effectively size optimizations for the content.</p>
78
Chris Lattner6fa6a322008-07-09 05:14:23 +0000[diff] [blame]79<p>LLVM IR files may be optionally embedded into a <a
80href="#wrapper">wrapper</a> structure that makes it easy to embed extra data
81along with LLVM IR files.</p>
82
83<p>This document first describes the LLVM bitstream format, describes the
84wrapper format, then describes the record structure used by LLVM IR files.
Chris Lattnere9ef4572007-05-12 03:23:40 +0000[diff] [blame]85</p>
86
Reid Spencer2c1ce4f2007-01-20 23:21:08 +0000[diff] [blame]87</div>
Chris Lattnere9ef4572007-05-12 03:23:40 +0000[diff] [blame]88
89<!-- *********************************************************************** -->
90<div class="doc_section"> <a name="bitstream">Bitstream Format</a></div>
91<!-- *********************************************************************** -->
92
93<div class="doc_text">
94
95<p>
96The bitstream format is literally a stream of bits, with a very simple
97structure. This structure consists of the following concepts:
98</p>
99
100<ul>
Chris Lattner3a1716d2007-05-12 05:37:42 +0000[diff] [blame]101<li>A "<a href="#magic">magic number</a>" that identifies the contents of
102 the stream.</li>
103<li>Encoding <a href="#primitives">primitives</a> like variable bit-rate
104 integers.</li>
105<li><a href="#blocks">Blocks</a>, which define nested content.</li>
106<li><a href="#datarecord">Data Records</a>, which describe entities within the
107 file.</li>
Chris Lattnere9ef4572007-05-12 03:23:40 +0000[diff] [blame]108<li>Abbreviations, which specify compression optimizations for the file.</li>
109</ul>
110
111<p>Note that the <a
112href="CommandGuide/html/llvm-bcanalyzer.html">llvm-bcanalyzer</a> tool can be
113used to dump and inspect arbitrary bitstreams, which is very useful for
114understanding the encoding.</p>
115
116</div>
117
118<!-- ======================================================================= -->
119<div class="doc_subsection"><a name="magic">Magic Numbers</a>
120</div>
121
122<div class="doc_text">
123
Chris Lattnerf19b8e42007-10-08 18:42:45 +0000[diff] [blame]124<p>The first two bytes of a bitcode file are 'BC' (0x42, 0x43).
125The second two bytes are an application-specific magic number. Generic
126bitcode tools can look at only the first two bytes to verify the file is
127bitcode, while application-specific programs will want to look at all four.</p>
Chris Lattnere9ef4572007-05-12 03:23:40 +0000[diff] [blame]128
129</div>
130
Chris Lattner3a1716d2007-05-12 05:37:42 +0000[diff] [blame]131<!-- ======================================================================= -->
132<div class="doc_subsection"><a name="primitives">Primitives</a>
133</div>
Chris Lattnere9ef4572007-05-12 03:23:40 +0000[diff] [blame]134
135<div class="doc_text">
136
Chris Lattner3a1716d2007-05-12 05:37:42 +0000[diff] [blame]137<p>
Chris Lattnerf19b8e42007-10-08 18:42:45 +0000[diff] [blame]138A bitstream literally consists of a stream of bits, which are read in order
139starting with the least significant bit of each byte. The stream is made up of a
Chris Lattner69b3e402007-05-13 01:39:44 +0000[diff] [blame]140number of primitive values that encode a stream of unsigned integer values.
Chris Lattnerf958dd22010-01-20 17:53:51 +0000[diff] [blame]141These integers are encoded in two ways: either as <a href="#fixedwidth">Fixed
Chris Lattner3a1716d2007-05-12 05:37:42 +0000[diff] [blame]142Width Integers</a> or as <a href="#variablewidth">Variable Width
143Integers</a>.
Chris Lattnere9ef4572007-05-12 03:23:40 +0000[diff] [blame]144</p>
145
146</div>
147
Chris Lattner3a1716d2007-05-12 05:37:42 +0000[diff] [blame]148<!-- _______________________________________________________________________ -->
149<div class="doc_subsubsection"> <a name="fixedwidth">Fixed Width Integers</a>
150</div>
151
152<div class="doc_text">
153
154<p>Fixed-width integer values have their low bits emitted directly to the file.
155 For example, a 3-bit integer value encodes 1 as 001. Fixed width integers
156 are used when there are a well-known number of options for a field. For
157 example, boolean values are usually encoded with a 1-bit wide integer.
158</p>
159
160</div>
161
162<!-- _______________________________________________________________________ -->
163<div class="doc_subsubsection"> <a name="variablewidth">Variable Width
164Integers</a></div>
165
166<div class="doc_text">
167
168<p>Variable-width integer (VBR) values encode values of arbitrary size,
169optimizing for the case where the values are small. Given a 4-bit VBR field,
170any 3-bit value (0 through 7) is encoded directly, with the high bit set to
171zero. Values larger than N-1 bits emit their bits in a series of N-1 bit
172chunks, where all but the last set the high bit.</p>
173
174<p>For example, the value 27 (0x1B) is encoded as 1011 0011 when emitted as a
175vbr4 value. The first set of four bits indicates the value 3 (011) with a
176continuation piece (indicated by a high bit of 1). The next word indicates a
177value of 24 (011 << 3) with no continuation. The sum (3+24) yields the value
17827.
179</p>
180
181</div>
182
183<!-- _______________________________________________________________________ -->
184<div class="doc_subsubsection"> <a name="char6">6-bit characters</a></div>
185
186<div class="doc_text">
187
188<p>6-bit characters encode common characters into a fixed 6-bit field. They
Chris Lattnerf1d64e92007-05-12 07:50:14 +0000[diff] [blame]189represent the following characters with the following 6-bit values:</p>
Chris Lattner3a1716d2007-05-12 05:37:42 +0000[diff] [blame]190
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]191<div class="doc_code">
192<pre>
193'a' .. 'z' &mdash; 0 .. 25
194'A' .. 'Z' &mdash; 26 .. 51
195'0' .. '9' &mdash; 52 .. 61
196 '.' &mdash; 62
197 '_' &mdash; 63
198</pre>
199</div>
Chris Lattner3a1716d2007-05-12 05:37:42 +0000[diff] [blame]200
201<p>This encoding is only suitable for encoding characters and strings that
202consist only of the above characters. It is completely incapable of encoding
203characters not in the set.</p>
204
205</div>
206
207<!-- _______________________________________________________________________ -->
208<div class="doc_subsubsection"> <a name="wordalign">Word Alignment</a></div>
209
210<div class="doc_text">
211
212<p>Occasionally, it is useful to emit zero bits until the bitstream is a
213multiple of 32 bits. This ensures that the bit position in the stream can be
214represented as a multiple of 32-bit words.</p>
215
216</div>
217
218
219<!-- ======================================================================= -->
220<div class="doc_subsection"><a name="abbrevid">Abbreviation IDs</a>
221</div>
222
223<div class="doc_text">
224
225<p>
226A bitstream is a sequential series of <a href="#blocks">Blocks</a> and
227<a href="#datarecord">Data Records</a>. Both of these start with an
228abbreviation ID encoded as a fixed-bitwidth field. The width is specified by
229the current block, as described below. The value of the abbreviation ID
230specifies either a builtin ID (which have special meanings, defined below) or
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]231one of the abbreviation IDs defined for the current block by the stream itself.
Chris Lattner3a1716d2007-05-12 05:37:42 +0000[diff] [blame]232</p>
233
234<p>
235The set of builtin abbrev IDs is:
236</p>
237
238<ul>
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]239<li><tt>0 - <a href="#END_BLOCK">END_BLOCK</a></tt> &mdash; This abbrev ID marks
240 the end of the current block.</li>
241<li><tt>1 - <a href="#ENTER_SUBBLOCK">ENTER_SUBBLOCK</a></tt> &mdash; This
242 abbrev ID marks the beginning of a new block.</li>
243<li><tt>2 - <a href="#DEFINE_ABBREV">DEFINE_ABBREV</a></tt> &mdash; This defines
244 a new abbreviation.</li>
245<li><tt>3 - <a href="#UNABBREV_RECORD">UNABBREV_RECORD</a></tt> &mdash; This ID
246 specifies the definition of an unabbreviated record.</li>
Chris Lattner3a1716d2007-05-12 05:37:42 +0000[diff] [blame]247</ul>
248
Chris Lattnerdaeb63c2007-05-12 07:49:15 +0000[diff] [blame]249<p>Abbreviation IDs 4 and above are defined by the stream itself, and specify
250an <a href="#abbrev_records">abbreviated record encoding</a>.</p>
Chris Lattner3a1716d2007-05-12 05:37:42 +0000[diff] [blame]251
252</div>
253
254<!-- ======================================================================= -->
255<div class="doc_subsection"><a name="blocks">Blocks</a>
256</div>
257
258<div class="doc_text">
259
260<p>
261Blocks in a bitstream denote nested regions of the stream, and are identified by
262a content-specific id number (for example, LLVM IR uses an ID of 12 to represent
Chris Lattnerf19b8e42007-10-08 18:42:45 +0000[diff] [blame]263function bodies). Block IDs 0-7 are reserved for <a href="#stdblocks">standard blocks</a>
264whose meaning is defined by Bitcode; block IDs 8 and greater are
Benjamin Kramer8040cd32009-10-12 14:46:08 +0000[diff] [blame]265application specific. Nested blocks capture the hierarchical structure of the data
Chris Lattner3a1716d2007-05-12 05:37:42 +0000[diff] [blame]266encoded in it, and various properties are associated with blocks as the file is
267parsed. Block definitions allow the reader to efficiently skip blocks
268in constant time if the reader wants a summary of blocks, or if it wants to
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]269efficiently skip data it does not understand. The LLVM IR reader uses this
Chris Lattner3a1716d2007-05-12 05:37:42 +0000[diff] [blame]270mechanism to skip function bodies, lazily reading them on demand.
271</p>
272
273<p>
274When reading and encoding the stream, several properties are maintained for the
275block. In particular, each block maintains:
276</p>
277
278<ol>
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]279<li>A current abbrev id width. This value starts at 2 at the beginning of
280 the stream, and is set every time a
Chris Lattner3a1716d2007-05-12 05:37:42 +0000[diff] [blame]281 block record is entered. The block entry specifies the abbrev id width for
282 the body of the block.</li>
283
Chris Lattnerf19b8e42007-10-08 18:42:45 +0000[diff] [blame]284<li>A set of abbreviations. Abbreviations may be defined within a block, in
285 which case they are only defined in that block (neither subblocks nor
286 enclosing blocks see the abbreviation). Abbreviations can also be defined
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]287 inside a <tt><a href="#BLOCKINFO">BLOCKINFO</a></tt> block, in which case
288 they are defined in all blocks that match the ID that the BLOCKINFO block is
289 describing.
Chris Lattner3a1716d2007-05-12 05:37:42 +0000[diff] [blame]290</li>
291</ol>
292
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]293<p>
294As sub blocks are entered, these properties are saved and the new sub-block has
295its own set of abbreviations, and its own abbrev id width. When a sub-block is
296popped, the saved values are restored.
297</p>
Chris Lattner3a1716d2007-05-12 05:37:42 +0000[diff] [blame]298
299</div>
300
301<!-- _______________________________________________________________________ -->
302<div class="doc_subsubsection"> <a name="ENTER_SUBBLOCK">ENTER_SUBBLOCK
303Encoding</a></div>
304
305<div class="doc_text">
306
307<p><tt>[ENTER_SUBBLOCK, blockid<sub>vbr8</sub>, newabbrevlen<sub>vbr4</sub>,
308 &lt;align32bits&gt;, blocklen<sub>32</sub>]</tt></p>
309
310<p>
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]311The <tt>ENTER_SUBBLOCK</tt> abbreviation ID specifies the start of a new block
312record. The <tt>blockid</tt> value is encoded as an 8-bit VBR identifier, and
313indicates the type of block being entered, which can be
314a <a href="#stdblocks">standard block</a> or an application-specific block.
315The <tt>newabbrevlen</tt> value is a 4-bit VBR, which specifies the abbrev id
316width for the sub-block. The <tt>blocklen</tt> value is a 32-bit aligned value
317that specifies the size of the subblock in 32-bit words. This value allows the
318reader to skip over the entire block in one jump.
Chris Lattner3a1716d2007-05-12 05:37:42 +0000[diff] [blame]319</p>
320
321</div>
322
323<!-- _______________________________________________________________________ -->
324<div class="doc_subsubsection"> <a name="END_BLOCK">END_BLOCK
325Encoding</a></div>
326
327<div class="doc_text">
328
329<p><tt>[END_BLOCK, &lt;align32bits&gt;]</tt></p>
330
331<p>
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]332The <tt>END_BLOCK</tt> abbreviation ID specifies the end of the current block
333record. Its end is aligned to 32-bits to ensure that the size of the block is
334an even multiple of 32-bits.
335</p>
Chris Lattner3a1716d2007-05-12 05:37:42 +0000[diff] [blame]336
337</div>
338
339
340
341<!-- ======================================================================= -->
342<div class="doc_subsection"><a name="datarecord">Data Records</a>
343</div>
344
345<div class="doc_text">
Chris Lattnerdaeb63c2007-05-12 07:49:15 +0000[diff] [blame]346<p>
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]347Data records consist of a record code and a number of (up to) 64-bit
348integer values. The interpretation of the code and values is
349application specific and may vary between different block types.
350Records can be encoded either using an unabbrev record, or with an
351abbreviation. In the LLVM IR format, for example, there is a record
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]352which encodes the target triple of a module. The code is
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]353<tt>MODULE_CODE_TRIPLE</tt>, and the values of the record are the
354ASCII codes for the characters in the string.
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]355</p>
Chris Lattnerdaeb63c2007-05-12 07:49:15 +0000[diff] [blame]356
357</div>
358
359<!-- _______________________________________________________________________ -->
360<div class="doc_subsubsection"> <a name="UNABBREV_RECORD">UNABBREV_RECORD
361Encoding</a></div>
362
363<div class="doc_text">
364
365<p><tt>[UNABBREV_RECORD, code<sub>vbr6</sub>, numops<sub>vbr6</sub>,
366 op0<sub>vbr6</sub>, op1<sub>vbr6</sub>, ...]</tt></p>
367
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]368<p>
369An <tt>UNABBREV_RECORD</tt> provides a default fallback encoding, which is both
370completely general and extremely inefficient. It can describe an arbitrary
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]371record by emitting the code and operands as VBRs.
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]372</p>
Chris Lattnerdaeb63c2007-05-12 07:49:15 +0000[diff] [blame]373
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]374<p>
375For example, emitting an LLVM IR target triple as an unabbreviated record
376requires emitting the <tt>UNABBREV_RECORD</tt> abbrevid, a vbr6 for the
377<tt>MODULE_CODE_TRIPLE</tt> code, a vbr6 for the length of the string, which is
378equal to the number of operands, and a vbr6 for each character. Because there
379are no letters with values less than 32, each letter would need to be emitted as
380at least a two-part VBR, which means that each letter would require at least 12
381bits. This is not an efficient encoding, but it is fully general.
382</p>
Chris Lattnerdaeb63c2007-05-12 07:49:15 +0000[diff] [blame]383
384</div>
385
386<!-- _______________________________________________________________________ -->
387<div class="doc_subsubsection"> <a name="abbrev_records">Abbreviated Record
388Encoding</a></div>
389
390<div class="doc_text">
391
392<p><tt>[&lt;abbrevid&gt;, fields...]</tt></p>
393
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]394<p>
395An abbreviated record is a abbreviation id followed by a set of fields that are
396encoded according to the <a href="#abbreviations">abbreviation definition</a>.
397This allows records to be encoded significantly more densely than records
398encoded with the <tt><a href="#UNABBREV_RECORD">UNABBREV_RECORD</a></tt> type,
399and allows the abbreviation types to be specified in the stream itself, which
400allows the files to be completely self describing. The actual encoding of
401abbreviations is defined below.
Chris Lattnerdaeb63c2007-05-12 07:49:15 +0000[diff] [blame]402</p>
403
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]404<p>The record code, which is the first field of an abbreviated record,
405may be encoded in the abbreviation definition (as a literal
406operand) or supplied in the abbreviated record (as a Fixed or VBR
407operand value).</p>
408
Chris Lattnerdaeb63c2007-05-12 07:49:15 +0000[diff] [blame]409</div>
410
411<!-- ======================================================================= -->
412<div class="doc_subsection"><a name="abbreviations">Abbreviations</a>
413</div>
414
415<div class="doc_text">
416<p>
417Abbreviations are an important form of compression for bitstreams. The idea is
418to specify a dense encoding for a class of records once, then use that encoding
419to emit many records. It takes space to emit the encoding into the file, but
420the space is recouped (hopefully plus some) when the records that use it are
421emitted.
422</p>
Chris Lattner3a1716d2007-05-12 05:37:42 +0000[diff] [blame]423
424<p>
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]425Abbreviations can be determined dynamically per client, per file. Because the
Chris Lattnerdaeb63c2007-05-12 07:49:15 +0000[diff] [blame]426abbreviations are stored in the bitstream itself, different streams of the same
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]427format can contain different sets of abbreviations according to the needs
428of the specific stream.
429As a concrete example, LLVM IR files usually emit an abbreviation
Chris Lattnerdaeb63c2007-05-12 07:49:15 +0000[diff] [blame]430for binary operators. If a specific LLVM module contained no or few binary
431operators, the abbreviation does not need to be emitted.
Chris Lattner3a1716d2007-05-12 05:37:42 +0000[diff] [blame]432</p>
Chris Lattnerdaeb63c2007-05-12 07:49:15 +0000[diff] [blame]433</div>
434
435<!-- _______________________________________________________________________ -->
436<div class="doc_subsubsection"><a name="DEFINE_ABBREV">DEFINE_ABBREV
437 Encoding</a></div>
438
439<div class="doc_text">
440
441<p><tt>[DEFINE_ABBREV, numabbrevops<sub>vbr5</sub>, abbrevop0, abbrevop1,
442 ...]</tt></p>
443
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]444<p>
445A <tt>DEFINE_ABBREV</tt> record adds an abbreviation to the list of currently
446defined abbreviations in the scope of this block. This definition only exists
447inside this immediate block &mdash; it is not visible in subblocks or enclosing
448blocks. Abbreviations are implicitly assigned IDs sequentially starting from 4
449(the first application-defined abbreviation ID). Any abbreviations defined in a
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]450<tt>BLOCKINFO</tt> record for the particular block type
451receive IDs first, in order, followed by any
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]452abbreviations defined within the block itself. Abbreviated data records
453reference this ID to indicate what abbreviation they are invoking.
454</p>
Chris Lattnerf19b8e42007-10-08 18:42:45 +0000[diff] [blame]455
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]456<p>
457An abbreviation definition consists of the <tt>DEFINE_ABBREV</tt> abbrevid
458followed by a VBR that specifies the number of abbrev operands, then the abbrev
Chris Lattnerdaeb63c2007-05-12 07:49:15 +0000[diff] [blame]459operands themselves. Abbreviation operands come in three forms. They all start
460with a single bit that indicates whether the abbrev operand is a literal operand
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]461(when the bit is 1) or an encoding operand (when the bit is 0).
462</p>
Chris Lattnerdaeb63c2007-05-12 07:49:15 +0000[diff] [blame]463
464<ol>
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]465<li>Literal operands &mdash; <tt>[1<sub>1</sub>, litvalue<sub>vbr8</sub>]</tt>
466&mdash; Literal operands specify that the value in the result is always a single
467specific value. This specific value is emitted as a vbr8 after the bit
468indicating that it is a literal operand.</li>
469<li>Encoding info without data &mdash; <tt>[0<sub>1</sub>,
470 encoding<sub>3</sub>]</tt> &mdash; Operand encodings that do not have extra
471 data are just emitted as their code.
Chris Lattnerdaeb63c2007-05-12 07:49:15 +0000[diff] [blame]472</li>
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]473<li>Encoding info with data &mdash; <tt>[0<sub>1</sub>, encoding<sub>3</sub>,
474value<sub>vbr5</sub>]</tt> &mdash; Operand encodings that do have extra data are
Chris Lattner7300af52007-05-13 00:59:52 +0000[diff] [blame]475emitted as their code, followed by the extra data.
Chris Lattnerdaeb63c2007-05-12 07:49:15 +0000[diff] [blame]476</li>
477</ol>
Chris Lattner3a1716d2007-05-12 05:37:42 +0000[diff] [blame]478
Chris Lattner7300af52007-05-13 00:59:52 +0000[diff] [blame]479<p>The possible operand encodings are:</p>
480
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]481<ul>
482<li>Fixed (code 1): The field should be emitted as
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]483 a <a href="#fixedwidth">fixed-width value</a>, whose width is specified by
484 the operand's extra data.</li>
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]485<li>VBR (code 2): The field should be emitted as
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]486 a <a href="#variablewidth">variable-width value</a>, whose width is
487 specified by the operand's extra data.</li>
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]488<li>Array (code 3): This field is an array of values. The array operand
489 has no extra data, but expects another operand to follow it, indicating
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]490 the element type of the array. When reading an array in an abbreviated
491 record, the first integer is a vbr6 that indicates the array length,
492 followed by the encoded elements of the array. An array may only occur as
493 the last operand of an abbreviation (except for the one final operand that
494 gives the array's type).</li>
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]495<li>Char6 (code 4): This field should be emitted as
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]496 a <a href="#char6">char6-encoded value</a>. This operand type takes no
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]497 extra data. Char6 encoding is normally used as an array element type.
498 </li>
499<li>Blob (code 5): This field is emitted as a vbr6, followed by padding to a
Chris Lattnerdcd006b2009-04-06 21:50:39 +0000[diff] [blame]500 32-bit boundary (for alignment) and an array of 8-bit objects. The array of
501 bytes is further followed by tail padding to ensure that its total length is
502 a multiple of 4 bytes. This makes it very efficient for the reader to
503 decode the data without having to make a copy of it: it can use a pointer to
504 the data in the mapped in file and poke directly at it. A blob may only
505 occur as the last operand of an abbreviation.</li>
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]506</ul>
Chris Lattner7300af52007-05-13 00:59:52 +0000[diff] [blame]507
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]508<p>
509For example, target triples in LLVM modules are encoded as a record of the
Chris Lattner7300af52007-05-13 00:59:52 +0000[diff] [blame]510form <tt>[TRIPLE, 'a', 'b', 'c', 'd']</tt>. Consider if the bitstream emitted
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]511the following abbrev entry:
512</p>
Chris Lattner7300af52007-05-13 00:59:52 +0000[diff] [blame]513
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]514<div class="doc_code">
515<pre>
516[0, Fixed, 4]
517[0, Array]
518[0, Char6]
519</pre>
520</div>
Chris Lattner7300af52007-05-13 00:59:52 +0000[diff] [blame]521
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]522<p>
523When emitting a record with this abbreviation, the above entry would be emitted
524as:
525</p>
Chris Lattner7300af52007-05-13 00:59:52 +0000[diff] [blame]526
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]527<div class="doc_code">
Bill Wendling903bcc42009-04-04 22:36:02 +0000[diff] [blame]528<p>
529<tt>[4<sub>abbrevwidth</sub>, 2<sub>4</sub>, 4<sub>vbr6</sub>, 0<sub>6</sub>,
5301<sub>6</sub>, 2<sub>6</sub>, 3<sub>6</sub>]</tt>
531</p>
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]532</div>
Chris Lattner7300af52007-05-13 00:59:52 +0000[diff] [blame]533
534<p>These values are:</p>
535
536<ol>
537<li>The first value, 4, is the abbreviation ID for this abbreviation.</li>
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]538<li>The second value, 2, is the record code for <tt>TRIPLE</tt> records within LLVM IR file <tt>MODULE_BLOCK</tt> blocks.</li>
Chris Lattner7300af52007-05-13 00:59:52 +0000[diff] [blame]539<li>The third value, 4, is the length of the array.</li>
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]540<li>The rest of the values are the char6 encoded values
541 for <tt>"abcd"</tt>.</li>
Chris Lattner7300af52007-05-13 00:59:52 +0000[diff] [blame]542</ol>
543
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]544<p>
545With this abbreviation, the triple is emitted with only 37 bits (assuming a
Chris Lattner7300af52007-05-13 00:59:52 +0000[diff] [blame]546abbrev id width of 3). Without the abbreviation, significantly more space would
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]547be required to emit the target triple. Also, because the <tt>TRIPLE</tt> value
548is not emitted as a literal in the abbreviation, the abbreviation can also be
549used for any other string value.
Chris Lattner7300af52007-05-13 00:59:52 +0000[diff] [blame]550</p>
551
Chris Lattner3a1716d2007-05-12 05:37:42 +0000[diff] [blame]552</div>
553
Chris Lattner7300af52007-05-13 00:59:52 +0000[diff] [blame]554<!-- ======================================================================= -->
555<div class="doc_subsection"><a name="stdblocks">Standard Blocks</a>
556</div>
557
558<div class="doc_text">
559
560<p>
561In addition to the basic block structure and record encodings, the bitstream
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]562also defines specific built-in block types. These block types specify how the
Chris Lattner7300af52007-05-13 00:59:52 +0000[diff] [blame]563stream is to be decoded or other metadata. In the future, new standard blocks
Chris Lattnerf19b8e42007-10-08 18:42:45 +0000[diff] [blame]564may be added. Block IDs 0-7 are reserved for standard blocks.
Chris Lattner7300af52007-05-13 00:59:52 +0000[diff] [blame]565</p>
566
567</div>
568
569<!-- _______________________________________________________________________ -->
570<div class="doc_subsubsection"><a name="BLOCKINFO">#0 - BLOCKINFO
571Block</a></div>
572
573<div class="doc_text">
574
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]575<p>
576The <tt>BLOCKINFO</tt> block allows the description of metadata for other
577blocks. The currently specified records are:
578</p>
579
580<div class="doc_code">
581<pre>
582[SETBID (#1), blockid]
583[DEFINE_ABBREV, ...]
Chris Lattnerf9a3ec82009-04-26 22:21:57 +0000[diff] [blame]584[BLOCKNAME, ...name...]
585[SETRECORDNAME, RecordID, ...name...]
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]586</pre>
587</div>
Chris Lattner7300af52007-05-13 00:59:52 +0000[diff] [blame]588
589<p>
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]590The <tt>SETBID</tt> record (code 1) indicates which block ID is being
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]591described. <tt>SETBID</tt> records can occur multiple times throughout the
592block to change which block ID is being described. There must be
593a <tt>SETBID</tt> record prior to any other records.
Chris Lattnerf19b8e42007-10-08 18:42:45 +0000[diff] [blame]594</p>
595
596<p>
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]597Standard <tt>DEFINE_ABBREV</tt> records can occur inside <tt>BLOCKINFO</tt>
598blocks, but unlike their occurrence in normal blocks, the abbreviation is
599defined for blocks matching the block ID we are describing, <i>not</i> the
600<tt>BLOCKINFO</tt> block itself. The abbreviations defined
601in <tt>BLOCKINFO</tt> blocks receive abbreviation IDs as described
602in <tt><a href="#DEFINE_ABBREV">DEFINE_ABBREV</a></tt>.
Chris Lattnerf19b8e42007-10-08 18:42:45 +0000[diff] [blame]603</p>
604
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]605<p>The <tt>BLOCKNAME</tt> record (code 2) can optionally occur in this block. The elements of
606the record are the bytes of the string name of the block. llvm-bcanalyzer can use
Chris Lattnerf9a3ec82009-04-26 22:21:57 +0000[diff] [blame]607this to dump out bitcode files symbolically.</p>
608
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]609<p>The <tt>SETRECORDNAME</tt> record (code 3) can also optionally occur in this block. The
610first operand value is a record ID number, and the rest of the elements of the record are
611the bytes for the string name of the record. llvm-bcanalyzer can use
Chris Lattnerf9a3ec82009-04-26 22:21:57 +0000[diff] [blame]612this to dump out bitcode files symbolically.</p>
613
Chris Lattnerf19b8e42007-10-08 18:42:45 +0000[diff] [blame]614<p>
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]615Note that although the data in <tt>BLOCKINFO</tt> blocks is described as
616"metadata," the abbreviations they contain are essential for parsing records
617from the corresponding blocks. It is not safe to skip them.
Chris Lattner7300af52007-05-13 00:59:52 +0000[diff] [blame]618</p>
619
620</div>
Chris Lattner3a1716d2007-05-12 05:37:42 +0000[diff] [blame]621
Chris Lattnere9ef4572007-05-12 03:23:40 +0000[diff] [blame]622<!-- *********************************************************************** -->
Chris Lattner6fa6a322008-07-09 05:14:23 +0000[diff] [blame]623<div class="doc_section"> <a name="wrapper">Bitcode Wrapper Format</a></div>
624<!-- *********************************************************************** -->
625
626<div class="doc_text">
627
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]628<p>
629Bitcode files for LLVM IR may optionally be wrapped in a simple wrapper
Chris Lattner6fa6a322008-07-09 05:14:23 +0000[diff] [blame]630structure. This structure contains a simple header that indicates the offset
631and size of the embedded BC file. This allows additional information to be
632stored alongside the BC file. The structure of this file header is:
633</p>
634
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]635<div class="doc_code">
Bill Wendling903bcc42009-04-04 22:36:02 +0000[diff] [blame]636<p>
637<tt>[Magic<sub>32</sub>, Version<sub>32</sub>, Offset<sub>32</sub>,
638Size<sub>32</sub>, CPUType<sub>32</sub>]</tt>
639</p>
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]640</div>
Chris Lattner6fa6a322008-07-09 05:14:23 +0000[diff] [blame]641
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]642<p>
643Each of the fields are 32-bit fields stored in little endian form (as with
Chris Lattner6fa6a322008-07-09 05:14:23 +0000[diff] [blame]644the rest of the bitcode file fields). The Magic number is always
645<tt>0x0B17C0DE</tt> and the version is currently always <tt>0</tt>. The Offset
646field is the offset in bytes to the start of the bitcode stream in the file, and
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]647the Size field is the size in bytes of the stream. CPUType is a target-specific
Chris Lattner6fa6a322008-07-09 05:14:23 +0000[diff] [blame]648value that can be used to encode the CPU of the target.
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]649</p>
Chris Lattner6fa6a322008-07-09 05:14:23 +0000[diff] [blame]650
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]651</div>
Chris Lattner6fa6a322008-07-09 05:14:23 +0000[diff] [blame]652
653<!-- *********************************************************************** -->
Chris Lattnere9ef4572007-05-12 03:23:40 +0000[diff] [blame]654<div class="doc_section"> <a name="llvmir">LLVM IR Encoding</a></div>
655<!-- *********************************************************************** -->
656
657<div class="doc_text">
658
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]659<p>
660LLVM IR is encoded into a bitstream by defining blocks and records. It uses
Chris Lattner69b3e402007-05-13 01:39:44 +0000[diff] [blame]661blocks for things like constant pools, functions, symbol tables, etc. It uses
662records for things like instructions, global variable descriptors, type
663descriptions, etc. This document does not describe the set of abbreviations
664that the writer uses, as these are fully self-described in the file, and the
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]665reader is not allowed to build in any knowledge of this.
666</p>
Chris Lattner69b3e402007-05-13 01:39:44 +0000[diff] [blame]667
668</div>
669
670<!-- ======================================================================= -->
671<div class="doc_subsection"><a name="basics">Basics</a>
672</div>
673
674<!-- _______________________________________________________________________ -->
675<div class="doc_subsubsection"><a name="ir_magic">LLVM IR Magic Number</a></div>
676
677<div class="doc_text">
678
679<p>
680The magic number for LLVM IR files is:
681</p>
682
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]683<div class="doc_code">
Bill Wendling903bcc42009-04-04 22:36:02 +0000[diff] [blame]684<p>
685<tt>[0x0<sub>4</sub>, 0xC<sub>4</sub>, 0xE<sub>4</sub>, 0xD<sub>4</sub>]</tt>
686</p>
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]687</div>
Chris Lattner69b3e402007-05-13 01:39:44 +0000[diff] [blame]688
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]689<p>
690When combined with the bitcode magic number and viewed as bytes, this is
691<tt>"BC&nbsp;0xC0DE"</tt>.
692</p>
Chris Lattner69b3e402007-05-13 01:39:44 +0000[diff] [blame]693
694</div>
695
696<!-- _______________________________________________________________________ -->
697<div class="doc_subsubsection"><a name="ir_signed_vbr">Signed VBRs</a></div>
698
699<div class="doc_text">
700
701<p>
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]702<a href="#variablewidth">Variable Width Integer</a> encoding is an efficient way to
703encode arbitrary sized unsigned values, but is an extremely inefficient for
704encoding signed values, as signed values are otherwise treated as maximally large
705unsigned values.
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]706</p>
Chris Lattner69b3e402007-05-13 01:39:44 +0000[diff] [blame]707
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]708<p>
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]709As such, signed VBR values of a specific width are emitted as follows:
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]710</p>
Chris Lattner69b3e402007-05-13 01:39:44 +0000[diff] [blame]711
712<ul>
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]713<li>Positive values are emitted as VBRs of the specified width, but with their
Chris Lattner69b3e402007-05-13 01:39:44 +0000[diff] [blame]714 value shifted left by one.</li>
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]715<li>Negative values are emitted as VBRs of the specified width, but the negated
Chris Lattner69b3e402007-05-13 01:39:44 +0000[diff] [blame]716 value is shifted left by one, and the low bit is set.</li>
717</ul>
718
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]719<p>
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]720With this encoding, small positive and small negative values can both
721be emitted efficiently. Signed VBR encoding is used in
722<tt>CST_CODE_INTEGER</tt> and <tt>CST_CODE_WIDE_INTEGER</tt> records
723within <tt>CONSTANTS_BLOCK</tt> blocks.
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]724</p>
Chris Lattner69b3e402007-05-13 01:39:44 +0000[diff] [blame]725
726</div>
727
728
729<!-- _______________________________________________________________________ -->
730<div class="doc_subsubsection"><a name="ir_blocks">LLVM IR Blocks</a></div>
731
732<div class="doc_text">
733
734<p>
735LLVM IR is defined with the following blocks:
736</p>
737
738<ul>
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]739<li>8 &mdash; <a href="#MODULE_BLOCK"><tt>MODULE_BLOCK</tt></a> &mdash; This is the top-level block that
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]740 contains the entire module, and describes a variety of per-module
741 information.</li>
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]742<li>9 &mdash; <a href="#PARAMATTR_BLOCK"><tt>PARAMATTR_BLOCK</tt></a> &mdash; This enumerates the parameter
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]743 attributes.</li>
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]744<li>10 &mdash; <a href="#TYPE_BLOCK"><tt>TYPE_BLOCK</tt></a> &mdash; This describes all of the types in
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]745 the module.</li>
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]746<li>11 &mdash; <a href="#CONSTANTS_BLOCK"><tt>CONSTANTS_BLOCK</tt></a> &mdash; This describes constants for a
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]747 module or function.</li>
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]748<li>12 &mdash; <a href="#FUNCTION_BLOCK"><tt>FUNCTION_BLOCK</tt></a> &mdash; This describes a function
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]749 body.</li>
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]750<li>13 &mdash; <a href="#TYPE_SYMTAB_BLOCK"><tt>TYPE_SYMTAB_BLOCK</tt></a> &mdash; This describes the type symbol
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]751 table.</li>
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]752<li>14 &mdash; <a href="#VALUE_SYMTAB_BLOCK"><tt>VALUE_SYMTAB_BLOCK</tt></a> &mdash; This describes a value symbol
Bill Wendlingbb7425f2009-04-04 22:27:03 +0000[diff] [blame]753 table.</li>
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]754<li>15 &mdash; <a href="#METADATA_BLOCK"><tt>METADATA_BLOCK</tt></a> &mdash; This describes metadata items.</li>
755<li>16 &mdash; <a href="#METADATA_ATTACHMENT"><tt>METADATA_ATTACHMENT</tt></a> &mdash; This contains records associating metadata with function instruction values.</li>
Chris Lattner69b3e402007-05-13 01:39:44 +0000[diff] [blame]756</ul>
757
758</div>
759
760<!-- ======================================================================= -->
761<div class="doc_subsection"><a name="MODULE_BLOCK">MODULE_BLOCK Contents</a>
762</div>
763
764<div class="doc_text">
765
Chris Lattner5c303e82009-10-29 04:25:46 +0000[diff] [blame]766<p>The <tt>MODULE_BLOCK</tt> block (id 8) is the top-level block for LLVM
767bitcode files, and each bitcode file must contain exactly one. In
768addition to records (described below) containing information
769about the module, a <tt>MODULE_BLOCK</tt> block may contain the
770following sub-blocks:
771</p>
772
773<ul>
774<li><a href="#BLOCKINFO"><tt>BLOCKINFO</tt></a></li>
775<li><a href="#PARAMATTR_BLOCK"><tt>PARAMATTR_BLOCK</tt></a></li>
776<li><a href="#TYPE_BLOCK"><tt>TYPE_BLOCK</tt></a></li>
777<li><a href="#TYPE_SYMTAB_BLOCK"><tt>TYPE_SYMTAB_BLOCK</tt></a></li>
778<li><a href="#VALUE_SYMTAB_BLOCK"><tt>VALUE_SYMTAB_BLOCK</tt></a></li>
779<li><a href="#CONSTANTS_BLOCK"><tt>CONSTANTS_BLOCK</tt></a></li>
780<li><a href="#FUNCTION_BLOCK"><tt>FUNCTION_BLOCK</tt></a></li>
781<li><a href="#METADATA_BLOCK"><tt>METADATA_BLOCK</tt></a></li>
782</ul>
783
784</div>
785
786<!-- _______________________________________________________________________ -->
787<div class="doc_subsubsection"><a name="MODULE_CODE_VERSION">MODULE_CODE_VERSION Record</a>
788</div>
789
790<div class="doc_text">
791
792<p><tt>[VERSION, version#]</tt></p>
793
794<p>The <tt>VERSION</tt> record (code 1) contains a single value
795indicating the format version. Only version 0 is supported at this
796time.</p>
797</div>
798
799<!-- _______________________________________________________________________ -->
800<div class="doc_subsubsection"><a name="MODULE_CODE_TRIPLE">MODULE_CODE_TRIPLE Record</a>
801</div>
802
803<div class="doc_text">
804<p><tt>[TRIPLE, ...string...]</tt></p>
805
806<p>The <tt>TRIPLE</tt> record (code 2) contains a variable number of
807values representing the bytes of the <tt>target triple</tt>
808specification string.</p>
809</div>
810
811<!-- _______________________________________________________________________ -->
812<div class="doc_subsubsection"><a name="MODULE_CODE_DATALAYOUT">MODULE_CODE_DATALAYOUT Record</a>
813</div>
814
815<div class="doc_text">
816<p><tt>[DATALAYOUT, ...string...]</tt></p>
817
818<p>The <tt>DATALAYOUT</tt> record (code 3) contains a variable number of
819values representing the bytes of the <tt>target datalayout</tt>
820specification string.</p>
821</div>
822
823<!-- _______________________________________________________________________ -->
824<div class="doc_subsubsection"><a name="MODULE_CODE_ASM">MODULE_CODE_ASM Record</a>
825</div>
826
827<div class="doc_text">
828<p><tt>[ASM, ...string...]</tt></p>
829
830<p>The <tt>ASM</tt> record (code 4) contains a variable number of
831values representing the bytes of <tt>module asm</tt> strings, with
832individual assembly blocks separated by newline (ASCII 10) characters.</p>
833</div>
834
835<!-- _______________________________________________________________________ -->
836<div class="doc_subsubsection"><a name="MODULE_CODE_SECTIONNAME">MODULE_CODE_SECTIONNAME Record</a>
837</div>
838
839<div class="doc_text">
840<p><tt>[SECTIONNAME, ...string...]</tt></p>
841
842<p>The <tt>SECTIONNAME</tt> record (code 5) contains a variable number
843of values representing the bytes of a single section name
844string. There should be one <tt>SECTIONNAME</tt> record for each
845section name referenced (e.g., in global variable or function
846<tt>section</tt> attributes) within the module. These records can be
847referenced by the 1-based index in the <i>section</i> fields of
848<tt>GLOBALVAR</tt> or <tt>FUNCTION</tt> records.</p>
849</div>
850
851<!-- _______________________________________________________________________ -->
852<div class="doc_subsubsection"><a name="MODULE_CODE_DEPLIB">MODULE_CODE_DEPLIB Record</a>
853</div>
854
855<div class="doc_text">
856<p><tt>[DEPLIB, ...string...]</tt></p>
857
858<p>The <tt>DEPLIB</tt> record (code 6) contains a variable number of
859values representing the bytes of a single dependent library name
860string, one of the libraries mentioned in a <tt>deplibs</tt>
861declaration. There should be one <tt>DEPLIB</tt> record for each
862library name referenced.</p>
863</div>
864
865<!-- _______________________________________________________________________ -->
866<div class="doc_subsubsection"><a name="MODULE_CODE_GLOBALVAR">MODULE_CODE_GLOBALVAR Record</a>
867</div>
868
869<div class="doc_text">
870<p><tt>[GLOBALVAR, pointer type, isconst, initid, linkage, alignment, section, visibility, threadlocal]</tt></p>
871
872<p>The <tt>GLOBALVAR</tt> record (code 7) marks the declaration or
873definition of a global variable. The operand fields are:</p>
874
875<ul>
876<li><i>pointer type</i>: The type index of the pointer type used to point to
877this global variable</li>
878
879<li><i>isconst</i>: Non-zero if the variable is treated as constant within
880the module, or zero if it is not</li>
881
882<li><i>initid</i>: If non-zero, the value index of the initializer for this
883variable, plus 1.</li>
884
885<li><a name="linkage"><i>linkage</i></a>: An encoding of the linkage
886type for this variable:
887 <ul>
888 <li><tt>external</tt>: code 0</li>
889 <li><tt>weak</tt>: code 1</li>
890 <li><tt>appending</tt>: code 2</li>
891 <li><tt>internal</tt>: code 3</li>
892 <li><tt>linkonce</tt>: code 4</li>
893 <li><tt>dllimport</tt>: code 5</li>
894 <li><tt>dllexport</tt>: code 6</li>
895 <li><tt>extern_weak</tt>: code 7</li>
896 <li><tt>common</tt>: code 8</li>
897 <li><tt>private</tt>: code 9</li>
898 <li><tt>weak_odr</tt>: code 10</li>
899 <li><tt>linkonce_odr</tt>: code 11</li>
900 <li><tt>available_externally</tt>: code 12</li>
901 <li><tt>linker_private</tt>: code 13</li>
902 </ul>
903</li>
904
905<li><i>alignment</i>: The logarithm base 2 of the variable's requested
906alignment, plus 1</li>
907
908<li><i>section</i>: If non-zero, the 1-based section index in the
909table of <a href="#MODULE_CODE_SECTIONNAME">MODULE_CODE_SECTIONNAME</a>
910entries.</li>
911
912<li><a name="visibility"><i>visibility</i></a>: If present, an
913encoding of the visibility of this variable:
914 <ul>
915 <li><tt>default</tt>: code 0</li>
916 <li><tt>hidden</tt>: code 1</li>
917 <li><tt>protected</tt>: code 2</li>
918 </ul>
919</li>
920
921<li><i>threadlocal</i>: If present and non-zero, indicates that the variable
922is <tt>thread_local</tt></li>
923
924</ul>
925</div>
926
927<!-- _______________________________________________________________________ -->
928<div class="doc_subsubsection"><a name="MODULE_CODE_FUNCTION">MODULE_CODE_FUNCTION Record</a>
929</div>
930
931<div class="doc_text">
932
933<p><tt>[FUNCTION, type, callingconv, isproto, linkage, paramattr, alignment, section, visibility, gc]</tt></p>
934
935<p>The <tt>FUNCTION</tt> record (code 8) marks the declaration or
936definition of a function. The operand fields are:</p>
937
938<ul>
939<li><i>type</i>: The type index of the function type describing this function</li>
940
941<li><i>callingconv</i>: The calling convention number:
942 <ul>
943 <li><tt>ccc</tt>: code 0</li>
944 <li><tt>fastcc</tt>: code 8</li>
945 <li><tt>coldcc</tt>: code 9</li>
946 <li><tt>x86_stdcallcc</tt>: code 64</li>
947 <li><tt>x86_fastcallcc</tt>: code 65</li>
948 <li><tt>arm_apcscc</tt>: code 66</li>
949 <li><tt>arm_aapcscc</tt>: code 67</li>
950 <li><tt>arm_aapcs_vfpcc</tt>: code 68</li>
951 </ul>
952</li>
953
954<li><i>isproto</i>: Non-zero if this entry represents a declaration
955rather than a definition</li>
956
957<li><i>linkage</i>: An encoding of the <a href="#linkage">linkage type</a>
958for this function</li>
959
960<li><i>paramattr</i>: If nonzero, the 1-based parameter attribute index
961into the table of <a href="#PARAMATTR_CODE_ENTRY">PARAMATTR_CODE_ENTRY</a>
962entries.</li>
963
964<li><i>alignment</i>: The logarithm base 2 of the function's requested
965alignment, plus 1</li>
966
967<li><i>section</i>: If non-zero, the 1-based section index in the
968table of <a href="#MODULE_CODE_SECTIONNAME">MODULE_CODE_SECTIONNAME</a>
969entries.</li>
970
971<li><i>visibility</i>: An encoding of the <a href="#visibility">visibility</a>
972 of this function</li>
973
974<li><i>gc</i>: If present and nonzero, the 1-based garbage collector
975index in the table of
976<a href="#MODULE_CODE_GCNAME">MODULE_CODE_GCNAME</a> entries.</li>
977</ul>
978</div>
979
980<!-- _______________________________________________________________________ -->
981<div class="doc_subsubsection"><a name="MODULE_CODE_ALIAS">MODULE_CODE_ALIAS Record</a>
982</div>
983
984<div class="doc_text">
985
986<p><tt>[ALIAS, alias type, aliasee val#, linkage, visibility]</tt></p>
987
988<p>The <tt>ALIAS</tt> record (code 9) marks the definition of an
989alias. The operand fields are</p>
990
991<ul>
992<li><i>alias type</i>: The type index of the alias</li>
993
994<li><i>aliasee val#</i>: The value index of the aliased value</li>
995
996<li><i>linkage</i>: An encoding of the <a href="#linkage">linkage type</a>
997for this alias</li>
998
999<li><i>visibility</i>: If present, an encoding of the
1000<a href="#visibility">visibility</a> of the alias</li>
1001
1002</ul>
1003</div>
1004
1005<!-- _______________________________________________________________________ -->
1006<div class="doc_subsubsection"><a name="MODULE_CODE_PURGEVALS">MODULE_CODE_PURGEVALS Record</a>
1007</div>
1008
1009<div class="doc_text">
1010<p><tt>[PURGEVALS, numvals]</tt></p>
1011
1012<p>The <tt>PURGEVALS</tt> record (code 10) resets the module-level
1013value list to the size given by the single operand value. Module-level
1014value list items are added by <tt>GLOBALVAR</tt>, <tt>FUNCTION</tt>,
1015and <tt>ALIAS</tt> records. After a <tt>PURGEVALS</tt> record is seen,
1016new value indices will start from the given <i>numvals</i> value.</p>
1017</div>
1018
1019<!-- _______________________________________________________________________ -->
1020<div class="doc_subsubsection"><a name="MODULE_CODE_GCNAME">MODULE_CODE_GCNAME Record</a>
1021</div>
1022
1023<div class="doc_text">
1024<p><tt>[GCNAME, ...string...]</tt></p>
1025
1026<p>The <tt>GCNAME</tt> record (code 11) contains a variable number of
1027values representing the bytes of a single garbage collector name
1028string. There should be one <tt>GCNAME</tt> record for each garbage
1029collector name referenced in function <tt>gc</tt> attributes within
1030the module. These records can be referenced by 1-based index in the <i>gc</i>
1031fields of <tt>FUNCTION</tt> records.</p>
1032</div>
1033
1034<!-- ======================================================================= -->
1035<div class="doc_subsection"><a name="PARAMATTR_BLOCK">PARAMATTR_BLOCK Contents</a>
1036</div>
1037
1038<div class="doc_text">
1039
1040<p>The <tt>PARAMATTR_BLOCK</tt> block (id 9) ...
1041</p>
1042
1043</div>
1044
1045
1046<!-- _______________________________________________________________________ -->
1047<div class="doc_subsubsection"><a name="PARAMATTR_CODE_ENTRY">PARAMATTR_CODE_ENTRY Record</a>
1048</div>
1049
1050<div class="doc_text">
1051
1052<p><tt>[ENTRY, paramidx0, attr0, paramidx1, attr1...]</tt></p>
1053
1054<p>The <tt>ENTRY</tt> record (code 1) ...
1055</p>
1056</div>
1057
1058<!-- ======================================================================= -->
1059<div class="doc_subsection"><a name="TYPE_BLOCK">TYPE_BLOCK Contents</a>
1060</div>
1061
1062<div class="doc_text">
1063
1064<p>The <tt>TYPE_BLOCK</tt> block (id 10) ...
1065</p>
1066
1067</div>
1068
1069
1070<!-- ======================================================================= -->
1071<div class="doc_subsection"><a name="CONSTANTS_BLOCK">CONSTANTS_BLOCK Contents</a>
1072</div>
1073
1074<div class="doc_text">
1075
1076<p>The <tt>CONSTANTS_BLOCK</tt> block (id 11) ...
1077</p>
1078
1079</div>
1080
1081
1082<!-- ======================================================================= -->
1083<div class="doc_subsection"><a name="FUNCTION_BLOCK">FUNCTION_BLOCK Contents</a>
1084</div>
1085
1086<div class="doc_text">
1087
1088<p>The <tt>FUNCTION_BLOCK</tt> block (id 12) ...
1089</p>
1090
1091<p>In addition to the record types described below, a
1092<tt>FUNCTION_BLOCK</tt> block may contain the following sub-blocks:
1093</p>
1094
1095<ul>
1096<li><a href="#CONSTANTS_BLOCK"><tt>CONSTANTS_BLOCK</tt></a></li>
1097<li><a href="#VALUE_SYMTAB_BLOCK"><tt>VALUE_SYMTAB_BLOCK</tt></a></li>
1098<li><a href="#METADATA_ATTACHMENT"><tt>METADATA_ATTACHMENT</tt></a></li>
1099</ul>
1100
1101</div>
1102
1103
1104<!-- ======================================================================= -->
1105<div class="doc_subsection"><a name="TYPE_SYMTAB_BLOCK">TYPE_SYMTAB_BLOCK Contents</a>
1106</div>
1107
1108<div class="doc_text">
1109
1110<p>The <tt>TYPE_SYMTAB_BLOCK</tt> block (id 13) ...
1111</p>
1112
1113</div>
1114
1115
1116<!-- ======================================================================= -->
1117<div class="doc_subsection"><a name="VALUE_SYMTAB_BLOCK">VALUE_SYMTAB_BLOCK Contents</a>
1118</div>
1119
1120<div class="doc_text">
1121
1122<p>The <tt>VALUE_SYMTAB_BLOCK</tt> block (id 14) ...
1123</p>
1124
1125</div>
1126
1127
1128<!-- ======================================================================= -->
1129<div class="doc_subsection"><a name="METADATA_BLOCK">METADATA_BLOCK Contents</a>
1130</div>
1131
1132<div class="doc_text">
1133
1134<p>The <tt>METADATA_BLOCK</tt> block (id 15) ...
1135</p>
1136
1137</div>
1138
1139
1140<!-- ======================================================================= -->
1141<div class="doc_subsection"><a name="METADATA_ATTACHMENT">METADATA_ATTACHMENT Contents</a>
1142</div>
1143
1144<div class="doc_text">
1145
1146<p>The <tt>METADATA_ATTACHMENT</tt> block (id 16) ...
Chris Lattner69b3e402007-05-13 01:39:44 +0000[diff] [blame]1147</p>
Chris Lattnere9ef4572007-05-12 03:23:40 +0000[diff] [blame]1148
1149</div>
1150
1151
Reid Spencer2c1ce4f2007-01-20 23:21:08 +0000[diff] [blame]1152<!-- *********************************************************************** -->
1153<hr>
1154<address> <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
Misha Brukman44408702008-12-11 17:34:48 +0000[diff] [blame]1155 src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
Reid Spencer2c1ce4f2007-01-20 23:21:08 +0000[diff] [blame]1156<a href="http://validator.w3.org/check/referer"><img
Misha Brukman44408702008-12-11 17:34:48 +0000[diff] [blame]1157 src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
Chris Lattnere9ef4572007-05-12 03:23:40 +0000[diff] [blame]1158 <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
Reid Spencer2c1ce4f2007-01-20 23:21:08 +0000[diff] [blame]1159<a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
1160Last modified: $Date$
1161</address>
1162</body>
1163</html>