docs/SourceLevelDebugging.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   2                       "http://www.w3.org/TR/html4/strict.dtd">
   3 <html>
   4 <head>
   5   <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   6   <title>Source Level Debugging with LLVM</title>
   7   <link rel="stylesheet" href="llvm.css" type="text/css">
   8 </head>
   9 <body>
  10
  11 <div class="doc_title">Source Level Debugging with LLVM</div>
  12
  13 <table class="layout" style="width:100%">
  14   <tr class="layout">
  15     <td class="left">
  16 <ul>
  17   <li><a href="#introduction">Introduction</a>
  18   <ol>
  19     <li><a href="#phil">Philosophy behind LLVM debugging information</a></li>
  20     <li><a href="#consumers">Debug information consumers</a></li>
  21     <li><a href="#debugopt">Debugging optimized code</a></li>
  22   </ol></li>
  23   <li><a href="#format">Debugging information format</a>
  24   <ol>
  25     <li><a href="#debug_info_descriptors">Debug information descriptors</a>
  26     <ul>
  27       <li><a href="#format_compile_units">Compile unit descriptors</a></li>
  28       <li><a href="#format_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 <div class="doc_section"><a name="introduction">Introduction</a></div>
  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 <div class="doc_subsection">
  87   <a name="phil">Philosophy behind LLVM debugging information</a>
  88 </div>
  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 <div class="doc_subsection">
 137   <a name="consumers">Debug information consumers</a>
 138 </div>
 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 <div class="doc_subsection">
 161   <a name="debugopt">Debugging optimized code</a>
 162 </div>
 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 <div class="doc_section">
 231   <a name="format">Debugging information format</a>
 232 </div>
 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 <div class="doc_subsection">
 272   <a name="debug_info_descriptors">Debug information descriptors</a>
 273 </div>
 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 <div class="doc_subsubsection">
 319   <a name="format_compile_units">Compile unit descriptors</a>
 320 </div>
 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 <div class="doc_subsubsection">
 355   <a name="format_files">File descriptors</a>
 356 </div>
 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 <div class="doc_subsubsection">
 384   <a name="format_global_variables">Global variable descriptors</a>
 385 </div>
 386
 387 <div class="doc_text">
 388
 389 <div class="doc_code">
 390 <pre>
 391 !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 <div class="doc_subsubsection">
 417   <a name="format_subprograms">Subprogram descriptors</a>
 418 </div>
 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 <div class="doc_subsubsection">
 460   <a name="format_blocks">Block descriptors</a>
 461 </div>
 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 <div class="doc_subsubsection">
 486   <a name="format_basic_type">Basic type descriptors</a>
 487 </div>
 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 <div class="doc_subsubsection">
 538   <a name="format_derived_type">Derived type descriptors</a>
 539 </div>
 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 }
 556 </pre>
 557 </div>
 558
 559 <p>These descriptors are used to define types derived from other types.  The
 560 value of the tag varies depending on the meaning.  The following are possible
 561 tag values:</p>
 562
 563 <div class="doc_code">
 564 <pre>
 565 DW_TAG_formal_parameter = 5
 566 DW_TAG_member           = 13
 567 DW_TAG_pointer_type     = 15
 568 DW_TAG_reference_type   = 16
 569 DW_TAG_typedef          = 22
 570 DW_TAG_const_type       = 38
 571 DW_TAG_volatile_type    = 53
 572 DW_TAG_restrict_type    = 55
 573 </pre>
 574 </div>
 575
 576 <p><tt>DW_TAG_member</tt> is used to define a member of
 577    a <a href="#format_composite_type">composite type</a>
 578    or <a href="#format_subprograms">subprogram</a>.  The type of the member is
 579    the <a href="#format_derived_type">derived
 580    type</a>. <tt>DW_TAG_formal_parameter</tt> is used to define a member which
 581    is a formal argument of a subprogram.</p>
 582
 583 <p><tt>DW_TAG_typedef</tt> is used to provide a name for the derived type.</p>
 584
 585 <p><tt>DW_TAG_pointer_type</tt>,<tt>DW_TAG_reference_type</tt>,
 586    <tt>DW_TAG_const_type</tt>, <tt>DW_TAG_volatile_type</tt>
 587    and <tt>DW_TAG_restrict_type</tt> are used to qualify
 588    the <a href="#format_derived_type">derived type</a>. </p>
 589
 590 <p><a href="#format_derived_type">Derived type</a> location can be determined
 591    from the compile unit and line number.  The size, alignment and offset are
 592    expressed in bits and can be 64 bit values.  The alignment is used to round
 593    the offset when embedded in a <a href="#format_composite_type">composite
 594    type</a> (example to keep float doubles on 64 bit boundaries.) The offset is
 595    the bit offset if embedded in a <a href="#format_composite_type">composite
 596    type</a>.</p>
 597
 598 <p>Note that the <tt>void *</tt> type is expressed as a type derived from NULL.
 599 </p>
 600
 601 </div>
 602
 603 <!-- ======================================================================= -->
 604 <div class="doc_subsubsection">
 605   <a name="format_composite_type">Composite type descriptors</a>
 606 </div>
 607
 608 <div class="doc_text">
 609
 610 <div class="doc_code">
 611 <pre>
 612 !6 = metadata !{
 613   i32,      ;; Tag (see below)
 614   metadata, ;; Reference to context
 615   metadata, ;; Name (may be "" for anonymous types)
 616   metadata, ;; Reference to file where defined (may be NULL)
 617   i32,      ;; Line number where defined (may be 0)
 618   i64,      ;; Size in bits
 619   i64,      ;; Alignment in bits
 620   i64,      ;; Offset in bits
 621   i32,      ;; Flags
 622   metadata, ;; Reference to type derived from
 623   metadata, ;; Reference to array of member descriptors
 624   i32       ;; Runtime languages
 625 }
 626 </pre>
 627 </div>
 628
 629 <p>These descriptors are used to define types that are composed of 0 or more
 630 elements.  The value of the tag varies depending on the meaning.  The following
 631 are possible tag values:</p>
 632
 633 <div class="doc_code">
 634 <pre>
 635 DW_TAG_array_type       = 1
 636 DW_TAG_enumeration_type = 4
 637 DW_TAG_structure_type   = 19
 638 DW_TAG_union_type       = 23
 639 DW_TAG_vector_type      = 259
 640 DW_TAG_subroutine_type  = 21
 641 DW_TAG_inheritance      = 28
 642 </pre>
 643 </div>
 644
 645 <p>The vector flag indicates that an array type is a native packed vector.</p>
 646
 647 <p>The members of array types (tag = <tt>DW_TAG_array_type</tt>) or vector types
 648    (tag = <tt>DW_TAG_vector_type</tt>) are <a href="#format_subrange">subrange
 649    descriptors</a>, each representing the range of subscripts at that level of
 650    indexing.</p>
 651
 652 <p>The members of enumeration types (tag = <tt>DW_TAG_enumeration_type</tt>) are
 653    <a href="#format_enumeration">enumerator descriptors</a>, each representing
 654    the definition of enumeration value for the set. All enumeration type
 655    descriptors are collected by named metadata <tt>!llvm.dbg.enum</tt>.</p>
 656
 657 <p>The members of structure (tag = <tt>DW_TAG_structure_type</tt>) or union (tag
 658    = <tt>DW_TAG_union_type</tt>) types are any one of
 659    the <a href="#format_basic_type">basic</a>,
 660    <a href="#format_derived_type">derived</a>
 661    or <a href="#format_composite_type">composite</a> type descriptors, each
 662    representing a field member of the structure or union.</p>
 663
 664 <p>For C++ classes (tag = <tt>DW_TAG_structure_type</tt>), member descriptors
 665    provide information about base classes, static members and member
 666    functions. If a member is a <a href="#format_derived_type">derived type
 667    descriptor</a> and has a tag of <tt>DW_TAG_inheritance</tt>, then the type
 668    represents a base class. If the member of is
 669    a <a href="#format_global_variables">global variable descriptor</a> then it
 670    represents a static member.  And, if the member is
 671    a <a href="#format_subprograms">subprogram descriptor</a> then it represents
 672    a member function.  For static members and member
 673    functions, <tt>getName()</tt> returns the members link or the C++ mangled
 674    name.  <tt>getDisplayName()</tt> the simplied version of the name.</p>
 675
 676 <p>The first member of subroutine (tag = <tt>DW_TAG_subroutine_type</tt>) type
 677    elements is the return type for the subroutine.  The remaining elements are
 678    the formal arguments to the subroutine.</p>
 679
 680 <p><a href="#format_composite_type">Composite type</a> location can be
 681    determined from the compile unit and line number.  The size, alignment and
 682    offset are expressed in bits and can be 64 bit values.  The alignment is used
 683    to round the offset when embedded in
 684    a <a href="#format_composite_type">composite type</a> (as an example, to keep
 685    float doubles on 64 bit boundaries.) The offset is the bit offset if embedded
 686    in a <a href="#format_composite_type">composite type</a>.</p>
 687
 688 </div>
 689
 690 <!-- ======================================================================= -->
 691 <div class="doc_subsubsection">
 692   <a name="format_subrange">Subrange descriptors</a>
 693 </div>
 694
 695 <div class="doc_text">
 696
 697 <div class="doc_code">
 698 <pre>
 699 !42 = metadata !{
 700   i32,    ;; Tag = 33 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_subrange_type)
 701   i64,    ;; Low value
 702   i64     ;; High value
 703 }
 704 </pre>
 705 </div>
 706
 707 <p>These descriptors are used to define ranges of array subscripts for an array
 708    <a href="#format_composite_type">composite type</a>.  The low value defines
 709    the lower bounds typically zero for C/C++.  The high value is the upper
 710    bounds.  Values are 64 bit.  High - low + 1 is the size of the array.  If low
 711    > high the array bounds are not included in generated debugging information.
 712 </p>
 713
 714 </div>
 715
 716 <!-- ======================================================================= -->
 717 <div class="doc_subsubsection">
 718   <a name="format_enumeration">Enumerator descriptors</a>
 719 </div>
 720
 721 <div class="doc_text">
 722
 723 <div class="doc_code">
 724 <pre>
 725 !6 = metadata !{
 726   i32,      ;; Tag = 40 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
 727             ;; (DW_TAG_enumerator)
 728   metadata, ;; Name
 729   i64       ;; Value
 730 }
 731 </pre>
 732 </div>
 733
 734 <p>These descriptors are used to define members of an
 735    enumeration <a href="#format_composite_type">composite type</a>, it
 736    associates the name to the value.</p>
 737
 738 </div>
 739
 740 <!-- ======================================================================= -->
 741 <div class="doc_subsubsection">
 742   <a name="format_variables">Local variables</a>
 743 </div>
 744
 745 <div class="doc_text">
 746
 747 <div class="doc_code">
 748 <pre>
 749 !7 = metadata !{
 750   i32,      ;; Tag (see below)
 751   metadata, ;; Context
 752   metadata, ;; Name
 753   metadata, ;; Reference to file where defined
 754   i32,      ;; 24 bit - Line number where defined
 755             ;; 8 bit - Argument number. 1 indicates 1st argument.
 756   metadata  ;; Type descriptor
 757 }
 758 </pre>
 759 </div>
 760
 761 <p>These descriptors are used to define variables local to a sub program.  The
 762    value of the tag depends on the usage of the variable:</p>
 763
 764 <div class="doc_code">
 765 <pre>
 766 DW_TAG_auto_variable   = 256
 767 DW_TAG_arg_variable    = 257
 768 DW_TAG_return_variable = 258
 769 </pre>
 770 </div>
 771
 772 <p>An auto variable is any variable declared in the body of the function.  An
 773    argument variable is any variable that appears as a formal argument to the
 774    function.  A return variable is used to track the result of a function and
 775    has no source correspondent.</p>
 776
 777 <p>The context is either the subprogram or block where the variable is defined.
 778    Name the source variable name.  Compile unit and line indicate where the
 779    variable was defined. Type descriptor defines the declared type of the
 780    variable.</p>
 781
 782 </div>
 783
 784 <!-- ======================================================================= -->
 785 <div class="doc_subsection">
 786   <a name="format_common_intrinsics">Debugger intrinsic functions</a>
 787 </div>
 788
 789 <div class="doc_text">
 790
 791 <p>LLVM uses several intrinsic functions (name prefixed with "llvm.dbg") to
 792    provide debug information at various points in generated code.</p>
 793
 794 </div>
 795
 796 <!-- ======================================================================= -->
 797 <div class="doc_subsubsection">
 798   <a name="format_common_declare">llvm.dbg.declare</a>
 799 </div>
 800
 801 <div class="doc_text">
 802 <pre>
 803   void %<a href="#format_common_declare">llvm.dbg.declare</a>(metadata, metadata)
 804 </pre>
 805
 806 <p>This intrinsic provides information about a local element (ex. variable.) The
 807    first argument is metadata holding alloca for the variable.</tt>. The
 808    second argument is metadata containing description of the variable. </p>
 809 </div>
 810
 811 <!-- ======================================================================= -->
 812 <div class="doc_subsubsection">
 813   <a name="format_common_value">llvm.dbg.value</a>
 814 </div>
 815
 816 <div class="doc_text">
 817 <pre>
 818   void %<a href="#format_common_value">llvm.dbg.value</a>(metadata, i64, metadata)
 819 </pre>
 820
 821 <p>This intrinsic provides information when a user source variable is set to a
 822    new value.  The first argument is the new value (wrapped as metadata).  The
 823    second argument is the offset in the user source variable where the new value
 824    is written.  The third argument is metadata containing description of the
 825    user source variable. </p>
 826 </div>
 827
 828 <!-- ======================================================================= -->
 829 <div class="doc_subsection">
 830   <a name="format_common_lifetime">Object lifetimes and scoping</a>
 831 </div>
 832
 833 <div class="doc_text">
 834 <p>In many languages, the local variables in functions can have their lifetimes
 835    or scopes limited to a subset of a function.  In the C family of languages,
 836    for example, variables are only live (readable and writable) within the
 837    source block that they are defined in.  In functional languages, values are
 838    only readable after they have been defined.  Though this is a very obvious
 839    concept, it is non-trivial to model in LLVM, because it has no notion of
 840    scoping in this sense, and does not want to be tied to a language's scoping
 841    rules.</p>
 842
 843 <p>In order to handle this, the LLVM debug format uses the metadata attached to
 844    llvm instructions to encode line number and scoping information. Consider
 845    the following C fragment, for example:</p>
 846
 847 <div class="doc_code">
 848 <pre>
 849 1.  void foo() {
 850 2.    int X = 21;
 851 3.    int Y = 22;
 852 4.    {
 853 5.      int Z = 23;
 854 6.      Z = X;
 855 7.    }
 856 8.    X = Y;
 857 9.  }
 858 </pre>
 859 </div>
 860
 861 <p>Compiled to LLVM, this function would be represented like this:</p>
 862
 863 <div class="doc_code">
 864 <pre>
 865 define void @foo() nounwind ssp {
 866 entry:
 867   %X = alloca i32, align 4                        ; &lt;i32*&gt; [#uses=4]
 868   %Y = alloca i32, align 4                        ; &lt;i32*&gt; [#uses=4]
 869   %Z = alloca i32, align 4                        ; &lt;i32*&gt; [#uses=3]
 870   %0 = bitcast i32* %X to {}*                     ; &lt;{}*&gt; [#uses=1]
 871   call void @llvm.dbg.declare(metadata !{i32 * %X}, metadata !0), !dbg !7
 872   store i32 21, i32* %X, !dbg !8
 873   %1 = bitcast i32* %Y to {}*                     ; &lt;{}*&gt; [#uses=1]
 874   call void @llvm.dbg.declare(metadata !{i32 * %Y}, metadata !9), !dbg !10
 875   store i32 22, i32* %Y, !dbg !11
 876   %2 = bitcast i32* %Z to {}*                     ; &lt;{}*&gt; [#uses=1]
 877   call void @llvm.dbg.declare(metadata !{i32 * %Z}, metadata !12), !dbg !14
 878   store i32 23, i32* %Z, !dbg !15
 879   %tmp = load i32* %X, !dbg !16                   ; &lt;i32&gt; [#uses=1]
 880   %tmp1 = load i32* %Y, !dbg !16                  ; &lt;i32&gt; [#uses=1]
 881   %add = add nsw i32 %tmp, %tmp1, !dbg !16        ; &lt;i32&gt; [#uses=1]
 882   store i32 %add, i32* %Z, !dbg !16
 883   %tmp2 = load i32* %Y, !dbg !17                  ; &lt;i32&gt; [#uses=1]
 884   store i32 %tmp2, i32* %X, !dbg !17
 885   ret void, !dbg !18
 886 }
 887
 888 declare void @llvm.dbg.declare(metadata, metadata) nounwind readnone
 889
 890 !0 = metadata !{i32 459008, metadata !1, metadata !"X",
 891                 metadata !3, i32 2, metadata !6}; [ DW_TAG_auto_variable ]
 892 !1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ]
 893 !2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo", metadata !"foo",
 894                metadata !"foo", metadata !3, i32 1, metadata !4,
 895                i1 false, i1 true}; [DW_TAG_subprogram ]
 896 !3 = metadata !{i32 458769, i32 0, i32 12, metadata !"foo.c",
 897                 metadata !"/private/tmp", metadata !"clang 1.1", i1 true,
 898                 i1 false, metadata !"", i32 0}; [DW_TAG_compile_unit ]
 899 !4 = metadata !{i32 458773, metadata !3, metadata !"", null, i32 0, i64 0, i64 0,
 900                 i64 0, i32 0, null, metadata !5, i32 0}; [DW_TAG_subroutine_type ]
 901 !5 = metadata !{null}
 902 !6 = metadata !{i32 458788, metadata !3, metadata !"int", metadata !3, i32 0,
 903                 i64 32, i64 32, i64 0, i32 0, i32 5}; [DW_TAG_base_type ]
 904 !7 = metadata !{i32 2, i32 7, metadata !1, null}
 905 !8 = metadata !{i32 2, i32 3, metadata !1, null}
 906 !9 = metadata !{i32 459008, metadata !1, metadata !"Y", metadata !3, i32 3,
 907                 metadata !6}; [ DW_TAG_auto_variable ]
 908 !10 = metadata !{i32 3, i32 7, metadata !1, null}
 909 !11 = metadata !{i32 3, i32 3, metadata !1, null}
 910 !12 = metadata !{i32 459008, metadata !13, metadata !"Z", metadata !3, i32 5,
 911                  metadata !6}; [ DW_TAG_auto_variable ]
 912 !13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ]
 913 !14 = metadata !{i32 5, i32 9, metadata !13, null}
 914 !15 = metadata !{i32 5, i32 5, metadata !13, null}
 915 !16 = metadata !{i32 6, i32 5, metadata !13, null}
 916 !17 = metadata !{i32 8, i32 3, metadata !1, null}
 917 !18 = metadata !{i32 9, i32 1, metadata !2, null}
 918 </pre>
 919 </div>
 920
 921 <p>This example illustrates a few important details about LLVM debugging
 922    information. In particular, it shows how the <tt>llvm.dbg.declare</tt>
 923    intrinsic and location information, which are attached to an instruction,
 924    are applied together to allow a debugger to analyze the relationship between
 925    statements, variable definitions, and the code used to implement the
 926    function.</p>
 927
 928 <div class="doc_code">
 929 <pre>
 930 call void @llvm.dbg.declare(metadata, metadata !0), !dbg !7
 931 </pre>
 932 </div>
 933
 934 <p>The first intrinsic
 935    <tt>%<a href="#format_common_declare">llvm.dbg.declare</a></tt>
 936    encodes debugging information for the variable <tt>X</tt>. The metadata
 937    <tt>!dbg !7</tt> attached to the intrinsic provides scope information for the
 938    variable <tt>X</tt>.</p>
 939
 940 <div class="doc_code">
 941 <pre>
 942 !7 = metadata !{i32 2, i32 7, metadata !1, null}
 943 !1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ]
 944 !2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo",
 945                 metadata !"foo", metadata !"foo", metadata !3, i32 1,
 946                 metadata !4, i1 false, i1 true}; [DW_TAG_subprogram ]
 947 </pre>
 948 </div>
 949
 950 <p>Here <tt>!7</tt> is metadata providing location information. It has four
 951    fields: line number, column number, scope, and original scope. The original
 952    scope represents inline location if this instruction is inlined inside a
 953    caller, and is null otherwise. In this example, scope is encoded by
 954    <tt>!1</tt>. <tt>!1</tt> represents a lexical block inside the scope
 955    <tt>!2</tt>, where <tt>!2</tt> is a
 956    <a href="#format_subprograms">subprogram descriptor</a>. This way the
 957    location information attached to the intrinsics indicates that the
 958    variable <tt>X</tt> is declared at line number 2 at a function level scope in
 959    function <tt>foo</tt>.</p>
 960
 961 <p>Now lets take another example.</p>
 962
 963 <div class="doc_code">
 964 <pre>
 965 call void @llvm.dbg.declare(metadata, metadata !12), !dbg !14
 966 </pre>
 967 </div>
 968
 969 <p>The second intrinsic
 970    <tt>%<a href="#format_common_declare">llvm.dbg.declare</a></tt>
 971    encodes debugging information for variable <tt>Z</tt>. The metadata
 972    <tt>!dbg !14</tt> attached to the intrinsic provides scope information for
 973    the variable <tt>Z</tt>.</p>
 974
 975 <div class="doc_code">
 976 <pre>
 977 !13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ]
 978 !14 = metadata !{i32 5, i32 9, metadata !13, null}
 979 </pre>
 980 </div>
 981
 982 <p>Here <tt>!14</tt> indicates that <tt>Z</tt> is declared at line number 5 and
 983    column number 9 inside of lexical scope <tt>!13</tt>. The lexical scope
 984    itself resides inside of lexical scope <tt>!1</tt> described above.</p>
 985
 986 <p>The scope information attached with each instruction provides a
 987    straightforward way to find instructions covered by a scope.</p>
 988
 989 </div>
 990
 991 <!-- *********************************************************************** -->
 992 <div class="doc_section">
 993   <a name="ccxx_frontend">C/C++ front-end specific debug information</a>
 994 </div>
 995 <!-- *********************************************************************** -->
 996
 997 <div class="doc_text">
 998
 999 <p>The C and C++ front-ends represent information about the program in a format
1000    that is effectively identical
1001    to <a href="http://www.eagercon.com/dwarf/dwarf3std.htm">DWARF 3.0</a> in
1002    terms of information content.  This allows code generators to trivially
1003    support native debuggers by generating standard dwarf information, and
1004    contains enough information for non-dwarf targets to translate it as
1005    needed.</p>
1006
1007 <p>This section describes the forms used to represent C and C++ programs. Other
1008    languages could pattern themselves after this (which itself is tuned to
1009    representing programs in the same way that DWARF 3 does), or they could
1010    choose to provide completely different forms if they don't fit into the DWARF
1011    model.  As support for debugging information gets added to the various LLVM
1012    source-language front-ends, the information used should be documented
1013    here.</p>
1014
1015 <p>The following sections provide examples of various C/C++ constructs and the
1016    debug information that would best describe those constructs.</p>
1017
1018 </div>
1019
1020 <!-- ======================================================================= -->
1021 <div class="doc_subsection">
1022   <a name="ccxx_compile_units">C/C++ source file information</a>
1023 </div>
1024
1025 <div class="doc_text">
1026
1027 <p>Given the source files <tt>MySource.cpp</tt> and <tt>MyHeader.h</tt> located
1028    in the directory <tt>/Users/mine/sources</tt>, the following code:</p>
1029
1030 <div class="doc_code">
1031 <pre>
1032 #include "MyHeader.h"
1033
1034 int main(int argc, char *argv[]) {
1035   return 0;
1036 }
1037 </pre>
1038 </div>
1039
1040 <p>a C/C++ front-end would generate the following descriptors:</p>
1041
1042 <div class="doc_code">
1043 <pre>
1044 ...
1045 ;;
1046 ;; Define the compile unit for the main source file "/Users/mine/sources/MySource.cpp".
1047 ;;
1048 !2 = metadata !{
1049   i32 524305,    ;; Tag
1050   i32 0,         ;; Unused
1051   i32 4,         ;; Language Id
1052   metadata !"MySource.cpp",
1053   metadata !"/Users/mine/sources",
1054   metadata !"4.2.1 (Based on Apple Inc. build 5649) (LLVM build 00)",
1055   i1 true,       ;; Main Compile Unit
1056   i1 false,      ;; Optimized compile unit
1057   metadata !"",  ;; Compiler flags
1058   i32 0}         ;; Runtime version
1059
1060 ;;
1061 ;; Define the file for the file "/Users/mine/sources/MySource.cpp".
1062 ;;
1063 !1 = metadata !{
1064   i32 524329,    ;; Tag
1065   metadata !"MySource.cpp",
1066   metadata !"/Users/mine/sources",
1067   metadata !2    ;; Compile unit
1068 }
1069
1070 ;;
1071 ;; Define the file for the file "/Users/mine/sources/Myheader.h"
1072 ;;
1073 !3 = metadata !{
1074   i32 524329,    ;; Tag
1075   metadata !"Myheader.h"
1076   metadata !"/Users/mine/sources",
1077   metadata !2    ;; Compile unit
1078 }
1079
1080 ...
1081 </pre>
1082 </div>
1083
1084 <p>llvm::Instruction provides easy access to metadata attached with an
1085 instruction. One can extract line number information encoded in LLVM IR
1086 using <tt>Instruction::getMetadata()</tt> and
1087 <tt>DILocation::getLineNumber()</tt>.
1088 <pre>
1089  if (MDNode *N = I->getMetadata("dbg")) {  // Here I is an LLVM instruction
1090    DILocation Loc(N);                      // DILocation is in DebugInfo.h
1091    unsigned Line = Loc.getLineNumber();
1092    StringRef File = Loc.getFilename();
1093    StringRef Dir = Loc.getDirectory();
1094  }
1095 </pre>
1096 </div>
1097
1098 <!-- ======================================================================= -->
1099 <div class="doc_subsection">
1100   <a name="ccxx_global_variable">C/C++ global variable information</a>
1101 </div>
1102
1103 <div class="doc_text">
1104
1105 <p>Given an integer global variable declared as follows:</p>
1106
1107 <div class="doc_code">
1108 <pre>
1109 int MyGlobal = 100;
1110 </pre>
1111 </div>
1112
1113 <p>a C/C++ front-end would generate the following descriptors:</p>
1114
1115 <div class="doc_code">
1116 <pre>
1117 ;;
1118 ;; Define the global itself.
1119 ;;
1120 %MyGlobal = global int 100
1121 ...
1122 ;;
1123 ;; List of debug info of globals
1124 ;;
1125 !llvm.dbg.gv = !{!0}
1126
1127 ;;
1128 ;; Define the global variable descriptor.  Note the reference to the global
1129 ;; variable anchor and the global variable itself.
1130 ;;
1131 !0 = metadata !{
1132   i32 524340,              ;; Tag
1133   i32 0,                   ;; Unused
1134   metadata !1,             ;; Context
1135   metadata !"MyGlobal",    ;; Name
1136   metadata !"MyGlobal",    ;; Display Name
1137   metadata !"MyGlobal",    ;; Linkage Name
1138   metadata !3,             ;; Compile Unit
1139   i32 1,                   ;; Line Number
1140   metadata !4,             ;; Type
1141   i1 false,                ;; Is a local variable
1142   i1 true,                 ;; Is this a definition
1143   i32* @MyGlobal           ;; The global variable
1144 }
1145
1146 ;;
1147 ;; Define the basic type of 32 bit signed integer.  Note that since int is an
1148 ;; intrinsic type the source file is NULL and line 0.
1149 ;;
1150 !4 = metadata !{
1151   i32 524324,              ;; Tag
1152   metadata !1,             ;; Context
1153   metadata !"int",         ;; Name
1154   metadata !1,             ;; File
1155   i32 0,                   ;; Line number
1156   i64 32,                  ;; Size in Bits
1157   i64 32,                  ;; Align in Bits
1158   i64 0,                   ;; Offset in Bits
1159   i32 0,                   ;; Flags
1160   i32 5                    ;; Encoding
1161 }
1162
1163 </pre>
1164 </div>
1165
1166 </div>
1167
1168 <!-- ======================================================================= -->
1169 <div class="doc_subsection">
1170   <a name="ccxx_subprogram">C/C++ function information</a>
1171 </div>
1172
1173 <div class="doc_text">
1174
1175 <p>Given a function declared as follows:</p>
1176
1177 <div class="doc_code">
1178 <pre>
1179 int main(int argc, char *argv[]) {
1180   return 0;
1181 }
1182 </pre>
1183 </div>
1184
1185 <p>a C/C++ front-end would generate the following descriptors:</p>
1186
1187 <div class="doc_code">
1188 <pre>
1189 ;;
1190 ;; Define the anchor for subprograms.  Note that the second field of the
1191 ;; anchor is 46, which is the same as the tag for subprograms
1192 ;; (46 = DW_TAG_subprogram.)
1193 ;;
1194 !6 = metadata !{
1195   i32 524334,        ;; Tag
1196   i32 0,             ;; Unused
1197   metadata !1,       ;; Context
1198   metadata !"main",  ;; Name
1199   metadata !"main",  ;; Display name
1200   metadata !"main",  ;; Linkage name
1201   metadata !1,       ;; File
1202   i32 1,             ;; Line number
1203   metadata !4,       ;; Type
1204   i1 false,          ;; Is local
1205   i1 true,           ;; Is definition
1206   i32 0,             ;; Virtuality attribute, e.g. pure virtual function
1207   i32 0,             ;; Index into virtual table for C++ methods
1208   i32 0,             ;; Type that holds virtual table.
1209   i32 0,             ;; Flags
1210   i1 false,          ;; True if this function is optimized
1211   Function *,        ;; Pointer to llvm::Function
1212   null               ;; Function template parameters
1213 }
1214 ;;
1215 ;; Define the subprogram itself.
1216 ;;
1217 define i32 @main(i32 %argc, i8** %argv) {
1218 ...
1219 }
1220 </pre>
1221 </div>
1222
1223 </div>
1224
1225 <!-- ======================================================================= -->
1226 <div class="doc_subsection">
1227   <a name="ccxx_basic_types">C/C++ basic types</a>
1228 </div>
1229
1230 <div class="doc_text">
1231
1232 <p>The following are the basic type descriptors for C/C++ core types:</p>
1233
1234 </div>
1235
1236 <!-- ======================================================================= -->
1237 <div class="doc_subsubsection">
1238   <a name="ccxx_basic_type_bool">bool</a>
1239 </div>
1240
1241 <div class="doc_text">
1242
1243 <div class="doc_code">
1244 <pre>
1245 !2 = metadata !{
1246   i32 524324,        ;; Tag
1247   metadata !1,       ;; Context
1248   metadata !"bool",  ;; Name
1249   metadata !1,       ;; File
1250   i32 0,             ;; Line number
1251   i64 8,             ;; Size in Bits
1252   i64 8,             ;; Align in Bits
1253   i64 0,             ;; Offset in Bits
1254   i32 0,             ;; Flags
1255   i32 2              ;; Encoding
1256 }
1257 </pre>
1258 </div>
1259
1260 </div>
1261
1262 <!-- ======================================================================= -->
1263 <div class="doc_subsubsection">
1264   <a name="ccxx_basic_char">char</a>
1265 </div>
1266
1267 <div class="doc_text">
1268
1269 <div class="doc_code">
1270 <pre>
1271 !2 = metadata !{
1272   i32 524324,        ;; Tag
1273   metadata !1,       ;; Context
1274   metadata !"char",  ;; Name
1275   metadata !1,       ;; File
1276   i32 0,             ;; Line number
1277   i64 8,             ;; Size in Bits
1278   i64 8,             ;; Align in Bits
1279   i64 0,             ;; Offset in Bits
1280   i32 0,             ;; Flags
1281   i32 6              ;; Encoding
1282 }
1283 </pre>
1284 </div>
1285
1286 </div>
1287
1288 <!-- ======================================================================= -->
1289 <div class="doc_subsubsection">
1290   <a name="ccxx_basic_unsigned_char">unsigned char</a>
1291 </div>
1292
1293 <div class="doc_text">
1294
1295 <div class="doc_code">
1296 <pre>
1297 !2 = metadata !{
1298   i32 524324,        ;; Tag
1299   metadata !1,       ;; Context
1300   metadata !"unsigned char",
1301   metadata !1,       ;; File
1302   i32 0,             ;; Line number
1303   i64 8,             ;; Size in Bits
1304   i64 8,             ;; Align in Bits
1305   i64 0,             ;; Offset in Bits
1306   i32 0,             ;; Flags
1307   i32 8              ;; Encoding
1308 }
1309 </pre>
1310 </div>
1311
1312 </div>
1313
1314 <!-- ======================================================================= -->
1315 <div class="doc_subsubsection">
1316   <a name="ccxx_basic_short">short</a>
1317 </div>
1318
1319 <div class="doc_text">
1320
1321 <div class="doc_code">
1322 <pre>
1323 !2 = metadata !{
1324   i32 524324,        ;; Tag
1325   metadata !1,       ;; Context
1326   metadata !"short int",
1327   metadata !1,       ;; File
1328   i32 0,             ;; Line number
1329   i64 16,            ;; Size in Bits
1330   i64 16,            ;; Align in Bits
1331   i64 0,             ;; Offset in Bits
1332   i32 0,             ;; Flags
1333   i32 5              ;; Encoding
1334 }
1335 </pre>
1336 </div>
1337
1338 </div>
1339
1340 <!-- ======================================================================= -->
1341 <div class="doc_subsubsection">
1342   <a name="ccxx_basic_unsigned_short">unsigned short</a>
1343 </div>
1344
1345 <div class="doc_text">
1346
1347 <div class="doc_code">
1348 <pre>
1349 !2 = metadata !{
1350   i32 524324,        ;; Tag
1351   metadata !1,       ;; Context
1352   metadata !"short unsigned int",
1353   metadata !1,       ;; File
1354   i32 0,             ;; Line number
1355   i64 16,            ;; Size in Bits
1356   i64 16,            ;; Align in Bits
1357   i64 0,             ;; Offset in Bits
1358   i32 0,             ;; Flags
1359   i32 7              ;; Encoding
1360 }
1361 </pre>
1362 </div>
1363
1364 </div>
1365
1366 <!-- ======================================================================= -->
1367 <div class="doc_subsubsection">
1368   <a name="ccxx_basic_int">int</a>
1369 </div>
1370
1371 <div class="doc_text">
1372
1373 <div class="doc_code">
1374 <pre>
1375 !2 = metadata !{
1376   i32 524324,        ;; Tag
1377   metadata !1,       ;; Context
1378   metadata !"int",   ;; Name
1379   metadata !1,       ;; File
1380   i32 0,             ;; Line number
1381   i64 32,            ;; Size in Bits
1382   i64 32,            ;; Align in Bits
1383   i64 0,             ;; Offset in Bits
1384   i32 0,             ;; Flags
1385   i32 5              ;; Encoding
1386 }
1387 </pre></div>
1388
1389 </div>
1390
1391 <!-- ======================================================================= -->
1392 <div class="doc_subsubsection">
1393   <a name="ccxx_basic_unsigned_int">unsigned int</a>
1394 </div>
1395
1396 <div class="doc_text">
1397
1398 <div class="doc_code">
1399 <pre>
1400 !2 = metadata !{
1401   i32 524324,        ;; Tag
1402   metadata !1,       ;; Context
1403   metadata !"unsigned int",
1404   metadata !1,       ;; File
1405   i32 0,             ;; Line number
1406   i64 32,            ;; Size in Bits
1407   i64 32,            ;; Align in Bits
1408   i64 0,             ;; Offset in Bits
1409   i32 0,             ;; Flags
1410   i32 7              ;; Encoding
1411 }
1412 </pre>
1413 </div>
1414
1415 </div>
1416
1417 <!-- ======================================================================= -->
1418 <div class="doc_subsubsection">
1419   <a name="ccxx_basic_long_long">long long</a>
1420 </div>
1421
1422 <div class="doc_text">
1423
1424 <div class="doc_code">
1425 <pre>
1426 !2 = metadata !{
1427   i32 524324,        ;; Tag
1428   metadata !1,       ;; Context
1429   metadata !"long long int",
1430   metadata !1,       ;; File
1431   i32 0,             ;; Line number
1432   i64 64,            ;; Size in Bits
1433   i64 64,            ;; Align in Bits
1434   i64 0,             ;; Offset in Bits
1435   i32 0,             ;; Flags
1436   i32 5              ;; Encoding
1437 }
1438 </pre>
1439 </div>
1440
1441 </div>
1442
1443 <!-- ======================================================================= -->
1444 <div class="doc_subsubsection">
1445   <a name="ccxx_basic_unsigned_long_long">unsigned long long</a>
1446 </div>
1447
1448 <div class="doc_text">
1449
1450 <div class="doc_code">
1451 <pre>
1452 !2 = metadata !{
1453   i32 524324,        ;; Tag
1454   metadata !1,       ;; Context
1455   metadata !"long long unsigned int",
1456   metadata !1,       ;; File
1457   i32 0,             ;; Line number
1458   i64 64,            ;; Size in Bits
1459   i64 64,            ;; Align in Bits
1460   i64 0,             ;; Offset in Bits
1461   i32 0,             ;; Flags
1462   i32 7              ;; Encoding
1463 }
1464 </pre>
1465 </div>
1466
1467 </div>
1468
1469 <!-- ======================================================================= -->
1470 <div class="doc_subsubsection">
1471   <a name="ccxx_basic_float">float</a>
1472 </div>
1473
1474 <div class="doc_text">
1475
1476 <div class="doc_code">
1477 <pre>
1478 !2 = metadata !{
1479   i32 524324,        ;; Tag
1480   metadata !1,       ;; Context
1481   metadata !"float",
1482   metadata !1,       ;; File
1483   i32 0,             ;; Line number
1484   i64 32,            ;; Size in Bits
1485   i64 32,            ;; Align in Bits
1486   i64 0,             ;; Offset in Bits
1487   i32 0,             ;; Flags
1488   i32 4              ;; Encoding
1489 }
1490 </pre>
1491 </div>
1492
1493 </div>
1494
1495 <!-- ======================================================================= -->
1496 <div class="doc_subsubsection">
1497   <a name="ccxx_basic_double">double</a>
1498 </div>
1499
1500 <div class="doc_text">
1501
1502 <div class="doc_code">
1503 <pre>
1504 !2 = metadata !{
1505   i32 524324,        ;; Tag
1506   metadata !1,       ;; Context
1507   metadata !"double",;; Name
1508   metadata !1,       ;; File
1509   i32 0,             ;; Line number
1510   i64 64,            ;; Size in Bits
1511   i64 64,            ;; Align in Bits
1512   i64 0,             ;; Offset in Bits
1513   i32 0,             ;; Flags
1514   i32 4              ;; Encoding
1515 }
1516 </pre>
1517 </div>
1518
1519 </div>
1520
1521 <!-- ======================================================================= -->
1522 <div class="doc_subsection">
1523   <a name="ccxx_derived_types">C/C++ derived types</a>
1524 </div>
1525
1526 <div class="doc_text">
1527
1528 <p>Given the following as an example of C/C++ derived type:</p>
1529
1530 <div class="doc_code">
1531 <pre>
1532 typedef const int *IntPtr;
1533 </pre>
1534 </div>
1535
1536 <p>a C/C++ front-end would generate the following descriptors:</p>
1537
1538 <div class="doc_code">
1539 <pre>
1540 ;;
1541 ;; Define the typedef "IntPtr".
1542 ;;
1543 !2 = metadata !{
1544   i32 524310,          ;; Tag
1545   metadata !1,         ;; Context
1546   metadata !"IntPtr",  ;; Name
1547   metadata !3,         ;; File
1548   i32 0,               ;; Line number
1549   i64 0,               ;; Size in bits
1550   i64 0,               ;; Align in bits
1551   i64 0,               ;; Offset in bits
1552   i32 0,               ;; Flags
1553   metadata !4          ;; Derived From type
1554 }
1555
1556 ;;
1557 ;; Define the pointer type.
1558 ;;
1559 !4 = metadata !{
1560   i32 524303,          ;; Tag
1561   metadata !1,         ;; Context
1562   metadata !"",        ;; Name
1563   metadata !1,         ;; File
1564   i32 0,               ;; Line number
1565   i64 64,              ;; Size in bits
1566   i64 64,              ;; Align in bits
1567   i64 0,               ;; Offset in bits
1568   i32 0,               ;; Flags
1569   metadata !5          ;; Derived From type
1570 }
1571 ;;
1572 ;; Define the const type.
1573 ;;
1574 !5 = metadata !{
1575   i32 524326,          ;; Tag
1576   metadata !1,         ;; Context
1577   metadata !"",        ;; Name
1578   metadata !1,         ;; File
1579   i32 0,               ;; Line number
1580   i64 32,              ;; Size in bits
1581   i64 32,              ;; Align in bits
1582   i64 0,               ;; Offset in bits
1583   i32 0,               ;; Flags
1584   metadata !6          ;; Derived From type
1585 }
1586 ;;
1587 ;; Define the int type.
1588 ;;
1589 !6 = metadata !{
1590   i32 524324,          ;; Tag
1591   metadata !1,         ;; Context
1592   metadata !"int",     ;; Name
1593   metadata !1,         ;; File
1594   i32 0,               ;; Line number
1595   i64 32,              ;; Size in bits
1596   i64 32,              ;; Align in bits
1597   i64 0,               ;; Offset in bits
1598   i32 0,               ;; Flags
1599   5                    ;; Encoding
1600 }
1601 </pre>
1602 </div>
1603
1604 </div>
1605
1606 <!-- ======================================================================= -->
1607 <div class="doc_subsection">
1608   <a name="ccxx_composite_types">C/C++ struct/union types</a>
1609 </div>
1610
1611 <div class="doc_text">
1612
1613 <p>Given the following as an example of C/C++ struct type:</p>
1614
1615 <div class="doc_code">
1616 <pre>
1617 struct Color {
1618   unsigned Red;
1619   unsigned Green;
1620   unsigned Blue;
1621 };
1622 </pre>
1623 </div>
1624
1625 <p>a C/C++ front-end would generate the following descriptors:</p>
1626
1627 <div class="doc_code">
1628 <pre>
1629 ;;
1630 ;; Define basic type for unsigned int.
1631 ;;
1632 !5 = metadata !{
1633   i32 524324,        ;; Tag
1634   metadata !1,       ;; Context
1635   metadata !"unsigned int",
1636   metadata !1,       ;; File
1637   i32 0,             ;; Line number
1638   i64 32,            ;; Size in Bits
1639   i64 32,            ;; Align in Bits
1640   i64 0,             ;; Offset in Bits
1641   i32 0,             ;; Flags
1642   i32 7              ;; Encoding
1643 }
1644 ;;
1645 ;; Define composite type for struct Color.
1646 ;;
1647 !2 = metadata !{
1648   i32 524307,        ;; Tag
1649   metadata !1,       ;; Context
1650   metadata !"Color", ;; Name
1651   metadata !1,       ;; Compile unit
1652   i32 1,             ;; Line number
1653   i64 96,            ;; Size in bits
1654   i64 32,            ;; Align in bits
1655   i64 0,             ;; Offset in bits
1656   i32 0,             ;; Flags
1657   null,              ;; Derived From
1658   metadata !3,       ;; Elements
1659   i32 0              ;; Runtime Language
1660 }
1661
1662 ;;
1663 ;; Define the Red field.
1664 ;;
1665 !4 = metadata !{
1666   i32 524301,        ;; Tag
1667   metadata !1,       ;; Context
1668   metadata !"Red",   ;; Name
1669   metadata !1,       ;; File
1670   i32 2,             ;; Line number
1671   i64 32,            ;; Size in bits
1672   i64 32,            ;; Align in bits
1673   i64 0,             ;; Offset in bits
1674   i32 0,             ;; Flags
1675   metadata !5        ;; Derived From type
1676 }
1677
1678 ;;
1679 ;; Define the Green field.
1680 ;;
1681 !6 = metadata !{
1682   i32 524301,        ;; Tag
1683   metadata !1,       ;; Context
1684   metadata !"Green", ;; Name
1685   metadata !1,       ;; File
1686   i32 3,             ;; Line number
1687   i64 32,            ;; Size in bits
1688   i64 32,            ;; Align in bits
1689   i64 32,             ;; Offset in bits
1690   i32 0,             ;; Flags
1691   metadata !5        ;; Derived From type
1692 }
1693
1694 ;;
1695 ;; Define the Blue field.
1696 ;;
1697 !7 = metadata !{
1698   i32 524301,        ;; Tag
1699   metadata !1,       ;; Context
1700   metadata !"Blue",  ;; Name
1701   metadata !1,       ;; File
1702   i32 4,             ;; Line number
1703   i64 32,            ;; Size in bits
1704   i64 32,            ;; Align in bits
1705   i64 64,             ;; Offset in bits
1706   i32 0,             ;; Flags
1707   metadata !5        ;; Derived From type
1708 }
1709
1710 ;;
1711 ;; Define the array of fields used by the composite type Color.
1712 ;;
1713 !3 = metadata !{metadata !4, metadata !6, metadata !7}
1714 </pre>
1715 </div>
1716
1717 </div>
1718
1719 <!-- ======================================================================= -->
1720 <div class="doc_subsection">
1721   <a name="ccxx_enumeration_types">C/C++ enumeration types</a>
1722 </div>
1723
1724 <div class="doc_text">
1725
1726 <p>Given the following as an example of C/C++ enumeration type:</p>
1727
1728 <div class="doc_code">
1729 <pre>
1730 enum Trees {
1731   Spruce = 100,
1732   Oak = 200,
1733   Maple = 300
1734 };
1735 </pre>
1736 </div>
1737
1738 <p>a C/C++ front-end would generate the following descriptors:</p>
1739
1740 <div class="doc_code">
1741 <pre>
1742 ;;
1743 ;; Define composite type for enum Trees
1744 ;;
1745 !2 = metadata !{
1746   i32 524292,        ;; Tag
1747   metadata !1,       ;; Context
1748   metadata !"Trees", ;; Name
1749   metadata !1,       ;; File
1750   i32 1,             ;; Line number
1751   i64 32,            ;; Size in bits
1752   i64 32,            ;; Align in bits
1753   i64 0,             ;; Offset in bits
1754   i32 0,             ;; Flags
1755   null,              ;; Derived From type
1756   metadata !3,       ;; Elements
1757   i32 0              ;; Runtime language
1758 }
1759
1760 ;;
1761 ;; Define the array of enumerators used by composite type Trees.
1762 ;;
1763 !3 = metadata !{metadata !4, metadata !5, metadata !6}
1764
1765 ;;
1766 ;; Define Spruce enumerator.
1767 ;;
1768 !4 = metadata !{i32 524328, metadata !"Spruce", i64 100}
1769
1770 ;;
1771 ;; Define Oak enumerator.
1772 ;;
1773 !5 = metadata !{i32 524328, metadata !"Oak", i64 200}
1774
1775 ;;
1776 ;; Define Maple enumerator.
1777 ;;
1778 !6 = metadata !{i32 524328, metadata !"Maple", i64 300}
1779
1780 </pre>
1781 </div>
1782
1783 </div>
1784
1785 <!-- *********************************************************************** -->
1786
1787 <hr>
1788 <address>
1789   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
1790   src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
1791   <a href="http://validator.w3.org/check/referer"><img
1792   src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
1793
1794   <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
1795   <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
1796   Last modified: $Date$
1797 </address>
1798
1799 </body>
1800 </html>