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