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