docs/SourceLevelDebugging.html

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