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++ looks like.</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   metadata,;; Reference to source file
 468   i32      ;; Unique ID to identify blocks from a template function
 469 }
 470 </pre>
 471 </div>
 472
 473 <p>These descriptors provide debug information about nested blocks within a
 474    subprogram. The line number and column numbers are used to dinstinguish
 475    two lexical blocks at same depth. </p>
 476
 477 </div>
 478
 479 <!-- ======================================================================= -->
 480 <div class="doc_subsubsection">
 481   <a name="format_basic_type">Basic type descriptors</a>
 482 </div>
 483
 484 <div class="doc_text">
 485
 486 <div class="doc_code">
 487 <pre>
 488 !4 = metadata !{
 489   i32,      ;; Tag = 36 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
 490             ;; (DW_TAG_base_type)
 491   metadata, ;; Reference to context (typically a compile unit)
 492   metadata, ;; Name (may be "" for anonymous types)
 493   metadata, ;; Reference to file where defined (may be NULL)
 494   i32,      ;; Line number where defined (may be 0)
 495   i64,      ;; Size in bits
 496   i64,      ;; Alignment in bits
 497   i64,      ;; Offset in bits
 498   i32,      ;; Flags
 499   i32       ;; DWARF type encoding
 500 }
 501 </pre>
 502 </div>
 503
 504 <p>These descriptors define primitive types used in the code. Example int, bool
 505    and float.  The context provides the scope of the type, which is usually the
 506    top level.  Since basic types are not usually user defined the compile unit
 507    and line number can be left as NULL and 0.  The size, alignment and offset
 508    are expressed in bits and can be 64 bit values.  The alignment is used to
 509    round the offset when embedded in a
 510    <a href="#format_composite_type">composite type</a> (example to keep float
 511    doubles on 64 bit boundaries.) The offset is the bit offset if embedded in
 512    a <a href="#format_composite_type">composite type</a>.</p>
 513
 514 <p>The type encoding provides the details of the type.  The values are typically
 515    one of the following:</p>
 516
 517 <div class="doc_code">
 518 <pre>
 519 DW_ATE_address       = 1
 520 DW_ATE_boolean       = 2
 521 DW_ATE_float         = 4
 522 DW_ATE_signed        = 5
 523 DW_ATE_signed_char   = 6
 524 DW_ATE_unsigned      = 7
 525 DW_ATE_unsigned_char = 8
 526 </pre>
 527 </div>
 528
 529 </div>
 530
 531 <!-- ======================================================================= -->
 532 <div class="doc_subsubsection">
 533   <a name="format_derived_type">Derived type descriptors</a>
 534 </div>
 535
 536 <div class="doc_text">
 537
 538 <div class="doc_code">
 539 <pre>
 540 !5 = metadata !{
 541   i32,      ;; Tag (see below)
 542   metadata, ;; Reference to context
 543   metadata, ;; Name (may be "" for anonymous types)
 544   metadata, ;; Reference to file where defined (may be NULL)
 545   i32,      ;; Line number where defined (may be 0)
 546   i64,      ;; Size in bits
 547   i64,      ;; Alignment in bits
 548   i64,      ;; Offset in bits
 549   metadata  ;; Reference to type derived from
 550 }
 551 </pre>
 552 </div>
 553
 554 <p>These descriptors are used to define types derived from other types.  The
 555 value of the tag varies depending on the meaning.  The following are possible
 556 tag values:</p>
 557
 558 <div class="doc_code">
 559 <pre>
 560 DW_TAG_formal_parameter = 5
 561 DW_TAG_member           = 13
 562 DW_TAG_pointer_type     = 15
 563 DW_TAG_reference_type   = 16
 564 DW_TAG_typedef          = 22
 565 DW_TAG_const_type       = 38
 566 DW_TAG_volatile_type    = 53
 567 DW_TAG_restrict_type    = 55
 568 </pre>
 569 </div>
 570
 571 <p><tt>DW_TAG_member</tt> is used to define a member of
 572    a <a href="#format_composite_type">composite type</a>
 573    or <a href="#format_subprograms">subprogram</a>.  The type of the member is
 574    the <a href="#format_derived_type">derived
 575    type</a>. <tt>DW_TAG_formal_parameter</tt> is used to define a member which
 576    is a formal argument of a subprogram.</p>
 577
 578 <p><tt>DW_TAG_typedef</tt> is used to provide a name for the derived type.</p>
 579
 580 <p><tt>DW_TAG_pointer_type</tt>,<tt>DW_TAG_reference_type</tt>,
 581    <tt>DW_TAG_const_type</tt>, <tt>DW_TAG_volatile_type</tt>
 582    and <tt>DW_TAG_restrict_type</tt> are used to qualify
 583    the <a href="#format_derived_type">derived type</a>. </p>
 584
 585 <p><a href="#format_derived_type">Derived type</a> location can be determined
 586    from the compile unit and line number.  The size, alignment and offset are
 587    expressed in bits and can be 64 bit values.  The alignment is used to round
 588    the offset when embedded in a <a href="#format_composite_type">composite
 589    type</a> (example to keep float doubles on 64 bit boundaries.) The offset is
 590    the bit offset if embedded in a <a href="#format_composite_type">composite
 591    type</a>.</p>
 592
 593 <p>Note that the <tt>void *</tt> type is expressed as a type derived from NULL.
 594 </p>
 595
 596 </div>
 597
 598 <!-- ======================================================================= -->
 599 <div class="doc_subsubsection">
 600   <a name="format_composite_type">Composite type descriptors</a>
 601 </div>
 602
 603 <div class="doc_text">
 604
 605 <div class="doc_code">
 606 <pre>
 607 !6 = metadata !{
 608   i32,      ;; Tag (see below)
 609   metadata, ;; Reference to context
 610   metadata, ;; Name (may be "" for anonymous types)
 611   metadata, ;; Reference to file where defined (may be NULL)
 612   i32,      ;; Line number where defined (may be 0)
 613   i64,      ;; Size in bits
 614   i64,      ;; Alignment in bits
 615   i64,      ;; Offset in bits
 616   i32,      ;; Flags
 617   metadata, ;; Reference to type derived from
 618   metadata, ;; Reference to array of member descriptors
 619   i32       ;; Runtime languages
 620 }
 621 </pre>
 622 </div>
 623
 624 <p>These descriptors are used to define types that are composed of 0 or more
 625 elements.  The value of the tag varies depending on the meaning.  The following
 626 are possible tag values:</p>
 627
 628 <div class="doc_code">
 629 <pre>
 630 DW_TAG_array_type       = 1
 631 DW_TAG_enumeration_type = 4
 632 DW_TAG_structure_type   = 19
 633 DW_TAG_union_type       = 23
 634 DW_TAG_vector_type      = 259
 635 DW_TAG_subroutine_type  = 21
 636 DW_TAG_inheritance      = 28
 637 </pre>
 638 </div>
 639
 640 <p>The vector flag indicates that an array type is a native packed vector.</p>
 641
 642 <p>The members of array types (tag = <tt>DW_TAG_array_type</tt>) or vector types
 643    (tag = <tt>DW_TAG_vector_type</tt>) are <a href="#format_subrange">subrange
 644    descriptors</a>, each representing the range of subscripts at that level of
 645    indexing.</p>
 646
 647 <p>The members of enumeration types (tag = <tt>DW_TAG_enumeration_type</tt>) are
 648    <a href="#format_enumeration">enumerator descriptors</a>, each representing
 649    the definition of enumeration value for the set.</p>
 650
 651 <p>The members of structure (tag = <tt>DW_TAG_structure_type</tt>) or union (tag
 652    = <tt>DW_TAG_union_type</tt>) types are any one of
 653    the <a href="#format_basic_type">basic</a>,
 654    <a href="#format_derived_type">derived</a>
 655    or <a href="#format_composite_type">composite</a> type descriptors, each
 656    representing a field member of the structure or union.</p>
 657
 658 <p>For C++ classes (tag = <tt>DW_TAG_structure_type</tt>), member descriptors
 659    provide information about base classes, static members and member
 660    functions. If a member is a <a href="#format_derived_type">derived type
 661    descriptor</a> and has a tag of <tt>DW_TAG_inheritance</tt>, then the type
 662    represents a base class. If the member of is
 663    a <a href="#format_global_variables">global variable descriptor</a> then it
 664    represents a static member.  And, if the member is
 665    a <a href="#format_subprograms">subprogram descriptor</a> then it represents
 666    a member function.  For static members and member
 667    functions, <tt>getName()</tt> returns the members link or the C++ mangled
 668    name.  <tt>getDisplayName()</tt> the simplied version of the name.</p>
 669
 670 <p>The first member of subroutine (tag = <tt>DW_TAG_subroutine_type</tt>) type
 671    elements is the return type for the subroutine.  The remaining elements are
 672    the formal arguments to the subroutine.</p>
 673
 674 <p><a href="#format_composite_type">Composite type</a> location can be
 675    determined from the compile unit and line number.  The size, alignment and
 676    offset are expressed in bits and can be 64 bit values.  The alignment is used
 677    to round the offset when embedded in
 678    a <a href="#format_composite_type">composite type</a> (as an example, to keep
 679    float doubles on 64 bit boundaries.) The offset is the bit offset if embedded
 680    in a <a href="#format_composite_type">composite type</a>.</p>
 681
 682 </div>
 683
 684 <!-- ======================================================================= -->
 685 <div class="doc_subsubsection">
 686   <a name="format_subrange">Subrange descriptors</a>
 687 </div>
 688
 689 <div class="doc_text">
 690
 691 <div class="doc_code">
 692 <pre>
 693 !42 = metadata !{
 694   i32,    ;; Tag = 33 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_subrange_type)
 695   i64,    ;; Low value
 696   i64     ;; High value
 697 }
 698 </pre>
 699 </div>
 700
 701 <p>These descriptors are used to define ranges of array subscripts for an array
 702    <a href="#format_composite_type">composite type</a>.  The low value defines
 703    the lower bounds typically zero for C/C++.  The high value is the upper
 704    bounds.  Values are 64 bit.  High - low + 1 is the size of the array.  If low
 705    == high the array will be unbounded.</p>
 706
 707 </div>
 708
 709 <!-- ======================================================================= -->
 710 <div class="doc_subsubsection">
 711   <a name="format_enumeration">Enumerator descriptors</a>
 712 </div>
 713
 714 <div class="doc_text">
 715
 716 <div class="doc_code">
 717 <pre>
 718 !6 = metadata !{
 719   i32,      ;; Tag = 40 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
 720             ;; (DW_TAG_enumerator)
 721   metadata, ;; Name
 722   i64       ;; Value
 723 }
 724 </pre>
 725 </div>
 726
 727 <p>These descriptors are used to define members of an
 728    enumeration <a href="#format_composite_type">composite type</a>, it
 729    associates the name to the value.</p>
 730
 731 </div>
 732
 733 <!-- ======================================================================= -->
 734 <div class="doc_subsubsection">
 735   <a name="format_variables">Local variables</a>
 736 </div>
 737
 738 <div class="doc_text">
 739
 740 <div class="doc_code">
 741 <pre>
 742 !7 = metadata !{
 743   i32,      ;; Tag (see below)
 744   metadata, ;; Context
 745   metadata, ;; Name
 746   metadata, ;; Reference to file where defined
 747   i32,      ;; 24 bit - Line number where defined
 748             ;; 8 bit - Argument number. 1 indicates 1st argument.
 749   metadata  ;; Type descriptor
 750 }
 751 </pre>
 752 </div>
 753
 754 <p>These descriptors are used to define variables local to a sub program.  The
 755    value of the tag depends on the usage of the variable:</p>
 756
 757 <div class="doc_code">
 758 <pre>
 759 DW_TAG_auto_variable   = 256
 760 DW_TAG_arg_variable    = 257
 761 DW_TAG_return_variable = 258
 762 </pre>
 763 </div>
 764
 765 <p>An auto variable is any variable declared in the body of the function.  An
 766    argument variable is any variable that appears as a formal argument to the
 767    function.  A return variable is used to track the result of a function and
 768    has no source correspondent.</p>
 769
 770 <p>The context is either the subprogram or block where the variable is defined.
 771    Name the source variable name.  Compile unit and line indicate where the
 772    variable was defined. Type descriptor defines the declared type of the
 773    variable.</p>
 774
 775 </div>
 776
 777 <!-- ======================================================================= -->
 778 <div class="doc_subsection">
 779   <a name="format_common_intrinsics">Debugger intrinsic functions</a>
 780 </div>
 781
 782 <div class="doc_text">
 783
 784 <p>LLVM uses several intrinsic functions (name prefixed with "llvm.dbg") to
 785    provide debug information at various points in generated code.</p>
 786
 787 </div>
 788
 789 <!-- ======================================================================= -->
 790 <div class="doc_subsubsection">
 791   <a name="format_common_declare">llvm.dbg.declare</a>
 792 </div>
 793
 794 <div class="doc_text">
 795 <pre>
 796   void %<a href="#format_common_declare">llvm.dbg.declare</a>(metadata, metadata)
 797 </pre>
 798
 799 <p>This intrinsic provides information about a local element (ex. variable.) The
 800    first argument is metadata holding alloca for the variable.</tt>. The
 801    second argument is metadata containing description of the variable. </p>
 802 </div>
 803
 804 <!-- ======================================================================= -->
 805 <div class="doc_subsubsection">
 806   <a name="format_common_value">llvm.dbg.value</a>
 807 </div>
 808
 809 <div class="doc_text">
 810 <pre>
 811   void %<a href="#format_common_value">llvm.dbg.value</a>(metadata, i64, metadata)
 812 </pre>
 813
 814 <p>This intrinsic provides information when a user source variable is set to a
 815    new value.  The first argument is the new value (wrapped as metadata).  The
 816    second argument is the offset in the user source variable where the new value
 817    is written.  The third argument is metadata containing description of the
 818    user source variable. </p>
 819 </div>
 820
 821 <!-- ======================================================================= -->
 822 <div class="doc_subsection">
 823   <a name="format_common_lifetime">Object lifetimes and scoping</a>
 824 </div>
 825
 826 <div class="doc_text">
 827 <p>In many languages, the local variables in functions can have their lifetimes
 828    or scopes limited to a subset of a function.  In the C family of languages,
 829    for example, variables are only live (readable and writable) within the
 830    source block that they are defined in.  In functional languages, values are
 831    only readable after they have been defined.  Though this is a very obvious
 832    concept, it is non-trivial to model in LLVM, because it has no notion of
 833    scoping in this sense, and does not want to be tied to a language's scoping
 834    rules.</p>
 835
 836 <p>In order to handle this, the LLVM debug format uses the metadata attached to
 837    llvm instructions to encode line number and scoping information. Consider
 838    the following C fragment, for example:</p>
 839
 840 <div class="doc_code">
 841 <pre>
 842 1.  void foo() {
 843 2.    int X = 21;
 844 3.    int Y = 22;
 845 4.    {
 846 5.      int Z = 23;
 847 6.      Z = X;
 848 7.    }
 849 8.    X = Y;
 850 9.  }
 851 </pre>
 852 </div>
 853
 854 <p>Compiled to LLVM, this function would be represented like this:</p>
 855
 856 <div class="doc_code">
 857 <pre>
 858 define void @foo() nounwind ssp {
 859 entry:
 860   %X = alloca i32, align 4                        ; &lt;i32*&gt; [#uses=4]
 861   %Y = alloca i32, align 4                        ; &lt;i32*&gt; [#uses=4]
 862   %Z = alloca i32, align 4                        ; &lt;i32*&gt; [#uses=3]
 863   %0 = bitcast i32* %X to {}*                     ; &lt;{}*&gt; [#uses=1]
 864   call void @llvm.dbg.declare(metadata !{i32 * %X}, metadata !0), !dbg !7
 865   store i32 21, i32* %X, !dbg !8
 866   %1 = bitcast i32* %Y to {}*                     ; &lt;{}*&gt; [#uses=1]
 867   call void @llvm.dbg.declare(metadata !{i32 * %Y}, metadata !9), !dbg !10
 868   store i32 22, i32* %Y, !dbg !11
 869   %2 = bitcast i32* %Z to {}*                     ; &lt;{}*&gt; [#uses=1]
 870   call void @llvm.dbg.declare(metadata !{i32 * %Z}, metadata !12), !dbg !14
 871   store i32 23, i32* %Z, !dbg !15
 872   %tmp = load i32* %X, !dbg !16                   ; &lt;i32&gt; [#uses=1]
 873   %tmp1 = load i32* %Y, !dbg !16                  ; &lt;i32&gt; [#uses=1]
 874   %add = add nsw i32 %tmp, %tmp1, !dbg !16        ; &lt;i32&gt; [#uses=1]
 875   store i32 %add, i32* %Z, !dbg !16
 876   %tmp2 = load i32* %Y, !dbg !17                  ; &lt;i32&gt; [#uses=1]
 877   store i32 %tmp2, i32* %X, !dbg !17
 878   ret void, !dbg !18
 879 }
 880
 881 declare void @llvm.dbg.declare(metadata, metadata) nounwind readnone
 882
 883 !0 = metadata !{i32 459008, metadata !1, metadata !"X",
 884                 metadata !3, i32 2, metadata !6}; [ DW_TAG_auto_variable ]
 885 !1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ]
 886 !2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo", metadata !"foo",
 887                metadata !"foo", metadata !3, i32 1, metadata !4,
 888                i1 false, i1 true}; [DW_TAG_subprogram ]
 889 !3 = metadata !{i32 458769, i32 0, i32 12, metadata !"foo.c",
 890                 metadata !"/private/tmp", metadata !"clang 1.1", i1 true,
 891                 i1 false, metadata !"", i32 0}; [DW_TAG_compile_unit ]
 892 !4 = metadata !{i32 458773, metadata !3, metadata !"", null, i32 0, i64 0, i64 0,
 893                 i64 0, i32 0, null, metadata !5, i32 0}; [DW_TAG_subroutine_type ]
 894 !5 = metadata !{null}
 895 !6 = metadata !{i32 458788, metadata !3, metadata !"int", metadata !3, i32 0,
 896                 i64 32, i64 32, i64 0, i32 0, i32 5}; [DW_TAG_base_type ]
 897 !7 = metadata !{i32 2, i32 7, metadata !1, null}
 898 !8 = metadata !{i32 2, i32 3, metadata !1, null}
 899 !9 = metadata !{i32 459008, metadata !1, metadata !"Y", metadata !3, i32 3,
 900                 metadata !6}; [ DW_TAG_auto_variable ]
 901 !10 = metadata !{i32 3, i32 7, metadata !1, null}
 902 !11 = metadata !{i32 3, i32 3, metadata !1, null}
 903 !12 = metadata !{i32 459008, metadata !13, metadata !"Z", metadata !3, i32 5,
 904                  metadata !6}; [ DW_TAG_auto_variable ]
 905 !13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ]
 906 !14 = metadata !{i32 5, i32 9, metadata !13, null}
 907 !15 = metadata !{i32 5, i32 5, metadata !13, null}
 908 !16 = metadata !{i32 6, i32 5, metadata !13, null}
 909 !17 = metadata !{i32 8, i32 3, metadata !1, null}
 910 !18 = metadata !{i32 9, i32 1, metadata !2, null}
 911 </pre>
 912 </div>
 913
 914 <p>This example illustrates a few important details about LLVM debugging
 915    information. In particular, it shows how the <tt>llvm.dbg.declare</tt>
 916    intrinsic and location information, which are attached to an instruction,
 917    are applied together to allow a debugger to analyze the relationship between
 918    statements, variable definitions, and the code used to implement the
 919    function.</p>
 920
 921 <div class="doc_code">
 922 <pre>
 923 call void @llvm.dbg.declare(metadata, metadata !0), !dbg !7
 924 </pre>
 925 </div>
 926
 927 <p>The first intrinsic
 928    <tt>%<a href="#format_common_declare">llvm.dbg.declare</a></tt>
 929    encodes debugging information for the variable <tt>X</tt>. The metadata
 930    <tt>!dbg !7</tt> attached to the intrinsic provides scope information for the
 931    variable <tt>X</tt>.</p>
 932
 933 <div class="doc_code">
 934 <pre>
 935 !7 = metadata !{i32 2, i32 7, metadata !1, null}
 936 !1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ]
 937 !2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo",
 938                 metadata !"foo", metadata !"foo", metadata !3, i32 1,
 939                 metadata !4, i1 false, i1 true}; [DW_TAG_subprogram ]
 940 </pre>
 941 </div>
 942
 943 <p>Here <tt>!7</tt> is metadata providing location information. It has four
 944    fields: line number, column number, scope, and original scope. The original
 945    scope represents inline location if this instruction is inlined inside a
 946    caller, and is null otherwise. In this example, scope is encoded by
 947    <tt>!1</tt>. <tt>!1</tt> represents a lexical block inside the scope
 948    <tt>!2</tt>, where <tt>!2</tt> is a
 949    <a href="#format_subprograms">subprogram descriptor</a>. This way the
 950    location information attached to the intrinsics indicates that the
 951    variable <tt>X</tt> is declared at line number 2 at a function level scope in
 952    function <tt>foo</tt>.</p>
 953
 954 <p>Now lets take another example.</p>
 955
 956 <div class="doc_code">
 957 <pre>
 958 call void @llvm.dbg.declare(metadata, metadata !12), !dbg !14
 959 </pre>
 960 </div>
 961
 962 <p>The second intrinsic
 963    <tt>%<a href="#format_common_declare">llvm.dbg.declare</a></tt>
 964    encodes debugging information for variable <tt>Z</tt>. The metadata
 965    <tt>!dbg !14</tt> attached to the intrinsic provides scope information for
 966    the variable <tt>Z</tt>.</p>
 967
 968 <div class="doc_code">
 969 <pre>
 970 !13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ]
 971 !14 = metadata !{i32 5, i32 9, metadata !13, null}
 972 </pre>
 973 </div>
 974
 975 <p>Here <tt>!14</tt> indicates that <tt>Z</tt> is declared at line number 5 and
 976    column number 9 inside of lexical scope <tt>!13</tt>. The lexical scope
 977    itself resides inside of lexical scope <tt>!1</tt> described above.</p>
 978
 979 <p>The scope information attached with each instruction provides a
 980    straightforward way to find instructions covered by a scope.</p>
 981
 982 </div>
 983
 984 <!-- *********************************************************************** -->
 985 <div class="doc_section">
 986   <a name="ccxx_frontend">C/C++ front-end specific debug information</a>
 987 </div>
 988 <!-- *********************************************************************** -->
 989
 990 <div class="doc_text">
 991
 992 <p>The C and C++ front-ends represent information about the program in a format
 993    that is effectively identical
 994    to <a href="http://www.eagercon.com/dwarf/dwarf3std.htm">DWARF 3.0</a> in
 995    terms of information content.  This allows code generators to trivially
 996    support native debuggers by generating standard dwarf information, and
 997    contains enough information for non-dwarf targets to translate it as
 998    needed.</p>
 999
1000 <p>This section describes the forms used to represent C and C++ programs. Other
1001    languages could pattern themselves after this (which itself is tuned to
1002    representing programs in the same way that DWARF 3 does), or they could
1003    choose to provide completely different forms if they don't fit into the DWARF
1004    model.  As support for debugging information gets added to the various LLVM
1005    source-language front-ends, the information used should be documented
1006    here.</p>
1007
1008 <p>The following sections provide examples of various C/C++ constructs and the
1009    debug information that would best describe those constructs.</p>
1010
1011 </div>
1012
1013 <!-- ======================================================================= -->
1014 <div class="doc_subsection">
1015   <a name="ccxx_compile_units">C/C++ source file information</a>
1016 </div>
1017
1018 <div class="doc_text">
1019
1020 <p>Given the source files <tt>MySource.cpp</tt> and <tt>MyHeader.h</tt> located
1021    in the directory <tt>/Users/mine/sources</tt>, the following code:</p>
1022
1023 <div class="doc_code">
1024 <pre>
1025 #include "MyHeader.h"
1026
1027 int main(int argc, char *argv[]) {
1028   return 0;
1029 }
1030 </pre>
1031 </div>
1032
1033 <p>a C/C++ front-end would generate the following descriptors:</p>
1034
1035 <div class="doc_code">
1036 <pre>
1037 ...
1038 ;;
1039 ;; Define the compile unit for the main source file "/Users/mine/sources/MySource.cpp".
1040 ;;
1041 !2 = metadata !{
1042   i32 524305,    ;; Tag
1043   i32 0,         ;; Unused
1044   i32 4,         ;; Language Id
1045   metadata !"MySource.cpp",
1046   metadata !"/Users/mine/sources",
1047   metadata !"4.2.1 (Based on Apple Inc. build 5649) (LLVM build 00)",
1048   i1 true,       ;; Main Compile Unit
1049   i1 false,      ;; Optimized compile unit
1050   metadata !"",  ;; Compiler flags
1051   i32 0}         ;; Runtime version
1052
1053 ;;
1054 ;; Define the file for the file "/Users/mine/sources/MySource.cpp".
1055 ;;
1056 !1 = metadata !{
1057   i32 524329,    ;; Tag
1058   metadata !"MySource.cpp",
1059   metadata !"/Users/mine/sources",
1060   metadata !2    ;; Compile unit
1061 }
1062
1063 ;;
1064 ;; Define the file for the file "/Users/mine/sources/Myheader.h"
1065 ;;
1066 !3 = metadata !{
1067   i32 524329,    ;; Tag
1068   metadata !"Myheader.h"
1069   metadata !"/Users/mine/sources",
1070   metadata !2    ;; Compile unit
1071 }
1072
1073 ...
1074 </pre>
1075 </div>
1076
1077 <p>llvm::Instruction provides easy access to metadata attached with an
1078 instruction. One can extract line number information encoded in LLVM IR
1079 using <tt>Instruction::getMetadata()</tt> and
1080 <tt>DILocation::getLineNumber()</tt>.
1081 <pre>
1082  if (MDNode *N = I->getMetadata("dbg")) {  // Here I is an LLVM instruction
1083    DILocation Loc(N);                      // DILocation is in DebugInfo.h
1084    unsigned Line = Loc.getLineNumber();
1085    StringRef File = Loc.getFilename();
1086    StringRef Dir = Loc.getDirectory();
1087  }
1088 </pre>
1089 </div>
1090
1091 <!-- ======================================================================= -->
1092 <div class="doc_subsection">
1093   <a name="ccxx_global_variable">C/C++ global variable information</a>
1094 </div>
1095
1096 <div class="doc_text">
1097
1098 <p>Given an integer global variable declared as follows:</p>
1099
1100 <div class="doc_code">
1101 <pre>
1102 int MyGlobal = 100;
1103 </pre>
1104 </div>
1105
1106 <p>a C/C++ front-end would generate the following descriptors:</p>
1107
1108 <div class="doc_code">
1109 <pre>
1110 ;;
1111 ;; Define the global itself.
1112 ;;
1113 %MyGlobal = global int 100
1114 ...
1115 ;;
1116 ;; List of debug info of globals
1117 ;;
1118 !llvm.dbg.gv = !{!0}
1119
1120 ;;
1121 ;; Define the global variable descriptor.  Note the reference to the global
1122 ;; variable anchor and the global variable itself.
1123 ;;
1124 !0 = metadata !{
1125   i32 524340,              ;; Tag
1126   i32 0,                   ;; Unused
1127   metadata !1,             ;; Context
1128   metadata !"MyGlobal",    ;; Name
1129   metadata !"MyGlobal",    ;; Display Name
1130   metadata !"MyGlobal",    ;; Linkage Name
1131   metadata !3,             ;; Compile Unit
1132   i32 1,                   ;; Line Number
1133   metadata !4,             ;; Type
1134   i1 false,                ;; Is a local variable
1135   i1 true,                 ;; Is this a definition
1136   i32* @MyGlobal           ;; The global variable
1137 }
1138
1139 ;;
1140 ;; Define the basic type of 32 bit signed integer.  Note that since int is an
1141 ;; intrinsic type the source file is NULL and line 0.
1142 ;;
1143 !4 = metadata !{
1144   i32 524324,              ;; Tag
1145   metadata !1,             ;; Context
1146   metadata !"int",         ;; Name
1147   metadata !1,             ;; File
1148   i32 0,                   ;; Line number
1149   i64 32,                  ;; Size in Bits
1150   i64 32,                  ;; Align in Bits
1151   i64 0,                   ;; Offset in Bits
1152   i32 0,                   ;; Flags
1153   i32 5                    ;; Encoding
1154 }
1155
1156 </pre>
1157 </div>
1158
1159 </div>
1160
1161 <!-- ======================================================================= -->
1162 <div class="doc_subsection">
1163   <a name="ccxx_subprogram">C/C++ function information</a>
1164 </div>
1165
1166 <div class="doc_text">
1167
1168 <p>Given a function declared as follows:</p>
1169
1170 <div class="doc_code">
1171 <pre>
1172 int main(int argc, char *argv[]) {
1173   return 0;
1174 }
1175 </pre>
1176 </div>
1177
1178 <p>a C/C++ front-end would generate the following descriptors:</p>
1179
1180 <div class="doc_code">
1181 <pre>
1182 ;;
1183 ;; Define the anchor for subprograms.  Note that the second field of the
1184 ;; anchor is 46, which is the same as the tag for subprograms
1185 ;; (46 = DW_TAG_subprogram.)
1186 ;;
1187 !6 = metadata !{
1188   i32 524334,        ;; Tag
1189   i32 0,             ;; Unused
1190   metadata !1,       ;; Context
1191   metadata !"main",  ;; Name
1192   metadata !"main",  ;; Display name
1193   metadata !"main",  ;; Linkage name
1194   metadata !1,       ;; File
1195   i32 1,             ;; Line number
1196   metadata !4,       ;; Type
1197   i1 false,          ;; Is local
1198   i1 true            ;; Is definition
1199 }
1200 ;;
1201 ;; Define the subprogram itself.
1202 ;;
1203 define i32 @main(i32 %argc, i8** %argv) {
1204 ...
1205 }
1206 </pre>
1207 </div>
1208
1209 </div>
1210
1211 <!-- ======================================================================= -->
1212 <div class="doc_subsection">
1213   <a name="ccxx_basic_types">C/C++ basic types</a>
1214 </div>
1215
1216 <div class="doc_text">
1217
1218 <p>The following are the basic type descriptors for C/C++ core types:</p>
1219
1220 </div>
1221
1222 <!-- ======================================================================= -->
1223 <div class="doc_subsubsection">
1224   <a name="ccxx_basic_type_bool">bool</a>
1225 </div>
1226
1227 <div class="doc_text">
1228
1229 <div class="doc_code">
1230 <pre>
1231 !2 = metadata !{
1232   i32 524324,        ;; Tag
1233   metadata !1,       ;; Context
1234   metadata !"bool",  ;; Name
1235   metadata !1,       ;; File
1236   i32 0,             ;; Line number
1237   i64 8,             ;; Size in Bits
1238   i64 8,             ;; Align in Bits
1239   i64 0,             ;; Offset in Bits
1240   i32 0,             ;; Flags
1241   i32 2              ;; Encoding
1242 }
1243 </pre>
1244 </div>
1245
1246 </div>
1247
1248 <!-- ======================================================================= -->
1249 <div class="doc_subsubsection">
1250   <a name="ccxx_basic_char">char</a>
1251 </div>
1252
1253 <div class="doc_text">
1254
1255 <div class="doc_code">
1256 <pre>
1257 !2 = metadata !{
1258   i32 524324,        ;; Tag
1259   metadata !1,       ;; Context
1260   metadata !"char",  ;; Name
1261   metadata !1,       ;; File
1262   i32 0,             ;; Line number
1263   i64 8,             ;; Size in Bits
1264   i64 8,             ;; Align in Bits
1265   i64 0,             ;; Offset in Bits
1266   i32 0,             ;; Flags
1267   i32 6              ;; Encoding
1268 }
1269 </pre>
1270 </div>
1271
1272 </div>
1273
1274 <!-- ======================================================================= -->
1275 <div class="doc_subsubsection">
1276   <a name="ccxx_basic_unsigned_char">unsigned char</a>
1277 </div>
1278
1279 <div class="doc_text">
1280
1281 <div class="doc_code">
1282 <pre>
1283 !2 = metadata !{
1284   i32 524324,        ;; Tag
1285   metadata !1,       ;; Context
1286   metadata !"unsigned char",
1287   metadata !1,       ;; File
1288   i32 0,             ;; Line number
1289   i64 8,             ;; Size in Bits
1290   i64 8,             ;; Align in Bits
1291   i64 0,             ;; Offset in Bits
1292   i32 0,             ;; Flags
1293   i32 8              ;; Encoding
1294 }
1295 </pre>
1296 </div>
1297
1298 </div>
1299
1300 <!-- ======================================================================= -->
1301 <div class="doc_subsubsection">
1302   <a name="ccxx_basic_short">short</a>
1303 </div>
1304
1305 <div class="doc_text">
1306
1307 <div class="doc_code">
1308 <pre>
1309 !2 = metadata !{
1310   i32 524324,        ;; Tag
1311   metadata !1,       ;; Context
1312   metadata !"short int",
1313   metadata !1,       ;; File
1314   i32 0,             ;; Line number
1315   i64 16,            ;; Size in Bits
1316   i64 16,            ;; Align in Bits
1317   i64 0,             ;; Offset in Bits
1318   i32 0,             ;; Flags
1319   i32 5              ;; Encoding
1320 }
1321 </pre>
1322 </div>
1323
1324 </div>
1325
1326 <!-- ======================================================================= -->
1327 <div class="doc_subsubsection">
1328   <a name="ccxx_basic_unsigned_short">unsigned short</a>
1329 </div>
1330
1331 <div class="doc_text">
1332
1333 <div class="doc_code">
1334 <pre>
1335 !2 = metadata !{
1336   i32 524324,        ;; Tag
1337   metadata !1,       ;; Context
1338   metadata !"short unsigned int",
1339   metadata !1,       ;; File
1340   i32 0,             ;; Line number
1341   i64 16,            ;; Size in Bits
1342   i64 16,            ;; Align in Bits
1343   i64 0,             ;; Offset in Bits
1344   i32 0,             ;; Flags
1345   i32 7              ;; Encoding
1346 }
1347 </pre>
1348 </div>
1349
1350 </div>
1351
1352 <!-- ======================================================================= -->
1353 <div class="doc_subsubsection">
1354   <a name="ccxx_basic_int">int</a>
1355 </div>
1356
1357 <div class="doc_text">
1358
1359 <div class="doc_code">
1360 <pre>
1361 !2 = metadata !{
1362   i32 524324,        ;; Tag
1363   metadata !1,       ;; Context
1364   metadata !"int",   ;; Name
1365   metadata !1,       ;; File
1366   i32 0,             ;; Line number
1367   i64 32,            ;; Size in Bits
1368   i64 32,            ;; Align in Bits
1369   i64 0,             ;; Offset in Bits
1370   i32 0,             ;; Flags
1371   i32 5              ;; Encoding
1372 }
1373 </pre></div>
1374
1375 </div>
1376
1377 <!-- ======================================================================= -->
1378 <div class="doc_subsubsection">
1379   <a name="ccxx_basic_unsigned_int">unsigned int</a>
1380 </div>
1381
1382 <div class="doc_text">
1383
1384 <div class="doc_code">
1385 <pre>
1386 !2 = metadata !{
1387   i32 524324,        ;; Tag
1388   metadata !1,       ;; Context
1389   metadata !"unsigned int",
1390   metadata !1,       ;; File
1391   i32 0,             ;; Line number
1392   i64 32,            ;; Size in Bits
1393   i64 32,            ;; Align in Bits
1394   i64 0,             ;; Offset in Bits
1395   i32 0,             ;; Flags
1396   i32 7              ;; Encoding
1397 }
1398 </pre>
1399 </div>
1400
1401 </div>
1402
1403 <!-- ======================================================================= -->
1404 <div class="doc_subsubsection">
1405   <a name="ccxx_basic_long_long">long long</a>
1406 </div>
1407
1408 <div class="doc_text">
1409
1410 <div class="doc_code">
1411 <pre>
1412 !2 = metadata !{
1413   i32 524324,        ;; Tag
1414   metadata !1,       ;; Context
1415   metadata !"long long int",
1416   metadata !1,       ;; File
1417   i32 0,             ;; Line number
1418   i64 64,            ;; Size in Bits
1419   i64 64,            ;; Align in Bits
1420   i64 0,             ;; Offset in Bits
1421   i32 0,             ;; Flags
1422   i32 5              ;; Encoding
1423 }
1424 </pre>
1425 </div>
1426
1427 </div>
1428
1429 <!-- ======================================================================= -->
1430 <div class="doc_subsubsection">
1431   <a name="ccxx_basic_unsigned_long_long">unsigned long long</a>
1432 </div>
1433
1434 <div class="doc_text">
1435
1436 <div class="doc_code">
1437 <pre>
1438 !2 = metadata !{
1439   i32 524324,        ;; Tag
1440   metadata !1,       ;; Context
1441   metadata !"long long unsigned int",
1442   metadata !1,       ;; File
1443   i32 0,             ;; Line number
1444   i64 64,            ;; Size in Bits
1445   i64 64,            ;; Align in Bits
1446   i64 0,             ;; Offset in Bits
1447   i32 0,             ;; Flags
1448   i32 7              ;; Encoding
1449 }
1450 </pre>
1451 </div>
1452
1453 </div>
1454
1455 <!-- ======================================================================= -->
1456 <div class="doc_subsubsection">
1457   <a name="ccxx_basic_float">float</a>
1458 </div>
1459
1460 <div class="doc_text">
1461
1462 <div class="doc_code">
1463 <pre>
1464 !2 = metadata !{
1465   i32 524324,        ;; Tag
1466   metadata !1,       ;; Context
1467   metadata !"float",
1468   metadata !1,       ;; File
1469   i32 0,             ;; Line number
1470   i64 32,            ;; Size in Bits
1471   i64 32,            ;; Align in Bits
1472   i64 0,             ;; Offset in Bits
1473   i32 0,             ;; Flags
1474   i32 4              ;; Encoding
1475 }
1476 </pre>
1477 </div>
1478
1479 </div>
1480
1481 <!-- ======================================================================= -->
1482 <div class="doc_subsubsection">
1483   <a name="ccxx_basic_double">double</a>
1484 </div>
1485
1486 <div class="doc_text">
1487
1488 <div class="doc_code">
1489 <pre>
1490 !2 = metadata !{
1491   i32 524324,        ;; Tag
1492   metadata !1,       ;; Context
1493   metadata !"double",;; Name
1494   metadata !1,       ;; File
1495   i32 0,             ;; Line number
1496   i64 64,            ;; Size in Bits
1497   i64 64,            ;; Align in Bits
1498   i64 0,             ;; Offset in Bits
1499   i32 0,             ;; Flags
1500   i32 4              ;; Encoding
1501 }
1502 </pre>
1503 </div>
1504
1505 </div>
1506
1507 <!-- ======================================================================= -->
1508 <div class="doc_subsection">
1509   <a name="ccxx_derived_types">C/C++ derived types</a>
1510 </div>
1511
1512 <div class="doc_text">
1513
1514 <p>Given the following as an example of C/C++ derived type:</p>
1515
1516 <div class="doc_code">
1517 <pre>
1518 typedef const int *IntPtr;
1519 </pre>
1520 </div>
1521
1522 <p>a C/C++ front-end would generate the following descriptors:</p>
1523
1524 <div class="doc_code">
1525 <pre>
1526 ;;
1527 ;; Define the typedef "IntPtr".
1528 ;;
1529 !2 = metadata !{
1530   i32 524310,          ;; Tag
1531   metadata !1,         ;; Context
1532   metadata !"IntPtr",  ;; Name
1533   metadata !3,         ;; File
1534   i32 0,               ;; Line number
1535   i64 0,               ;; Size in bits
1536   i64 0,               ;; Align in bits
1537   i64 0,               ;; Offset in bits
1538   i32 0,               ;; Flags
1539   metadata !4          ;; Derived From type
1540 }
1541
1542 ;;
1543 ;; Define the pointer type.
1544 ;;
1545 !4 = metadata !{
1546   i32 524303,          ;; Tag
1547   metadata !1,         ;; Context
1548   metadata !"",        ;; Name
1549   metadata !1,         ;; File
1550   i32 0,               ;; Line number
1551   i64 64,              ;; Size in bits
1552   i64 64,              ;; Align in bits
1553   i64 0,               ;; Offset in bits
1554   i32 0,               ;; Flags
1555   metadata !5          ;; Derived From type
1556 }
1557 ;;
1558 ;; Define the const type.
1559 ;;
1560 !5 = metadata !{
1561   i32 524326,          ;; Tag
1562   metadata !1,         ;; Context
1563   metadata !"",        ;; Name
1564   metadata !1,         ;; File
1565   i32 0,               ;; Line number
1566   i64 32,              ;; Size in bits
1567   i64 32,              ;; Align in bits
1568   i64 0,               ;; Offset in bits
1569   i32 0,               ;; Flags
1570   metadata !6          ;; Derived From type
1571 }
1572 ;;
1573 ;; Define the int type.
1574 ;;
1575 !6 = metadata !{
1576   i32 524324,          ;; Tag
1577   metadata !1,         ;; Context
1578   metadata !"int",     ;; Name
1579   metadata !1,         ;; File
1580   i32 0,               ;; Line number
1581   i64 32,              ;; Size in bits
1582   i64 32,              ;; Align in bits
1583   i64 0,               ;; Offset in bits
1584   i32 0,               ;; Flags
1585   5                    ;; Encoding
1586 }
1587 </pre>
1588 </div>
1589
1590 </div>
1591
1592 <!-- ======================================================================= -->
1593 <div class="doc_subsection">
1594   <a name="ccxx_composite_types">C/C++ struct/union types</a>
1595 </div>
1596
1597 <div class="doc_text">
1598
1599 <p>Given the following as an example of C/C++ struct type:</p>
1600
1601 <div class="doc_code">
1602 <pre>
1603 struct Color {
1604   unsigned Red;
1605   unsigned Green;
1606   unsigned Blue;
1607 };
1608 </pre>
1609 </div>
1610
1611 <p>a C/C++ front-end would generate the following descriptors:</p>
1612
1613 <div class="doc_code">
1614 <pre>
1615 ;;
1616 ;; Define basic type for unsigned int.
1617 ;;
1618 !5 = metadata !{
1619   i32 524324,        ;; Tag
1620   metadata !1,       ;; Context
1621   metadata !"unsigned int",
1622   metadata !1,       ;; File
1623   i32 0,             ;; Line number
1624   i64 32,            ;; Size in Bits
1625   i64 32,            ;; Align in Bits
1626   i64 0,             ;; Offset in Bits
1627   i32 0,             ;; Flags
1628   i32 7              ;; Encoding
1629 }
1630 ;;
1631 ;; Define composite type for struct Color.
1632 ;;
1633 !2 = metadata !{
1634   i32 524307,        ;; Tag
1635   metadata !1,       ;; Context
1636   metadata !"Color", ;; Name
1637   metadata !1,       ;; Compile unit
1638   i32 1,             ;; Line number
1639   i64 96,            ;; Size in bits
1640   i64 32,            ;; Align in bits
1641   i64 0,             ;; Offset in bits
1642   i32 0,             ;; Flags
1643   null,              ;; Derived From
1644   metadata !3,       ;; Elements
1645   i32 0              ;; Runtime Language
1646 }
1647
1648 ;;
1649 ;; Define the Red field.
1650 ;;
1651 !4 = metadata !{
1652   i32 524301,        ;; Tag
1653   metadata !1,       ;; Context
1654   metadata !"Red",   ;; Name
1655   metadata !1,       ;; File
1656   i32 2,             ;; Line number
1657   i64 32,            ;; Size in bits
1658   i64 32,            ;; Align in bits
1659   i64 0,             ;; Offset in bits
1660   i32 0,             ;; Flags
1661   metadata !5        ;; Derived From type
1662 }
1663
1664 ;;
1665 ;; Define the Green field.
1666 ;;
1667 !6 = metadata !{
1668   i32 524301,        ;; Tag
1669   metadata !1,       ;; Context
1670   metadata !"Green", ;; Name
1671   metadata !1,       ;; File
1672   i32 3,             ;; Line number
1673   i64 32,            ;; Size in bits
1674   i64 32,            ;; Align in bits
1675   i64 32,             ;; Offset in bits
1676   i32 0,             ;; Flags
1677   metadata !5        ;; Derived From type
1678 }
1679
1680 ;;
1681 ;; Define the Blue field.
1682 ;;
1683 !7 = metadata !{
1684   i32 524301,        ;; Tag
1685   metadata !1,       ;; Context
1686   metadata !"Blue",  ;; Name
1687   metadata !1,       ;; File
1688   i32 4,             ;; Line number
1689   i64 32,            ;; Size in bits
1690   i64 32,            ;; Align in bits
1691   i64 64,             ;; Offset in bits
1692   i32 0,             ;; Flags
1693   metadata !5        ;; Derived From type
1694 }
1695
1696 ;;
1697 ;; Define the array of fields used by the composite type Color.
1698 ;;
1699 !3 = metadata !{metadata !4, metadata !6, metadata !7}
1700 </pre>
1701 </div>
1702
1703 </div>
1704
1705 <!-- ======================================================================= -->
1706 <div class="doc_subsection">
1707   <a name="ccxx_enumeration_types">C/C++ enumeration types</a>
1708 </div>
1709
1710 <div class="doc_text">
1711
1712 <p>Given the following as an example of C/C++ enumeration type:</p>
1713
1714 <div class="doc_code">
1715 <pre>
1716 enum Trees {
1717   Spruce = 100,
1718   Oak = 200,
1719   Maple = 300
1720 };
1721 </pre>
1722 </div>
1723
1724 <p>a C/C++ front-end would generate the following descriptors:</p>
1725
1726 <div class="doc_code">
1727 <pre>
1728 ;;
1729 ;; Define composite type for enum Trees
1730 ;;
1731 !2 = metadata !{
1732   i32 524292,        ;; Tag
1733   metadata !1,       ;; Context
1734   metadata !"Trees", ;; Name
1735   metadata !1,       ;; File
1736   i32 1,             ;; Line number
1737   i64 32,            ;; Size in bits
1738   i64 32,            ;; Align in bits
1739   i64 0,             ;; Offset in bits
1740   i32 0,             ;; Flags
1741   null,              ;; Derived From type
1742   metadata !3,       ;; Elements
1743   i32 0              ;; Runtime language
1744 }
1745
1746 ;;
1747 ;; Define the array of enumerators used by composite type Trees.
1748 ;;
1749 !3 = metadata !{metadata !4, metadata !5, metadata !6}
1750
1751 ;;
1752 ;; Define Spruce enumerator.
1753 ;;
1754 !4 = metadata !{i32 524328, metadata !"Spruce", i64 100}
1755
1756 ;;
1757 ;; Define Oak enumerator.
1758 ;;
1759 !5 = metadata !{i32 524328, metadata !"Oak", i64 200}
1760
1761 ;;
1762 ;; Define Maple enumerator.
1763 ;;
1764 !6 = metadata !{i32 524328, metadata !"Maple", i64 300}
1765
1766 </pre>
1767 </div>
1768
1769 </div>
1770
1771 <!-- *********************************************************************** -->
1772
1773 <hr>
1774 <address>
1775   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
1776   src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
1777   <a href="http://validator.w3.org/check/referer"><img
1778   src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
1779
1780   <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
1781   <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
1782   Last modified: $Date$
1783 </address>
1784
1785 </body>
1786 </html>