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=http://llvm.org/docs/TestingGuide.html#quicktestsuite>
 212 LLVM test suite </a> provides a framework to test optimizer's handling of
 213 debugging information. It can be run like this:</p>
 214
 215 <div class="doc_code">
 216 <pre>
 217 % cd llvm/projects/test-suite/MultiSource/Benchmarks  # or some other level
 218 % make TEST=dbgopt
 219 </pre>
 220 </div>
 221
 222 <p>
 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=//llvm.org/docs/TestingGuide.html> TestingGuide</a>
 226 for more information on LLVM test infratsture 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>sbyte*</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     sbyte*, ;; Source file name
 379     sbyte*, ;; Source file directory (includes trailing slash)
 380     sbyte*  ;; Producer (ex. "4.0.1 LLVM (LLVM research group)")
 381   }
 382 </pre>
 383
 384 <p>These descriptors contain a source language ID for the file (we use the Dwarf
 385 3.0 ID numbers, such as <tt>DW_LANG_C89</tt>, <tt>DW_LANG_C_plus_plus</tt>,
 386 <tt>DW_LANG_Cobol74</tt>, etc), three strings describing the filename, working
 387 directory of the compiler, and an identifier string for the compiler that
 388 produced it.</p>
 389
 390 <p> Compile unit descriptors provide the root context for objects declared in a
 391 specific source file.  Global variables and top level functions would be defined
 392 using this context.  Compile unit descriptors also provide context for source
 393 line correspondence.</p>
 394
 395 </div>
 396
 397 <!-- ======================================================================= -->
 398 <div class="doc_subsubsection">
 399   <a name="format_global_variables">Global variable descriptors</a>
 400 </div>
 401
 402 <div class="doc_text">
 403
 404 <pre>
 405   %<a href="#format_global_variables">llvm.dbg.global_variable.type</a> = type {
 406     uint,   ;; Tag = 52 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_variable)
 407     {  }*,  ;; Global variable anchor = cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_global_variables">llvm.dbg.global_variables</a> to {  }*),
 408     {  }*,  ;; Reference to context descriptor
 409     sbyte*, ;; Name
 410     sbyte*, ;; Display name (fully qualified C++ name)
 411     sbyte*, ;; MIPS linkage name (for C++)
 412     {  }*,  ;; Reference to compile unit where defined
 413     uint,   ;; Line number where defined
 414     {  }*,  ;; Reference to type descriptor
 415     bool,   ;; True if the global is local to compile unit (static)
 416     bool,   ;; True if the global is defined in the compile unit (not extern)
 417     {  }*   ;; Reference to the global variable
 418   }
 419 </pre>
 420
 421 <p>These descriptors provide debug information about globals variables.  The
 422 provide details such as name, type and where the variable is defined.</p>
 423
 424 </div>
 425
 426 <!-- ======================================================================= -->
 427 <div class="doc_subsubsection">
 428   <a name="format_subprograms">Subprogram descriptors</a>
 429 </div>
 430
 431 <div class="doc_text">
 432
 433 <pre>
 434   %<a href="#format_subprograms">llvm.dbg.subprogram.type</a> = type {
 435     uint,   ;; Tag = 46 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_subprogram)
 436     {  }*,  ;; Subprogram anchor = cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_subprograms">llvm.dbg.subprograms</a> to {  }*),
 437     {  }*,  ;; Reference to context descriptor
 438     sbyte*, ;; Name
 439     sbyte*, ;; Display name (fully qualified C++ name)
 440     sbyte*, ;; MIPS linkage name (for C++)
 441     {  }*,  ;; Reference to compile unit where defined
 442     uint,   ;; Line number where defined
 443     {  }*,  ;; Reference to type descriptor
 444     bool,   ;; True if the global is local to compile unit (static)
 445     bool    ;; True if the global is defined in the compile unit (not extern)
 446   }
 447 </pre>
 448
 449 <p>These descriptors provide debug information about functions, methods and
 450 subprograms.  They provide details such as name, return types and the source
 451 location where the subprogram is defined.</p>
 452
 453 </div>
 454 <!-- ======================================================================= -->
 455 <div class="doc_subsubsection">
 456   <a name="format_blocks">Block descriptors</a>
 457 </div>
 458
 459 <div class="doc_text">
 460
 461 <pre>
 462   %<a href="#format_blocks">llvm.dbg.block</a> = type {
 463     uint,   ;; Tag = 13 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_lexical_block)
 464     {  }*   ;; Reference to context descriptor
 465   }
 466 </pre>
 467
 468 <p>These descriptors provide debug information about nested blocks within a
 469 subprogram.  The array of member descriptors is used to define local variables
 470 and deeper nested blocks.</p>
 471
 472 </div>
 473
 474 <!-- ======================================================================= -->
 475 <div class="doc_subsubsection">
 476   <a name="format_basic_type">Basic type descriptors</a>
 477 </div>
 478
 479 <div class="doc_text">
 480
 481 <pre>
 482   %<a href="#format_basic_type">llvm.dbg.basictype.type</a> = type {
 483     uint,   ;; Tag = 36 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_base_type)
 484     {  }*,  ;; Reference to context (typically a compile unit)
 485     sbyte*, ;; Name (may be "" for anonymous types)
 486     {  }*,  ;; Reference to compile unit where defined (may be NULL)
 487     uint,   ;; Line number where defined (may be 0)
 488     uint,   ;; Size in bits
 489     uint,   ;; Alignment in bits
 490     uint,   ;; Offset in bits
 491     uint    ;; Dwarf type encoding
 492   }
 493 </pre>
 494
 495 <p>These descriptors define primitive types used in the code. Example int, bool
 496 and float.  The context provides the scope of the type, which is usually the top
 497 level.  Since basic types are not usually user defined the compile unit and line
 498 number can be left as NULL and 0.  The size, alignment and offset are expressed
 499 in bits and can be 64 bit values.  The alignment is used to round the offset
 500 when embedded in a <a href="#format_composite_type">composite type</a>
 501 (example to keep float doubles on 64 bit boundaries.) The offset is the bit
 502 offset if embedded in a <a href="#format_composite_type">composite
 503 type</a>.</p>
 504
 505 <p>The type encoding provides the details of the type.  The values are typically
 506 one of the following;</p>
 507
 508 <pre>
 509   DW_ATE_address = 1
 510   DW_ATE_boolean = 2
 511   DW_ATE_float = 4
 512   DW_ATE_signed = 5
 513   DW_ATE_signed_char = 6
 514   DW_ATE_unsigned = 7
 515   DW_ATE_unsigned_char = 8
 516 </pre>
 517
 518 </div>
 519
 520 <!-- ======================================================================= -->
 521 <div class="doc_subsubsection">
 522   <a name="format_derived_type">Derived type descriptors</a>
 523 </div>
 524
 525 <div class="doc_text">
 526
 527 <pre>
 528   %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> = type {
 529     uint,   ;; Tag (see below)
 530     {  }*,  ;; Reference to context
 531     sbyte*, ;; Name (may be "" for anonymous types)
 532     {  }*,  ;; Reference to compile unit where defined (may be NULL)
 533     uint,   ;; Line number where defined (may be 0)
 534     uint,   ;; Size in bits
 535     uint,   ;; Alignment in bits
 536     uint,   ;; Offset in bits
 537     {  }*   ;; Reference to type derived from
 538   }
 539 </pre>
 540
 541 <p>These descriptors are used to define types derived from other types.  The
 542 value of the tag varies depending on the meaning.  The following are possible
 543 tag values;</p>
 544
 545 <pre>
 546   DW_TAG_formal_parameter = 5
 547   DW_TAG_member = 13
 548   DW_TAG_pointer_type = 15
 549   DW_TAG_reference_type = 16
 550   DW_TAG_typedef = 22
 551   DW_TAG_const_type = 38
 552   DW_TAG_volatile_type = 53
 553   DW_TAG_restrict_type = 55
 554 </pre>
 555
 556 <p> <tt>DW_TAG_member</tt> is used to define a member of a <a
 557 href="#format_composite_type">composite type</a> or <a
 558 href="#format_subprograms">subprogram</a>.  The type of the member is the <a
 559 href="#format_derived_type">derived type</a>. <tt>DW_TAG_formal_parameter</tt>
 560 is used to define a member which is a formal argument of a subprogram.</p>
 561
 562 <p><tt>DW_TAG_typedef</tt> is used to
 563 provide a name for the derived type.</p>
 564
 565 <p><tt>DW_TAG_pointer_type</tt>,
 566 <tt>DW_TAG_reference_type</tt>, <tt>DW_TAG_const_type</tt>,
 567 <tt>DW_TAG_volatile_type</tt> and <tt>DW_TAG_restrict_type</tt> are used to
 568 qualify the <a href="#format_derived_type">derived type</a>. </p>
 569
 570 <p><a href="#format_derived_type">Derived type</a> location can be determined
 571 from the compile unit and line number.  The size, alignment and offset are
 572 expressed in bits and can be 64 bit values.  The alignment is used to round the
 573 offset when embedded in a <a href="#format_composite_type">composite type</a>
 574 (example to keep float doubles on 64 bit boundaries.) The offset is the bit
 575 offset if embedded in a <a href="#format_composite_type">composite
 576 type</a>.</p>
 577
 578 <p>Note that the <tt>void *</tt> type is expressed as a
 579 <tt>llvm.dbg.derivedtype.type</tt> with tag of <tt>DW_TAG_pointer_type</tt> and
 580 NULL derived type.</p>
 581
 582 </div>
 583
 584 <!-- ======================================================================= -->
 585 <div class="doc_subsubsection">
 586   <a name="format_composite_type">Composite type descriptors</a>
 587 </div>
 588
 589 <div class="doc_text">
 590
 591 <pre>
 592   %<a href="#format_composite_type">llvm.dbg.compositetype.type</a> = type {
 593     uint,   ;; Tag (see below)
 594     {  }*,  ;; Reference to context
 595     sbyte*, ;; Name (may be "" for anonymous types)
 596     {  }*,  ;; Reference to compile unit where defined (may be NULL)
 597     uint,   ;; Line number where defined (may be 0)
 598     uint,   ;; Size in bits
 599     uint,   ;; Alignment in bits
 600     uint,   ;; Offset in bits
 601     {  }*   ;; Reference to array of member descriptors
 602   }
 603 </pre>
 604
 605 <p>These descriptors are used to define types that are composed of 0 or more
 606 elements.  The value of the tag varies depending on the meaning.  The following
 607 are possible tag values;</p>
 608
 609 <pre>
 610   DW_TAG_array_type = 1
 611   DW_TAG_enumeration_type = 4
 612   DW_TAG_structure_type = 19
 613   DW_TAG_union_type = 23
 614   DW_TAG_vector_type = 259
 615   DW_TAG_subroutine_type = 46
 616   DW_TAG_inheritance = 26
 617 </pre>
 618
 619 <p>The vector flag indicates that an array type is a native packed vector.</p>
 620
 621 <p>The members of array types (tag = <tt>DW_TAG_array_type</tt>) or vector types
 622 (tag = <tt>DW_TAG_vector_type</tt>) are <a href="#format_subrange">subrange
 623 descriptors</a>, each representing the range of subscripts at that level of
 624 indexing.</p>
 625
 626 <p>The members of enumeration types (tag = <tt>DW_TAG_enumeration_type</tt>) are
 627 <a href="#format_enumeration">enumerator descriptors</a>, each representing the
 628 definition of enumeration value
 629 for the set.</p>
 630
 631 <p>The members of structure (tag = <tt>DW_TAG_structure_type</tt>) or union (tag
 632 = <tt>DW_TAG_union_type</tt>) types are any one of the <a
 633 href="#format_basic_type">basic</a>, <a href="#format_derived_type">derived</a>
 634 or <a href="#format_composite_type">composite</a> type descriptors, each
 635 representing a field member of the structure or union.</p>
 636
 637 <p>For C++ classes (tag = <tt>DW_TAG_structure_type</tt>), member descriptors
 638 provide information about base classes, static members and member functions. If
 639 a member is a <a href="#format_derived_type">derived type descriptor</a> and has
 640 a tag of <tt>DW_TAG_inheritance</tt>, then the type represents a base class. If
 641 the member of is a <a href="#format_global_variables">global variable
 642 descriptor</a> then it represents a static member.  And, if the member is a <a
 643 href="#format_subprograms">subprogram descriptor</a> then it represents a member
 644 function.  For static members and member functions, <tt>getName()</tt> returns
 645 the members link or the C++ mangled name.  <tt>getDisplayName()</tt> the
 646 simplied version of the name.</p>
 647
 648 <p>The first member of subroutine (tag = <tt>DW_TAG_subroutine_type</tt>)
 649 type elements is the return type for the subroutine.  The remaining
 650 elements are the formal arguments to the subroutine.</p>
 651
 652 <p><a href="#format_composite_type">Composite type</a> location can be
 653 determined from the compile unit and line number.  The size, alignment and
 654 offset are expressed in bits and can be 64 bit values.  The alignment is used to
 655 round the offset when embedded in a <a href="#format_composite_type">composite
 656 type</a> (as an example, to keep float doubles on 64 bit boundaries.) The offset
 657 is the bit offset if embedded in a <a href="#format_composite_type">composite
 658 type</a>.</p>
 659
 660 </div>
 661
 662 <!-- ======================================================================= -->
 663 <div class="doc_subsubsection">
 664   <a name="format_subrange">Subrange descriptors</a>
 665 </div>
 666
 667 <div class="doc_text">
 668
 669 <pre>
 670   %<a href="#format_subrange">llvm.dbg.subrange.type</a> = type {
 671     uint,   ;; Tag = 33 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_subrange_type)
 672     uint,   ;; Low value
 673     uint    ;; High value
 674   }
 675 </pre>
 676
 677 <p>These descriptors are used to define ranges of array subscripts for an array
 678 <a href="#format_composite_type">composite type</a>.  The low value defines the
 679 lower bounds typically zero for C/C++.  The high value is the upper bounds.
 680 Values are 64 bit.  High - low + 1 is the size of the array.  If
 681 low == high the array will be unbounded.</p>
 682
 683 </div>
 684
 685 <!-- ======================================================================= -->
 686 <div class="doc_subsubsection">
 687   <a name="format_enumeration">Enumerator descriptors</a>
 688 </div>
 689
 690 <div class="doc_text">
 691
 692 <pre>
 693   %<a href="#format_enumeration">llvm.dbg.enumerator.type</a> = type {
 694     uint,   ;; Tag = 40 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_enumerator)
 695     sbyte*, ;; Name
 696     uint    ;; Value
 697   }
 698 </pre>
 699
 700 <p>These descriptors are used to define members of an enumeration <a
 701 href="#format_composite_type">composite type</a>, it associates the name to the
 702 value.</p>
 703
 704 </div>
 705
 706 <!-- ======================================================================= -->
 707 <div class="doc_subsubsection">
 708   <a name="format_variables">Local variables</a>
 709 </div>
 710
 711 <div class="doc_text">
 712 <pre>
 713   %<a href="#format_variables">llvm.dbg.variable.type</a> = type {
 714     uint,    ;; Tag (see below)
 715     {  }*,   ;; Context
 716     sbyte*,  ;; Name
 717     {  }*,   ;; Reference to compile unit where defined
 718     uint,    ;; Line number where defined
 719     {  }*    ;; Type descriptor
 720   }
 721 </pre>
 722
 723 <p>These descriptors are used to define variables local to a sub program.  The
 724 value of the tag depends on the usage of the variable;</p>
 725
 726 <pre>
 727   DW_TAG_auto_variable = 256
 728   DW_TAG_arg_variable = 257
 729   DW_TAG_return_variable = 258
 730 </pre>
 731
 732 <p>An auto variable is any variable declared in the body of the function.  An
 733 argument variable is any variable that appears as a formal argument to the
 734 function.  A return variable is used to track the result of a function and has
 735 no source correspondent.</p>
 736
 737 <p>The context is either the subprogram or block where the variable is defined.
 738 Name the source variable name.  Compile unit and line indicate where the
 739 variable was defined. Type descriptor defines the declared type of the
 740 variable.</p>
 741
 742 </div>
 743
 744 <!-- ======================================================================= -->
 745 <div class="doc_subsection">
 746   <a name="format_common_intrinsics">Debugger intrinsic functions</a>
 747 </div>
 748
 749 <div class="doc_text">
 750
 751 <p>LLVM uses several intrinsic functions (name prefixed with "llvm.dbg") to
 752 provide debug information at various points in generated code.</p>
 753
 754 </div>
 755
 756 <!-- ======================================================================= -->
 757 <div class="doc_subsubsection">
 758   <a name="format_common_stoppoint">llvm.dbg.stoppoint</a>
 759 </div>
 760
 761 <div class="doc_text">
 762 <pre>
 763   void %<a href="#format_common_stoppoint">llvm.dbg.stoppoint</a>( uint, uint, { }* )
 764 </pre>
 765
 766 <p>This intrinsic is used to provide correspondence between the source file and
 767 the generated code.  The first argument is the line number (base 1), second
 768 argument is the column number (0 if unknown) and the third argument the source
 769 <tt>%<a href="#format_compile_units">llvm.dbg.compile_unit</a>*</tt> cast to a
 770 <tt>{ }*</tt>.  Code following a call to this intrinsic will have been defined
 771 in close proximity of the line, column and file.  This information holds until
 772 the next call to <tt>%<a
 773 href="#format_common_stoppoint">lvm.dbg.stoppoint</a></tt>.</p>
 774
 775 </div>
 776
 777 <!-- ======================================================================= -->
 778 <div class="doc_subsubsection">
 779   <a name="format_common_func_start">llvm.dbg.func.start</a>
 780 </div>
 781
 782 <div class="doc_text">
 783 <pre>
 784   void %<a href="#format_common_func_start">llvm.dbg.func.start</a>( { }* )
 785 </pre>
 786
 787 <p>This intrinsic is used to link the debug information in <tt>%<a
 788 href="#format_subprograms">llvm.dbg.subprogram</a></tt> to the function. It
 789 defines the beginning of the function's declarative region (scope). It also
 790 implies a call to %<tt><a
 791 href="#format_common_stoppoint">llvm.dbg.stoppoint</a></tt> which defines a
 792 source line "stop point". The intrinsic should be called early in the function
 793 after the all the alloca instructions.  It should be paired off with a closing
 794 <tt>%<a
 795 href="#format_common_region_end">llvm.dbg.region.end</a></tt>.  The function's
 796 single argument is the <tt>%<a
 797 href="#format_subprograms">llvm.dbg.subprogram.type</a></tt>.</p>
 798
 799 </div>
 800
 801 <!-- ======================================================================= -->
 802 <div class="doc_subsubsection">
 803   <a name="format_common_region_start">llvm.dbg.region.start</a>
 804 </div>
 805
 806 <div class="doc_text">
 807 <pre>
 808   void %<a href="#format_common_region_start">llvm.dbg.region.start</a>( { }* )
 809 </pre>
 810
 811 <p>This intrinsic is used to define the beginning of a declarative scope (ex.
 812 block) for local language elements.  It should be paired off with a closing
 813 <tt>%<a href="#format_common_region_end">llvm.dbg.region.end</a></tt>.  The
 814 function's single argument is the <tt>%<a
 815 href="#format_blocks">llvm.dbg.block</a></tt> which is starting.</p>
 816
 817
 818 </div>
 819
 820 <!-- ======================================================================= -->
 821 <div class="doc_subsubsection">
 822   <a name="format_common_region_end">llvm.dbg.region.end</a>
 823 </div>
 824
 825 <div class="doc_text">
 826 <pre>
 827   void %<a href="#format_common_region_end">llvm.dbg.region.end</a>( { }* )
 828 </pre>
 829
 830 <p>This intrinsic is used to define the end of a declarative scope (ex. block)
 831 for local language elements.  It should be paired off with an opening <tt>%<a
 832 href="#format_common_region_start">llvm.dbg.region.start</a></tt> or <tt>%<a
 833 href="#format_common_func_start">llvm.dbg.func.start</a></tt>.  The function's
 834 single argument is either the <tt>%<a
 835 href="#format_blocks">llvm.dbg.block</a></tt> or the <tt>%<a
 836 href="#format_subprograms">llvm.dbg.subprogram.type</a></tt> which is
 837 ending.</p>
 838
 839 </div>
 840
 841 <!-- ======================================================================= -->
 842 <div class="doc_subsubsection">
 843   <a name="format_common_declare">llvm.dbg.declare</a>
 844 </div>
 845
 846 <div class="doc_text">
 847 <pre>
 848   void %<a href="#format_common_declare">llvm.dbg.declare</a>( { } *, { }* )
 849 </pre>
 850
 851 <p>This intrinsic provides information about a local element (ex. variable.) The
 852 first argument is the alloca for the variable, cast to a <tt>{ }*</tt>. The
 853 second argument is the <tt>%<a
 854 href="#format_variables">llvm.dbg.variable</a></tt> containing the description
 855 of the variable, also cast to a <tt>{ }*</tt>.</p>
 856
 857 </div>
 858
 859 <!-- ======================================================================= -->
 860 <div class="doc_subsection">
 861   <a name="format_common_stoppoints">
 862      Representing stopping points in the source program
 863   </a>
 864 </div>
 865
 866 <div class="doc_text">
 867
 868 <p>LLVM debugger "stop points" are a key part of the debugging representation
 869 that allows the LLVM to maintain simple semantics for <a
 870 href="#debugopt">debugging optimized code</a>.  The basic idea is that the
 871 front-end inserts calls to the <a
 872 href="#format_common_stoppoint">%<tt>llvm.dbg.stoppoint</tt></a> intrinsic
 873 function at every point in the program where a debugger should be able to
 874 inspect the program (these correspond to places a debugger stops when you
 875 "<tt>step</tt>" through it).  The front-end can choose to place these as
 876 fine-grained as it would like (for example, before every subexpression
 877 evaluated), but it is recommended to only put them after every source statement
 878 that includes executable code.</p>
 879
 880 <p>Using calls to this intrinsic function to demark legal points for the
 881 debugger to inspect the program automatically disables any optimizations that
 882 could potentially confuse debugging information.  To non-debug-information-aware
 883 transformations, these calls simply look like calls to an external function,
 884 which they must assume to do anything (including reading or writing to any part
 885 of reachable memory).  On the other hand, it does not impact many optimizations,
 886 such as code motion of non-trapping instructions, nor does it impact
 887 optimization of subexpressions, code duplication transformations, or basic-block
 888 reordering transformations.</p>
 889
 890 </div>
 891
 892
 893 <!-- ======================================================================= -->
 894 <div class="doc_subsection">
 895   <a name="format_common_lifetime">Object lifetimes and scoping</a>
 896 </div>
 897
 898 <div class="doc_text">
 899 <p>In many languages, the local variables in functions can have their lifetime
 900 or scope limited to a subset of a function.  In the C family of languages, for
 901 example, variables are only live (readable and writable) within the source block
 902 that they are defined in.  In functional languages, values are only readable
 903 after they have been defined.  Though this is a very obvious concept, it is also
 904 non-trivial to model in LLVM, because it has no notion of scoping in this sense,
 905 and does not want to be tied to a language's scoping rules.</p>
 906
 907 <p>In order to handle this, the LLVM debug format uses the notion of "regions"
 908 of a function, delineated by calls to intrinsic functions.  These intrinsic
 909 functions define new regions of the program and indicate when the region
 910 lifetime expires.  Consider the following C fragment, for example:</p>
 911
 912 <pre>
 913 1.  void foo() {
 914 2.    int X = ...;
 915 3.    int Y = ...;
 916 4.    {
 917 5.      int Z = ...;
 918 6.      ...
 919 7.    }
 920 8.    ...
 921 9.  }
 922 </pre>
 923
 924 <p>Compiled to LLVM, this function would be represented like this:</p>
 925
 926 <pre>
 927 void %foo() {
 928 entry:
 929     %X = alloca int
 930     %Y = alloca int
 931     %Z = alloca int
 932
 933     ...
 934
 935     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 )
 936
 937     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 )
 938
 939     call void %<a href="#format_common_declare">llvm.dbg.declare</a>({}* %X, ...)
 940     call void %<a href="#format_common_declare">llvm.dbg.declare</a>({}* %Y, ...)
 941
 942     <i>;; Evaluate expression on line 2, assigning to X.</i>
 943
 944     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 )
 945
 946     <i>;; Evaluate expression on line 3, assigning to Y.</i>
 947
 948     call void %<a href="#format_common_stoppoint">llvm.region.start</a>()
 949     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 )
 950     call void %<a href="#format_common_declare">llvm.dbg.declare</a>({}* %X, ...)
 951
 952     <i>;; Evaluate expression on line 5, assigning to Z.</i>
 953
 954     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 )
 955     call void %<a href="#format_common_region_end">llvm.region.end</a>()
 956
 957     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 )
 958
 959     call void %<a href="#format_common_region_end">llvm.region.end</a>()
 960
 961     ret void
 962 }
 963 </pre>
 964
 965 <p>This example illustrates a few important details about the LLVM debugging
 966 information.  In particular, it shows how the various intrinsics are applied
 967 together to allow a debugger to analyze the relationship between statements,
 968 variable definitions, and the code used to implement the function.</p>
 969
 970 <p>The first intrinsic <tt>%<a
 971 href="#format_common_func_start">llvm.dbg.func.start</a></tt> provides
 972 a link with the <a href="#format_subprograms">subprogram descriptor</a>
 973 containing the details of this function.  This call also defines the beginning
 974 of the function region, bounded by the <tt>%<a
 975 href="#format_common_region_end">llvm.region.end</a></tt> at the end of
 976 the function.  This region is used to bracket the lifetime of variables declared
 977 within.  For a function, this outer region defines a new stack frame whose
 978 lifetime ends when the region is ended.</p>
 979
 980 <p>It is possible to define inner regions for short term variables by using the
 981 %<a href="#format_common_stoppoint"><tt>llvm.region.start</tt></a> and <a
 982 href="#format_common_region_end"><tt>%llvm.region.end</tt></a> to bound a
 983 region.  The inner region in this example would be for the block containing the
 984 declaration of Z.</p>
 985
 986 <p>Using regions to represent the boundaries of source-level functions allow
 987 LLVM interprocedural optimizations to arbitrarily modify LLVM functions without
 988 having to worry about breaking mapping information between the LLVM code and the
 989 and source-level program.  In particular, the inliner requires no modification
 990 to support inlining with debugging information: there is no explicit correlation
 991 drawn between LLVM functions and their source-level counterparts (note however,
 992 that if the inliner inlines all instances of a non-strong-linkage function into
 993 its caller that it will not be possible for the user to manually invoke the
 994 inlined function from a debugger).</p>
 995
 996 <p>Once the function has been defined, the <a
 997 href="#format_common_stoppoint"><tt>stopping point</tt></a> corresponding to
 998 line #2 (column #2) of the function is encountered.  At this point in the
 999 function, <b>no</b> local variables are live.  As lines 2 and 3 of the example
