docs/SourceLevelDebugging.html

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