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