1000 are executed, their variable definitions are introduced into the program using
1001 %<a href="#format_common_declare"><tt>llvm.dbg.declare</tt></a>, without the
1002 need to specify a new region.  These variables do not require new regions to be
1003 introduced because they go out of scope at the same point in the program: line
1004 9.</p>
1005
1006 <p>In contrast, the <tt>Z</tt> variable goes out of scope at a different time,
1007 on line 7.  For this reason, it is defined within the inner region, which kills
1008 the availability of <tt>Z</tt> before the code for line 8 is executed.  In this
1009 way, regions can support arbitrary source-language scoping rules, as long as
1010 they can only be nested (ie, one scope cannot partially overlap with a part of
1011 another scope).</p>
1012
1013 <p>It is worth noting that this scoping mechanism is used to control scoping of
1014 all declarations, not just variable declarations.  For example, the scope of a
1015 C++ using declaration is controlled with this and could change how name lookup is
1016 performed.</p>
1017
1018 </div>
1019
1020
1021
1022 <!-- *********************************************************************** -->
1023 <div class="doc_section">
1024   <a name="ccxx_frontend">C/C++ front-end specific debug information</a>
1025 </div>
1026 <!-- *********************************************************************** -->
1027
1028 <div class="doc_text">
1029
1030 <p>The C and C++ front-ends represent information about the program in a format
1031 that is effectively identical to <a
1032 href="http://www.eagercon.com/dwarf/dwarf3std.htm">Dwarf 3.0</a> in terms of
1033 information content.  This allows code generators to trivially support native
1034 debuggers by generating standard dwarf information, and contains enough
1035 information for non-dwarf targets to translate it as needed.</p>
1036
1037 <p>This section describes the forms used to represent C and C++ programs. Other
1038 languages could pattern themselves after this (which itself is tuned to
1039 representing programs in the same way that Dwarf 3 does), or they could choose
1040 to provide completely different forms if they don't fit into the Dwarf model.
1041 As support for debugging information gets added to the various LLVM
1042 source-language front-ends, the information used should be documented here.</p>
1043
1044 <p>The following sections provide examples of various C/C++ constructs and the
1045 debug information that would best describe those constructs.</p>
1046
1047 </div>
1048
1049 <!-- ======================================================================= -->
1050 <div class="doc_subsection">
1051   <a name="ccxx_compile_units">C/C++ source file information</a>
1052 </div>
1053
1054 <div class="doc_text">
1055
1056 <p>Given the source files "MySource.cpp" and "MyHeader.h" located in the
1057 directory "/Users/mine/sources", the following code;</p>
1058
1059 <pre>
1060 #include "MyHeader.h"
1061
1062 int main(int argc, char *argv[]) {
1063   return 0;
1064 }
1065 </pre>
1066
1067 <p>a C/C++ front-end would generate the following descriptors;</p>
1068
1069 <pre>
1070 ...
1071 ;;
1072 ;; Define types used.  In this case we need one for compile unit anchors and one
1073 ;; for compile units.
1074 ;;
1075 %<a href="#format_anchors">llvm.dbg.anchor.type</a> = type { uint, uint }
1076 %<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> = type { uint, {  }*, uint, uint, sbyte*, sbyte*, sbyte* }
1077 ...
1078 ;;
1079 ;; Define the anchor for compile units.  Note that the second field of the
1080 ;; anchor is 17, which is the same as the tag for compile units
1081 ;; (17 = DW_TAG_compile_unit.)
1082 ;;
1083 %<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"
1084
1085 ;;
1086 ;; Define the compile unit for the source file "/Users/mine/sources/MySource.cpp".
1087 ;;
1088 %<a href="#format_compile_units">llvm.dbg.compile_unit1</a> = internal constant %<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> {
1089     uint add(uint 17, uint 262144),
1090     {  }* cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_units</a> to {  }*),
1091     uint 1,
1092     uint 1,
1093     sbyte* getelementptr ([13 x sbyte]* %str1, int 0, int 0),
1094     sbyte* getelementptr ([21 x sbyte]* %str2, int 0, int 0),
1095     sbyte* getelementptr ([33 x sbyte]* %str3, int 0, int 0) }, section "llvm.metadata"
1096
1097 ;;
1098 ;; Define the compile unit for the header file "/Users/mine/sources/MyHeader.h".
1099 ;;
1100 %<a href="#format_compile_units">llvm.dbg.compile_unit2</a> = internal constant %<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> {
1101     uint add(uint 17, uint 262144),
1102     {  }* cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_units</a> to {  }*),
1103     uint 1,
1104     uint 1,
1105     sbyte* getelementptr ([11 x sbyte]* %str4, int 0, int 0),
1106     sbyte* getelementptr ([21 x sbyte]* %str2, int 0, int 0),
1107     sbyte* getelementptr ([33 x sbyte]* %str3, int 0, int 0) }, section "llvm.metadata"
1108
1109 ;;
1110 ;; Define each of the strings used in the compile units.
1111 ;;
1112 %str1 = internal constant [13 x sbyte] c"MySource.cpp\00", section "llvm.metadata";
1113 %str2 = internal constant [21 x sbyte] c"/Users/mine/sources/\00", section "llvm.metadata";
1114 %str3 = internal constant [33 x sbyte] c"4.0.1 LLVM (LLVM research group)\00", section "llvm.metadata";
1115 %str4 = internal constant [11 x sbyte] c"MyHeader.h\00", section "llvm.metadata";
1116 ...
1117 </pre>
1118
1119 </div>
1120
1121 <!-- ======================================================================= -->
1122 <div class="doc_subsection">
1123   <a name="ccxx_global_variable">C/C++ global variable information</a>
1124 </div>
1125
1126 <div class="doc_text">
1127
1128 <p>Given an integer global variable declared as follows;</p>
1129
1130 <pre>
1131 int MyGlobal = 100;
1132 </pre>
1133
1134 <p>a C/C++ front-end would generate the following descriptors;</p>
1135
1136 <pre>
1137 ;;
1138 ;; Define types used. One for global variable anchors, one for the global
1139 ;; variable descriptor, one for the global's basic type and one for the global's
1140 ;; compile unit.
1141 ;;
1142 %<a href="#format_anchors">llvm.dbg.anchor.type</a> = type { uint, uint }
1143 %<a href="#format_global_variables">llvm.dbg.global_variable.type</a> = type { uint, {  }*, {  }*, sbyte*, {  }*, uint, {  }*, bool, bool, {  }*, uint }
1144 %<a href="#format_basic_type">llvm.dbg.basictype.type</a> = type { uint, {  }*, sbyte*, {  }*, int, uint, uint, uint, uint }
1145 %<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> = ...
1146 ...
1147 ;;
1148 ;; Define the global itself.
1149 ;;
1150 %MyGlobal = global int 100
1151 ...
1152 ;;
1153 ;; Define the anchor for global variables.  Note that the second field of the
1154 ;; anchor is 52, which is the same as the tag for global variables
1155 ;; (52 = DW_TAG_variable.)
1156 ;;
1157 %<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"
1158
1159 ;;
1160 ;; Define the global variable descriptor.  Note the reference to the global
1161 ;; variable anchor and the global variable itself.
1162 ;;
1163 %<a href="#format_global_variables">llvm.dbg.global_variable</a> = internal constant %<a href="#format_global_variables">llvm.dbg.global_variable.type</a> {
1164     uint add(uint 52, uint 262144),
1165     {  }* cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_global_variables">llvm.dbg.global_variables</a> to {  }*),
1166     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1167     sbyte* getelementptr ([9 x sbyte]* %str1, int 0, int 0),
1168     sbyte* getelementptr ([1 x sbyte]* %str2, int 0, int 0),
1169     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1170     uint 1,
1171     {  }* cast (%<a href="#format_basic_type">llvm.dbg.basictype.type</a>* %<a href="#format_basic_type">llvm.dbg.basictype</a> to {  }*),
1172     bool false,
1173     bool true,
1174     {  }* cast (int* %MyGlobal to {  }*) }, section "llvm.metadata"
1175
1176 ;;
1177 ;; Define the basic type of 32 bit signed integer.  Note that since int is an
1178 ;; intrinsic type the source file is NULL and line 0.
1179 ;;
1180 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1181     uint add(uint 36, uint 262144),
1182     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1183     sbyte* getelementptr ([4 x sbyte]* %str3, int 0, int 0),
1184     {  }* null,
1185     int 0,
1186     uint 32,
1187     uint 32,
1188     uint 0,
1189     uint 5 }, section "llvm.metadata"
1190
1191 ;;
1192 ;; Define the names of the global variable and basic type.
1193 ;;
1194 %str1 = internal constant [9 x sbyte] c"MyGlobal\00", section "llvm.metadata"
1195 %str2 = internal constant [1 x sbyte] c"\00", section "llvm.metadata"
1196 %str3 = internal constant [4 x sbyte] c"int\00", section "llvm.metadata"
1197 </pre>
1198
1199 </div>
1200
1201 <!-- ======================================================================= -->
1202 <div class="doc_subsection">
1203   <a name="ccxx_subprogram">C/C++ function information</a>
1204 </div>
1205
1206 <div class="doc_text">
1207
1208 <p>Given a function declared as follows;</p>
1209
1210 <pre>
1211 int main(int argc, char *argv[]) {
1212   return 0;
1213 }
1214 </pre>
1215
1216 <p>a C/C++ front-end would generate the following descriptors;</p>
1217
1218 <pre>
1219 ;;
1220 ;; Define types used. One for subprogram anchors, one for the subprogram
1221 ;; descriptor, one for the global's basic type and one for the subprogram's
1222 ;; compile unit.
1223 ;;
1224 %<a href="#format_subprograms">llvm.dbg.subprogram.type</a> = type { uint, {  }*, {  }*, sbyte*, {  }*, bool, bool }
1225 %<a href="#format_anchors">llvm.dbg.anchor.type</a> = type { uint, uint }
1226 %<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> = ...
1227
1228 ;;
1229 ;; Define the anchor for subprograms.  Note that the second field of the
1230 ;; anchor is 46, which is the same as the tag for subprograms
1231 ;; (46 = DW_TAG_subprogram.)
1232 ;;
1233 %<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"
1234
1235 ;;
1236 ;; Define the descriptor for the subprogram.  TODO - more details.
1237 ;;
1238 %<a href="#format_subprograms">llvm.dbg.subprogram</a> = internal constant %<a href="#format_subprograms">llvm.dbg.subprogram.type</a> {
1239     uint add(uint 46, uint 262144),
1240     {  }* cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_subprograms">llvm.dbg.subprograms</a> to {  }*),
1241     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1242     sbyte* getelementptr ([5 x sbyte]* %str1, int 0, int 0),
1243     sbyte* getelementptr ([1 x sbyte]* %str2, int 0, int 0),
1244     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1245     uint 1,
1246     {  }* null,
1247     bool false,
1248     bool true }, section "llvm.metadata"
1249
1250 ;;
1251 ;; Define the name of the subprogram.
1252 ;;
1253 %str1 = internal constant [5 x sbyte] c"main\00", section "llvm.metadata"
1254 %str2 = internal constant [1 x sbyte] c"\00", section "llvm.metadata"
1255
1256 ;;
1257 ;; Define the subprogram itself.
1258 ;;
1259 int %main(int %argc, sbyte** %argv) {
1260 ...
1261 }
1262 </pre>
1263
1264 </div>
1265
1266 <!-- ======================================================================= -->
1267 <div class="doc_subsection">
1268   <a name="ccxx_basic_types">C/C++ basic types</a>
1269 </div>
1270
1271 <div class="doc_text">
1272
1273 <p>The following are the basic type descriptors for C/C++ core types;</p>
1274
1275 </div>
1276
1277 <!-- ======================================================================= -->
1278 <div class="doc_subsubsection">
1279   <a name="ccxx_basic_type_bool">bool</a>
1280 </div>
1281
1282 <div class="doc_text">
1283
1284 <pre>
1285 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1286     uint add(uint 36, uint 262144),
1287     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1288     sbyte* getelementptr ([5 x sbyte]* %str1, int 0, int 0),
1289     {  }* null,
1290     int 0,
1291     uint 32,
1292     uint 32,
1293     uint 0,
1294     uint 2 }, section "llvm.metadata"
1295 %str1 = internal constant [5 x sbyte] c"bool\00", section "llvm.metadata"
1296 </pre>
1297
1298 </div>
1299
1300 <!-- ======================================================================= -->
1301 <div class="doc_subsubsection">
1302   <a name="ccxx_basic_char">char</a>
1303 </div>
1304
1305 <div class="doc_text">
1306
1307 <pre>
1308 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1309     uint add(uint 36, uint 262144),
1310     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1311     sbyte* getelementptr ([5 x sbyte]* %str1, int 0, int 0),
1312     {  }* null,
1313     int 0,
1314     uint 8,
1315     uint 8,
1316     uint 0,
1317     uint 6 }, section "llvm.metadata"
1318 %str1 = internal constant [5 x sbyte] c"char\00", section "llvm.metadata"
1319 </pre>
1320
1321 </div>
1322
1323 <!-- ======================================================================= -->
1324 <div class="doc_subsubsection">
1325   <a name="ccxx_basic_unsigned_char">unsigned char</a>
1326 </div>
1327
1328 <div class="doc_text">
1329
1330 <pre>
1331 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1332     uint add(uint 36, uint 262144),
1333     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1334     sbyte* getelementptr ([14 x sbyte]* %str1, int 0, int 0),
1335     {  }* null,
1336     int 0,
1337     uint 8,
1338     uint 8,
1339     uint 0,
1340     uint 8 }, section "llvm.metadata"
1341 %str1 = internal constant [14 x sbyte] c"unsigned char\00", section "llvm.metadata"
1342 </pre>
1343
1344 </div>
1345
1346 <!-- ======================================================================= -->
1347 <div class="doc_subsubsection">
1348   <a name="ccxx_basic_short">short</a>
1349 </div>
1350
1351 <div class="doc_text">
1352
1353 <pre>
1354 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1355     uint add(uint 36, uint 262144),
1356     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1357     sbyte* getelementptr ([10 x sbyte]* %str1, int 0, int 0),
1358     {  }* null,
1359     int 0,
1360     uint 16,
1361     uint 16,
1362     uint 0,
1363     uint 5 }, section "llvm.metadata"
1364 %str1 = internal constant [10 x sbyte] c"short int\00", section "llvm.metadata"
1365 </pre>
1366
1367 </div>
1368
1369 <!-- ======================================================================= -->
1370 <div class="doc_subsubsection">
1371   <a name="ccxx_basic_unsigned_short">unsigned short</a>
1372 </div>
1373
1374 <div class="doc_text">
1375
1376 <pre>
1377 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1378     uint add(uint 36, uint 262144),
1379     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1380     sbyte* getelementptr ([19 x sbyte]* %str1, int 0, int 0),
1381     {  }* null,
1382     int 0,
1383     uint 16,
1384     uint 16,
1385     uint 0,
1386     uint 7 }, section "llvm.metadata"
1387 %str1 = internal constant [19 x sbyte] c"short unsigned int\00", section "llvm.metadata"
1388 </pre>
1389
1390 </div>
1391
1392 <!-- ======================================================================= -->
1393 <div class="doc_subsubsection">
1394   <a name="ccxx_basic_int">int</a>
1395 </div>
1396
1397 <div class="doc_text">
1398
1399 <pre>
1400 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1401     uint add(uint 36, uint 262144),
1402     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1403     sbyte* getelementptr ([4 x sbyte]* %str1, int 0, int 0),
1404     {  }* null,
1405     int 0,
1406     uint 32,
1407     uint 32,
1408     uint 0,
1409     uint 5 }, section "llvm.metadata"
1410 %str1 = internal constant [4 x sbyte] c"int\00", section "llvm.metadata"
1411 </pre>
1412
1413 </div>
1414
1415 <!-- ======================================================================= -->
1416 <div class="doc_subsubsection">
1417   <a name="ccxx_basic_unsigned_int">unsigned int</a>
1418 </div>
1419
1420 <div class="doc_text">
1421
1422 <pre>
1423 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1424     uint add(uint 36, uint 262144),
1425     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1426     sbyte* getelementptr ([13 x sbyte]* %str1, int 0, int 0),
1427     {  }* null,
1428     int 0,
1429     uint 32,
1430     uint 32,
1431     uint 0,
1432     uint 7 }, section "llvm.metadata"
1433 %str1 = internal constant [13 x sbyte] c"unsigned int\00", section "llvm.metadata"
1434 </pre>
1435
1436 </div>
1437
1438 <!-- ======================================================================= -->
1439 <div class="doc_subsubsection">
1440   <a name="ccxx_basic_long_long">long long</a>
1441 </div>
1442
1443 <div class="doc_text">
1444
1445 <pre>
1446 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1447     uint add(uint 36, uint 262144),
1448     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1449     sbyte* getelementptr ([14 x sbyte]* %str1, int 0, int 0),
1450     {  }* null,
1451     int 0,
1452     uint 64,
1453     uint 64,
1454     uint 0,
1455     uint 5 }, section "llvm.metadata"
1456 %str1 = internal constant [14 x sbyte] c"long long int\00", section "llvm.metadata"
1457 </pre>
1458
1459 </div>
1460
1461 <!-- ======================================================================= -->
1462 <div class="doc_subsubsection">
1463   <a name="ccxx_basic_unsigned_long_long">unsigned long long</a>
1464 </div>
1465
1466 <div class="doc_text">
1467
1468 <pre>
1469 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1470     uint add(uint 36, uint 262144),
1471     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1472     sbyte* getelementptr ([23 x sbyte]* %str1, int 0, int 0),
1473     {  }* null,
1474     int 0,
1475     uint 64,
1476     uint 64,
1477     uint 0,
1478     uint 7 }, section "llvm.metadata"
1479 %str1 = internal constant [23 x sbyte] c"long long unsigned int\00", section "llvm.metadata"
1480 </pre>
1481
1482 </div>
1483
1484 <!-- ======================================================================= -->
1485 <div class="doc_subsubsection">
1486   <a name="ccxx_basic_float">float</a>
1487 </div>
1488
1489 <div class="doc_text">
1490
1491 <pre>
1492 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1493     uint add(uint 36, uint 262144),
1494     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1495     sbyte* getelementptr ([6 x sbyte]* %str1, int 0, int 0),
1496     {  }* null,
1497     int 0,
1498     uint 32,
1499     uint 32,
1500     uint 0,
1501     uint 4 }, section "llvm.metadata"
1502 %str1 = internal constant [6 x sbyte] c"float\00", section "llvm.metadata"
1503 </pre>
1504
1505 </div>
1506
1507 <!-- ======================================================================= -->
1508 <div class="doc_subsubsection">
1509   <a name="ccxx_basic_double">double</a>
1510 </div>
1511
1512 <div class="doc_text">
1513
1514 <pre>
1515 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1516     uint add(uint 36, uint 262144),
1517     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1518     sbyte* getelementptr ([7 x sbyte]* %str1, int 0, int 0),
1519     {  }* null,
1520     int 0,
1521     uint 64,
1522     uint 64,
1523     uint 0,
1524     uint 4 }, section "llvm.metadata"
1525 %str1 = internal constant [7 x sbyte] c"double\00", section "llvm.metadata"
1526 </pre>
1527
1528 </div>
1529
1530 <!-- ======================================================================= -->
1531 <div class="doc_subsection">
1532   <a name="ccxx_derived_types">C/C++ derived types</a>
1533 </div>
1534
1535 <div class="doc_text">
1536
1537 <p>Given the following as an example of C/C++ derived type;</p>
1538
1539 <pre>
1540 typedef const int *IntPtr;
1541 </pre>
1542
1543 <p>a C/C++ front-end would generate the following descriptors;</p>
1544
1545 <pre>
1546 ;;
1547 ;; Define the typedef "IntPtr".
1548 ;;
1549 %<a href="#format_derived_type">llvm.dbg.derivedtype1</a> = internal constant %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> {
1550     uint add(uint 22, uint 262144),
1551     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1552     sbyte* getelementptr ([7 x sbyte]* %str1, int 0, int 0),
1553     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1554     int 1,
1555     uint 0,
1556     uint 0,
1557     uint 0,
1558     {  }* cast (%<a href="#format_derived_type">llvm.dbg.derivedtype.type</a>* %<a href="#format_derived_type">llvm.dbg.derivedtype2</a> to {  }*) }, section "llvm.metadata"
1559 %str1 = internal constant [7 x sbyte] c"IntPtr\00", section "llvm.metadata"
1560
1561 ;;
1562 ;; Define the pointer type.
1563 ;;
1564 %<a href="#format_derived_type">llvm.dbg.derivedtype2</a> = internal constant %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> {
1565     uint add(uint 15, uint 262144),
1566     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1567     sbyte* null,
1568     {  }* null,
1569     int 0,
1570     uint 32,
1571     uint 32,
1572     uint 0,
1573     {  }* cast (%<a href="#format_derived_type">llvm.dbg.derivedtype.type</a>* %<a href="#format_derived_type">llvm.dbg.derivedtype3</a> to {  }*) }, section "llvm.metadata"
1574
1575 ;;
1576 ;; Define the const type.
1577 ;;
1578 %<a href="#format_derived_type">llvm.dbg.derivedtype3</a> = internal constant %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> {
1579     uint add(uint 38, uint 262144),
1580     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1581     sbyte* null,
1582     {  }* null,
1583     int 0,
1584     uint 0,
1585     uint 0,
1586     uint 0,
1587     {  }* cast (%<a href="#format_basic_type">llvm.dbg.basictype.type</a>* %<a href="#format_basic_type">llvm.dbg.basictype1</a> to {  }*) }, section "llvm.metadata"
1588
1589 ;;
1590 ;; Define the int type.
1591 ;;
1592 %<a href="#format_basic_type">llvm.dbg.basictype1</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1593     uint add(uint 36, uint 262144),
1594     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1595     sbyte* getelementptr ([4 x sbyte]* %str2, int 0, int 0),
1596     {  }* null,
1597     int 0,
1598     uint 32,
1599     uint 32,
1600     uint 0,
1601     uint 5 }, section "llvm.metadata"
1602 %str2 = internal constant [4 x sbyte] c"int\00", section "llvm.metadata"
1603 </pre>
1604
1605 </div>
1606
1607 <!-- ======================================================================= -->
1608 <div class="doc_subsection">
1609   <a name="ccxx_composite_types">C/C++ struct/union types</a>
1610 </div>
1611
1612 <div class="doc_text">
1613
1614 <p>Given the following as an example of C/C++ struct type;</p>
1615
1616 <pre>
1617 struct Color {
1618   unsigned Red;
1619   unsigned Green;
1620   unsigned Blue;
1621 };
1622 </pre>
1623
1624 <p>a C/C++ front-end would generate the following descriptors;</p>
1625
1626 <pre>
1627 ;;
1628 ;; Define basic type for unsigned int.
1629 ;;
1630 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1631     uint add(uint 36, uint 262144),
1632     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1633     sbyte* getelementptr ([13 x sbyte]* %str1, int 0, int 0),
1634     {  }* null,
1635     int 0,
1636     uint 32,
1637     uint 32,
1638     uint 0,
1639     uint 7 }, section "llvm.metadata"
1640 %str1 = internal constant [13 x sbyte] c"unsigned int\00", section "llvm.metadata"
1641
1642 ;;
1643 ;; Define composite type for struct Color.
1644 ;;
1645 %<a href="#format_composite_type">llvm.dbg.compositetype</a> = internal constant %<a href="#format_composite_type">llvm.dbg.compositetype.type</a> {
1646     uint add(uint 19, uint 262144),
1647     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1648     sbyte* getelementptr ([6 x sbyte]* %str2, int 0, int 0),
1649     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1650     int 1,
1651     uint 96,
1652     uint 32,
1653     uint 0,
1654     {  }* null,
1655     {  }* cast ([3 x {  }*]* %llvm.dbg.array to {  }*) }, section "llvm.metadata"
1656 %str2 = internal constant [6 x sbyte] c"Color\00", section "llvm.metadata"
1657
1658 ;;
1659 ;; Define the Red field.
1660 ;;
1661 %<a href="#format_derived_type">llvm.dbg.derivedtype1</a> = internal constant %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> {
1662     uint add(uint 13, uint 262144),
1663     {  }* null,
1664     sbyte* getelementptr ([4 x sbyte]* %str3, int 0, int 0),
1665     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1666     int 2,
1667     uint 32,
1668     uint 32,
1669     uint 0,
1670     {  }* cast (%<a href="#format_basic_type">llvm.dbg.basictype.type</a>* %<a href="#format_basic_type">llvm.dbg.basictype</a> to {  }*) }, section "llvm.metadata"
1671 %str3 = internal constant [4 x sbyte] c"Red\00", section "llvm.metadata"
1672
1673 ;;
1674 ;; Define the Green field.
1675 ;;
1676 %<a href="#format_derived_type">llvm.dbg.derivedtype2</a> = internal constant %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> {
1677     uint add(uint 13, uint 262144),
1678     {  }* null,
1679     sbyte* getelementptr ([6 x sbyte]* %str4, int 0, int 0),
1680     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1681     int 3,
1682     uint 32,
1683     uint 32,
1684     uint 32,
1685     {  }* cast (%<a href="#format_basic_type">llvm.dbg.basictype.type</a>* %<a href="#format_basic_type">llvm.dbg.basictype</a> to {  }*) }, section "llvm.metadata"
1686 %str4 = internal constant [6 x sbyte] c"Green\00", section "llvm.metadata"
1687
1688 ;;
1689 ;; Define the Blue field.
1690 ;;
1691 %<a href="#format_derived_type">llvm.dbg.derivedtype3</a> = internal constant %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> {
1692     uint add(uint 13, uint 262144),
1693     {  }* null,
1694     sbyte* getelementptr ([5 x sbyte]* %str5, int 0, int 0),
1695     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1696     int 4,
1697     uint 32,
1698     uint 32,
1699     uint 64,
1700     {  }* cast (%<a href="#format_basic_type">llvm.dbg.basictype.type</a>* %<a href="#format_basic_type">llvm.dbg.basictype</a> to {  }*) }, section "llvm.metadata"
1701 %str5 = internal constant [5 x sbyte] c"Blue\00", section "llvm.metadata"
1702
1703 ;;
1704 ;; Define the array of fields used by the composite type Color.
1705 ;;
1706 %llvm.dbg.array = internal constant [3 x {  }*] [
1707       {  }* cast (%<a href="#format_derived_type">llvm.dbg.derivedtype.type</a>* %<a href="#format_derived_type">llvm.dbg.derivedtype1</a> to {  }*),
1708       {  }* cast (%<a href="#format_derived_type">llvm.dbg.derivedtype.type</a>* %<a href="#format_derived_type">llvm.dbg.derivedtype2</a> to {  }*),
1709       {  }* cast (%<a href="#format_derived_type">llvm.dbg.derivedtype.type</a>* %<a href="#format_derived_type">llvm.dbg.derivedtype3</a> to {  }*) ], section "llvm.metadata"
1710 </pre>
1711
1712 </div>
1713
1714 <!-- ======================================================================= -->
1715 <div class="doc_subsection">
1716   <a name="ccxx_enumeration_types">C/C++ enumeration types</a>
1717 </div>
1718
1719 <div class="doc_text">
1720
1721 <p>Given the following as an example of C/C++ enumeration type;</p>
1722
1723 <pre>
1724 enum Trees {
1725   Spruce = 100,
1726   Oak = 200,
1727   Maple = 300
1728 };
1729 </pre>
1730
1731 <p>a C/C++ front-end would generate the following descriptors;</p>
1732
1733 <pre>
1734 ;;
1735 ;; Define composite type for enum Trees
1736 ;;
1737 %<a href="#format_composite_type">llvm.dbg.compositetype</a> = internal constant %<a href="#format_composite_type">llvm.dbg.compositetype.type</a> {
1738     uint add(uint 4, uint 262144),
1739     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1740     sbyte* getelementptr ([6 x sbyte]* %str1, int 0, int 0),
1741     {  }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to {  }*),
1742     int 1,
1743     uint 32,
1744     uint 32,
1745     uint 0,
1746     {  }* null,
1747     {  }* cast ([3 x {  }*]* %llvm.dbg.array to {  }*) }, section "llvm.metadata"
1748 %str1 = internal constant [6 x sbyte] c"Trees\00", section "llvm.metadata"
1749
1750 ;;
1751 ;; Define Spruce enumerator.
1752 ;;
1753 %<a href="#format_enumeration">llvm.dbg.enumerator1</a> = internal constant %<a href="#format_enumeration">llvm.dbg.enumerator.type</a> {
1754     uint add(uint 40, uint 262144),
1755     sbyte* getelementptr ([7 x sbyte]* %str2, int 0, int 0),
1756     int 100 }, section "llvm.metadata"
1757 %str2 = internal constant [7 x sbyte] c"Spruce\00", section "llvm.metadata"
1758
1759 ;;
1760 ;; Define Oak enumerator.
1761 ;;
1762 %<a href="#format_enumeration">llvm.dbg.enumerator2</a> = internal constant %<a href="#format_enumeration">llvm.dbg.enumerator.type</a> {
1763     uint add(uint 40, uint 262144),
1764     sbyte* getelementptr ([4 x sbyte]* %str3, int 0, int 0),
1765     int 200 }, section "llvm.metadata"
1766 %str3 = internal constant [4 x sbyte] c"Oak\00", section "llvm.metadata"
1767
1768 ;;
1769 ;; Define Maple enumerator.
1770 ;;
1771 %<a href="#format_enumeration">llvm.dbg.enumerator3</a> = internal constant %<a href="#format_enumeration">llvm.dbg.enumerator.type</a> {
1772     uint add(uint 40, uint 262144),
1773     sbyte* getelementptr ([6 x sbyte]* %str4, int 0, int 0),
1774     int 300 }, section "llvm.metadata"
1775 %str4 = internal constant [6 x sbyte] c"Maple\00", section "llvm.metadata"
1776
1777 ;;
1778 ;; Define the array of enumerators used by composite type Trees.
1779 ;;
1780 %llvm.dbg.array = internal constant [3 x {  }*] [
1781   {  }* cast (%<a href="#format_enumeration">llvm.dbg.enumerator.type</a>* %<a href="#format_enumeration">llvm.dbg.enumerator1</a> to {  }*),
1782   {  }* cast (%<a href="#format_enumeration">llvm.dbg.enumerator.type</a>* %<a href="#format_enumeration">llvm.dbg.enumerator2</a> to {  }*),
1783   {  }* cast (%<a href="#format_enumeration">llvm.dbg.enumerator.type</a>* %<a href="#format_enumeration">llvm.dbg.enumerator3</a> to {  }*) ], section "llvm.metadata"
1784 </pre>
1785
1786 </div>
1787
1788 <!-- *********************************************************************** -->
1789
1790 <hr>
1791 <address>
1792   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
1793   src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
1794   <a href="http://validator.w3.org/check/referer"><img
1795   src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
1796
1797   <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
1798   <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
1799   Last modified: $Date$
1800 </address>
1801
1802 </body>
1803 </html>