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