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