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