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