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