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