docs/SourceLevelDebugging.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>Source Level Debugging with LLVM</title>
   7   <link rel="stylesheet" href="llvm.css" type="text/css">
   8 </head>
   9 <body>
  10
  11 <div class="doc_title">Source Level Debugging with LLVM</div>
  12
  13 <table class="layout" style="width:100%">
  14   <tr class="layout">
  15     <td class="left">
  16 <ul>
  17   <li><a href="#introduction">Introduction</a>
  18   <ol>
  19     <li><a href="#phil">Philosophy behind LLVM debugging information</a></li>
  20     <li><a href="#consumers">Debug information consumers</a></li>
  21     <li><a href="#debugopt">Debugging optimized code</a></li>
  22   </ol></li>
  23   <li><a href="#format">Debugging information format</a>
  24   <ol>
  25     <li><a href="#debug_info_descriptors">Debug information descriptors</a>
  26     <ul>
  27       <li><a href="#format_compile_units">Compile unit descriptors</a></li>
  28       <li><a href="#format_global_variables">Global variable descriptors</a></li>
  29       <li><a href="#format_subprograms">Subprogram descriptors</a></li>
  30       <li><a href="#format_blocks">Block descriptors</a></li>
  31       <li><a href="#format_basic_type">Basic type descriptors</a></li>
  32       <li><a href="#format_derived_type">Derived type descriptors</a></li>
  33       <li><a href="#format_composite_type">Composite type descriptors</a></li>
  34       <li><a href="#format_subrange">Subrange descriptors</a></li>
  35       <li><a href="#format_enumeration">Enumerator descriptors</a></li>
  36       <li><a href="#format_variables">Local variables</a></li>
  37     </ul></li>
  38     <li><a href="#format_common_intrinsics">Debugger intrinsic functions</a>
  39       <ul>
  40       <li><a href="#format_common_declare">llvm.dbg.declare</a></li>
  41       <li><a href="#format_common_value">llvm.dbg.value</a></li>
  42     </ul></li>
  43   </ol></li>
  44   <li><a href="#format_common_lifetime">Object lifetimes and scoping</a></li>
  45   <li><a href="#ccxx_frontend">C/C++ front-end specific debug information</a>
  46   <ol>
  47     <li><a href="#ccxx_compile_units">C/C++ source file information</a></li>
  48     <li><a href="#ccxx_global_variable">C/C++ global variable information</a></li>
  49     <li><a href="#ccxx_subprogram">C/C++ function information</a></li>
  50     <li><a href="#ccxx_basic_types">C/C++ basic types</a></li>
  51     <li><a href="#ccxx_derived_types">C/C++ derived types</a></li>
  52     <li><a href="#ccxx_composite_types">C/C++ struct/union types</a></li>
  53     <li><a href="#ccxx_enumeration_types">C/C++ enumeration types</a></li>
  54   </ol></li>
  55 </ul>
  56 </td>
  57 <td class="right">
  58 <img src="img/venusflytrap.jpg" alt="A leafy and green bug eater" width="247"
  59 height="369">
  60 </td>
  61 </tr></table>
  62
  63 <div class="doc_author">
  64   <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>
  65             and <a href="mailto:jlaskey@mac.com">Jim Laskey</a></p>
  66 </div>
  67
  68
  69 <!-- *********************************************************************** -->
  70 <div class="doc_section"><a name="introduction">Introduction</a></div>
  71 <!-- *********************************************************************** -->
  72
  73 <div class="doc_text">
  74
  75 <p>This document is the central repository for all information pertaining to
  76    debug information in LLVM.  It describes the <a href="#format">actual format
  77    that the LLVM debug information</a> takes, which is useful for those
  78    interested in creating front-ends or dealing directly with the information.
  79    Further, this document provides specific examples of what debug information
  80    for C/C++.</p>
  81
  82 </div>
  83
  84 <!-- ======================================================================= -->
  85 <div class="doc_subsection">
  86   <a name="phil">Philosophy behind LLVM debugging information</a>
  87 </div>
  88
  89 <div class="doc_text">
  90
  91 <p>The idea of the LLVM debugging information is to capture how the important
  92    pieces of the source-language's Abstract Syntax Tree map onto LLVM code.
  93    Several design aspects have shaped the solution that appears here.  The
  94    important ones are:</p>
  95
  96 <ul>
  97   <li>Debugging information should have very little impact on the rest of the
  98       compiler.  No transformations, analyses, or code generators should need to
  99       be modified because of debugging information.</li>
 100
 101   <li>LLVM optimizations should interact in <a href="#debugopt">well-defined and
 102       easily described ways</a> with the debugging information.</li>
 103
 104   <li>Because LLVM is designed to support arbitrary programming languages,
 105       LLVM-to-LLVM tools should not need to know anything about the semantics of
 106       the source-level-language.</li>
 107
 108   <li>Source-level languages are often <b>widely</b> different from one another.
 109       LLVM should not put any restrictions of the flavor of the source-language,
 110       and the debugging information should work with any language.</li>
 111
 112   <li>With code generator support, it should be possible to use an LLVM compiler
 113       to compile a program to native machine code and standard debugging
 114       formats.  This allows compatibility with traditional machine-code level
 115       debuggers, like GDB or DBX.</li>
 116 </ul>
 117
 118 <p>The approach used by the LLVM implementation is to use a small set
 119    of <a href="#format_common_intrinsics">intrinsic functions</a> to define a
 120    mapping between LLVM program objects and the source-level objects.  The
 121    description of the source-level program is maintained in LLVM metadata
 122    in an <a href="#ccxx_frontend">implementation-defined format</a>
 123    (the C/C++ front-end currently uses working draft 7 of
 124    the <a href="http://www.eagercon.com/dwarf/dwarf3std.htm">DWARF 3
 125    standard</a>).</p>
 126
 127 <p>When a program is being debugged, a debugger interacts with the user and
 128    turns the stored debug information into source-language specific information.
 129    As such, a debugger must be aware of the source-language, and is thus tied to
 130    a specific language or family of languages.</p>
 131
 132 </div>
 133
 134 <!-- ======================================================================= -->
 135 <div class="doc_subsection">
 136   <a name="consumers">Debug information consumers</a>
 137 </div>
 138
 139 <div class="doc_text">
 140
 141 <p>The role of debug information is to provide meta information normally
 142    stripped away during the compilation process.  This meta information provides
 143    an LLVM user a relationship between generated code and the original program
 144    source code.</p>
 145
 146 <p>Currently, debug information is consumed by the DwarfWriter to produce dwarf
 147    information used by the gdb debugger.  Other targets could use the same
 148    information to produce stabs or other debug forms.</p>
 149
 150 <p>It would also be reasonable to use debug information to feed profiling tools
 151    for analysis of generated code, or, tools for reconstructing the original
 152    source from generated code.</p>
 153
 154 <p>TODO - expound a bit more.</p>
 155
 156 </div>
 157
 158 <!-- ======================================================================= -->
 159 <div class="doc_subsection">
 160   <a name="debugopt">Debugging optimized code</a>
 161 </div>
 162
 163 <div class="doc_text">
 164
 165 <p>An extremely high priority of LLVM debugging information is to make it
 166    interact well with optimizations and analysis.  In particular, the LLVM debug
 167    information provides the following guarantees:</p>
 168
 169 <ul>
 170   <li>LLVM debug information <b>always provides information to accurately read
 171       the source-level state of the program</b>, regardless of which LLVM
 172       optimizations have been run, and without any modification to the
 173       optimizations themselves.  However, some optimizations may impact the
 174       ability to modify the current state of the program with a debugger, such
 175       as setting program variables, or calling functions that have been
 176       deleted.</li>
 177
 178   <li>LLVM optimizations gracefully interact with debugging information.  If
 179       they are not aware of debug information, they are automatically disabled
 180       as necessary in the cases that would invalidate the debug info.  This
 181       retains the LLVM features, making it easy to write new
 182       transformations.</li>
 183
 184   <li>As desired, LLVM optimizations can be upgraded to be aware of the LLVM
 185       debugging information, allowing them to update the debugging information
 186       as they perform aggressive optimizations.  This means that, with effort,
 187       the LLVM optimizers could optimize debug code just as well as non-debug
 188       code.</li>
 189
 190   <li>LLVM debug information does not prevent many important optimizations from
 191       happening (for example inlining, basic block reordering/merging/cleanup,
 192       tail duplication, etc), further reducing the amount of the compiler that
 193       eventually is "aware" of debugging information.</li>
 194
 195   <li>LLVM debug information is automatically optimized along with the rest of
 196       the program, using existing facilities.  For example, duplicate
 197       information is automatically merged by the linker, and unused information
 198       is automatically removed.</li>
 199 </ul>
 200
 201 <p>Basically, the debug information allows you to compile a program with
 202    "<tt>-O0 -g</tt>" and get full debug information, allowing you to arbitrarily
 203    modify the program as it executes from a debugger.  Compiling a program with
 204    "<tt>-O3 -g</tt>" gives you full debug information that is always available
 205    and accurate for reading (e.g., you get accurate stack traces despite tail
 206    call elimination and inlining), but you might lose the ability to modify the
 207    program and call functions where were optimized out of the program, or
 208    inlined away completely.</p>
 209
 210 <p><a href="TestingGuide.html#quicktestsuite">LLVM test suite</a> provides a
 211    framework to test optimizer's handling of debugging information. It can be
 212    run like this:</p>
 213
 214 <div class="doc_code">
 215 <pre>
 216 % cd llvm/projects/test-suite/MultiSource/Benchmarks  # or some other level
 217 % make TEST=dbgopt
 218 </pre>
 219 </div>
 220
 221 <p>This will test impact of debugging information on optimization passes. If
 222    debugging information influences optimization passes then it will be reported
 223    as a failure. See <a href="TestingGuide.html">TestingGuide</a> for more
 224    information on LLVM test infrastructure and how to run various tests.</p>
 225
 226 </div>
 227
 228 <!-- *********************************************************************** -->
 229 <div class="doc_section">
 230   <a name="format">Debugging information format</a>
 231 </div>
 232 <!-- *********************************************************************** -->
 233
 234 <div class="doc_text">
 235
 236 <p>LLVM debugging information has been carefully designed to make it possible
 237    for the optimizer to optimize the program and debugging information without
 238    necessarily having to know anything about debugging information.  In
 239    particular, te use of metadadta avoids duplicated dubgging information from
 240    the beginning, and the global dead code elimination pass automatically
 241    deletes debugging information for a function if it decides to delete the
 242    function. </p>
 243
 244 <p>To do this, most of the debugging information (descriptors for types,
 245    variables, functions, source files, etc) is inserted by the language
 246    front-end in the form of LLVM metadata. </p>
 247
 248 <p>Debug information is designed to be agnostic about the target debugger and
 249    debugging information representation (e.g. DWARF/Stabs/etc).  It uses a
 250    generic pass to decode the information that represents variables, types,
 251    functions, namespaces, etc: this allows for arbitrary source-language
 252    semantics and type-systems to be used, as long as there is a module
 253    written for the target debugger to interpret the information. </p>
 254
 255 <p>To provide basic functionality, the LLVM debugger does have to make some
 256    assumptions about the source-level language being debugged, though it keeps
 257    these to a minimum.  The only common features that the LLVM debugger assumes
 258    exist are <a href="#format_compile_units">source files</a>,
 259    and <a href="#format_global_variables">program objects</a>.  These abstract
 260    objects are used by a debugger to form stack traces, show information about
 261    local variables, etc.</p>
 262
 263 <p>This section of the documentation first describes the representation aspects
 264    common to any source-language.  The <a href="#ccxx_frontend">next section</a>
 265    describes the data layout conventions used by the C and C++ front-ends.</p>
 266
 267 </div>
 268
 269 <!-- ======================================================================= -->
 270 <div class="doc_subsection">
 271   <a name="debug_info_descriptors">Debug information descriptors</a>
 272 </div>
 273
 274 <div class="doc_text">
 275
 276 <p>In consideration of the complexity and volume of debug information, LLVM
 277    provides a specification for well formed debug descriptors. </p>
 278
 279 <p>Consumers of LLVM debug information expect the descriptors for program
 280    objects to start in a canonical format, but the descriptors can include
 281    additional information appended at the end that is source-language
 282    specific. All LLVM debugging information is versioned, allowing backwards
 283    compatibility in the case that the core structures need to change in some
 284    way.  Also, all debugging information objects start with a tag to indicate
 285    what type of object it is.  The source-language is allowed to define its own
 286    objects, by using unreserved tag numbers.  We recommend using with tags in
 287    the range 0x1000 through 0x2000 (there is a defined enum DW_TAG_user_base =
 288    0x1000.)</p>
 289
 290 <p>The fields of debug descriptors used internally by LLVM
 291    are restricted to only the simple data types <tt>int</tt>, <tt>uint</tt>,
 292    <tt>bool</tt>, <tt>float</tt>, <tt>double</tt>, <tt>mdstring</tt> and
 293    <tt>mdnode</tt>. </p>
 294
 295 <div class="doc_code">
 296 <pre>
 297 !1 = metadata !{
 298   uint,   ;; A tag
 299   ...
 300 }
 301 </pre>
 302 </div>
 303
 304 <p><a name="LLVMDebugVersion">The first field of a descriptor is always an
 305    <tt>uint</tt> containing a tag value identifying the content of the
 306    descriptor.  The remaining fields are specific to the descriptor.  The values
 307    of tags are loosely bound to the tag values of DWARF information entries.
 308    However, that does not restrict the use of the information supplied to DWARF
 309    targets.  To facilitate versioning of debug information, the tag is augmented
 310    with the current debug version (LLVMDebugVersion = 7 << 16 or 0x70000 or
 311    458752.)</a></p>
 312
 313 <p>The details of the various descriptors follow.</p>
 314
 315 </div>
 316
 317 <!-- ======================================================================= -->
 318 <div class="doc_subsubsection">
 319   <a name="format_compile_units">Compile unit descriptors</a>
 320 </div>
 321
 322 <div class="doc_text">
 323
 324 <div class="doc_code">
 325 <pre>
 326 !0 = metadata !{
 327   i32,       ;; Tag = 17 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
 328              ;; (DW_TAG_compile_unit)
 329   i32,       ;; Unused field.
 330   i32,       ;; DWARF language identifier (ex. DW_LANG_C89)
 331   metadata,  ;; Source file name
 332   metadata,  ;; Source file directory (includes trailing slash)
 333   metadata   ;; Producer (ex. "4.0.1 LLVM (LLVM research group)")
 334   i1,        ;; True if this is a main compile unit.
 335   i1,        ;; True if this is optimized.
 336   metadata,  ;; Flags
 337   i32        ;; Runtime version
 338 }
 339 </pre>
 340 </div>
 341
 342 <p>These descriptors contain a source language ID for the file (we use the DWARF
 343    3.0 ID numbers, such as <tt>DW_LANG_C89</tt>, <tt>DW_LANG_C_plus_plus</tt>,
 344    <tt>DW_LANG_Cobol74</tt>, etc), three strings describing the filename,
 345    working directory of the compiler, and an identifier string for the compiler
 346    that produced it.</p>
 347
 348 <p>Compile unit descriptors provide the root context for objects declared in a
 349    specific source file.  Global variables and top level functions would be
 350    defined using this context. Compile unit descriptors also provide context
 351    for source line correspondence.</p>
 352
 353 <p>Each input file is encoded as a separate compile unit in LLVM debugging
 354    information output. However, many target specific tool chains prefer to
 355    encode only one compile unit in an object file. In this situation, the LLVM
 356    code generator will include debugging information entities in the compile
 357    unit that is marked as main compile unit. The code generator accepts maximum
 358    one main compile unit per module. If a module does not contain any main
 359    compile unit then the code generator will emit multiple compile units in the
 360    output object file.</p>
 361
 362 </div>
 363
 364 <!-- ======================================================================= -->
 365 <div class="doc_subsubsection">
 366   <a name="format_global_variables">Global variable descriptors</a>
 367 </div>
 368
 369 <div class="doc_text">
 370
 371 <div class="doc_code">
 372 <pre>
 373 !1 = metadata !{
 374   i32,      ;; Tag = 52 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
 375             ;; (DW_TAG_variable)
 376   i32,      ;; Unused field.
 377   metadata, ;; Reference to context descriptor
 378   metadata, ;; Name
 379   metadata, ;; Display name (fully qualified C++ name)
 380   metadata, ;; MIPS linkage name (for C++)
 381   metadata, ;; Reference to compile unit where defined
 382   i32,      ;; Line number where defined
 383   metadata, ;; Reference to type descriptor
 384   i1,       ;; True if the global is local to compile unit (static)
 385   i1,       ;; True if the global is defined in the compile unit (not extern)
 386   {  }*     ;; Reference to the global variable
 387 }
 388 </pre>
 389 </div>
 390
 391 <p>These descriptors provide debug information about globals variables.  The
 392 provide details such as name, type and where the variable is defined.</p>
 393
 394 </div>
 395
 396 <!-- ======================================================================= -->
 397 <div class="doc_subsubsection">
 398   <a name="format_subprograms">Subprogram descriptors</a>
 399 </div>
 400
 401 <div class="doc_text">
 402
 403 <div class="doc_code">
 404 <pre>
 405 !2 = metadata !{
 406   i32,      ;; Tag = 46 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
 407             ;; (DW_TAG_subprogram)
 408   i32,      ;; Unused field.
 409   metadata, ;; Reference to context descriptor
 410   metadata, ;; Name
 411   metadata, ;; Display name (fully qualified C++ name)
 412   metadata, ;; MIPS linkage name (for C++)
 413   metadata, ;; Reference to compile unit where defined
 414   i32,      ;; Line number where defined
 415   metadata, ;; Reference to type descriptor
 416   i1,       ;; True if the global is local to compile unit (static)
 417   i1        ;; True if the global is defined in the compile unit (not extern)
 418 }
 419 </pre>
 420 </div>
 421
 422 <p>These descriptors provide debug information about functions, methods and
 423    subprograms.  They provide details such as name, return types and the source
 424    location where the subprogram is defined.</p>
 425
 426 </div>
 427
 428 <!-- ======================================================================= -->
 429 <div class="doc_subsubsection">
 430   <a name="format_blocks">Block descriptors</a>
 431 </div>
 432
 433 <div class="doc_text">
 434
 435 <div class="doc_code">
 436 <pre>
 437 !3 = metadata !{
 438   i32,     ;; Tag = 13 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_lexical_block)
 439   metadata ;; Reference to context descriptor
 440 }
 441 </pre>
 442 </div>
 443
 444 <p>These descriptors provide debug information about nested blocks within a
 445    subprogram.  The array of member descriptors is used to define local
 446    variables and deeper nested blocks.</p>
 447
 448 </div>
 449
 450 <!-- ======================================================================= -->
 451 <div class="doc_subsubsection">
 452   <a name="format_basic_type">Basic type descriptors</a>
 453 </div>
 454
 455 <div class="doc_text">
 456
 457 <div class="doc_code">
 458 <pre>
 459 !4 = metadata !{
 460   i32,      ;; Tag = 36 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
 461             ;; (DW_TAG_base_type)
 462   metadata, ;; Reference to context (typically a compile unit)
 463   metadata, ;; Name (may be "" for anonymous types)
 464   metadata, ;; Reference to compile unit where defined (may be NULL)
 465   i32,      ;; Line number where defined (may be 0)
 466   i64,      ;; Size in bits
 467   i64,      ;; Alignment in bits
 468   i64,      ;; Offset in bits
 469   i32,      ;; Flags
 470   i32       ;; DWARF type encoding
 471 }
 472 </pre>
 473 </div>
 474
 475 <p>These descriptors define primitive types used in the code. Example int, bool
 476    and float.  The context provides the scope of the type, which is usually the
 477    top level.  Since basic types are not usually user defined the compile unit
 478    and line number can be left as NULL and 0.  The size, alignment and offset
 479    are expressed in bits and can be 64 bit values.  The alignment is used to
 480    round the offset when embedded in a
 481    <a href="#format_composite_type">composite type</a> (example to keep float
 482    doubles on 64 bit boundaries.) The offset is the bit offset if embedded in
 483    a <a href="#format_composite_type">composite type</a>.</p>
 484
 485 <p>The type encoding provides the details of the type.  The values are typically
 486    one of the following:</p>
 487
 488 <div class="doc_code">
 489 <pre>
 490 DW_ATE_address       = 1
 491 DW_ATE_boolean       = 2
 492 DW_ATE_float         = 4
 493 DW_ATE_signed        = 5
 494 DW_ATE_signed_char   = 6
 495 DW_ATE_unsigned      = 7
 496 DW_ATE_unsigned_char = 8
 497 </pre>
 498 </div>
 499
 500 </div>
 501
 502 <!-- ======================================================================= -->
 503 <div class="doc_subsubsection">
 504   <a name="format_derived_type">Derived type descriptors</a>
 505 </div>
 506
 507 <div class="doc_text">
 508
 509 <div class="doc_code">
 510 <pre>
 511 !5 = metadata !{
 512   i32,      ;; Tag (see below)
 513   metadata, ;; Reference to context
 514   metadata, ;; Name (may be "" for anonymous types)
 515   metadata, ;; Reference to compile unit where defined (may be NULL)
 516   i32,      ;; Line number where defined (may be 0)
 517   i32,      ;; Size in bits
 518   i32,      ;; Alignment in bits
 519   i32,      ;; Offset in bits
 520   metadata  ;; Reference to type derived from
 521 }
 522 </pre>
 523 </div>
 524
 525 <p>These descriptors are used to define types derived from other types.  The
 526 value of the tag varies depending on the meaning.  The following are possible
 527 tag values:</p>
 528
 529 <div class="doc_code">
 530 <pre>
 531 DW_TAG_formal_parameter = 5
 532 DW_TAG_member           = 13
 533 DW_TAG_pointer_type     = 15
 534 DW_TAG_reference_type   = 16
 535 DW_TAG_typedef          = 22
 536 DW_TAG_const_type       = 38
 537 DW_TAG_volatile_type    = 53
 538 DW_TAG_restrict_type    = 55
 539 </pre>
 540 </div>
 541
 542 <p><tt>DW_TAG_member</tt> is used to define a member of
 543    a <a href="#format_composite_type">composite type</a>
 544    or <a href="#format_subprograms">subprogram</a>.  The type of the member is
 545    the <a href="#format_derived_type">derived
 546    type</a>. <tt>DW_TAG_formal_parameter</tt> is used to define a member which
 547    is a formal argument of a subprogram.</p>
 548
 549 <p><tt>DW_TAG_typedef</tt> is used to provide a name for the derived type.</p>
 550
 551 <p><tt>DW_TAG_pointer_type</tt>,<tt>DW_TAG_reference_type</tt>,
 552    <tt>DW_TAG_const_type</tt>, <tt>DW_TAG_volatile_type</tt>
 553    and <tt>DW_TAG_restrict_type</tt> are used to qualify
 554    the <a href="#format_derived_type">derived type</a>. </p>
 555
 556 <p><a href="#format_derived_type">Derived type</a> location can be determined
 557    from the compile unit and line number.  The size, alignment and offset are
 558    expressed in bits and can be 64 bit values.  The alignment is used to round
 559    the offset when embedded in a <a href="#format_composite_type">composite
 560    type</a> (example to keep float doubles on 64 bit boundaries.) The offset is
 561    the bit offset if embedded in a <a href="#format_composite_type">composite
 562    type</a>.</p>
 563
 564 <p>Note that the <tt>void *</tt> type is expressed as a
 565    <tt>llvm.dbg.derivedtype.type</tt> with tag of <tt>DW_TAG_pointer_type</tt>
 566    and <tt>NULL</tt> derived type.</p>
 567
 568 </div>
 569
 570 <!-- ======================================================================= -->
 571 <div class="doc_subsubsection">
 572   <a name="format_composite_type">Composite type descriptors</a>
 573 </div>
 574
 575 <div class="doc_text">
 576
 577 <div class="doc_code">
 578 <pre>
 579 !6 = metadata !{
 580   i32,      ;; Tag (see below)
 581   metadata, ;; Reference to context
 582   metadata, ;; Name (may be "" for anonymous types)
 583   metadata, ;; Reference to compile unit where defined (may be NULL)
 584   i32,      ;; Line number where defined (may be 0)
 585   i64,      ;; Size in bits
 586   i64,      ;; Alignment in bits
 587   i64,      ;; Offset in bits
 588   i32,      ;; Flags
 589   metadata, ;; Reference to type derived from
 590   metadata, ;; Reference to array of member descriptors
 591   i32       ;; Runtime languages
 592 }
 593 </pre>
 594 </div>
 595
 596 <p>These descriptors are used to define types that are composed of 0 or more
 597 elements.  The value of the tag varies depending on the meaning.  The following
 598 are possible tag values:</p>
 599
 600 <div class="doc_code">
 601 <pre>
 602 DW_TAG_array_type       = 1
 603 DW_TAG_enumeration_type = 4
 604 DW_TAG_structure_type   = 19
 605 DW_TAG_union_type       = 23
 606 DW_TAG_vector_type      = 259
 607 DW_TAG_subroutine_type  = 21
 608 DW_TAG_inheritance      = 28
 609 </pre>
 610 </div>
 611
 612 <p>The vector flag indicates that an array type is a native packed vector.</p>
 613
 614 <p>The members of array types (tag = <tt>DW_TAG_array_type</tt>) or vector types
 615    (tag = <tt>DW_TAG_vector_type</tt>) are <a href="#format_subrange">subrange
 616    descriptors</a>, each representing the range of subscripts at that level of
 617    indexing.</p>
 618
 619 <p>The members of enumeration types (tag = <tt>DW_TAG_enumeration_type</tt>) are
 620    <a href="#format_enumeration">enumerator descriptors</a>, each representing
 621    the definition of enumeration value for the set.</p>
 622
 623 <p>The members of structure (tag = <tt>DW_TAG_structure_type</tt>) or union (tag
 624    = <tt>DW_TAG_union_type</tt>) types are any one of
 625    the <a href="#format_basic_type">basic</a>,
 626    <a href="#format_derived_type">derived</a>
 627    or <a href="#format_composite_type">composite</a> type descriptors, each
 628    representing a field member of the structure or union.</p>
 629
 630 <p>For C++ classes (tag = <tt>DW_TAG_structure_type</tt>), member descriptors
 631    provide information about base classes, static members and member
 632    functions. If a member is a <a href="#format_derived_type">derived type
 633    descriptor</a> and has a tag of <tt>DW_TAG_inheritance</tt>, then the type
 634    represents a base class. If the member of is
 635    a <a href="#format_global_variables">global variable descriptor</a> then it
 636    represents a static member.  And, if the member is
 637    a <a href="#format_subprograms">subprogram descriptor</a> then it represents
 638    a member function.  For static members and member
 639    functions, <tt>getName()</tt> returns the members link or the C++ mangled
 640    name.  <tt>getDisplayName()</tt> the simplied version of the name.</p>
 641
 642 <p>The first member of subroutine (tag = <tt>DW_TAG_subroutine_type</tt>) type
 643    elements is the return type for the subroutine.  The remaining elements are
 644    the formal arguments to the subroutine.</p>
 645
 646 <p><a href="#format_composite_type">Composite type</a> location can be
 647    determined from the compile unit and line number.  The size, alignment and
 648    offset are expressed in bits and can be 64 bit values.  The alignment is used
 649    to round the offset when embedded in
 650    a <a href="#format_composite_type">composite type</a> (as an example, to keep
 651    float doubles on 64 bit boundaries.) The offset is the bit offset if embedded
 652    in a <a href="#format_composite_type">composite type</a>.</p>
 653
 654 </div>
 655
 656 <!-- ======================================================================= -->
 657 <div class="doc_subsubsection">
 658   <a name="format_subrange">Subrange descriptors</a>
 659 </div>
 660
 661 <div class="doc_text">
 662
 663 <div class="doc_code">
 664 <pre>
 665 %<a href="#format_subrange">llvm.dbg.subrange.type</a> = type {
 666   i32,    ;; Tag = 33 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_subrange_type)
 667   i64,    ;; Low value
 668   i64     ;; High value
 669 }
 670 </pre>
 671 </div>
 672
 673 <p>These descriptors are used to define ranges of array subscripts for an array
 674    <a href="#format_composite_type">composite type</a>.  The low value defines
 675    the lower bounds typically zero for C/C++.  The high value is the upper
 676    bounds.  Values are 64 bit.  High - low + 1 is the size of the array.  If low
 677    == high the array will be unbounded.</p>
 678
 679 </div>
 680
 681 <!-- ======================================================================= -->
 682 <div class="doc_subsubsection">
 683   <a name="format_enumeration">Enumerator descriptors</a>
 684 </div>
 685
 686 <div class="doc_text">
 687
 688 <div class="doc_code">
 689 <pre>
 690 !6 = metadata !{
 691   i32,      ;; Tag = 40 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
 692             ;; (DW_TAG_enumerator)
 693   metadata, ;; Name
 694   i64       ;; Value
 695 }
 696 </pre>
 697 </div>
 698
 699 <p>These descriptors are used to define members of an
 700    enumeration <a href="#format_composite_type">composite type</a>, it
 701    associates the name to the value.</p>
 702
 703 </div>
 704
 705 <!-- ======================================================================= -->
 706 <div class="doc_subsubsection">
 707   <a name="format_variables">Local variables</a>
 708 </div>
 709
 710 <div class="doc_text">
 711
 712 <div class="doc_code">
 713 <pre>
 714 !7 = metadata !{
 715   i32,      ;; Tag (see below)
 716   metadata, ;; Context
 717   metadata, ;; Name
 718   metadata, ;; Reference to compile unit where defined
 719   i32,      ;; Line number where defined
 720   metadata  ;; Type descriptor
 721 }
 722 </pre>
 723 </div>
 724
 725 <p>These descriptors are used to define variables local to a sub program.  The
 726    value of the tag depends on the usage of the variable:</p>
 727
 728 <div class="doc_code">
 729 <pre>
 730 DW_TAG_auto_variable   = 256
 731 DW_TAG_arg_variable    = 257
 732 DW_TAG_return_variable = 258
 733 </pre>
 734 </div>
 735
 736 <p>An auto variable is any variable declared in the body of the function.  An
 737    argument variable is any variable that appears as a formal argument to the
 738    function.  A return variable is used to track the result of a function and
 739    has no source correspondent.</p>
 740
 741 <p>The context is either the subprogram or block where the variable is defined.
 742    Name the source variable name.  Compile unit and line indicate where the
 743    variable was defined. Type descriptor defines the declared type of the
 744    variable.</p>
 745
 746 </div>
 747
 748 <!-- ======================================================================= -->
 749 <div class="doc_subsection">
 750   <a name="format_common_intrinsics">Debugger intrinsic functions</a>
 751 </div>
 752
 753 <div class="doc_text">
 754
 755 <p>LLVM uses several intrinsic functions (name prefixed with "llvm.dbg") to
 756    provide debug information at various points in generated code.</p>
 757
 758 </div>
 759
 760 <!-- ======================================================================= -->
 761 <div class="doc_subsubsection">
 762   <a name="format_common_declare">llvm.dbg.declare</a>
 763 </div>
 764
 765 <div class="doc_text">
 766 <pre>
 767   void %<a href="#format_common_declare">llvm.dbg.declare</a>( { } *, metadata )
 768 </pre>
 769
 770 <p>This intrinsic provides information about a local element (ex. variable.) The
 771    first argument is the alloca for the variable, cast to a <tt>{ }*</tt>. The
 772    second argument is
 773    the <tt>%<a href="#format_variables">llvm.dbg.variable</a></tt> containing
 774    the description of the variable. </p>
 775
 776 </div>
 777
 778 <!-- ======================================================================= -->
 779 <div class="doc_subsubsection">
 780   <a name="format_common_value">llvm.dbg.value</a>
 781 </div>
 782
 783 <div class="doc_text">
 784 <pre>
 785   void %<a href="#format_common_value">llvm.dbg.value</a>( metadata, i64, metadata )
 786 </pre>
 787
 788 <p>This intrinsic provides information when a user source variable is set to a
 789    new value.  The first argument is the new value (wrapped as metadata).  The
 790    second argument is the offset in the user source variable where the new value
 791    is written.  The third argument is
 792    the <tt>%<a href="#format_variables">llvm.dbg.variable</a></tt> containing
 793    the description of the user source variable. </p>
 794
 795 </div>
 796
 797 <!-- ======================================================================= -->
 798 <div class="doc_subsection">
 799   <a name="format_common_lifetime">Object lifetimes and scoping</a>
 800 </div>
 801
 802 <div class="doc_text">
 803 <p>In many languages, the local variables in functions can have their lifetimes
 804    or scopes limited to a subset of a function.  In the C family of languages,
 805    for example, variables are only live (readable and writable) within the
 806    source block that they are defined in.  In functional languages, values are
 807    only readable after they have been defined.  Though this is a very obvious
 808    concept, it is non-trivial to model in LLVM, because it has no notion of
 809    scoping in this sense, and does not want to be tied to a language's scoping
 810    rules.</p>
 811
 812 <p>In order to handle this, the LLVM debug format uses the metadata attached to
 813    llvm instructions to encode line nuber and scoping information. Consider the
 814    following C fragment, for example:</p>
 815
 816 <div class="doc_code">
 817 <pre>
 818 1.  void foo() {
 819 2.    int X = 21;
 820 3.    int Y = 22;
 821 4.    {
 822 5.      int Z = 23;
 823 6.      Z = X;
 824 7.    }
 825 8.    X = Y;
 826 9.  }
 827 </pre>
 828 </div>
 829
 830 <p>Compiled to LLVM, this function would be represented like this:</p>
 831
 832 <div class="doc_code">
 833 <pre>
 834 define void @foo() nounwind ssp {
 835 entry:
 836   %X = alloca i32, align 4                        ; &lt;i32*&gt; [#uses=4]
 837   %Y = alloca i32, align 4                        ; &lt;i32*&gt; [#uses=4]
 838   %Z = alloca i32, align 4                        ; &lt;i32*&gt; [#uses=3]
 839   %0 = bitcast i32* %X to { }*                    ; &lt;{ }*&gt; [#uses=1]
 840   call void @llvm.dbg.declare({ }* %0, metadata !0), !dbg !7
 841   store i32 21, i32* %X, !dbg !8
 842   %1 = bitcast i32* %Y to { }*                    ; &lt;{ }*&gt; [#uses=1]
 843   call void @llvm.dbg.declare({ }* %1, metadata !9), !dbg !10
 844   store i32 22, i32* %Y, !dbg !11
 845   %2 = bitcast i32* %Z to { }*                    ; &lt;{ }*&gt; [#uses=1]
 846   call void @llvm.dbg.declare({ }* %2, metadata !12), !dbg !14
 847   store i32 23, i32* %Z, !dbg !15
 848   %tmp = load i32* %X, !dbg !16                   ; &lt;i32&gt; [#uses=1]
 849   %tmp1 = load i32* %Y, !dbg !16                  ; &lt;i32&gt; [#uses=1]
 850   %add = add nsw i32 %tmp, %tmp1, !dbg !16        ; &lt;i32&gt; [#uses=1]
 851   store i32 %add, i32* %Z, !dbg !16
 852   %tmp2 = load i32* %Y, !dbg !17                  ; &lt;i32&gt; [#uses=1]
 853   store i32 %tmp2, i32* %X, !dbg !17
 854   ret void, !dbg !18
 855 }
 856
 857 declare void @llvm.dbg.declare({ }*, metadata) nounwind readnone
 858
 859 !0 = metadata !{i32 459008, metadata !1, metadata !"X",
 860                 metadata !3, i32 2, metadata !6}; [ DW_TAG_auto_variable ]
 861 !1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ]
 862 !2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo", metadata !"foo",
 863                metadata !"foo", metadata !3, i32 1, metadata !4,
 864                i1 false, i1 true}; [DW_TAG_subprogram ]
 865 !3 = metadata !{i32 458769, i32 0, i32 12, metadata !"foo.c",
 866                 metadata !"/private/tmp", metadata !"clang 1.1", i1 true,
 867                 i1 false, metadata !"", i32 0}; [DW_TAG_compile_unit ]
 868 !4 = metadata !{i32 458773, metadata !3, metadata !"", null, i32 0, i64 0, i64 0,
 869                 i64 0, i32 0, null, metadata !5, i32 0}; [DW_TAG_subroutine_type ]
 870 !5 = metadata !{null}
 871 !6 = metadata !{i32 458788, metadata !3, metadata !"int", metadata !3, i32 0,
 872                 i64 32, i64 32, i64 0, i32 0, i32 5}; [DW_TAG_base_type ]
 873 !7 = metadata !{i32 2, i32 7, metadata !1, null}
 874 !8 = metadata !{i32 2, i32 3, metadata !1, null}
 875 !9 = metadata !{i32 459008, metadata !1, metadata !"Y", metadata !3, i32 3,
 876                 metadata !6}; [ DW_TAG_auto_variable ]
 877 !10 = metadata !{i32 3, i32 7, metadata !1, null}
 878 !11 = metadata !{i32 3, i32 3, metadata !1, null}
 879 !12 = metadata !{i32 459008, metadata !13, metadata !"Z", metadata !3, i32 5,
 880                  metadata !6}; [ DW_TAG_auto_variable ]
 881 !13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ]
 882 !14 = metadata !{i32 5, i32 9, metadata !13, null}
 883 !15 = metadata !{i32 5, i32 5, metadata !13, null}
 884 !16 = metadata !{i32 6, i32 5, metadata !13, null}
 885 !17 = metadata !{i32 8, i32 3, metadata !1, null}
 886 !18 = metadata !{i32 9, i32 1, metadata !2, null}
 887 </pre>
 888 </div>
 889
 890 <p>This example illustrates a few important details about LLVM debugging
 891    information. In particular, it shows how the <tt>llvm.dbg.declare</tt>
 892    intrinsic and location information, which are attached to an instruction,
 893    are applied together to allow a debugger to analyze the relationship between
 894    statements, variable definitions, and the code used to implement the
 895    function.</p>
 896
 897 <div class="doc_code">
 898 <pre>
 899 call void @llvm.dbg.declare({ }* %0, metadata !0), !dbg !7
 900 </pre>
 901 </div>
 902
 903 <p>The first intrinsic
 904    <tt>%<a href="#format_common_declare">llvm.dbg.declare</a></tt>
 905    encodes debugging information for the variable <tt>X</tt>. The metadata
 906    <tt>!dbg !7</tt> attached to the intrinsic provides scope information for the
 907    variable <tt>X</tt>.</p>
 908
 909 <div class="doc_code">
 910 <pre>
 911 !7 = metadata !{i32 2, i32 7, metadata !1, null}
 912 !1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ]
 913 !2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo",
 914                 metadata !"foo", metadata !"foo", metadata !3, i32 1,
 915                 metadata !4, i1 false, i1 true}; [DW_TAG_subprogram ]
 916 </pre>
 917 </div>
 918
 919 <p>Here <tt>!7</tt> is metadata providing location information. It has four
 920    fields: line number, column number, scope, and original scope. The original
 921    scope represents inline location if this instruction is inlined inside a
 922    caller, and is null otherwise. In this example, scope is encoded by
 923    <tt>!1</tt>. <tt>!1</tt> represents a lexical block inside the scope
 924    <tt>!2</tt>, where <tt>!2</tt> is a
 925    <a href="#format_subprograms">subprogram descriptor</a>. This way the
 926    location information attached to the intrinsics indicates that the
 927    variable <tt>X</tt> is declared at line number 2 at a function level scope in
 928    function <tt>foo</tt>.</p>
 929
 930 <p>Now lets take another example.</p>
 931
 932 <div class="doc_code">
 933 <pre>
 934 call void @llvm.dbg.declare({ }* %2, metadata !12), !dbg !14
 935 </pre>
 936 </div>
 937
 938 <p>The second intrinsic
 939    <tt>%<a href="#format_common_declare">llvm.dbg.declare</a></tt>
 940    encodes debugging information for variable <tt>Z</tt>. The metadata
 941    <tt>!dbg !14</tt> attached to the intrinsic provides scope information for
 942    the variable <tt>Z</tt>.</p>
 943
 944 <div class="doc_code">
 945 <pre>
 946 !13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ]
 947 !14 = metadata !{i32 5, i32 9, metadata !13, null}
 948 </pre>
 949 </div>
 950
 951 <p>Here <tt>!14</tt> indicates that <tt>Z</tt> is declaread at line number 5 and
 952    column number 9 inside of lexical scope <tt>!13</tt>. The lexical scope
 953    itself resides inside of lexical scope <tt>!1</tt> described above.</p>
 954
 955 <p>The scope information attached with each instruction provides a
 956    straightforward way to find instructions covered by a scope.</p>
 957
 958 </div>
 959
 960 <!-- *********************************************************************** -->
 961 <div class="doc_section">
 962   <a name="ccxx_frontend">C/C++ front-end specific debug information</a>
 963 </div>
 964 <!-- *********************************************************************** -->
 965
 966 <div class="doc_text">
 967
 968 <p>The C and C++ front-ends represent information about the program in a format
 969    that is effectively identical
 970    to <a href="http://www.eagercon.com/dwarf/dwarf3std.htm">DWARF 3.0</a> in
 971    terms of information content.  This allows code generators to trivially
 972    support native debuggers by generating standard dwarf information, and
 973    contains enough information for non-dwarf targets to translate it as
 974    needed.</p>
 975
 976 <p>This section describes the forms used to represent C and C++ programs. Other
 977    languages could pattern themselves after this (which itself is tuned to
 978    representing programs in the same way that DWARF 3 does), or they could
 979    choose to provide completely different forms if they don't fit into the DWARF
 980    model.  As support for debugging information gets added to the various LLVM
 981    source-language front-ends, the information used should be documented
 982    here.</p>
 983
 984 <p>The following sections provide examples of various C/C++ constructs and the
 985    debug information that would best describe those constructs.</p>
 986
 987 </div>
 988
 989 <!-- ======================================================================= -->
 990 <div class="doc_subsection">
 991   <a name="ccxx_compile_units">C/C++ source file information</a>
 992 </div>
 993
 994 <div class="doc_text">
 995
 996 <p>Given the source files <tt>MySource.cpp</tt> and <tt>MyHeader.h</tt> located
 997    in the directory <tt>/Users/mine/sources</tt>, the following code:</p>
 998
 999 <div class="doc_code">
1000 <pre>
1001 #include "MyHeader.h"
1002
1003 int main(int argc, char *argv[]) {
1004   return 0;
1005 }
1006 </pre>
1007 </div>
1008
1009 <p>a C/C++ front-end would generate the following descriptors:</p>
1010
1011 <div class="doc_code">
1012 <pre>
1013 ...
1014 ;;
1015 ;; Define the compile unit for the source file "/Users/mine/sources/MySource.cpp".
1016 ;;
1017 !3 = metadata !{
1018   i32 458769,    ;; Tag
1019   i32 0,         ;; Unused
1020   i32 4,         ;; Language Id
1021   metadata !"MySource.cpp",
1022   metadata !"/Users/mine/sources",
1023   metadata !"4.2.1 (Based on Apple Inc. build 5649) (LLVM build 00)",
1024   i1 true,       ;; Main Compile Unit
1025   i1 false,      ;; Optimized compile unit
1026   metadata !"",  ;; Compiler flags
1027   i32 0}         ;; Runtime version
1028
1029 ;;
1030 ;; Define the compile unit for the header file "/Users/mine/sources/MyHeader.h".
1031 ;;
1032 !1 = metadata !{
1033   i32 458769,    ;; Tag
1034   i32 0,         ;; Unused
1035   i32 4,         ;; Language Id
1036   metadata !"MyHeader.h",
1037   metadata !"/Users/mine/sources",
1038   metadata !"4.2.1 (Based on Apple Inc. build 5649) (LLVM build 00)",
1039   i1 false,      ;; Main Compile Unit
1040   i1 false,      ;; Optimized compile unit
1041   metadata !"",  ;; Compiler flags
1042   i32 0}         ;; Runtime version
1043
1044 ...
1045 </pre>
1046 </div>
1047
1048 </div>
1049
1050 <!-- ======================================================================= -->
1051 <div class="doc_subsection">
1052   <a name="ccxx_global_variable">C/C++ global variable information</a>
1053 </div>
1054
1055 <div class="doc_text">
1056
1057 <p>Given an integer global variable declared as follows:</p>
1058
1059 <div class="doc_code">
1060 <pre>
1061 int MyGlobal = 100;
1062 </pre>
1063 </div>
1064
1065 <p>a C/C++ front-end would generate the following descriptors:</p>
1066
1067 <div class="doc_code">
1068 <pre>
1069 ;;
1070 ;; Define the global itself.
1071 ;;
1072 %MyGlobal = global int 100
1073 ...
1074 ;;
1075 ;; List of debug info of globals
1076 ;;
1077 !llvm.dbg.gv = !{!0}
1078
1079 ;;
1080 ;; Define the global variable descriptor.  Note the reference to the global
1081 ;; variable anchor and the global variable itself.
1082 ;;
1083 !0 = metadata !{
1084   i32 458804,              ;; Tag
1085   i32 0,                   ;; Unused
1086   metadata !1,             ;; Context
1087   metadata !"MyGlobal",    ;; Name
1088   metadata !"MyGlobal",    ;; Display Name
1089   metadata !"MyGlobal",    ;; Linkage Name
1090   metadata !1,             ;; Compile Unit
1091   i32 1,                   ;; Line Number
1092   metadata !2,             ;; Type
1093   i1 false,                ;; Is a local variable
1094   i1 true,                 ;; Is this a definition
1095   i32* @MyGlobal           ;; The global variable
1096 }
1097
1098 ;;
1099 ;; Define the basic type of 32 bit signed integer.  Note that since int is an
1100 ;; intrinsic type the source file is NULL and line 0.
1101 ;;
1102 !2 = metadata !{
1103   i32 458788,              ;; Tag
1104   metadata !1,             ;; Context
1105   metadata !"int",         ;; Name
1106   metadata !1,             ;; Compile Unit
1107   i32 0,                   ;; Line number
1108   i64 32,                  ;; Size in Bits
1109   i64 32,                  ;; Align in Bits
1110   i64 0,                   ;; Offset in Bits
1111   i32 0,                   ;; Flags
1112   i32 5                    ;; Encoding
1113 }
1114
1115 </pre>
1116 </div>
1117
1118 </div>
1119
1120 <!-- ======================================================================= -->
1121 <div class="doc_subsection">
1122   <a name="ccxx_subprogram">C/C++ function information</a>
1123 </div>
1124
1125 <div class="doc_text">
1126
1127 <p>Given a function declared as follows:</p>
1128
1129 <div class="doc_code">
1130 <pre>
1131 int main(int argc, char *argv[]) {
1132   return 0;
1133 }
1134 </pre>
1135 </div>
1136
1137 <p>a C/C++ front-end would generate the following descriptors:</p>
1138
1139 <div class="doc_code">
1140 <pre>
1141 ;;
1142 ;; Define the anchor for subprograms.  Note that the second field of the
1143 ;; anchor is 46, which is the same as the tag for subprograms
1144 ;; (46 = DW_TAG_subprogram.)
1145 ;;
1146 !0 = metadata !{
1147   i32 458798,        ;; Tag
1148   i32 0,             ;; Unused
1149   metadata !1,       ;; Context
1150   metadata !"main",  ;; Name
1151   metadata !"main",  ;; Display name
1152   metadata !"main",  ;; Linkage name
1153   metadata !1,       ;; Compile unit
1154   i32 1,             ;; Line number
1155   metadata !2,       ;; Type
1156   i1 false,          ;; Is local
1157   i1 true            ;; Is definition
1158 }
1159 ;;
1160 ;; Define the subprogram itself.
1161 ;;
1162 define i32 @main(i32 %argc, i8** %argv) {
1163 ...
1164 }
1165 </pre>
1166 </div>
1167
1168 </div>
1169
1170 <!-- ======================================================================= -->
1171 <div class="doc_subsection">
1172   <a name="ccxx_basic_types">C/C++ basic types</a>
1173 </div>
1174
1175 <div class="doc_text">
1176
1177 <p>The following are the basic type descriptors for C/C++ core types:</p>
1178
1179 </div>
1180
1181 <!-- ======================================================================= -->
1182 <div class="doc_subsubsection">
1183   <a name="ccxx_basic_type_bool">bool</a>
1184 </div>
1185
1186 <div class="doc_text">
1187
1188 <div class="doc_code">
1189 <pre>
1190 !2 = metadata !{
1191   i32 458788,        ;; Tag
1192   metadata !1,       ;; Context
1193   metadata !"bool",  ;; Name
1194   metadata !1,       ;; Compile Unit
1195   i32 0,             ;; Line number
1196   i64 8,             ;; Size in Bits
1197   i64 8,             ;; Align in Bits
1198   i64 0,             ;; Offset in Bits
1199   i32 0,             ;; Flags
1200   i32 2              ;; Encoding
1201 }
1202 </pre>
1203 </div>
1204
1205 </div>
1206
1207 <!-- ======================================================================= -->
1208 <div class="doc_subsubsection">
1209   <a name="ccxx_basic_char">char</a>
1210 </div>
1211
1212 <div class="doc_text">
1213
1214 <div class="doc_code">
1215 <pre>
1216 !2 = metadata !{
1217   i32 458788,        ;; Tag
1218   metadata !1,       ;; Context
1219   metadata !"char",  ;; Name
1220   metadata !1,       ;; Compile Unit
1221   i32 0,             ;; Line number
1222   i64 8,             ;; Size in Bits
1223   i64 8,             ;; Align in Bits
1224   i64 0,             ;; Offset in Bits
1225   i32 0,             ;; Flags
1226   i32 6              ;; Encoding
1227 }
1228 </pre>
1229 </div>
1230
1231 </div>
1232
1233 <!-- ======================================================================= -->
1234 <div class="doc_subsubsection">
1235   <a name="ccxx_basic_unsigned_char">unsigned char</a>
1236 </div>
1237
1238 <div class="doc_text">
1239
1240 <div class="doc_code">
1241 <pre>
1242 !2 = metadata !{
1243   i32 458788,        ;; Tag
1244   metadata !1,       ;; Context
1245   metadata !"unsigned char",
1246   metadata !1,       ;; Compile Unit
1247   i32 0,             ;; Line number
1248   i64 8,             ;; Size in Bits
1249   i64 8,             ;; Align in Bits
1250   i64 0,             ;; Offset in Bits
1251   i32 0,             ;; Flags
1252   i32 8              ;; Encoding
1253 }
1254 </pre>
1255 </div>
1256
1257 </div>
1258
1259 <!-- ======================================================================= -->
1260 <div class="doc_subsubsection">
1261   <a name="ccxx_basic_short">short</a>
1262 </div>
1263
1264 <div class="doc_text">
1265
1266 <div class="doc_code">
1267 <pre>
1268 !2 = metadata !{
1269   i32 458788,        ;; Tag
1270   metadata !1,       ;; Context
1271   metadata !"short int",
1272   metadata !1,       ;; Compile Unit
1273   i32 0,             ;; Line number
1274   i64 16,            ;; Size in Bits
1275   i64 16,            ;; Align in Bits
1276   i64 0,             ;; Offset in Bits
1277   i32 0,             ;; Flags
1278   i32 5              ;; Encoding
1279 }
1280 </pre>
1281 </div>
1282
1283 </div>
1284
1285 <!-- ======================================================================= -->
1286 <div class="doc_subsubsection">
1287   <a name="ccxx_basic_unsigned_short">unsigned short</a>
1288 </div>
1289
1290 <div class="doc_text">
1291
1292 <div class="doc_code">
1293 <pre>
1294 !2 = metadata !{
1295   i32 458788,        ;; Tag
1296   metadata !1,       ;; Context
1297   metadata !"short unsigned int",
1298   metadata !1,       ;; Compile Unit
1299   i32 0,             ;; Line number
1300   i64 16,            ;; Size in Bits
1301   i64 16,            ;; Align in Bits
1302   i64 0,             ;; Offset in Bits
1303   i32 0,             ;; Flags
1304   i32 7              ;; Encoding
1305 }
1306 </pre>
1307 </div>
1308
1309 </div>
1310
1311 <!-- ======================================================================= -->
1312 <div class="doc_subsubsection">
1313   <a name="ccxx_basic_int">int</a>
1314 </div>
1315
1316 <div class="doc_text">
1317
1318 <div class="doc_code">
1319 <pre>
1320 !2 = metadata !{
1321   i32 458788,        ;; Tag
1322   metadata !1,       ;; Context
1323   metadata !"int",   ;; Name
1324   metadata !1,       ;; Compile Unit
1325   i32 0,             ;; Line number
1326   i64 32,            ;; Size in Bits
1327   i64 32,            ;; Align in Bits
1328   i64 0,             ;; Offset in Bits
1329   i32 0,             ;; Flags
1330   i32 5              ;; Encoding
1331 }
1332 </pre></div>
1333
1334 </div>
1335
1336 <!-- ======================================================================= -->
1337 <div class="doc_subsubsection">
1338   <a name="ccxx_basic_unsigned_int">unsigned int</a>
1339 </div>
1340
1341 <div class="doc_text">
1342
1343 <div class="doc_code">
1344 <pre>
1345 !2 = metadata !{
1346   i32 458788,        ;; Tag
1347   metadata !1,       ;; Context
1348   metadata !"unsigned int",
1349   metadata !1,       ;; Compile Unit
1350   i32 0,             ;; Line number
1351   i64 32,            ;; Size in Bits
1352   i64 32,            ;; Align in Bits
1353   i64 0,             ;; Offset in Bits
1354   i32 0,             ;; Flags
1355   i32 7              ;; Encoding
1356 }
1357 </pre>
1358 </div>
1359
1360 </div>
1361
1362 <!-- ======================================================================= -->
1363 <div class="doc_subsubsection">
1364   <a name="ccxx_basic_long_long">long long</a>
1365 </div>
1366
1367 <div class="doc_text">
1368
1369 <div class="doc_code">
1370 <pre>
1371 !2 = metadata !{
1372   i32 458788,        ;; Tag
1373   metadata !1,       ;; Context
1374   metadata !"long long int",
1375   metadata !1,       ;; Compile Unit
1376   i32 0,             ;; Line number
1377   i64 64,            ;; Size in Bits
1378   i64 64,            ;; Align in Bits
1379   i64 0,             ;; Offset in Bits
1380   i32 0,             ;; Flags
1381   i32 5              ;; Encoding
1382 }
1383 </pre>
1384 </div>
1385
1386 </div>
1387
1388 <!-- ======================================================================= -->
1389 <div class="doc_subsubsection">
1390   <a name="ccxx_basic_unsigned_long_long">unsigned long long</a>
1391 </div>
1392
1393 <div class="doc_text">
1394
1395 <div class="doc_code">
1396 <pre>
1397 !2 = metadata !{
1398   i32 458788,        ;; Tag
1399   metadata !1,       ;; Context
1400   metadata !"long long unsigned int",
1401   metadata !1,       ;; Compile Unit
1402   i32 0,             ;; Line number
1403   i64 64,            ;; Size in Bits
1404   i64 64,            ;; Align in Bits
1405   i64 0,             ;; Offset in Bits
1406   i32 0,             ;; Flags
1407   i32 7              ;; Encoding
1408 }
1409 </pre>
1410 </div>
1411
1412 </div>
1413
1414 <!-- ======================================================================= -->
1415 <div class="doc_subsubsection">
1416   <a name="ccxx_basic_float">float</a>
1417 </div>
1418
1419 <div class="doc_text">
1420
1421 <div class="doc_code">
1422 <pre>
1423 !2 = metadata !{
1424   i32 458788,        ;; Tag
1425   metadata !1,       ;; Context
1426   metadata !"float",
1427   metadata !1,       ;; Compile Unit
1428   i32 0,             ;; Line number
1429   i64 32,            ;; Size in Bits
1430   i64 32,            ;; Align in Bits
1431   i64 0,             ;; Offset in Bits
1432   i32 0,             ;; Flags
1433   i32 4              ;; Encoding
1434 }
1435 </pre>
1436 </div>
1437
1438 </div>
1439
1440 <!-- ======================================================================= -->
1441 <div class="doc_subsubsection">
1442   <a name="ccxx_basic_double">double</a>
1443 </div>
1444
1445 <div class="doc_text">
1446
1447 <div class="doc_code">
1448 <pre>
1449 !2 = metadata !{
1450   i32 458788,        ;; Tag
1451   metadata !1,       ;; Context
1452   metadata !"double",;; Name
1453   metadata !1,       ;; Compile Unit
1454   i32 0,             ;; Line number
1455   i64 64,            ;; Size in Bits
1456   i64 64,            ;; Align in Bits
1457   i64 0,             ;; Offset in Bits
1458   i32 0,             ;; Flags
1459   i32 4              ;; Encoding
1460 }
1461 </pre>
1462 </div>
1463
1464 </div>
1465
1466 <!-- ======================================================================= -->
1467 <div class="doc_subsection">
1468   <a name="ccxx_derived_types">C/C++ derived types</a>
1469 </div>
1470
1471 <div class="doc_text">
1472
1473 <p>Given the following as an example of C/C++ derived type:</p>
1474
1475 <div class="doc_code">
1476 <pre>
1477 typedef const int *IntPtr;
1478 </pre>
1479 </div>
1480
1481 <p>a C/C++ front-end would generate the following descriptors:</p>
1482
1483 <div class="doc_code">
1484 <pre>
1485 ;;
1486 ;; Define the typedef "IntPtr".
1487 ;;
1488 !2 = metadata !{
1489   i32 458774,          ;; Tag
1490   metadata !1,         ;; Context
1491   metadata !"IntPtr",  ;; Name
1492   metadata !3,         ;; Compile unit
1493   i32 0,               ;; Line number
1494   i64 0,               ;; Size in bits
1495   i64 0,               ;; Align in bits
1496   i64 0,               ;; Offset in bits
1497   i32 0,               ;; Flags
1498   metadata !4          ;; Derived From type
1499 }
1500
1501 ;;
1502 ;; Define the pointer type.
1503 ;;
1504 !4 = metadata !{
1505   i32 458767,          ;; Tag
1506   metadata !1,         ;; Context
1507   metadata !"",        ;; Name
1508   metadata !1,         ;; Compile unit
1509   i32 0,               ;; Line number
1510   i64 64,              ;; Size in bits
1511   i64 64,              ;; Align in bits
1512   i64 0,               ;; Offset in bits
1513   i32 0,               ;; Flags
1514   metadata !5          ;; Derived From type
1515 }
1516 ;;
1517 ;; Define the const type.
1518 ;;
1519 !5 = metadata !{
1520   i32 458790,          ;; Tag
1521   metadata !1,         ;; Context
1522   metadata !"",        ;; Name
1523   metadata !1,         ;; Compile unit
1524   i32 0,               ;; Line number
1525   i64 32,              ;; Size in bits
1526   i64 32,              ;; Align in bits
1527   i64 0,               ;; Offset in bits
1528   i32 0,               ;; Flags
1529   metadata !6          ;; Derived From type
1530 }
1531 ;;
1532 ;; Define the int type.
1533 ;;
1534 !6 = metadata !{
1535   i32 458788,          ;; Tag
1536   metadata !1,         ;; Context
1537   metadata !"int",     ;; Name
1538   metadata !1,         ;; Compile unit
1539   i32 0,               ;; Line number
1540   i64 32,              ;; Size in bits
1541   i64 32,              ;; Align in bits
1542   i64 0,               ;; Offset in bits
1543   i32 0,               ;; Flags
1544   5                    ;; Encoding
1545 }
1546 </pre>
1547 </div>
1548
1549 </div>
1550
1551 <!-- ======================================================================= -->
1552 <div class="doc_subsection">
1553   <a name="ccxx_composite_types">C/C++ struct/union types</a>
1554 </div>
1555
1556 <div class="doc_text">
1557
1558 <p>Given the following as an example of C/C++ struct type:</p>
1559
1560 <div class="doc_code">
1561 <pre>
1562 struct Color {
1563   unsigned Red;
1564   unsigned Green;
1565   unsigned Blue;
1566 };
1567 </pre>
1568 </div>
1569
1570 <p>a C/C++ front-end would generate the following descriptors:</p>
1571
1572 <div class="doc_code">
1573 <pre>
1574 ;;
1575 ;; Define basic type for unsigned int.
1576 ;;
1577 !5 = metadata !{
1578   i32 458788,        ;; Tag
1579   metadata !1,       ;; Context
1580   metadata !"unsigned int",
1581   metadata !1,       ;; Compile Unit
1582   i32 0,             ;; Line number
1583   i64 32,            ;; Size in Bits
1584   i64 32,            ;; Align in Bits
1585   i64 0,             ;; Offset in Bits
1586   i32 0,             ;; Flags
1587   i32 7              ;; Encoding
1588 }
1589 ;;
1590 ;; Define composite type for struct Color.
1591 ;;
1592 !2 = metadata !{
1593   i32 458771,        ;; Tag
1594   metadata !1,       ;; Context
1595   metadata !"Color", ;; Name
1596   metadata !1,       ;; Compile unit
1597   i32 1,             ;; Line number
1598   i64 96,            ;; Size in bits
1599   i64 32,            ;; Align in bits
1600   i64 0,             ;; Offset in bits
1601   i32 0,             ;; Flags
1602   null,              ;; Derived From
1603   metadata !3,       ;; Elements
1604   i32 0              ;; Runtime Language
1605 }
1606
1607 ;;
1608 ;; Define the Red field.
1609 ;;
1610 !4 = metadata !{
1611   i32 458765,        ;; Tag
1612   metadata !1,       ;; Context
1613   metadata !"Red",   ;; Name
1614   metadata !1,       ;; Compile Unit
1615   i32 2,             ;; Line number
1616   i64 32,            ;; Size in bits
1617   i64 32,            ;; Align in bits
1618   i64 0,             ;; Offset in bits
1619   i32 0,             ;; Flags
1620   metadata !5        ;; Derived From type
1621 }
1622
1623 ;;
1624 ;; Define the Green field.
1625 ;;
1626 !6 = metadata !{
1627   i32 458765,        ;; Tag
1628   metadata !1,       ;; Context
1629   metadata !"Green", ;; Name
1630   metadata !1,       ;; Compile Unit
1631   i32 3,             ;; Line number
1632   i64 32,            ;; Size in bits
1633   i64 32,            ;; Align in bits
1634   i64 32,             ;; Offset in bits
1635   i32 0,             ;; Flags
1636   metadata !5        ;; Derived From type
1637 }
1638
1639 ;;
1640 ;; Define the Blue field.
1641 ;;
1642 !7 = metadata !{
1643   i32 458765,        ;; Tag
1644   metadata !1,       ;; Context
1645   metadata !"Blue",  ;; Name
1646   metadata !1,       ;; Compile Unit
1647   i32 4,             ;; Line number
1648   i64 32,            ;; Size in bits
1649   i64 32,            ;; Align in bits
1650   i64 64,             ;; Offset in bits
1651   i32 0,             ;; Flags
1652   metadata !5        ;; Derived From type
1653 }
1654
1655 ;;
1656 ;; Define the array of fields used by the composite type Color.
1657 ;;
1658 !3 = metadata !{metadata !4, metadata !6, metadata !7}
1659 </pre>
1660 </div>
1661
1662 </div>
1663
1664 <!-- ======================================================================= -->
1665 <div class="doc_subsection">
1666   <a name="ccxx_enumeration_types">C/C++ enumeration types</a>
1667 </div>
1668
1669 <div class="doc_text">
1670
1671 <p>Given the following as an example of C/C++ enumeration type:</p>
1672
1673 <div class="doc_code">
1674 <pre>
1675 enum Trees {
1676   Spruce = 100,
1677   Oak = 200,
1678   Maple = 300
1679 };
1680 </pre>
1681 </div>
1682
1683 <p>a C/C++ front-end would generate the following descriptors:</p>
1684
1685 <div class="doc_code">
1686 <pre>
1687 ;;
1688 ;; Define composite type for enum Trees
1689 ;;
1690 !2 = metadata !{
1691   i32 458756,        ;; Tag
1692   metadata !1,       ;; Context
1693   metadata !"Trees", ;; Name
1694   metadata !1,       ;; Compile unit
1695   i32 1,             ;; Line number
1696   i64 32,            ;; Size in bits
1697   i64 32,            ;; Align in bits
1698   i64 0,             ;; Offset in bits
1699   i32 0,             ;; Flags
1700   null,              ;; Derived From type
1701   metadata !3,       ;; Elements
1702   i32 0              ;; Runtime language
1703 }
1704
1705 ;;
1706 ;; Define the array of enumerators used by composite type Trees.
1707 ;;
1708 !3 = metadata !{metadata !4, metadata !5, metadata !6}
1709
1710 ;;
1711 ;; Define Spruce enumerator.
1712 ;;
1713 !4 = metadata !{i32 458792, metadata !"Spruce", i64 100}
1714
1715 ;;
1716 ;; Define Oak enumerator.
1717 ;;
1718 !5 = metadata !{i32 458792, metadata !"Oak", i64 200}
1719
1720 ;;
1721 ;; Define Maple enumerator.
1722 ;;
1723 !6 = metadata !{i32 458792, metadata !"Maple", i64 300}
1724
1725 </pre>
1726 </div>
1727
1728 </div>
1729
1730 <!-- *********************************************************************** -->
1731
1732 <hr>
1733 <address>
1734   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
1735   src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
1736   <a href="http://validator.w3.org/check/referer"><img
1737   src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
1738
1739   <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
1740   <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
1741   Last modified: $Date$
1742 </address>
1743
1744 </body>
1745 </html>