docs/SourceLevelDebugging.html

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