docs/SourceLevelDebugging.html

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