docs/BitCodeFormat.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   2                       "http://www.w3.org/TR/html4/strict.dtd">
   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">
   8 </head>
   9 <body>
  10 <h1> LLVM Bitcode File Format</h1>
  11 <ol>
  12   <li><a href="#abstract">Abstract</a></li>
  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>
  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>
  21     <li><a href="#abbreviations">Abbreviations</a></li>
  22     <li><a href="#stdblocks">Standard Blocks</a></li>
  23     </ol>
  24   </li>
  25   <li><a href="#wrapper">Bitcode Wrapper Format</a>
  26   </li>
  27   <li><a href="#llvmir">LLVM IR Encoding</a>
  28     <ol>
  29     <li><a href="#basics">Basics</a></li>
  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>
  39     </ol>
  40   </li>
  41 </ol>
  42 <div class="doc_author">
  43   <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>,
  44   <a href="http://www.reverberate.org">Joshua Haberman</a>,
  45   and <a href="mailto:housel@acm.org">Peter S. Housel</a>.
  46 </p>
  47 </div>
  48
  49 <!-- *********************************************************************** -->
  50 <h2><a name="abstract">Abstract</a></h2>
  51 <!-- *********************************************************************** -->
  52
  53 <div class="doc_text">
  54
  55 <p>This document describes the LLVM bitstream file format and the encoding of
  56 the LLVM IR into it.</p>
  57
  58 </div>
  59
  60 <!-- *********************************************************************** -->
  61 <h2><a name="overview">Overview</a></h2>
  62 <!-- *********************************************************************** -->
  63
  64 <div class="doc_text">
  65
  66 <p>
  67 What is commonly known as the LLVM bitcode file format (also, sometimes
  68 anachronistically known as bytecode) is actually two things: a <a
  69 href="#bitstream">bitstream container format</a>
  70 and an <a href="#llvmir">encoding of LLVM IR</a> into the container format.</p>
  71
  72 <p>
  73 The bitstream format is an abstract encoding of structured data, very
  74 similar to XML in some ways.  Like XML, bitstream files contain tags, and nested
  75 structures, and you can parse the file without having to understand the tags.
  76 Unlike XML, the bitstream format is a binary encoding, and unlike XML it
  77 provides a mechanism for the file to self-describe "abbreviations", which are
  78 effectively size optimizations for the content.</p>
  79
  80 <p>LLVM IR files may be optionally embedded into a <a
  81 href="#wrapper">wrapper</a> structure that makes it easy to embed extra data
  82 along with LLVM IR files.</p>
  83
  84 <p>This document first describes the LLVM bitstream format, describes the
  85 wrapper format, then describes the record structure used by LLVM IR files.
  86 </p>
  87
  88 </div>
  89
  90 <!-- *********************************************************************** -->
  91 <h2><a name="bitstream">Bitstream Format</a></h2>
  92 <!-- *********************************************************************** -->
  93
  94 <div class="doc_text">
  95
  96 <p>
  97 The bitstream format is literally a stream of bits, with a very simple
  98 structure.  This structure consists of the following concepts:
  99 </p>
 100
 101 <ul>
 102 <li>A "<a href="#magic">magic number</a>" that identifies the contents of
 103     the stream.</li>
 104 <li>Encoding <a href="#primitives">primitives</a> like variable bit-rate
 105     integers.</li>
 106 <li><a href="#blocks">Blocks</a>, which define nested content.</li>
 107 <li><a href="#datarecord">Data Records</a>, which describe entities within the
 108     file.</li>
 109 <li>Abbreviations, which specify compression optimizations for the file.</li>
 110 </ul>
 111
 112 <p>Note that the <a
 113 href="CommandGuide/html/llvm-bcanalyzer.html">llvm-bcanalyzer</a> tool can be
 114 used to dump and inspect arbitrary bitstreams, which is very useful for
 115 understanding the encoding.</p>
 116
 117 </div>
 118
 119 <!-- ======================================================================= -->
 120 <h3>
 121   <a name="magic">Magic Numbers</a>
 122 </h3>
 123
 124 <div class="doc_text">
 125
 126 <p>The first two bytes of a bitcode file are 'BC' (0x42, 0x43).
 127 The second two bytes are an application-specific magic number.  Generic
 128 bitcode tools can look at only the first two bytes to verify the file is
 129 bitcode, while application-specific programs will want to look at all four.</p>
 130
 131 </div>
 132
 133 <!-- ======================================================================= -->
 134 <h3>
 135   <a name="primitives">Primitives</a>
 136 </h3>
 137
 138 <div class="doc_text">
 139
 140 <p>
 141 A bitstream literally consists of a stream of bits, which are read in order
 142 starting with the least significant bit of each byte.  The stream is made up of a
 143 number of primitive values that encode a stream of unsigned integer values.
 144 These integers are encoded in two ways: either as <a href="#fixedwidth">Fixed
 145 Width Integers</a> or as <a href="#variablewidth">Variable Width
 146 Integers</a>.
 147 </p>
 148
 149 </div>
 150
 151 <!-- _______________________________________________________________________ -->
 152 <h4>
 153   <a name="fixedwidth">Fixed Width Integers</a>
 154 </h4>
 155
 156 <div class="doc_text">
 157
 158 <p>Fixed-width integer values have their low bits emitted directly to the file.
 159    For example, a 3-bit integer value encodes 1 as 001.  Fixed width integers
 160    are used when there are a well-known number of options for a field.  For
 161    example, boolean values are usually encoded with a 1-bit wide integer.
 162 </p>
 163
 164 </div>
 165
 166 <!-- _______________________________________________________________________ -->
 167 <h4>
 168   <a name="variablewidth">Variable Width Integers</a>
 169 </h4>
 170
 171 <div class="doc_text">
 172
 173 <p>Variable-width integer (VBR) values encode values of arbitrary size,
 174 optimizing for the case where the values are small.  Given a 4-bit VBR field,
 175 any 3-bit value (0 through 7) is encoded directly, with the high bit set to
 176 zero.  Values larger than N-1 bits emit their bits in a series of N-1 bit
 177 chunks, where all but the last set the high bit.</p>
 178
 179 <p>For example, the value 27 (0x1B) is encoded as 1011 0011 when emitted as a
 180 vbr4 value.  The first set of four bits indicates the value 3 (011) with a
 181 continuation piece (indicated by a high bit of 1).  The next word indicates a
 182 value of 24 (011 << 3) with no continuation.  The sum (3+24) yields the value
 183 27.
 184 </p>
 185
 186 </div>
 187
 188 <!-- _______________________________________________________________________ -->
 189 <h4><a name="char6">6-bit characters</a></h4>
 190
 191 <div class="doc_text">
 192
 193 <p>6-bit characters encode common characters into a fixed 6-bit field.  They
 194 represent the following characters with the following 6-bit values:</p>
 195
 196 <div class="doc_code">
 197 <pre>
 198 'a' .. 'z' &mdash;  0 .. 25
 199 'A' .. 'Z' &mdash; 26 .. 51
 200 '0' .. '9' &mdash; 52 .. 61
 201        '.' &mdash; 62
 202        '_' &mdash; 63
 203 </pre>
 204 </div>
 205
 206 <p>This encoding is only suitable for encoding characters and strings that
 207 consist only of the above characters.  It is completely incapable of encoding
 208 characters not in the set.</p>
 209
 210 </div>
 211
 212 <!-- _______________________________________________________________________ -->
 213 <h4><a name="wordalign">Word Alignment</a></h4>
 214
 215 <div class="doc_text">
 216
 217 <p>Occasionally, it is useful to emit zero bits until the bitstream is a
 218 multiple of 32 bits.  This ensures that the bit position in the stream can be
 219 represented as a multiple of 32-bit words.</p>
 220
 221 </div>
 222
 223
 224 <!-- ======================================================================= -->
 225 <h3>
 226   <a name="abbrevid">Abbreviation IDs</a>
 227 </h3>
 228
 229 <div class="doc_text">
 230
 231 <p>
 232 A bitstream is a sequential series of <a href="#blocks">Blocks</a> and
 233 <a href="#datarecord">Data Records</a>.  Both of these start with an
 234 abbreviation ID encoded as a fixed-bitwidth field.  The width is specified by
 235 the current block, as described below.  The value of the abbreviation ID
 236 specifies either a builtin ID (which have special meanings, defined below) or
 237 one of the abbreviation IDs defined for the current block by the stream itself.
 238 </p>
 239
 240 <p>
 241 The set of builtin abbrev IDs is:
 242 </p>
 243
 244 <ul>
 245 <li><tt>0 - <a href="#END_BLOCK">END_BLOCK</a></tt> &mdash; This abbrev ID marks
 246     the end of the current block.</li>
 247 <li><tt>1 - <a href="#ENTER_SUBBLOCK">ENTER_SUBBLOCK</a></tt> &mdash; This
 248     abbrev ID marks the beginning of a new block.</li>
 249 <li><tt>2 - <a href="#DEFINE_ABBREV">DEFINE_ABBREV</a></tt> &mdash; This defines
 250     a new abbreviation.</li>
 251 <li><tt>3 - <a href="#UNABBREV_RECORD">UNABBREV_RECORD</a></tt> &mdash; This ID
 252     specifies the definition of an unabbreviated record.</li>
 253 </ul>
 254
 255 <p>Abbreviation IDs 4 and above are defined by the stream itself, and specify
 256 an <a href="#abbrev_records">abbreviated record encoding</a>.</p>
 257
 258 </div>
 259
 260 <!-- ======================================================================= -->
 261 <h3>
 262   <a name="blocks">Blocks</a>
 263 </h3>
 264
 265 <div class="doc_text">
 266
 267 <p>
 268 Blocks in a bitstream denote nested regions of the stream, and are identified by
 269 a content-specific id number (for example, LLVM IR uses an ID of 12 to represent
 270 function bodies).  Block IDs 0-7 are reserved for <a href="#stdblocks">standard blocks</a>
 271 whose meaning is defined by Bitcode; block IDs 8 and greater are
 272 application specific. Nested blocks capture the hierarchical structure of the data
 273 encoded in it, and various properties are associated with blocks as the file is
 274 parsed.  Block definitions allow the reader to efficiently skip blocks
 275 in constant time if the reader wants a summary of blocks, or if it wants to
 276 efficiently skip data it does not understand.  The LLVM IR reader uses this
 277 mechanism to skip function bodies, lazily reading them on demand.
 278 </p>
 279
 280 <p>
 281 When reading and encoding the stream, several properties are maintained for the
 282 block.  In particular, each block maintains:
 283 </p>
 284
 285 <ol>
 286 <li>A current abbrev id width.  This value starts at 2 at the beginning of
 287     the stream, and is set every time a
 288     block record is entered.  The block entry specifies the abbrev id width for
 289     the body of the block.</li>
 290
 291 <li>A set of abbreviations.  Abbreviations may be defined within a block, in
 292     which case they are only defined in that block (neither subblocks nor
 293     enclosing blocks see the abbreviation).  Abbreviations can also be defined
 294     inside a <tt><a href="#BLOCKINFO">BLOCKINFO</a></tt> block, in which case
 295     they are defined in all blocks that match the ID that the BLOCKINFO block is
 296     describing.
 297 </li>
 298 </ol>
 299
 300 <p>
 301 As sub blocks are entered, these properties are saved and the new sub-block has
 302 its own set of abbreviations, and its own abbrev id width.  When a sub-block is
 303 popped, the saved values are restored.
 304 </p>
 305
 306 </div>
 307
 308 <!-- _______________________________________________________________________ -->
 309 <h4><a name="ENTER_SUBBLOCK">ENTER_SUBBLOCK Encoding</a></h4>
 310
 311 <div class="doc_text">
 312
 313 <p><tt>[ENTER_SUBBLOCK, blockid<sub>vbr8</sub>, newabbrevlen<sub>vbr4</sub>,
 314      &lt;align32bits&gt;, blocklen<sub>32</sub>]</tt></p>
 315
 316 <p>
 317 The <tt>ENTER_SUBBLOCK</tt> abbreviation ID specifies the start of a new block
 318 record.  The <tt>blockid</tt> value is encoded as an 8-bit VBR identifier, and
 319 indicates the type of block being entered, which can be
 320 a <a href="#stdblocks">standard block</a> or an application-specific block.
 321 The <tt>newabbrevlen</tt> value is a 4-bit VBR, which specifies the abbrev id
 322 width for the sub-block.  The <tt>blocklen</tt> value is a 32-bit aligned value
 323 that specifies the size of the subblock in 32-bit words. This value allows the
 324 reader to skip over the entire block in one jump.
 325 </p>
 326
 327 </div>
 328
 329 <!-- _______________________________________________________________________ -->
 330 <h4><a name="END_BLOCK">END_BLOCK Encoding</a></h4>
 331
 332 <div class="doc_text">
 333
 334 <p><tt>[END_BLOCK, &lt;align32bits&gt;]</tt></p>
 335
 336 <p>
 337 The <tt>END_BLOCK</tt> abbreviation ID specifies the end of the current block
 338 record.  Its end is aligned to 32-bits to ensure that the size of the block is
 339 an even multiple of 32-bits.
 340 </p>
 341
 342 </div>
 343
 344
 345
 346 <!-- ======================================================================= -->
 347 <h3>
 348   <a name="datarecord">Data Records</a>
 349 </h3>
 350
 351 <div class="doc_text">
 352 <p>
 353 Data records consist of a record code and a number of (up to) 64-bit
 354 integer values.  The interpretation of the code and values is
 355 application specific and may vary between different block types.
 356 Records can be encoded either using an unabbrev record, or with an
 357 abbreviation.  In the LLVM IR format, for example, there is a record
 358 which encodes the target triple of a module.  The code is
 359 <tt>MODULE_CODE_TRIPLE</tt>, and the values of the record are the
 360 ASCII codes for the characters in the string.
 361 </p>
 362
 363 </div>
 364
 365 <!-- _______________________________________________________________________ -->
 366 <h4><a name="UNABBREV_RECORD">UNABBREV_RECORD Encoding</a></h4>
 367
 368 <div class="doc_text">
 369
 370 <p><tt>[UNABBREV_RECORD, code<sub>vbr6</sub>, numops<sub>vbr6</sub>,
 371        op0<sub>vbr6</sub>, op1<sub>vbr6</sub>, ...]</tt></p>
 372
 373 <p>
 374 An <tt>UNABBREV_RECORD</tt> provides a default fallback encoding, which is both
 375 completely general and extremely inefficient.  It can describe an arbitrary
 376 record by emitting the code and operands as VBRs.
 377 </p>
 378
 379 <p>
 380 For example, emitting an LLVM IR target triple as an unabbreviated record
 381 requires emitting the <tt>UNABBREV_RECORD</tt> abbrevid, a vbr6 for the
 382 <tt>MODULE_CODE_TRIPLE</tt> code, a vbr6 for the length of the string, which is
 383 equal to the number of operands, and a vbr6 for each character.  Because there
 384 are no letters with values less than 32, each letter would need to be emitted as
 385 at least a two-part VBR, which means that each letter would require at least 12
 386 bits.  This is not an efficient encoding, but it is fully general.
 387 </p>
 388
 389 </div>
 390
 391 <!-- _______________________________________________________________________ -->
 392 <h4><a name="abbrev_records">Abbreviated Record Encoding</a></h4>
 393
 394 <div class="doc_text">
 395
 396 <p><tt>[&lt;abbrevid&gt;, fields...]</tt></p>
 397
 398 <p>
 399 An abbreviated record is a abbreviation id followed by a set of fields that are
 400 encoded according to the <a href="#abbreviations">abbreviation definition</a>.
 401 This allows records to be encoded significantly more densely than records
 402 encoded with the <tt><a href="#UNABBREV_RECORD">UNABBREV_RECORD</a></tt> type,
 403 and allows the abbreviation types to be specified in the stream itself, which
 404 allows the files to be completely self describing.  The actual encoding of
 405 abbreviations is defined below.
 406 </p>
 407
 408 <p>The record code, which is the first field of an abbreviated record,
 409 may be encoded in the abbreviation definition (as a literal
 410 operand) or supplied in the abbreviated record (as a Fixed or VBR
 411 operand value).</p>
 412
 413 </div>
 414
 415 <!-- ======================================================================= -->
 416 <h3>
 417   <a name="abbreviations">Abbreviations</a>
 418 </h3>
 419
 420 <div class="doc_text">
 421 <p>
 422 Abbreviations are an important form of compression for bitstreams.  The idea is
 423 to specify a dense encoding for a class of records once, then use that encoding
 424 to emit many records.  It takes space to emit the encoding into the file, but
 425 the space is recouped (hopefully plus some) when the records that use it are
 426 emitted.
 427 </p>
 428
 429 <p>
 430 Abbreviations can be determined dynamically per client, per file. Because the
 431 abbreviations are stored in the bitstream itself, different streams of the same
 432 format can contain different sets of abbreviations according to the needs
 433 of the specific stream.
 434 As a concrete example, LLVM IR files usually emit an abbreviation
 435 for binary operators.  If a specific LLVM module contained no or few binary
 436 operators, the abbreviation does not need to be emitted.
 437 </p>
 438 </div>
 439
 440 <!-- _______________________________________________________________________ -->
 441 <h4><a name="DEFINE_ABBREV">DEFINE_ABBREV  Encoding</a></h4>
 442
 443 <div class="doc_text">
 444
 445 <p><tt>[DEFINE_ABBREV, numabbrevops<sub>vbr5</sub>, abbrevop0, abbrevop1,
 446  ...]</tt></p>
 447
 448 <p>
 449 A <tt>DEFINE_ABBREV</tt> record adds an abbreviation to the list of currently
 450 defined abbreviations in the scope of this block.  This definition only exists
 451 inside this immediate block &mdash; it is not visible in subblocks or enclosing
 452 blocks.  Abbreviations are implicitly assigned IDs sequentially starting from 4
 453 (the first application-defined abbreviation ID).  Any abbreviations defined in a
 454 <tt>BLOCKINFO</tt> record for the particular block type
 455 receive IDs first, in order, followed by any
 456 abbreviations defined within the block itself.  Abbreviated data records
 457 reference this ID to indicate what abbreviation they are invoking.
 458 </p>
 459
 460 <p>
 461 An abbreviation definition consists of the <tt>DEFINE_ABBREV</tt> abbrevid
 462 followed by a VBR that specifies the number of abbrev operands, then the abbrev
 463 operands themselves.  Abbreviation operands come in three forms.  They all start
 464 with a single bit that indicates whether the abbrev operand is a literal operand
 465 (when the bit is 1) or an encoding operand (when the bit is 0).
 466 </p>
 467
 468 <ol>
 469 <li>Literal operands &mdash; <tt>[1<sub>1</sub>, litvalue<sub>vbr8</sub>]</tt>
 470 &mdash; Literal operands specify that the value in the result is always a single
 471 specific value.  This specific value is emitted as a vbr8 after the bit
 472 indicating that it is a literal operand.</li>
 473 <li>Encoding info without data &mdash; <tt>[0<sub>1</sub>,
 474  encoding<sub>3</sub>]</tt> &mdash; Operand encodings that do not have extra
 475  data are just emitted as their code.
 476 </li>
 477 <li>Encoding info with data &mdash; <tt>[0<sub>1</sub>, encoding<sub>3</sub>,
 478 value<sub>vbr5</sub>]</tt> &mdash; Operand encodings that do have extra data are
 479 emitted as their code, followed by the extra data.
 480 </li>
 481 </ol>
 482
 483 <p>The possible operand encodings are:</p>
 484
 485 <ul>
 486 <li>Fixed (code 1): The field should be emitted as
 487     a <a href="#fixedwidth">fixed-width value</a>, whose width is specified by
 488     the operand's extra data.</li>
 489 <li>VBR (code 2): The field should be emitted as
 490     a <a href="#variablewidth">variable-width value</a>, whose width is
 491     specified by the operand's extra data.</li>
 492 <li>Array (code 3): This field is an array of values.  The array operand
 493     has no extra data, but expects another operand to follow it, indicating
 494     the element type of the array.  When reading an array in an abbreviated
 495     record, the first integer is a vbr6 that indicates the array length,
 496     followed by the encoded elements of the array.  An array may only occur as
 497     the last operand of an abbreviation (except for the one final operand that
 498     gives the array's type).</li>
 499 <li>Char6 (code 4): This field should be emitted as
 500     a <a href="#char6">char6-encoded value</a>.  This operand type takes no
 501     extra data. Char6 encoding is normally used as an array element type.
 502     </li>
 503 <li>Blob (code 5): This field is emitted as a vbr6, followed by padding to a
 504     32-bit boundary (for alignment) and an array of 8-bit objects.  The array of
 505     bytes is further followed by tail padding to ensure that its total length is
 506     a multiple of 4 bytes.  This makes it very efficient for the reader to
 507     decode the data without having to make a copy of it: it can use a pointer to
 508     the data in the mapped in file and poke directly at it.  A blob may only
 509     occur as the last operand of an abbreviation.</li>
 510 </ul>
 511
 512 <p>
 513 For example, target triples in LLVM modules are encoded as a record of the
 514 form <tt>[TRIPLE, 'a', 'b', 'c', 'd']</tt>.  Consider if the bitstream emitted
 515 the following abbrev entry:
 516 </p>
 517
 518 <div class="doc_code">
 519 <pre>
 520 [0, Fixed, 4]
 521 [0, Array]
 522 [0, Char6]
 523 </pre>
 524 </div>
 525
 526 <p>
 527 When emitting a record with this abbreviation, the above entry would be emitted
 528 as:
 529 </p>
 530
 531 <div class="doc_code">
 532 <p>
 533 <tt>[4<sub>abbrevwidth</sub>, 2<sub>4</sub>, 4<sub>vbr6</sub>, 0<sub>6</sub>,
 534 1<sub>6</sub>, 2<sub>6</sub>, 3<sub>6</sub>]</tt>
 535 </p>
 536 </div>
 537
 538 <p>These values are:</p>
 539
 540 <ol>
 541 <li>The first value, 4, is the abbreviation ID for this abbreviation.</li>
 542 <li>The second value, 2, is the record code for <tt>TRIPLE</tt> records within LLVM IR file <tt>MODULE_BLOCK</tt> blocks.</li>
 543 <li>The third value, 4, is the length of the array.</li>
 544 <li>The rest of the values are the char6 encoded values
 545     for <tt>"abcd"</tt>.</li>
 546 </ol>
 547
 548 <p>
 549 With this abbreviation, the triple is emitted with only 37 bits (assuming a
 550 abbrev id width of 3).  Without the abbreviation, significantly more space would
 551 be required to emit the target triple.  Also, because the <tt>TRIPLE</tt> value
 552 is not emitted as a literal in the abbreviation, the abbreviation can also be
 553 used for any other string value.
 554 </p>
 555
 556 </div>
 557
 558 <!-- ======================================================================= -->
 559 <h3>
 560   <a name="stdblocks">Standard Blocks</a>
 561 </h3>
 562
 563 <div class="doc_text">
 564
 565 <p>
 566 In addition to the basic block structure and record encodings, the bitstream
 567 also defines specific built-in block types.  These block types specify how the
 568 stream is to be decoded or other metadata.  In the future, new standard blocks
 569 may be added.  Block IDs 0-7 are reserved for standard blocks.
 570 </p>
 571
 572 </div>
 573
 574 <!-- _______________________________________________________________________ -->
 575 <h4><a name="BLOCKINFO">#0 - BLOCKINFO Block</a></h4>
 576
 577 <div class="doc_text">
 578
 579 <p>
 580 The <tt>BLOCKINFO</tt> block allows the description of metadata for other
 581 blocks.  The currently specified records are:
 582 </p>
 583
 584 <div class="doc_code">
 585 <pre>
 586 [SETBID (#1), blockid]
 587 [DEFINE_ABBREV, ...]
 588 [BLOCKNAME, ...name...]
 589 [SETRECORDNAME, RecordID, ...name...]
 590 </pre>
 591 </div>
 592
 593 <p>
 594 The <tt>SETBID</tt> record (code 1) indicates which block ID is being
 595 described.  <tt>SETBID</tt> records can occur multiple times throughout the
 596 block to change which block ID is being described.  There must be
 597 a <tt>SETBID</tt> record prior to any other records.
 598 </p>
 599
 600 <p>
 601 Standard <tt>DEFINE_ABBREV</tt> records can occur inside <tt>BLOCKINFO</tt>
 602 blocks, but unlike their occurrence in normal blocks, the abbreviation is
 603 defined for blocks matching the block ID we are describing, <i>not</i> the
 604 <tt>BLOCKINFO</tt> block itself.  The abbreviations defined
 605 in <tt>BLOCKINFO</tt> blocks receive abbreviation IDs as described
 606 in <tt><a href="#DEFINE_ABBREV">DEFINE_ABBREV</a></tt>.
 607 </p>
 608
 609 <p>The <tt>BLOCKNAME</tt> record (code 2) can optionally occur in this block.  The elements of
 610 the record are the bytes of the string name of the block.  llvm-bcanalyzer can use
 611 this to dump out bitcode files symbolically.</p>
 612
 613 <p>The <tt>SETRECORDNAME</tt> record (code 3) can also optionally occur in this block.  The
 614 first operand value is a record ID number, and the rest of the elements of the record are
 615 the bytes for the string name of the record.  llvm-bcanalyzer can use
 616 this to dump out bitcode files symbolically.</p>
 617
 618 <p>
 619 Note that although the data in <tt>BLOCKINFO</tt> blocks is described as
 620 "metadata," the abbreviations they contain are essential for parsing records
 621 from the corresponding blocks.  It is not safe to skip them.
 622 </p>
 623
 624 </div>
 625
 626 <!-- *********************************************************************** -->
 627 <h2><a name="wrapper">Bitcode Wrapper Format</a></h2>
 628 <!-- *********************************************************************** -->
 629
 630 <div class="doc_text">
 631
 632 <p>
 633 Bitcode files for LLVM IR may optionally be wrapped in a simple wrapper
 634 structure.  This structure contains a simple header that indicates the offset
 635 and size of the embedded BC file.  This allows additional information to be
 636 stored alongside the BC file.  The structure of this file header is:
 637 </p>
 638
 639 <div class="doc_code">
 640 <p>
 641 <tt>[Magic<sub>32</sub>, Version<sub>32</sub>, Offset<sub>32</sub>,
 642 Size<sub>32</sub>, CPUType<sub>32</sub>]</tt>
 643 </p>
 644 </div>
 645
 646 <p>
 647 Each of the fields are 32-bit fields stored in little endian form (as with
 648 the rest of the bitcode file fields).  The Magic number is always
 649 <tt>0x0B17C0DE</tt> and the version is currently always <tt>0</tt>.  The Offset
 650 field is the offset in bytes to the start of the bitcode stream in the file, and
 651 the Size field is the size in bytes of the stream. CPUType is a target-specific
 652 value that can be used to encode the CPU of the target.
 653 </p>
 654
 655 </div>
 656
 657 <!-- *********************************************************************** -->
 658 <h2><a name="llvmir">LLVM IR Encoding</a></h2>
 659 <!-- *********************************************************************** -->
 660
 661 <div class="doc_text">
 662
 663 <p>
 664 LLVM IR is encoded into a bitstream by defining blocks and records.  It uses
 665 blocks for things like constant pools, functions, symbol tables, etc.  It uses
 666 records for things like instructions, global variable descriptors, type
 667 descriptions, etc.  This document does not describe the set of abbreviations
 668 that the writer uses, as these are fully self-described in the file, and the
 669 reader is not allowed to build in any knowledge of this.
 670 </p>
 671
 672 </div>
 673
 674 <!-- ======================================================================= -->
 675 <h3>
 676   <a name="basics">Basics</a>
 677 </h3>
 678
 679 <!-- _______________________________________________________________________ -->
 680 <h4><a name="ir_magic">LLVM IR Magic Number</a></h4>
 681
 682 <div class="doc_text">
 683
 684 <p>
 685 The magic number for LLVM IR files is:
 686 </p>
 687
 688 <div class="doc_code">
 689 <p>
 690 <tt>[0x0<sub>4</sub>, 0xC<sub>4</sub>, 0xE<sub>4</sub>, 0xD<sub>4</sub>]</tt>
 691 </p>
 692 </div>
 693
 694 <p>
 695 When combined with the bitcode magic number and viewed as bytes, this is
 696 <tt>"BC&nbsp;0xC0DE"</tt>.
 697 </p>
 698
 699 </div>
 700
 701 <!-- _______________________________________________________________________ -->
 702 <h4><a name="ir_signed_vbr">Signed VBRs</a></h4>
 703
 704 <div class="doc_text">
 705
 706 <p>
 707 <a href="#variablewidth">Variable Width Integer</a> encoding is an efficient way to
 708 encode arbitrary sized unsigned values, but is an extremely inefficient for
 709 encoding signed values, as signed values are otherwise treated as maximally large
 710 unsigned values.
 711 </p>
 712
 713 <p>
 714 As such, signed VBR values of a specific width are emitted as follows:
 715 </p>
 716
 717 <ul>
 718 <li>Positive values are emitted as VBRs of the specified width, but with their
 719     value shifted left by one.</li>
 720 <li>Negative values are emitted as VBRs of the specified width, but the negated
 721     value is shifted left by one, and the low bit is set.</li>
 722 </ul>
 723
 724 <p>
 725 With this encoding, small positive and small negative values can both
 726 be emitted efficiently. Signed VBR encoding is used in
 727 <tt>CST_CODE_INTEGER</tt> and <tt>CST_CODE_WIDE_INTEGER</tt> records
 728 within <tt>CONSTANTS_BLOCK</tt> blocks.
 729 </p>
 730
 731 </div>
 732
 733
 734 <!-- _______________________________________________________________________ -->
 735 <h4><a name="ir_blocks">LLVM IR Blocks</a></h4>
 736
 737 <div class="doc_text">
 738
 739 <p>
 740 LLVM IR is defined with the following blocks:
 741 </p>
 742
 743 <ul>
 744 <li>8  &mdash; <a href="#MODULE_BLOCK"><tt>MODULE_BLOCK</tt></a> &mdash; This is the top-level block that
 745     contains the entire module, and describes a variety of per-module
 746     information.</li>
 747 <li>9  &mdash; <a href="#PARAMATTR_BLOCK"><tt>PARAMATTR_BLOCK</tt></a> &mdash; This enumerates the parameter
 748     attributes.</li>
 749 <li>10 &mdash; <a href="#TYPE_BLOCK"><tt>TYPE_BLOCK</tt></a> &mdash; This describes all of the types in
 750     the module.</li>
 751 <li>11 &mdash; <a href="#CONSTANTS_BLOCK"><tt>CONSTANTS_BLOCK</tt></a> &mdash; This describes constants for a
 752     module or function.</li>
 753 <li>12 &mdash; <a href="#FUNCTION_BLOCK"><tt>FUNCTION_BLOCK</tt></a> &mdash; This describes a function
 754     body.</li>
 755 <li>13 &mdash; <a href="#TYPE_SYMTAB_BLOCK"><tt>TYPE_SYMTAB_BLOCK</tt></a> &mdash; This describes the type symbol
 756     table.</li>
 757 <li>14 &mdash; <a href="#VALUE_SYMTAB_BLOCK"><tt>VALUE_SYMTAB_BLOCK</tt></a> &mdash; This describes a value symbol
 758     table.</li>
 759 <li>15 &mdash; <a href="#METADATA_BLOCK"><tt>METADATA_BLOCK</tt></a> &mdash; This describes metadata items.</li>
 760 <li>16 &mdash; <a href="#METADATA_ATTACHMENT"><tt>METADATA_ATTACHMENT</tt></a> &mdash; This contains records associating metadata with function instruction values.</li>
 761 </ul>
 762
 763 </div>
 764
 765 <!-- ======================================================================= -->
 766 <h3>
 767   <a name="MODULE_BLOCK">MODULE_BLOCK Contents</a>
 768 </h3>
 769
 770 <div class="doc_text">
 771
 772 <p>The <tt>MODULE_BLOCK</tt> block (id 8) is the top-level block for LLVM
 773 bitcode files, and each bitcode file must contain exactly one. In
 774 addition to records (described below) containing information
 775 about the module, a <tt>MODULE_BLOCK</tt> block may contain the
 776 following sub-blocks:
 777 </p>
 778
 779 <ul>
 780 <li><a href="#BLOCKINFO"><tt>BLOCKINFO</tt></a></li>
 781 <li><a href="#PARAMATTR_BLOCK"><tt>PARAMATTR_BLOCK</tt></a></li>
 782 <li><a href="#TYPE_BLOCK"><tt>TYPE_BLOCK</tt></a></li>
 783 <li><a href="#TYPE_SYMTAB_BLOCK"><tt>TYPE_SYMTAB_BLOCK</tt></a></li>
 784 <li><a href="#VALUE_SYMTAB_BLOCK"><tt>VALUE_SYMTAB_BLOCK</tt></a></li>
 785 <li><a href="#CONSTANTS_BLOCK"><tt>CONSTANTS_BLOCK</tt></a></li>
 786 <li><a href="#FUNCTION_BLOCK"><tt>FUNCTION_BLOCK</tt></a></li>
 787 <li><a href="#METADATA_BLOCK"><tt>METADATA_BLOCK</tt></a></li>
 788 </ul>
 789
 790 </div>
 791
 792 <!-- _______________________________________________________________________ -->
 793 <h4><a name="MODULE_CODE_VERSION">MODULE_CODE_VERSION Record</a></h4>
 794
 795 <div class="doc_text">
 796
 797 <p><tt>[VERSION, version#]</tt></p>
 798
 799 <p>The <tt>VERSION</tt> record (code 1) contains a single value
 800 indicating the format version. Only version 0 is supported at this
 801 time.</p>
 802 </div>
 803
 804 <!-- _______________________________________________________________________ -->
 805 <h4><a name="MODULE_CODE_TRIPLE">MODULE_CODE_TRIPLE Record</a></h4>
 806
 807 <div class="doc_text">
 808 <p><tt>[TRIPLE, ...string...]</tt></p>
 809
 810 <p>The <tt>TRIPLE</tt> record (code 2) contains a variable number of
 811 values representing the bytes of the <tt>target triple</tt>
 812 specification string.</p>
 813 </div>
 814
 815 <!-- _______________________________________________________________________ -->
 816 <h4><a name="MODULE_CODE_DATALAYOUT">MODULE_CODE_DATALAYOUT Record</a></h4>
 817
 818 <div class="doc_text">
 819 <p><tt>[DATALAYOUT, ...string...]</tt></p>
 820
 821 <p>The <tt>DATALAYOUT</tt> record (code 3) contains a variable number of
 822 values representing the bytes of the <tt>target datalayout</tt>
 823 specification string.</p>
 824 </div>
 825
 826 <!-- _______________________________________________________________________ -->
 827 <h4><a name="MODULE_CODE_ASM">MODULE_CODE_ASM Record</a></h4>
 828
 829 <div class="doc_text">
 830 <p><tt>[ASM, ...string...]</tt></p>
 831
 832 <p>The <tt>ASM</tt> record (code 4) contains a variable number of
 833 values representing the bytes of <tt>module asm</tt> strings, with
 834 individual assembly blocks separated by newline (ASCII 10) characters.</p>
 835 </div>
 836
 837 <!-- _______________________________________________________________________ -->
 838 <h4><a name="MODULE_CODE_SECTIONNAME">MODULE_CODE_SECTIONNAME Record</a></h4>
 839
 840 <div class="doc_text">
 841 <p><tt>[SECTIONNAME, ...string...]</tt></p>
 842
 843 <p>The <tt>SECTIONNAME</tt> record (code 5) contains a variable number
 844 of values representing the bytes of a single section name
 845 string. There should be one <tt>SECTIONNAME</tt> record for each
 846 section name referenced (e.g., in global variable or function
 847 <tt>section</tt> attributes) within the module. These records can be
 848 referenced by the 1-based index in the <i>section</i> fields of
 849 <tt>GLOBALVAR</tt> or <tt>FUNCTION</tt> records.</p>
 850 </div>
 851
 852 <!-- _______________________________________________________________________ -->
 853 <h4><a name="MODULE_CODE_DEPLIB">MODULE_CODE_DEPLIB Record</a></h4>
 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
 859 values representing the bytes of a single dependent library name
 860 string, one of the libraries mentioned in a <tt>deplibs</tt>
 861 declaration.  There should be one <tt>DEPLIB</tt> record for each
 862 library name referenced.</p>
 863 </div>
 864
 865 <!-- _______________________________________________________________________ -->
 866 <h4><a name="MODULE_CODE_GLOBALVAR">MODULE_CODE_GLOBALVAR Record</a></h4>
 867
 868 <div class="doc_text">
 869 <p><tt>[GLOBALVAR, pointer type, isconst, initid, linkage, alignment, section, visibility, threadlocal]</tt></p>
 870
 871 <p>The <tt>GLOBALVAR</tt> record (code 7) marks the declaration or
 872 definition of a global variable. The operand fields are:</p>
 873
 874 <ul>
 875 <li><i>pointer type</i>: The type index of the pointer type used to point to
 876 this global variable</li>
 877
 878 <li><i>isconst</i>: Non-zero if the variable is treated as constant within
 879 the module, or zero if it is not</li>
 880
 881 <li><i>initid</i>: If non-zero, the value index of the initializer for this
 882 variable, plus 1.</li>
 883
 884 <li><a name="linkage"><i>linkage</i></a>: An encoding of the linkage
 885 type for this variable:
 886   <ul>
 887     <li><tt>external</tt>: code 0</li>
 888     <li><tt>weak</tt>: code 1</li>
 889     <li><tt>appending</tt>: code 2</li>
 890     <li><tt>internal</tt>: code 3</li>
 891     <li><tt>linkonce</tt>: code 4</li>
 892     <li><tt>dllimport</tt>: code 5</li>
 893     <li><tt>dllexport</tt>: code 6</li>
 894     <li><tt>extern_weak</tt>: code 7</li>
 895     <li><tt>common</tt>: code 8</li>
 896     <li><tt>private</tt>: code 9</li>
 897     <li><tt>weak_odr</tt>: code 10</li>
 898     <li><tt>linkonce_odr</tt>: code 11</li>
 899     <li><tt>available_externally</tt>: code 12</li>
 900     <li><tt>linker_private</tt>: code 13</li>
 901   </ul>
 902 </li>
 903
 904 <li><i>alignment</i>: The logarithm base 2 of the variable's requested
 905 alignment, plus 1</li>
 906
 907 <li><i>section</i>: If non-zero, the 1-based section index in the
 908 table of <a href="#MODULE_CODE_SECTIONNAME">MODULE_CODE_SECTIONNAME</a>
 909 entries.</li>
 910
 911 <li><a name="visibility"><i>visibility</i></a>: If present, an
 912 encoding of the visibility of this variable:
 913   <ul>
 914     <li><tt>default</tt>: code 0</li>
 915     <li><tt>hidden</tt>: code 1</li>
 916     <li><tt>protected</tt>: code 2</li>
 917   </ul>
 918 </li>
 919
 920 <li><i>threadlocal</i>: If present and non-zero, indicates that the variable
 921 is <tt>thread_local</tt></li>
 922
 923 <li><i>unnamed_addr</i>: If present and non-zero, indicates that the variable
 924 has <tt>unnamed_addr</tt></li>
 925
 926 </ul>
 927 </div>
 928
 929 <!-- _______________________________________________________________________ -->
 930 <h4><a name="MODULE_CODE_FUNCTION">MODULE_CODE_FUNCTION Record</a></h4>
 931
 932 <div class="doc_text">
 933
 934 <p><tt>[FUNCTION, type, callingconv, isproto, linkage, paramattr, alignment, section, visibility, gc]</tt></p>
 935
 936 <p>The <tt>FUNCTION</tt> record (code 8) marks the declaration or
 937 definition of a function. The operand fields are:</p>
 938
 939 <ul>
 940 <li><i>type</i>: The type index of the function type describing this function</li>
 941
 942 <li><i>callingconv</i>: The calling convention number:
 943   <ul>
 944     <li><tt>ccc</tt>: code 0</li>
 945     <li><tt>fastcc</tt>: code 8</li>
 946     <li><tt>coldcc</tt>: code 9</li>
 947     <li><tt>x86_stdcallcc</tt>: code 64</li>
 948     <li><tt>x86_fastcallcc</tt>: code 65</li>
 949     <li><tt>arm_apcscc</tt>: code 66</li>
 950     <li><tt>arm_aapcscc</tt>: code 67</li>
 951     <li><tt>arm_aapcs_vfpcc</tt>: code 68</li>
 952   </ul>
 953 </li>
 954
 955 <li><i>isproto</i>: Non-zero if this entry represents a declaration
 956 rather than a definition</li>
 957
 958 <li><i>linkage</i>: An encoding of the <a href="#linkage">linkage type</a>
 959 for this function</li>
 960
 961 <li><i>paramattr</i>: If nonzero, the 1-based parameter attribute index
 962 into the table of <a href="#PARAMATTR_CODE_ENTRY">PARAMATTR_CODE_ENTRY</a>
 963 entries.</li>
 964
 965 <li><i>alignment</i>: The logarithm base 2 of the function's requested
 966 alignment, plus 1</li>
 967
 968 <li><i>section</i>: If non-zero, the 1-based section index in the
 969 table of <a href="#MODULE_CODE_SECTIONNAME">MODULE_CODE_SECTIONNAME</a>
 970 entries.</li>
 971
 972 <li><i>visibility</i>: An encoding of the <a href="#visibility">visibility</a>
 973     of this function</li>
 974
 975 <li><i>gc</i>: If present and nonzero, the 1-based garbage collector
 976 index in the table of
 977 <a href="#MODULE_CODE_GCNAME">MODULE_CODE_GCNAME</a> entries.</li>
 978
 979 <li><i>unnamed_addr</i>: If present and non-zero, indicates that the function
 980 has <tt>unnamed_addr</tt></li>
 981
 982 </ul>
 983 </div>
 984
 985 <!-- _______________________________________________________________________ -->
 986 <h4><a name="MODULE_CODE_ALIAS">MODULE_CODE_ALIAS Record</a></h4>
 987
 988 <div class="doc_text">
 989
 990 <p><tt>[ALIAS, alias type, aliasee val#, linkage, visibility]</tt></p>
 991
 992 <p>The <tt>ALIAS</tt> record (code 9) marks the definition of an
 993 alias. The operand fields are</p>
 994
 995 <ul>
 996 <li><i>alias type</i>: The type index of the alias</li>
 997
 998 <li><i>aliasee val#</i>: The value index of the aliased value</li>
 999
1000 <li><i>linkage</i>: An encoding of the <a href="#linkage">linkage type</a>
1001 for this alias</li>
1002
1003 <li><i>visibility</i>: If present, an encoding of the
1004 <a href="#visibility">visibility</a> of the alias</li>
1005
1006 </ul>
1007 </div>
1008
1009 <!-- _______________________________________________________________________ -->
1010 <h4><a name="MODULE_CODE_PURGEVALS">MODULE_CODE_PURGEVALS Record</a></h4>
1011
1012 <div class="doc_text">
1013 <p><tt>[PURGEVALS, numvals]</tt></p>
1014
1015 <p>The <tt>PURGEVALS</tt> record (code 10) resets the module-level
1016 value list to the size given by the single operand value. Module-level
1017 value list items are added by <tt>GLOBALVAR</tt>, <tt>FUNCTION</tt>,
1018 and <tt>ALIAS</tt> records.  After a <tt>PURGEVALS</tt> record is seen,
1019 new value indices will start from the given <i>numvals</i> value.</p>
1020 </div>
1021
1022 <!-- _______________________________________________________________________ -->
1023 <h4><a name="MODULE_CODE_GCNAME">MODULE_CODE_GCNAME Record</a></h4>
1024
1025 <div class="doc_text">
1026 <p><tt>[GCNAME, ...string...]</tt></p>
1027
1028 <p>The <tt>GCNAME</tt> record (code 11) contains a variable number of
1029 values representing the bytes of a single garbage collector name
1030 string. There should be one <tt>GCNAME</tt> record for each garbage
1031 collector name referenced in function <tt>gc</tt> attributes within
1032 the module. These records can be referenced by 1-based index in the <i>gc</i>
1033 fields of <tt>FUNCTION</tt> records.</p>
1034 </div>
1035
1036 <!-- ======================================================================= -->
1037 <h3>
1038   <a name="PARAMATTR_BLOCK">PARAMATTR_BLOCK Contents</a>
1039 </h3>
1040
1041 <div class="doc_text">
1042
1043 <p>The <tt>PARAMATTR_BLOCK</tt> block (id 9) contains a table of
1044 entries describing the attributes of function parameters. These
1045 entries are referenced by 1-based index in the <i>paramattr</i> field
1046 of module block <a name="MODULE_CODE_FUNCTION"><tt>FUNCTION</tt></a>
1047 records, or within the <i>attr</i> field of function block <a
1048 href="#FUNC_CODE_INST_INVOKE"><tt>INST_INVOKE</tt></a> and <a
1049 href="#FUNC_CODE_INST_CALL"><tt>INST_CALL</tt></a> records.</p>
1050
1051 <p>Entries within <tt>PARAMATTR_BLOCK</tt> are constructed to ensure
1052 that each is unique (i.e., no two indicies represent equivalent
1053 attribute lists). </p>
1054
1055 </div>
1056
1057
1058 <!-- _______________________________________________________________________ -->
1059 <h4><a name="PARAMATTR_CODE_ENTRY">PARAMATTR_CODE_ENTRY Record</a></h4>
1060
1061 <div class="doc_text">
1062
1063 <p><tt>[ENTRY, paramidx0, attr0, paramidx1, attr1...]</tt></p>
1064
1065 <p>The <tt>ENTRY</tt> record (code 1) contains an even number of
1066 values describing a unique set of function parameter attributes. Each
1067 <i>paramidx</i> value indicates which set of attributes is
1068 represented, with 0 representing the return value attributes,
1069 0xFFFFFFFF representing function attributes, and other values
1070 representing 1-based function parameters. Each <i>attr</i> value is a
1071 bitmap with the following interpretation:
1072 </p>
1073
1074 <ul>
1075 <li>bit 0: <tt>zeroext</tt></li>
1076 <li>bit 1: <tt>signext</tt></li>
1077 <li>bit 2: <tt>noreturn</tt></li>
1078 <li>bit 3: <tt>inreg</tt></li>
1079 <li>bit 4: <tt>sret</tt></li>
1080 <li>bit 5: <tt>nounwind</tt></li>
1081 <li>bit 6: <tt>noalias</tt></li>
1082 <li>bit 7: <tt>byval</tt></li>
1083 <li>bit 8: <tt>nest</tt></li>
1084 <li>bit 9: <tt>readnone</tt></li>
1085 <li>bit 10: <tt>readonly</tt></li>
1086 <li>bit 11: <tt>noinline</tt></li>
1087 <li>bit 12: <tt>alwaysinline</tt></li>
1088 <li>bit 13: <tt>optsize</tt></li>
1089 <li>bit 14: <tt>ssp</tt></li>
1090 <li>bit 15: <tt>sspreq</tt></li>
1091 <li>bits 16&ndash;31: <tt>align <var>n</var></tt></li>
1092 <li>bit 32: <tt>nocapture</tt></li>
1093 <li>bit 33: <tt>noredzone</tt></li>
1094 <li>bit 34: <tt>noimplicitfloat</tt></li>
1095 <li>bit 35: <tt>naked</tt></li>
1096 <li>bit 36: <tt>inlinehint</tt></li>
1097 <li>bits 37&ndash;39: <tt>alignstack <var>n</var></tt>, represented as
1098 the logarithm base 2 of the requested alignment, plus 1</li>
1099 </ul>
1100 </div>
1101
1102 <!-- ======================================================================= -->
1103 <h3>
1104   <a name="TYPE_BLOCK">TYPE_BLOCK Contents</a>
1105 </h3>
1106
1107 <div class="doc_text">
1108
1109 <p>The <tt>TYPE_BLOCK</tt> block (id 10) contains records which
1110 constitute a table of type operator entries used to represent types
1111 referenced within an LLVM module. Each record (with the exception of
1112 <a href="#TYPE_CODE_NUMENTRY"><tt>NUMENTRY</tt></a>) generates a
1113 single type table entry, which may be referenced by 0-based index from
1114 instructions, constants, metadata, type symbol table entries, or other
1115 type operator records.
1116 </p>
1117
1118 <p>Entries within <tt>TYPE_BLOCK</tt> are constructed to ensure that
1119 each entry is unique (i.e., no two indicies represent structurally
1120 equivalent types). </p>
1121
1122 </div>
1123
1124 <!-- _______________________________________________________________________ -->
1125 <h4><a name="TYPE_CODE_NUMENTRY">TYPE_CODE_NUMENTRY Record</a></h4>
1126
1127 <div class="doc_text">
1128
1129 <p><tt>[NUMENTRY, numentries]</tt></p>
1130
1131 <p>The <tt>NUMENTRY</tt> record (code 1) contains a single value which
1132 indicates the total number of type code entries in the type table of
1133 the module. If present, <tt>NUMENTRY</tt> should be the first record
1134 in the block.
1135 </p>
1136 </div>
1137
1138 <!-- _______________________________________________________________________ -->
1139 <h4><a name="TYPE_CODE_VOID">TYPE_CODE_VOID Record</a></h4>
1140
1141 <div class="doc_text">
1142
1143 <p><tt>[VOID]</tt></p>
1144
1145 <p>The <tt>VOID</tt> record (code 2) adds a <tt>void</tt> type to the
1146 type table.
1147 </p>
1148 </div>
1149
1150 <!-- _______________________________________________________________________ -->
1151 <h4><a name="TYPE_CODE_FLOAT">TYPE_CODE_FLOAT Record</a></h4>
1152
1153 <div class="doc_text">
1154
1155 <p><tt>[FLOAT]</tt></p>
1156
1157 <p>The <tt>FLOAT</tt> record (code 3) adds a <tt>float</tt> (32-bit
1158 floating point) type to the type table.
1159 </p>
1160 </div>
1161
1162 <!-- _______________________________________________________________________ -->
1163 <h4><a name="TYPE_CODE_DOUBLE">TYPE_CODE_DOUBLE Record</a></h4>
1164
1165 <div class="doc_text">
1166
1167 <p><tt>[DOUBLE]</tt></p>
1168
1169 <p>The <tt>DOUBLE</tt> record (code 4) adds a <tt>double</tt> (64-bit
1170 floating point) type to the type table.
1171 </p>
1172 </div>
1173
1174 <!-- _______________________________________________________________________ -->
1175 <h4><a name="TYPE_CODE_LABEL">TYPE_CODE_LABEL Record</a></h4>
1176
1177 <div class="doc_text">
1178
1179 <p><tt>[LABEL]</tt></p>
1180
1181 <p>The <tt>LABEL</tt> record (code 5) adds a <tt>label</tt> type to
1182 the type table.
1183 </p>
1184 </div>
1185
1186 <!-- _______________________________________________________________________ -->
1187 <h4><a name="TYPE_CODE_OPAQUE">TYPE_CODE_OPAQUE Record</a></h4>
1188
1189 <div class="doc_text">
1190
1191 <p><tt>[OPAQUE]</tt></p>
1192
1193 <p>The <tt>OPAQUE</tt> record (code 6) adds an <tt>opaque</tt> type to
1194 the type table. Note that distinct <tt>opaque</tt> types are not
1195 unified.
1196 </p>
1197 </div>
1198
1199 <!-- _______________________________________________________________________ -->
1200 <h4><a name="TYPE_CODE_INTEGER">TYPE_CODE_INTEGER  Record</a></h4>
1201
1202 <div class="doc_text">
1203
1204 <p><tt>[INTEGER, width]</tt></p>
1205
1206 <p>The <tt>INTEGER</tt> record (code 7) adds an integer type to the
1207 type table. The single <i>width</i> field indicates the width of the
1208 integer type.
1209 </p>
1210 </div>
1211
1212 <!-- _______________________________________________________________________ -->
1213 <h4><a name="TYPE_CODE_POINTER">TYPE_CODE_POINTER Record</a></h4>
1214
1215 <div class="doc_text">
1216
1217 <p><tt>[POINTER, pointee type, address space]</tt></p>
1218
1219 <p>The <tt>POINTER</tt> record (code 8) adds a pointer type to the
1220 type table. The operand fields are</p>
1221
1222 <ul>
1223 <li><i>pointee type</i>: The type index of the pointed-to type</li>
1224
1225 <li><i>address space</i>: If supplied, the target-specific numbered
1226 address space where the pointed-to object resides. Otherwise, the
1227 default address space is zero.
1228 </li>
1229 </ul>
1230 </div>
1231
1232 <!-- _______________________________________________________________________ -->
1233 <h4><a name="TYPE_CODE_FUNCTION">TYPE_CODE_FUNCTION Record</a></h4>
1234
1235 <div class="doc_text">
1236
1237 <p><tt>[FUNCTION, vararg, ignored, retty, ...paramty... ]</tt></p>
1238
1239 <p>The <tt>FUNCTION</tt> record (code 9) adds a function type to the
1240 type table. The operand fields are</p>
1241
1242 <ul>
1243 <li><i>vararg</i>: Non-zero if the type represents a varargs function</li>
1244
1245 <li><i>ignored</i>: This value field is present for backward
1246 compatibility only, and is ignored</li>
1247
1248 <li><i>retty</i>: The type index of the function's return type</li>
1249
1250 <li><i>paramty</i>: Zero or more type indices representing the
1251 parameter types of the function</li>
1252 </ul>
1253
1254 </div>
1255
1256 <!-- _______________________________________________________________________ -->
1257 <h4><a name="TYPE_CODE_STRUCT">TYPE_CODE_STRUCT Record</a></h4>
1258
1259 <div class="doc_text">
1260
1261 <p><tt>[STRUCT, ispacked, ...eltty...]</tt></p>
1262
1263 <p>The <tt>STRUCT </tt> record (code 10) adds a struct type to the
1264 type table. The operand fields are</p>
1265
1266 <ul>
1267 <li><i>ispacked</i>: Non-zero if the type represents a packed structure</li>
1268
1269 <li><i>eltty</i>: Zero or more type indices representing the element
1270 types of the structure</li>
1271 </ul>
1272 </div>
1273
1274 <!-- _______________________________________________________________________ -->
1275 <h4><a name="TYPE_CODE_ARRAY">TYPE_CODE_ARRAY Record</a></h4>
1276
1277 <div class="doc_text">
1278
1279 <p><tt>[ARRAY, numelts, eltty]</tt></p>
1280
1281 <p>The <tt>ARRAY</tt> record (code 11) adds an array type to the type
1282 table.  The operand fields are</p>
1283
1284 <ul>
1285 <li><i>numelts</i>: The number of elements in arrays of this type</li>
1286
1287 <li><i>eltty</i>: The type index of the array element type</li>
1288 </ul>
1289 </div>
1290
1291 <!-- _______________________________________________________________________ -->
1292 <h4><a name="TYPE_CODE_VECTOR">TYPE_CODE_VECTOR Record</a></h4>
1293
1294 <div class="doc_text">
1295
1296 <p><tt>[VECTOR, numelts, eltty]</tt></p>
1297
1298 <p>The <tt>VECTOR</tt> record (code 12) adds a vector type to the type
1299 table.  The operand fields are</p>
1300
1301 <ul>
1302 <li><i>numelts</i>: The number of elements in vectors of this type</li>
1303
1304 <li><i>eltty</i>: The type index of the vector element type</li>
1305 </ul>
1306 </div>
1307
1308 <!-- _______________________________________________________________________ -->
1309 <h4><a name="TYPE_CODE_X86_FP80">TYPE_CODE_X86_FP80 Record</a></h4>
1310
1311 <div class="doc_text">
1312
1313 <p><tt>[X86_FP80]</tt></p>
1314
1315 <p>The <tt>X86_FP80</tt> record (code 13) adds an <tt>x86_fp80</tt> (80-bit
1316 floating point) type to the type table.
1317 </p>
1318 </div>
1319
1320 <!-- _______________________________________________________________________ -->
1321 <h4><a name="TYPE_CODE_FP128">TYPE_CODE_FP128 Record</a></h4>
1322
1323 <div class="doc_text">
1324
1325 <p><tt>[FP128]</tt></p>
1326
1327 <p>The <tt>FP128</tt> record (code 14) adds an <tt>fp128</tt> (128-bit
1328 floating point) type to the type table.
1329 </p>
1330 </div>
1331
1332 <!-- _______________________________________________________________________ -->
1333 <h4><a name="TYPE_CODE_PPC_FP128">TYPE_CODE_PPC_FP128 Record</a></h4>
1334
1335 <div class="doc_text">
1336
1337 <p><tt>[PPC_FP128]</tt></p>
1338
1339 <p>The <tt>PPC_FP128</tt> record (code 15) adds a <tt>ppc_fp128</tt>
1340 (128-bit floating point) type to the type table.
1341 </p>
1342 </div>
1343
1344 <!-- _______________________________________________________________________ -->
1345 <h4><a name="TYPE_CODE_METADATA">TYPE_CODE_METADATA Record</a></h4>
1346
1347 <div class="doc_text">
1348
1349 <p><tt>[METADATA]</tt></p>
1350
1351 <p>The <tt>METADATA</tt> record (code 16) adds a <tt>metadata</tt>
1352 type to the type table.
1353 </p>
1354 </div>
1355
1356 <!-- ======================================================================= -->
1357 <h3>
1358   <a name="CONSTANTS_BLOCK">CONSTANTS_BLOCK Contents</a>
1359 </h3>
1360
1361 <div class="doc_text">
1362
1363 <p>The <tt>CONSTANTS_BLOCK</tt> block (id 11) ...
1364 </p>
1365
1366 </div>
1367
1368
1369 <!-- ======================================================================= -->
1370 <h3>
1371   <a name="FUNCTION_BLOCK">FUNCTION_BLOCK Contents</a>
1372 </h3>
1373
1374 <div class="doc_text">
1375
1376 <p>The <tt>FUNCTION_BLOCK</tt> block (id 12) ...
1377 </p>
1378
1379 <p>In addition to the record types described below, a
1380 <tt>FUNCTION_BLOCK</tt> block may contain the following sub-blocks:
1381 </p>
1382
1383 <ul>
1384 <li><a href="#CONSTANTS_BLOCK"><tt>CONSTANTS_BLOCK</tt></a></li>
1385 <li><a href="#VALUE_SYMTAB_BLOCK"><tt>VALUE_SYMTAB_BLOCK</tt></a></li>
1386 <li><a href="#METADATA_ATTACHMENT"><tt>METADATA_ATTACHMENT</tt></a></li>
1387 </ul>
1388
1389 </div>
1390
1391
1392 <!-- ======================================================================= -->
1393 <h3>
1394   <a name="TYPE_SYMTAB_BLOCK">TYPE_SYMTAB_BLOCK Contents</a>
1395 </h3>
1396
1397 <div class="doc_text">
1398
1399 <p>The <tt>TYPE_SYMTAB_BLOCK</tt> block (id 13) contains entries which
1400 map between module-level named types and their corresponding type
1401 indices.
1402 </p>
1403
1404 </div>
1405
1406 <!-- _______________________________________________________________________ -->
1407 <h4><a name="TST_CODE_ENTRY">TST_CODE_ENTRY Record</a></h4>
1408
1409 <div class="doc_text">
1410
1411 <p><tt>[ENTRY, typeid, ...string...]</tt></p>
1412
1413 <p>The <tt>ENTRY</tt> record (code 1) contains a variable number of
1414 values, with the first giving the type index of the designated type,
1415 and the remaining values giving the character codes of the type
1416 name. Each entry corresponds to a single named type.
1417 </p>
1418 </div>
1419
1420
1421 <!-- ======================================================================= -->
1422 <h3>
1423   <a name="VALUE_SYMTAB_BLOCK">VALUE_SYMTAB_BLOCK Contents</a>
1424 </h3>
1425
1426 <div class="doc_text">
1427
1428 <p>The <tt>VALUE_SYMTAB_BLOCK</tt> block (id 14) ...
1429 </p>
1430
1431 </div>
1432
1433
1434 <!-- ======================================================================= -->
1435 <h3>
1436   <a name="METADATA_BLOCK">METADATA_BLOCK Contents</a>
1437 </h3>
1438
1439 <div class="doc_text">
1440
1441 <p>The <tt>METADATA_BLOCK</tt> block (id 15) ...
1442 </p>
1443
1444 </div>
1445
1446
1447 <!-- ======================================================================= -->
1448 <h3>
1449   <a name="METADATA_ATTACHMENT">METADATA_ATTACHMENT Contents</a>
1450 </h3>
1451
1452 <div class="doc_text">
1453
1454 <p>The <tt>METADATA_ATTACHMENT</tt> block (id 16) ...
1455 </p>
1456
1457 </div>
1458
1459
1460 <!-- *********************************************************************** -->
1461 <hr>
1462 <address> <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
1463  src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
1464 <a href="http://validator.w3.org/check/referer"><img
1465  src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
1466  <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
1467 <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
1468 Last modified: $Date$
1469 </address>
1470 </body>
1471 </html>