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