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