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 lifetimes
 784    or scopes 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 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 to
 793    llvm instructions to encode line nuber and scoping information. Consider the
 794    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 define void @foo() nounwind ssp {
 815 entry:
 816   %X = alloca i32, align 4                        ; &lt;i32*&gt; [#uses=4]
 817   %Y = alloca i32, align 4                        ; &lt;i32*&gt; [#uses=4]
 818   %Z = alloca i32, align 4                        ; &lt;i32*&gt; [#uses=3]
 819   %0 = bitcast i32* %X to { }*                    ; &lt;{ }*&gt; [#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 { }*                    ; &lt;{ }*&gt; [#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 { }*                    ; &lt;{ }*&gt; [#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                   ; &lt;i32&gt; [#uses=1]
 829   %tmp1 = load i32* %Y, !dbg !16                  ; &lt;i32&gt; [#uses=1]
 830   %add = add nsw i32 %tmp, %tmp1, !dbg !16        ; &lt;i32&gt; [#uses=1]
 831   store i32 %add, i32* %Z, !dbg !16
 832   %tmp2 = load i32* %Y, !dbg !17                  ; &lt;i32&gt; [#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 LLVM debugging
 871    information. In particular, it shows how the <tt>llvm.dbg.declare</tt>
 872    intrinsic and location information, which are attached to an instruction,
 873    are applied together to allow a debugger to analyze the relationship between
 874    statements, variable definitions, and the code used to implement the
 875    function.</p>
 876
 877 <div class="doc_code">
 878 <pre>
 879 call void @llvm.dbg.declare({ }* %0, metadata !0), !dbg !7
 880 </pre>
 881 </div>
 882
 883 <p>The first intrinsic
 884    <tt>%<a href="#format_common_declare">llvm.dbg.declare</a></tt>
 885    encodes debugging information for the variable <tt>X</tt>. The metadata
 886    <tt>!dbg !7</tt> attached to the intrinsic provides scope information for the
 887    variable <tt>X</tt>.</p>
 888
 889 <div class="doc_code">
 890 <pre>
 891 !7 = metadata !{i32 2, i32 7, metadata !1, null}
 892 !1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ]
 893 !2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo",
 894                 metadata !"foo", metadata !"foo", metadata !3, i32 1,
 895                 metadata !4, i1 false, i1 true}; [DW_TAG_subprogram ]
 896 </pre>
 897 </div>
 898
 899 <p>Here <tt>!7</tt> is metadata providing location information. It has four
 900    fields: line number, column number, scope, and original scope. The original
 901    scope represents inline location if this instruction is inlined inside a
 902    caller, and is null otherwise. In this example, scope is encoded by
 903    <tt>!1</tt>. <tt>!1</tt> represents a lexical block inside the scope
 904    <tt>!2</tt>, where <tt>!2</tt> is a
 905    <a href="#format_subprograms">subprogram descriptor</a>. This way the
 906    location information attached to the intrinsics indicates that the
 907    variable <tt>X</tt> is declared at line number 2 at a function level scope in
 908    function <tt>foo</tt>.</p>
 909
 910 <p>Now lets take another example.</p>
 911
 912 <div class="doc_code">
 913 <pre>
 914 call void @llvm.dbg.declare({ }* %2, metadata !12), !dbg !14
 915 </pre>
 916 </div>
 917
 918 <p>The second intrinsic
 919    <tt>%<a href="#format_common_declare">llvm.dbg.declare</a></tt>
 920    encodes debugging information for variable <tt>Z</tt>. The metadata
 921    <tt>!dbg !14</tt> attached to the intrinsic provides scope information for
 922    the variable <tt>Z</tt>.</p>
 923
 924 <div class="doc_code">
 925 <pre>
 926 !13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ]
 927 !14 = metadata !{i32 5, i32 9, metadata !13, null}
 928 </pre>
 929 </div>
 930
 931 <p>Here <tt>!14</tt> indicates that <tt>Z</tt> is declaread at line number 5 and
 932    column number 9 inside of lexical scope <tt>!13</tt>. The lexical scope
 933    itself resides inside of lexical scope <tt>!1</tt> described above.</p>
 934
 935 <p>The scope information attached with each instruction provides a
 936    straightforward way to find instructions covered by a scope.</p>
 937
 938 </div>
 939
 940 <!-- *********************************************************************** -->
 941 <div class="doc_section">
 942   <a name="ccxx_frontend">C/C++ front-end specific debug information</a>
 943 </div>
 944 <!-- *********************************************************************** -->
 945
 946 <div class="doc_text">
 947
 948 <p>The C and C++ front-ends represent information about the program in a format
 949    that is effectively identical
 950    to <a href="http://www.eagercon.com/dwarf/dwarf3std.htm">DWARF 3.0</a> in
 951    terms of information content.  This allows code generators to trivially
 952    support native debuggers by generating standard dwarf information, and
 953    contains enough information for non-dwarf targets to translate it as
 954    needed.</p>
 955
 956 <p>This section describes the forms used to represent C and C++ programs. Other
 957    languages could pattern themselves after this (which itself is tuned to
 958    representing programs in the same way that DWARF 3 does), or they could
 959    choose to provide completely different forms if they don't fit into the DWARF
 960    model.  As support for debugging information gets added to the various LLVM
 961    source-language front-ends, the information used should be documented
 962    here.</p>
 963
 964 <p>The following sections provide examples of various C/C++ constructs and the
 965    debug information that would best describe those constructs.</p>
 966
 967 </div>
 968
 969 <!-- ======================================================================= -->
 970 <div class="doc_subsection">
 971   <a name="ccxx_compile_units">C/C++ source file information</a>
 972 </div>
 973
 974 <div class="doc_text">
 975
 976 <p>Given the source files <tt>MySource.cpp</tt> and <tt>MyHeader.h</tt> located
 977    in the directory <tt>/Users/mine/sources</tt>, the following code:</p>
 978
 979 <div class="doc_code">
 980 <pre>
 981 #include "MyHeader.h"
 982
 983 int main(int argc, char *argv[]) {
 984   return 0;
 985 }
 986 </pre>
 987 </div>
 988
 989 <p>a C/C++ front-end would generate the following descriptors:</p>
 990
 991 <div class="doc_code">
 992 <pre>
 993 ...
 994 ;;
 995 ;; Define the compile unit for the source file "/Users/mine/sources/MySource.cpp".
 996 ;;
 997 !3 = metadata !{
 998   i32 458769,    ;; Tag
 999   i32 0,         ;; Unused
1000   i32 4,         ;; Language Id
1001   metadata !"MySource.cpp",
1002   metadata !"/Users/mine/sources",
1003   metadata !"4.2.1 (Based on Apple Inc. build 5649) (LLVM build 00)",
1004   i1 true,       ;; Main Compile Unit
1005   i1 false,      ;; Optimized compile unit
1006   metadata !"",  ;; Compiler flags
1007   i32 0}         ;; Runtime version
1008
1009 ;;
1010 ;; Define the compile unit for the header file "/Users/mine/sources/MyHeader.h".
1011 ;;
1012 !1 = metadata !{
1013   i32 458769,    ;; Tag
1014   i32 0,         ;; Unused
1015   i32 4,         ;; Language Id
1016   metadata !"MyHeader.h",
1017   metadata !"/Users/mine/sources",
1018   metadata !"4.2.1 (Based on Apple Inc. build 5649) (LLVM build 00)",
1019   i1 false,      ;; Main Compile Unit
1020   i1 false,      ;; Optimized compile unit
1021   metadata !"",  ;; Compiler flags
1022   i32 0}         ;; Runtime version
1023
1024 ...
1025 </pre>
1026 </div>
1027
1028 </div>
1029
1030 <!-- ======================================================================= -->
1031 <div class="doc_subsection">
1032   <a name="ccxx_global_variable">C/C++ global variable information</a>
1033 </div>
1034
1035 <div class="doc_text">
1036
1037 <p>Given an integer global variable declared as follows:</p>
1038
1039 <div class="doc_code">
1040 <pre>
1041 int MyGlobal = 100;
1042 </pre>
1043 </div>
1044
1045 <p>a C/C++ front-end would generate the following descriptors:</p>
1046
1047 <div class="doc_code">
1048 <pre>
1049 ;;
1050 ;; Define the global itself.
1051 ;;
1052 %MyGlobal = global int 100
1053 ...
1054 ;;
1055 ;; List of debug info of globals
1056 ;;
1057 !llvm.dbg.gv = !{!0}
1058
1059 ;;
1060 ;; Define the global variable descriptor.  Note the reference to the global
1061 ;; variable anchor and the global variable itself.
1062 ;;
1063 !0 = metadata !{
1064   i32 458804,              ;; Tag
1065   i32 0,                   ;; Unused
1066   metadata !1,             ;; Context
1067   metadata !"MyGlobal",    ;; Name
1068   metadata !"MyGlobal",    ;; Display Name
1069   metadata !"MyGlobal",    ;; Linkage Name
1070   metadata !1,             ;; Compile Unit
1071   i32 1,                   ;; Line Number
1072   metadata !2,             ;; Type
1073   i1 false,                ;; Is a local variable
1074   i1 true,                 ;; Is this a definition
1075   i32* @MyGlobal           ;; The global variable
1076 }
1077
1078 ;;
1079 ;; Define the basic type of 32 bit signed integer.  Note that since int is an
1080 ;; intrinsic type the source file is NULL and line 0.
1081 ;;
1082 !2 = metadata !{
1083   i32 458788,              ;; Tag
1084   metadata !1,             ;; Context
1085   metadata !"int",         ;; Name
1086   metadata !1,             ;; Compile Unit
1087   i32 0,                   ;; Line number
1088   i64 32,                  ;; Size in Bits
1089   i64 32,                  ;; Align in Bits
1090   i64 0,                   ;; Offset in Bits
1091   i32 0,                   ;; Flags
1092   i32 5                    ;; Encoding
1093 }
1094
1095 </pre>
1096 </div>
1097
1098 </div>
1099
1100 <!-- ======================================================================= -->
1101 <div class="doc_subsection">
1102   <a name="ccxx_subprogram">C/C++ function information</a>
1103 </div>
1104
1105 <div class="doc_text">
1106
1107 <p>Given a function declared as follows:</p>
1108
1109 <div class="doc_code">
1110 <pre>
1111 int main(int argc, char *argv[]) {
1112   return 0;
1113 }
1114 </pre>
1115 </div>
1116
1117 <p>a C/C++ front-end would generate the following descriptors:</p>
1118
1119 <div class="doc_code">
1120 <pre>
1121 ;;
1122 ;; Define the anchor for subprograms.  Note that the second field of the
1123 ;; anchor is 46, which is the same as the tag for subprograms
1124 ;; (46 = DW_TAG_subprogram.)
1125 ;;
1126 !0 = metadata !{
1127   i32 458798,        ;; Tag
1128   i32 0,             ;; Unused
1129   metadata !1,       ;; Context
1130   metadata !"main",  ;; Name
1131   metadata !"main",  ;; Display name
1132   metadata !"main",  ;; Linkage name
1133   metadata !1,       ;; Compile unit
1134   i32 1,             ;; Line number
1135   metadata !2,       ;; Type
1136   i1 false,          ;; Is local
1137   i1 true            ;; Is definition
1138 }
1139 ;;
1140 ;; Define the subprogram itself.
1141 ;;
1142 define i32 @main(i32 %argc, i8** %argv) {
1143 ...
1144 }
1145 </pre>
1146 </div>
1147
1148 </div>
1149
1150 <!-- ======================================================================= -->
1151 <div class="doc_subsection">
1152   <a name="ccxx_basic_types">C/C++ basic types</a>
1153 </div>
1154
1155 <div class="doc_text">
1156
1157 <p>The following are the basic type descriptors for C/C++ core types:</p>
1158
1159 </div>
1160
1161 <!-- ======================================================================= -->
1162 <div class="doc_subsubsection">
1163   <a name="ccxx_basic_type_bool">bool</a>
1164 </div>
1165
1166 <div class="doc_text">
1167
1168 <div class="doc_code">
1169 <pre>
1170 !2 = metadata !{
1171   i32 458788,        ;; Tag
1172   metadata !1,       ;; Context
1173   metadata !"bool",  ;; Name
1174   metadata !1,       ;; Compile Unit
1175   i32 0,             ;; Line number
1176   i64 8,             ;; Size in Bits
1177   i64 8,             ;; Align in Bits
1178   i64 0,             ;; Offset in Bits
1179   i32 0,             ;; Flags
1180   i32 2              ;; Encoding
1181 }
1182 </pre>
1183 </div>
1184
1185 </div>
1186
1187 <!-- ======================================================================= -->
1188 <div class="doc_subsubsection">
1189   <a name="ccxx_basic_char">char</a>
1190 </div>
1191
1192 <div class="doc_text">
1193
1194 <div class="doc_code">
1195 <pre>
1196 !2 = metadata !{
1197   i32 458788,        ;; Tag
1198   metadata !1,       ;; Context
1199   metadata !"char",  ;; Name
1200   metadata !1,       ;; Compile Unit
1201   i32 0,             ;; Line number
1202   i64 8,             ;; Size in Bits
1203   i64 8,             ;; Align in Bits
1204   i64 0,             ;; Offset in Bits
1205   i32 0,             ;; Flags
1206   i32 6              ;; Encoding
1207 }
1208 </pre>
1209 </div>
1210
1211 </div>
1212
1213 <!-- ======================================================================= -->
1214 <div class="doc_subsubsection">
1215   <a name="ccxx_basic_unsigned_char">unsigned char</a>
1216 </div>
1217
1218 <div class="doc_text">
1219
1220 <div class="doc_code">
1221 <pre>
1222 !2 = metadata !{
1223   i32 458788,        ;; Tag
1224   metadata !1,       ;; Context
1225   metadata !"unsigned char",
1226   metadata !1,       ;; Compile Unit
1227   i32 0,             ;; Line number
1228   i64 8,             ;; Size in Bits
1229   i64 8,             ;; Align in Bits
1230   i64 0,             ;; Offset in Bits
1231   i32 0,             ;; Flags
1232   i32 8              ;; Encoding
1233 }
1234 </pre>
1235 </div>
1236
1237 </div>
1238
1239 <!-- ======================================================================= -->
1240 <div class="doc_subsubsection">
1241   <a name="ccxx_basic_short">short</a>
1242 </div>
1243
1244 <div class="doc_text">
1245
1246 <div class="doc_code">
1247 <pre>
1248 !2 = metadata !{
1249   i32 458788,        ;; Tag
1250   metadata !1,       ;; Context
1251   metadata !"short int",
1252   metadata !1,       ;; Compile Unit
1253   i32 0,             ;; Line number
1254   i64 16,            ;; Size in Bits
1255   i64 16,            ;; Align in Bits
1256   i64 0,             ;; Offset in Bits
1257   i32 0,             ;; Flags
1258   i32 5              ;; Encoding
1259 }
1260 </pre>
1261 </div>
1262
1263 </div>
1264
1265 <!-- ======================================================================= -->
1266 <div class="doc_subsubsection">
1267   <a name="ccxx_basic_unsigned_short">unsigned short</a>
1268 </div>
1269
1270 <div class="doc_text">
1271
1272 <div class="doc_code">
1273 <pre>
1274 !2 = metadata !{
1275   i32 458788,        ;; Tag
1276   metadata !1,       ;; Context
1277   metadata !"short unsigned int",
1278   metadata !1,       ;; Compile Unit
1279   i32 0,             ;; Line number
1280   i64 16,            ;; Size in Bits
1281   i64 16,            ;; Align in Bits
1282   i64 0,             ;; Offset in Bits
1283   i32 0,             ;; Flags
1284   i32 7              ;; Encoding
1285 }
1286 </pre>
1287 </div>
1288
1289 </div>
1290
1291 <!-- ======================================================================= -->
1292 <div class="doc_subsubsection">
1293   <a name="ccxx_basic_int">int</a>
1294 </div>
1295
1296 <div class="doc_text">
1297
1298 <div class="doc_code">
1299 <pre>
1300 !2 = metadata !{
1301   i32 458788,        ;; Tag
1302   metadata !1,       ;; Context
1303   metadata !"int",   ;; Name
1304   metadata !1,       ;; Compile Unit
1305   i32 0,             ;; Line number
1306   i64 32,            ;; Size in Bits
1307   i64 32,            ;; Align in Bits
1308   i64 0,             ;; Offset in Bits
1309   i32 0,             ;; Flags
1310   i32 5              ;; Encoding
1311 }
1312 </pre></div>
1313
1314 </div>
1315
1316 <!-- ======================================================================= -->
1317 <div class="doc_subsubsection">
1318   <a name="ccxx_basic_unsigned_int">unsigned int</a>
1319 </div>
1320
1321 <div class="doc_text">
1322
1323 <div class="doc_code">
1324 <pre>
1325 !2 = metadata !{
1326   i32 458788,        ;; Tag
1327   metadata !1,       ;; Context
1328   metadata !"unsigned int",
1329   metadata !1,       ;; Compile Unit
1330   i32 0,             ;; Line number
1331   i64 32,            ;; Size in Bits
1332   i64 32,            ;; Align in Bits
1333   i64 0,             ;; Offset in Bits
1334   i32 0,             ;; Flags
1335   i32 7              ;; Encoding
1336 }
1337 </pre>
1338 </div>
1339
1340 </div>
1341
1342 <!-- ======================================================================= -->
1343 <div class="doc_subsubsection">
1344   <a name="ccxx_basic_long_long">long long</a>
1345 </div>
1346
1347 <div class="doc_text">
1348
1349 <div class="doc_code">
1350 <pre>
1351 !2 = metadata !{
1352   i32 458788,        ;; Tag
1353   metadata !1,       ;; Context
1354   metadata !"long long int",
1355   metadata !1,       ;; Compile Unit
1356   i32 0,             ;; Line number
1357   i64 64,            ;; Size in Bits
1358   i64 64,            ;; Align in Bits
1359   i64 0,             ;; Offset in Bits
1360   i32 0,             ;; Flags
1361   i32 5              ;; Encoding
1362 }
1363 </pre>
1364 </div>
1365
1366 </div>
1367
1368 <!-- ======================================================================= -->
1369 <div class="doc_subsubsection">
1370   <a name="ccxx_basic_unsigned_long_long">unsigned long long</a>
1371 </div>
1372
1373 <div class="doc_text">
1374
1375 <div class="doc_code">
1376 <pre>
1377 !2 = metadata !{
1378   i32 458788,        ;; Tag
1379   metadata !1,       ;; Context
1380   metadata !"long long unsigned int",
1381   metadata !1,       ;; Compile Unit
1382   i32 0,             ;; Line number
1383   i64 64,            ;; Size in Bits
1384   i64 64,            ;; Align in Bits
1385   i64 0,             ;; Offset in Bits
1386   i32 0,             ;; Flags
1387   i32 7              ;; Encoding
1388 }
1389 </pre>
1390 </div>
1391
1392 </div>
1393
1394 <!-- ======================================================================= -->
1395 <div class="doc_subsubsection">
1396   <a name="ccxx_basic_float">float</a>
1397 </div>
1398
1399 <div class="doc_text">
1400
1401 <div class="doc_code">
1402 <pre>
1403 !2 = metadata !{
1404   i32 458788,        ;; Tag
1405   metadata !1,       ;; Context
1406   metadata !"float",
1407   metadata !1,       ;; Compile Unit
1408   i32 0,             ;; Line number
1409   i64 32,            ;; Size in Bits
1410   i64 32,            ;; Align in Bits
1411   i64 0,             ;; Offset in Bits
1412   i32 0,             ;; Flags
1413   i32 4              ;; Encoding
1414 }
1415 </pre>
1416 </div>
1417
1418 </div>
1419
1420 <!-- ======================================================================= -->
1421 <div class="doc_subsubsection">
1422   <a name="ccxx_basic_double">double</a>
1423 </div>
1424
1425 <div class="doc_text">
1426
1427 <div class="doc_code">
1428 <pre>
1429 !2 = metadata !{
1430   i32 458788,        ;; Tag
1431   metadata !1,       ;; Context
1432   metadata !"double",;; Name
1433   metadata !1,       ;; Compile Unit
1434   i32 0,             ;; Line number
1435   i64 64,            ;; Size in Bits
1436   i64 64,            ;; Align in Bits
1437   i64 0,             ;; Offset in Bits
1438   i32 0,             ;; Flags
1439   i32 4              ;; Encoding
1440 }
1441 </pre>
1442 </div>
1443
1444 </div>
1445
1446 <!-- ======================================================================= -->
1447 <div class="doc_subsection">
1448   <a name="ccxx_derived_types">C/C++ derived types</a>
1449 </div>
1450
1451 <div class="doc_text">
1452
1453 <p>Given the following as an example of C/C++ derived type:</p>
1454
1455 <div class="doc_code">
1456 <pre>
1457 typedef const int *IntPtr;
1458 </pre>
1459 </div>
1460
1461 <p>a C/C++ front-end would generate the following descriptors:</p>
1462
1463 <div class="doc_code">
1464 <pre>
1465 ;;
1466 ;; Define the typedef "IntPtr".
1467 ;;
1468 !2 = metadata !{
1469   i32 458774,          ;; Tag
1470   metadata !1,         ;; Context
1471   metadata !"IntPtr",  ;; Name
1472   metadata !3,         ;; Compile unit
1473   i32 0,               ;; Line number
1474   i64 0,               ;; Size in bits
1475   i64 0,               ;; Align in bits
1476   i64 0,               ;; Offset in bits
1477   i32 0,               ;; Flags
1478   metadata !4          ;; Derived From type
1479 }
1480
1481 ;;
1482 ;; Define the pointer type.
1483 ;;
1484 !4 = metadata !{
1485   i32 458767,          ;; Tag
1486   metadata !1,         ;; Context
1487   metadata !"",        ;; Name
1488   metadata !1,         ;; Compile unit
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   metadata !5          ;; Derived From type
1495 }
1496 ;;
1497 ;; Define the const type.
1498 ;;
1499 !5 = metadata !{
1500   i32 458790,          ;; Tag
1501   metadata !1,         ;; Context
1502   metadata !"",        ;; Name
1503   metadata !1,         ;; Compile unit
1504   i32 0,               ;; Line number
1505   i64 32,              ;; Size in bits
1506   i64 32,              ;; Align in bits
1507   i64 0,               ;; Offset in bits
1508   i32 0,               ;; Flags
1509   metadata !6          ;; Derived From type
1510 }
1511 ;;
1512 ;; Define the int type.
1513 ;;
1514 !6 = metadata !{
1515   i32 458788,          ;; Tag
1516   metadata !1,         ;; Context
1517   metadata !"int",     ;; Name
1518   metadata !1,         ;; Compile unit
1519   i32 0,               ;; Line number
1520   i64 32,              ;; Size in bits
1521   i64 32,              ;; Align in bits
1522   i64 0,               ;; Offset in bits
1523   i32 0,               ;; Flags
1524   5                    ;; Encoding
1525 }
1526 </pre>
1527 </div>
1528
1529 </div>
1530
1531 <!-- ======================================================================= -->
1532 <div class="doc_subsection">
1533   <a name="ccxx_composite_types">C/C++ struct/union types</a>
1534 </div>
1535
1536 <div class="doc_text">
1537
1538 <p>Given the following as an example of C/C++ struct type:</p>
1539
1540 <div class="doc_code">
1541 <pre>
1542 struct Color {
1543   unsigned Red;
1544   unsigned Green;
1545   unsigned Blue;
1546 };
1547 </pre>
1548 </div>
1549
1550 <p>a C/C++ front-end would generate the following descriptors:</p>
1551
1552 <div class="doc_code">
1553 <pre>
1554 ;;
1555 ;; Define basic type for unsigned int.
1556 ;;
1557 !5 = metadata !{
1558   i32 458788,        ;; Tag
1559   metadata !1,       ;; Context
1560   metadata !"unsigned int",
1561   metadata !1,       ;; Compile Unit
1562   i32 0,             ;; Line number
1563   i64 32,            ;; Size in Bits
1564   i64 32,            ;; Align in Bits
1565   i64 0,             ;; Offset in Bits
1566   i32 0,             ;; Flags
1567   i32 7              ;; Encoding
1568 }
1569 ;;
1570 ;; Define composite type for struct Color.
1571 ;;
1572 !2 = metadata !{
1573   i32 458771,        ;; Tag
1574   metadata !1,       ;; Context
1575   metadata !"Color", ;; Name
1576   metadata !1,       ;; Compile unit
1577   i32 1,             ;; Line number
1578   i64 96,            ;; Size in bits
1579   i64 32,            ;; Align in bits
1580   i64 0,             ;; Offset in bits
1581   i32 0,             ;; Flags
1582   null,              ;; Derived From
1583   metadata !3,       ;; Elements
1584   i32 0              ;; Runtime Language
1585 }
1586
1587 ;;
1588 ;; Define the Red field.
1589 ;;
1590 !4 = metadata !{
1591   i32 458765,        ;; Tag
1592   metadata !1,       ;; Context
1593   metadata !"Red",   ;; Name
1594   metadata !1,       ;; Compile Unit
1595   i32 2,             ;; Line number
1596   i64 32,            ;; Size in bits
1597   i64 32,            ;; Align in bits
1598   i64 0,             ;; Offset in bits
1599   i32 0,             ;; Flags
1600   metadata !5        ;; Derived From type
1601 }
1602
1603 ;;
1604 ;; Define the Green field.
1605 ;;
1606 !6 = metadata !{
1607   i32 458765,        ;; Tag
1608   metadata !1,       ;; Context
1609   metadata !"Green", ;; Name
1610   metadata !1,       ;; Compile Unit
1611   i32 3,             ;; Line number
1612   i64 32,            ;; Size in bits
1613   i64 32,            ;; Align in bits
1614   i64 32,             ;; Offset in bits
1615   i32 0,             ;; Flags
1616   metadata !5        ;; Derived From type
1617 }
1618
1619 ;;
1620 ;; Define the Blue field.
1621 ;;
1622 !7 = metadata !{
1623   i32 458765,        ;; Tag
1624   metadata !1,       ;; Context
1625   metadata !"Blue",  ;; Name
1626   metadata !1,       ;; Compile Unit
1627   i32 4,             ;; Line number
1628   i64 32,            ;; Size in bits
1629   i64 32,            ;; Align in bits
1630   i64 64,             ;; Offset in bits
1631   i32 0,             ;; Flags
1632   metadata !5        ;; Derived From type
1633 }
1634
1635 ;;
1636 ;; Define the array of fields used by the composite type Color.
1637 ;;
1638 !3 = metadata !{metadata !4, metadata !6, metadata !7}
1639 </pre>
1640 </div>
1641
1642 </div>
1643
1644 <!-- ======================================================================= -->
1645 <div class="doc_subsection">
1646   <a name="ccxx_enumeration_types">C/C++ enumeration types</a>
1647 </div>
1648
1649 <div class="doc_text">
1650
1651 <p>Given the following as an example of C/C++ enumeration type:</p>
1652
1653 <div class="doc_code">
1654 <pre>
1655 enum Trees {
1656   Spruce = 100,
1657   Oak = 200,
1658   Maple = 300
1659 };
1660 </pre>
1661 </div>
1662
1663 <p>a C/C++ front-end would generate the following descriptors:</p>
1664
1665 <div class="doc_code">
1666 <pre>
1667 ;;
1668 ;; Define composite type for enum Trees
1669 ;;
1670 !2 = metadata !{
1671   i32 458756,        ;; Tag
1672   metadata !1,       ;; Context
1673   metadata !"Trees", ;; Name
1674   metadata !1,       ;; Compile unit
1675   i32 1,             ;; Line number
1676   i64 32,            ;; Size in bits
1677   i64 32,            ;; Align in bits
1678   i64 0,             ;; Offset in bits
1679   i32 0,             ;; Flags
1680   null,              ;; Derived From type
1681   metadata !3,       ;; Elements
1682   i32 0              ;; Runtime language
1683 }
1684
1685 ;;
1686 ;; Define the array of enumerators used by composite type Trees.
1687 ;;
1688 !3 = metadata !{metadata !4, metadata !5, metadata !6}
1689
1690 ;;
1691 ;; Define Spruce enumerator.
1692 ;;
1693 !4 = metadata !{i32 458792, metadata !"Spruce", i64 100}
1694
1695 ;;
1696 ;; Define Oak enumerator.
1697 ;;
1698 !5 = metadata !{i32 458792, metadata !"Oak", i64 200}
1699
1700 ;;
1701 ;; Define Maple enumerator.
1702 ;;
1703 !6 = metadata !{i32 458792, metadata !"Maple", i64 300}
1704
1705 </pre>
1706 </div>
1707
1708 </div>
1709
1710 <!-- *********************************************************************** -->
1711
1712 <hr>
1713 <address>
1714   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
1715   src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
1716   <a href="http://validator.w3.org/check/referer"><img
1717   src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
1718
1719   <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
1720   <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
1721   Last modified: $Date$
1722 </address>
1723
1724 </body>
1725 </html>