docs/SourceLevelDebugging.html

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