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