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