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