1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6 <title>Source Level Debugging with LLVM</title>
7 <link rel="stylesheet" href="llvm.css" type="text/css">
11 <div class="doc_title">Source Level Debugging with LLVM</div>
13 <table class="layout" style="width:100%">
17 <li><a href="#introduction">Introduction</a>
19 <li><a href="#phil">Philosophy behind LLVM debugging information</a></li>
20 <li><a href="#consumers">Debug information consumers</a></li>
21 <li><a href="#debugopt">Debugging optimized code</a></li>
23 <li><a href="#format">Debugging information format</a>
25 <li><a href="#debug_info_descriptors">Debug information descriptors</a>
27 <li><a href="#format_anchors">Anchor descriptors</a></li>
28 <li><a href="#format_compile_units">Compile unit descriptors</a></li>
29 <li><a href="#format_global_variables">Global variable descriptors</a></li>
30 <li><a href="#format_subprograms">Subprogram descriptors</a></li>
31 <li><a href="#format_blocks">Block descriptors</a></li>
32 <li><a href="#format_basic_type">Basic type descriptors</a></li>
33 <li><a href="#format_derived_type">Derived type descriptors</a></li>
34 <li><a href="#format_composite_type">Composite type descriptors</a></li>
35 <li><a href="#format_subrange">Subrange descriptors</a></li>
36 <li><a href="#format_enumeration">Enumerator descriptors</a></li>
37 <li><a href="#format_variables">Local variables</a></li>
39 <li><a href="#format_common_intrinsics">Debugger intrinsic functions</a>
41 <li><a href="#format_common_stoppoint">llvm.dbg.stoppoint</a></li>
42 <li><a href="#format_common_func_start">llvm.dbg.func.start</a></li>
43 <li><a href="#format_common_region_start">llvm.dbg.region.start</a></li>
44 <li><a href="#format_common_region_end">llvm.dbg.region.end</a></li>
45 <li><a href="#format_common_declare">llvm.dbg.declare</a></li>
47 <li><a href="#format_common_stoppoints">Representing stopping points in the
48 source program</a></li>
50 <li><a href="#ccxx_frontend">C/C++ front-end specific debug information</a>
52 <li><a href="#ccxx_compile_units">C/C++ source file information</a></li>
53 <li><a href="#ccxx_global_variable">C/C++ global variable information</a></li>
54 <li><a href="#ccxx_subprogram">C/C++ function information</a></li>
55 <li><a href="#ccxx_basic_types">C/C++ basic types</a></li>
56 <li><a href="#ccxx_derived_types">C/C++ derived types</a></li>
57 <li><a href="#ccxx_composite_types">C/C++ struct/union types</a></li>
58 <li><a href="#ccxx_enumeration_types">C/C++ enumeration types</a></li>
63 <img src="img/venusflytrap.jpg" alt="A leafy and green bug eater" width="247"
68 <div class="doc_author">
69 <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>
70 and <a href="mailto:jlaskey@mac.com">Jim Laskey</a></p>
74 <!-- *********************************************************************** -->
75 <div class="doc_section"><a name="introduction">Introduction</a></div>
76 <!-- *********************************************************************** -->
78 <div class="doc_text">
80 <p>This document is the central repository for all information pertaining to
81 debug information in LLVM. It describes the <a href="#format">actual format
82 that the LLVM debug information</a> takes, which is useful for those
83 interested in creating front-ends or dealing directly with the information.
84 Further, this document provides specifc examples of what debug information
89 <!-- ======================================================================= -->
90 <div class="doc_subsection">
91 <a name="phil">Philosophy behind LLVM debugging information</a>
94 <div class="doc_text">
96 <p>The idea of the LLVM debugging information is to capture how the important
97 pieces of the source-language's Abstract Syntax Tree map onto LLVM code.
98 Several design aspects have shaped the solution that appears here. The
99 important ones are:</p>
102 <li>Debugging information should have very little impact on the rest of the
103 compiler. No transformations, analyses, or code generators should need to
104 be modified because of debugging information.</li>
106 <li>LLVM optimizations should interact in <a href="#debugopt">well-defined and
107 easily described ways</a> with the debugging information.</li>
109 <li>Because LLVM is designed to support arbitrary programming languages,
110 LLVM-to-LLVM tools should not need to know anything about the semantics of
111 the source-level-language.</li>
113 <li>Source-level languages are often <b>widely</b> different from one another.
114 LLVM should not put any restrictions of the flavor of the source-language,
115 and the debugging information should work with any language.</li>
117 <li>With code generator support, it should be possible to use an LLVM compiler
118 to compile a program to native machine code and standard debugging
119 formats. This allows compatibility with traditional machine-code level
120 debuggers, like GDB or DBX.</li>
123 <p>The approach used by the LLVM implementation is to use a small set
124 of <a href="#format_common_intrinsics">intrinsic functions</a> to define a
125 mapping between LLVM program objects and the source-level objects. The
126 description of the source-level program is maintained in LLVM global
127 variables in an <a href="#ccxx_frontend">implementation-defined format</a>
128 (the C/C++ front-end currently uses working draft 7 of
129 the <a href="http://www.eagercon.com/dwarf/dwarf3std.htm">DWARF 3
132 <p>When a program is being debugged, a debugger interacts with the user and
133 turns the stored debug information into source-language specific information.
134 As such, a debugger must be aware of the source-language, and is thus tied to
135 a specific language or family of languages.</p>
139 <!-- ======================================================================= -->
140 <div class="doc_subsection">
141 <a name="consumers">Debug information consumers</a>
144 <div class="doc_text">
146 <p>The role of debug information is to provide meta information normally
147 stripped away during the compilation process. This meta information provides
148 an LLVM user a relationship between generated code and the original program
151 <p>Currently, debug information is consumed by the DwarfWriter to produce dwarf
152 information used by the gdb debugger. Other targets could use the same
153 information to produce stabs or other debug forms.</p>
155 <p>It would also be reasonable to use debug information to feed profiling tools
156 for analysis of generated code, or, tools for reconstructing the original
157 source from generated code.</p>
159 <p>TODO - expound a bit more.</p>
163 <!-- ======================================================================= -->
164 <div class="doc_subsection">
165 <a name="debugopt">Debugging optimized code</a>
168 <div class="doc_text">
170 <p>An extremely high priority of LLVM debugging information is to make it
171 interact well with optimizations and analysis. In particular, the LLVM debug
172 information provides the following guarantees:</p>
175 <li>LLVM debug information <b>always provides information to accurately read
176 the source-level state of the program</b>, regardless of which LLVM
177 optimizations have been run, and without any modification to the
178 optimizations themselves. However, some optimizations may impact the
179 ability to modify the current state of the program with a debugger, such
180 as setting program variables, or calling functions that have been
183 <li>LLVM optimizations gracefully interact with debugging information. If
184 they are not aware of debug information, they are automatically disabled
185 as necessary in the cases that would invalidate the debug info. This
186 retains the LLVM features, making it easy to write new
187 transformations.</li>
189 <li>As desired, LLVM optimizations can be upgraded to be aware of the LLVM
190 debugging information, allowing them to update the debugging information
191 as they perform aggressive optimizations. This means that, with effort,
192 the LLVM optimizers could optimize debug code just as well as non-debug
195 <li>LLVM debug information does not prevent many important optimizations from
196 happening (for example inlining, basic block reordering/merging/cleanup,
197 tail duplication, etc), further reducing the amount of the compiler that
198 eventually is "aware" of debugging information.</li>
200 <li>LLVM debug information is automatically optimized along with the rest of
201 the program, using existing facilities. For example, duplicate
202 information is automatically merged by the linker, and unused information
203 is automatically removed.</li>
206 <p>Basically, the debug information allows you to compile a program with
207 "<tt>-O0 -g</tt>" and get full debug information, allowing you to arbitrarily
208 modify the program as it executes from a debugger. Compiling a program with
209 "<tt>-O3 -g</tt>" gives you full debug information that is always available
210 and accurate for reading (e.g., you get accurate stack traces despite tail
211 call elimination and inlining), but you might lose the ability to modify the
212 program and call functions where were optimized out of the program, or
213 inlined away completely.</p>
215 <p><a href="TestingGuide.html#quicktestsuite">LLVM test suite</a> provides a
216 framework to test optimizer's handling of debugging information. It can be
219 <div class="doc_code">
221 % cd llvm/projects/test-suite/MultiSource/Benchmarks # or some other level
226 <p>This will test impact of debugging information on optimization passes. If
227 debugging information influences optimization passes then it will be reported
228 as a failure. See <a href="TestingGuide.html">TestingGuide</a> for more
229 information on LLVM test infrastructure and how to run various tests.</p>
233 <!-- *********************************************************************** -->
234 <div class="doc_section">
235 <a name="format">Debugging information format</a>
237 <!-- *********************************************************************** -->
239 <div class="doc_text">
241 <p>LLVM debugging information has been carefully designed to make it possible
242 for the optimizer to optimize the program and debugging information without
243 necessarily having to know anything about debugging information. In
244 particular, the global constant merging pass automatically eliminates
245 duplicated debugging information (often caused by header files), the global
246 dead code elimination pass automatically deletes debugging information for a
247 function if it decides to delete the function, and the linker eliminates
248 debug information when it merges <tt>linkonce</tt> functions.</p>
250 <p>To do this, most of the debugging information (descriptors for types,
251 variables, functions, source files, etc) is inserted by the language
252 front-end in the form of LLVM global variables. These LLVM global variables
253 are no different from any other global variables, except that they have a web
254 of LLVM intrinsic functions that point to them. If the last references to a
255 particular piece of debugging information are deleted (for example, by the
256 <tt>-globaldce</tt> pass), the extraneous debug information will
257 automatically become dead and be removed by the optimizer.</p>
259 <p>Debug information is designed to be agnostic about the target debugger and
260 debugging information representation (e.g. DWARF/Stabs/etc). It uses a
261 generic machine debug information pass to decode the information that
262 represents variables, types, functions, namespaces, etc: this allows for
263 arbitrary source-language semantics and type-systems to be used, as long as
264 there is a module written for the target debugger to interpret the
265 information. In addition, debug global variables are declared in
266 the <tt>"llvm.metadata"</tt> section. All values declared in this section
267 are stripped away after target debug information is constructed and before
268 the program object is emitted.</p>
270 <p>To provide basic functionality, the LLVM debugger does have to make some
271 assumptions about the source-level language being debugged, though it keeps
272 these to a minimum. The only common features that the LLVM debugger assumes
273 exist are <a href="#format_compile_units">source files</a>,
274 and <a href="#format_global_variables">program objects</a>. These abstract
275 objects are used by a debugger to form stack traces, show information about
276 local variables, etc.</p>
278 <p>This section of the documentation first describes the representation aspects
279 common to any source-language. The <a href="#ccxx_frontend">next section</a>
280 describes the data layout conventions used by the C and C++ front-ends.</p>
284 <!-- ======================================================================= -->
285 <div class="doc_subsection">
286 <a name="debug_info_descriptors">Debug information descriptors</a>
289 <div class="doc_text">
291 <p>In consideration of the complexity and volume of debug information, LLVM
292 provides a specification for well formed debug global variables. The
293 constant value of each of these globals is one of a limited set of
294 structures, known as debug descriptors.</p>
296 <p>Consumers of LLVM debug information expect the descriptors for program
297 objects to start in a canonical format, but the descriptors can include
298 additional information appended at the end that is source-language
299 specific. All LLVM debugging information is versioned, allowing backwards
300 compatibility in the case that the core structures need to change in some
301 way. Also, all debugging information objects start with a tag to indicate
302 what type of object it is. The source-language is allowed to define its own
303 objects, by using unreserved tag numbers. We recommend using with tags in
304 the range 0x1000 thru 0x2000 (there is a defined enum DW_TAG_user_base =
307 <p>The fields of debug descriptors used internally by LLVM (MachineModuleInfo)
308 are restricted to only the simple data types <tt>int</tt>, <tt>uint</tt>,
309 <tt>bool</tt>, <tt>float</tt>, <tt>double</tt>, <tt>i8*</tt> and
310 <tt>{ }*</tt>. References to arbitrary values are handled using a
311 <tt>{ }*</tt> and a cast to <tt>{ }*</tt> expression; typically
312 references to other field descriptors, arrays of descriptors or global
315 <div class="doc_code">
317 %llvm.dbg.object.type = type {
324 <p><a name="LLVMDebugVersion">The first field of a descriptor is always an
325 <tt>uint</tt> containing a tag value identifying the content of the
326 descriptor. The remaining fields are specific to the descriptor. The values
327 of tags are loosely bound to the tag values of DWARF information entries.
328 However, that does not restrict the use of the information supplied to DWARF
329 targets. To facilitate versioning of debug information, the tag is augmented
330 with the current debug version (LLVMDebugVersion = 4 << 16 or 0x40000 or
333 <p>The details of the various descriptors follow.</p>
337 <!-- ======================================================================= -->
338 <div class="doc_subsubsection">
339 <a name="format_anchors">Anchor descriptors</a>
342 <div class="doc_text">
344 <div class="doc_code">
346 %<a href="#format_anchors">llvm.dbg.anchor.type</a> = type {
347 i32, ;; Tag = 0 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
348 i32 ;; Tag of descriptors grouped by the anchor
353 <p>One important aspect of the LLVM debug representation is that it allows the
354 LLVM debugger to efficiently index all of the global objects without having
355 the scan the program. To do this, all of the global objects use "anchor"
356 descriptors with designated names. All of the global objects of a particular
357 type (e.g., compile units) contain a pointer to the anchor. This pointer
358 allows a debugger to use def-use chains to find all global objects of that
361 <p>The following names are recognized as anchors by LLVM:</p>
363 <div class="doc_code">
365 %<a href="#format_compile_units">llvm.dbg.compile_units</a> = linkonce constant %<a href="#format_anchors">llvm.dbg.anchor.type</a> {
368 } ;; DW_TAG_compile_unit
369 %<a href="#format_global_variables">llvm.dbg.global_variables</a> = linkonce constant %<a href="#format_anchors">llvm.dbg.anchor.type</a> {
373 %<a href="#format_subprograms">llvm.dbg.subprograms</a> = linkonce constant %<a href="#format_anchors">llvm.dbg.anchor.type</a> {
376 } ;; DW_TAG_subprogram
380 <p>Using anchors in this way (where the compile unit descriptor points to the
381 anchors, as opposed to having a list of compile unit descriptors) allows for
382 the standard dead global elimination and merging passes to automatically
383 remove unused debugging information. If the globals were kept track of
384 through lists, there would always be an object pointing to the descriptors,
385 thus would never be deleted.</p>
389 <!-- ======================================================================= -->
390 <div class="doc_subsubsection">
391 <a name="format_compile_units">Compile unit descriptors</a>
394 <div class="doc_text">
396 <div class="doc_code">
398 %<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> = type {
399 i32, ;; Tag = 17 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_compile_unit)
400 { }*, ;; Compile unit anchor = cast = (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_units</a> to { }*)
401 i32, ;; DWARF language identifier (ex. DW_LANG_C89)
402 i8*, ;; Source file name
403 i8*, ;; Source file directory (includes trailing slash)
404 i8* ;; Producer (ex. "4.0.1 LLVM (LLVM research group)")
405 i1, ;; True if this is a main compile unit.
406 i1, ;; True if this is optimized.
408 i32 ;; Runtime version
413 <p>These descriptors contain a source language ID for the file (we use the DWARF
414 3.0 ID numbers, such as <tt>DW_LANG_C89</tt>, <tt>DW_LANG_C_plus_plus</tt>,
415 <tt>DW_LANG_Cobol74</tt>, etc), three strings describing the filename,
416 working directory of the compiler, and an identifier string for the compiler
417 that produced it.</p>
419 <p>Compile unit descriptors provide the root context for objects declared in a
420 specific source file. Global variables and top level functions would be
421 defined using this context. Compile unit descriptors also provide context
422 for source line correspondence.</p>
424 <p>Each input file is encoded as a separate compile unit in LLVM debugging
425 information output. However, many target specific tool chains prefer to
426 encode only one compile unit in an object file. In this situation, the LLVM
427 code generator will include debugging information entities in the compile
428 unit that is marked as main compile unit. The code generator accepts maximum
429 one main compile unit per module. If a module does not contain any main
430 compile unit then the code generator will emit multiple compile units in the
431 output object file.</p>
435 <!-- ======================================================================= -->
436 <div class="doc_subsubsection">
437 <a name="format_global_variables">Global variable descriptors</a>
440 <div class="doc_text">
442 <div class="doc_code">
444 %<a href="#format_global_variables">llvm.dbg.global_variable.type</a> = type {
445 i32, ;; Tag = 52 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_variable)
446 { }*, ;; Global variable anchor = cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_global_variables">llvm.dbg.global_variables</a> to { }*),
447 { }*, ;; Reference to context descriptor
449 i8*, ;; Display name (fully qualified C++ name)
450 i8*, ;; MIPS linkage name (for C++)
451 { }*, ;; Reference to compile unit where defined
452 i32, ;; Line number where defined
453 { }*, ;; Reference to type descriptor
454 i1, ;; True if the global is local to compile unit (static)
455 i1, ;; True if the global is defined in the compile unit (not extern)
456 { }* ;; Reference to the global variable
461 <p>These descriptors provide debug information about globals variables. The
462 provide details such as name, type and where the variable is defined.</p>
466 <!-- ======================================================================= -->
467 <div class="doc_subsubsection">
468 <a name="format_subprograms">Subprogram descriptors</a>
471 <div class="doc_text">
473 <div class="doc_code">
475 %<a href="#format_subprograms">llvm.dbg.subprogram.type</a> = type {
476 i32, ;; Tag = 46 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_subprogram)
477 { }*, ;; Subprogram anchor = cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_subprograms">llvm.dbg.subprograms</a> to { }*),
478 { }*, ;; Reference to context descriptor
480 i8*, ;; Display name (fully qualified C++ name)
481 i8*, ;; MIPS linkage name (for C++)
482 { }*, ;; Reference to compile unit where defined
483 i32, ;; Line number where defined
484 { }*, ;; Reference to type descriptor
485 i1, ;; True if the global is local to compile unit (static)
486 i1 ;; True if the global is defined in the compile unit (not extern)
491 <p>These descriptors provide debug information about functions, methods and
492 subprograms. They provide details such as name, return types and the source
493 location where the subprogram is defined.</p>
497 <!-- ======================================================================= -->
498 <div class="doc_subsubsection">
499 <a name="format_blocks">Block descriptors</a>
502 <div class="doc_text">
504 <div class="doc_code">
506 %<a href="#format_blocks">llvm.dbg.block</a> = type {
507 i32, ;; Tag = 13 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_lexical_block)
508 { }* ;; Reference to context descriptor
513 <p>These descriptors provide debug information about nested blocks within a
514 subprogram. The array of member descriptors is used to define local
515 variables and deeper nested blocks.</p>
519 <!-- ======================================================================= -->
520 <div class="doc_subsubsection">
521 <a name="format_basic_type">Basic type descriptors</a>
524 <div class="doc_text">
526 <div class="doc_code">
528 %<a href="#format_basic_type">llvm.dbg.basictype.type</a> = type {
529 i32, ;; Tag = 36 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_base_type)
530 { }*, ;; Reference to context (typically a compile unit)
531 i8*, ;; Name (may be "" for anonymous types)
532 { }*, ;; Reference to compile unit where defined (may be NULL)
533 i32, ;; Line number where defined (may be 0)
535 i64, ;; Alignment in bits
536 i64, ;; Offset in bits
538 i32 ;; DWARF type encoding
543 <p>These descriptors define primitive types used in the code. Example int, bool
544 and float. The context provides the scope of the type, which is usually the
545 top level. Since basic types are not usually user defined the compile unit
546 and line number can be left as NULL and 0. The size, alignment and offset
547 are expressed in bits and can be 64 bit values. The alignment is used to
548 round the offset when embedded in a
549 <a href="#format_composite_type">composite type</a> (example to keep float
550 doubles on 64 bit boundaries.) The offset is the bit offset if embedded in
551 a <a href="#format_composite_type">composite type</a>.</p>
553 <p>The type encoding provides the details of the type. The values are typically
554 one of the following:</p>
556 <div class="doc_code">
562 DW_ATE_signed_char = 6
564 DW_ATE_unsigned_char = 8
570 <!-- ======================================================================= -->
571 <div class="doc_subsubsection">
572 <a name="format_derived_type">Derived type descriptors</a>
575 <div class="doc_text">
577 <div class="doc_code">
579 %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> = type {
580 i32, ;; Tag (see below)
581 { }*, ;; Reference to context
582 i8*, ;; Name (may be "" for anonymous types)
583 { }*, ;; Reference to compile unit where defined (may be NULL)
584 i32, ;; Line number where defined (may be 0)
586 i32, ;; Alignment in bits
587 i32, ;; Offset in bits
588 { }* ;; Reference to type derived from
593 <p>These descriptors are used to define types derived from other types. The
594 value of the tag varies depending on the meaning. The following are possible
597 <div class="doc_code">
599 DW_TAG_formal_parameter = 5
601 DW_TAG_pointer_type = 15
602 DW_TAG_reference_type = 16
604 DW_TAG_const_type = 38
605 DW_TAG_volatile_type = 53
606 DW_TAG_restrict_type = 55
610 <p><tt>DW_TAG_member</tt> is used to define a member of
611 a <a href="#format_composite_type">composite type</a>
612 or <a href="#format_subprograms">subprogram</a>. The type of the member is
613 the <a href="#format_derived_type">derived
614 type</a>. <tt>DW_TAG_formal_parameter</tt> is used to define a member which
615 is a formal argument of a subprogram.</p>
617 <p><tt>DW_TAG_typedef</tt> is used to provide a name for the derived type.</p>
619 <p><tt>DW_TAG_pointer_type</tt>,<tt>DW_TAG_reference_type</tt>,
620 <tt>DW_TAG_const_type</tt>, <tt>DW_TAG_volatile_type</tt>
621 and <tt>DW_TAG_restrict_type</tt> are used to qualify
622 the <a href="#format_derived_type">derived type</a>. </p>
624 <p><a href="#format_derived_type">Derived type</a> location can be determined
625 from the compile unit and line number. The size, alignment and offset are
626 expressed in bits and can be 64 bit values. The alignment is used to round
627 the offset when embedded in a <a href="#format_composite_type">composite
628 type</a> (example to keep float doubles on 64 bit boundaries.) The offset is
629 the bit offset if embedded in a <a href="#format_composite_type">composite
632 <p>Note that the <tt>void *</tt> type is expressed as a
633 <tt>llvm.dbg.derivedtype.type</tt> with tag of <tt>DW_TAG_pointer_type</tt>
634 and <tt>NULL</tt> derived type.</p>
638 <!-- ======================================================================= -->
639 <div class="doc_subsubsection">
640 <a name="format_composite_type">Composite type descriptors</a>
643 <div class="doc_text">
645 <div class="doc_code">
647 %<a href="#format_composite_type">llvm.dbg.compositetype.type</a> = type {
648 i32, ;; Tag (see below)
649 { }*, ;; Reference to context
650 i8*, ;; Name (may be "" for anonymous types)
651 { }*, ;; Reference to compile unit where defined (may be NULL)
652 i32, ;; Line number where defined (may be 0)
654 i64, ;; Alignment in bits
655 i64, ;; Offset in bits
657 { }*, ;; Reference to type derived from
658 { }*, ;; Reference to array of member descriptors
659 i32 ;; Runtime languages
664 <p>These descriptors are used to define types that are composed of 0 or more
665 elements. The value of the tag varies depending on the meaning. The following
666 are possible tag values:</p>
668 <div class="doc_code">
670 DW_TAG_array_type = 1
671 DW_TAG_enumeration_type = 4
672 DW_TAG_structure_type = 19
673 DW_TAG_union_type = 23
674 DW_TAG_vector_type = 259
675 DW_TAG_subroutine_type = 46
676 DW_TAG_inheritance = 26
680 <p>The vector flag indicates that an array type is a native packed vector.</p>
682 <p>The members of array types (tag = <tt>DW_TAG_array_type</tt>) or vector types
683 (tag = <tt>DW_TAG_vector_type</tt>) are <a href="#format_subrange">subrange
684 descriptors</a>, each representing the range of subscripts at that level of
687 <p>The members of enumeration types (tag = <tt>DW_TAG_enumeration_type</tt>) are
688 <a href="#format_enumeration">enumerator descriptors</a>, each representing
689 the definition of enumeration value for the set.</p>
691 <p>The members of structure (tag = <tt>DW_TAG_structure_type</tt>) or union (tag
692 = <tt>DW_TAG_union_type</tt>) types are any one of
693 the <a href="#format_basic_type">basic</a>,
694 <a href="#format_derived_type">derived</a>
695 or <a href="#format_composite_type">composite</a> type descriptors, each
696 representing a field member of the structure or union.</p>
698 <p>For C++ classes (tag = <tt>DW_TAG_structure_type</tt>), member descriptors
699 provide information about base classes, static members and member
700 functions. If a member is a <a href="#format_derived_type">derived type
701 descriptor</a> and has a tag of <tt>DW_TAG_inheritance</tt>, then the type
702 represents a base class. If the member of is
703 a <a href="#format_global_variables">global variable descriptor</a> then it
704 represents a static member. And, if the member is
705 a <a href="#format_subprograms">subprogram descriptor</a> then it represents
706 a member function. For static members and member
707 functions, <tt>getName()</tt> returns the members link or the C++ mangled
708 name. <tt>getDisplayName()</tt> the simplied version of the name.</p>
710 <p>The first member of subroutine (tag = <tt>DW_TAG_subroutine_type</tt>) type
711 elements is the return type for the subroutine. The remaining elements are
712 the formal arguments to the subroutine.</p>
714 <p><a href="#format_composite_type">Composite type</a> location can be
715 determined from the compile unit and line number. The size, alignment and
716 offset are expressed in bits and can be 64 bit values. The alignment is used
717 to round the offset when embedded in
718 a <a href="#format_composite_type">composite type</a> (as an example, to keep
719 float doubles on 64 bit boundaries.) The offset is the bit offset if embedded
720 in a <a href="#format_composite_type">composite type</a>.</p>
724 <!-- ======================================================================= -->
725 <div class="doc_subsubsection">
726 <a name="format_subrange">Subrange descriptors</a>
729 <div class="doc_text">
731 <div class="doc_code">
733 %<a href="#format_subrange">llvm.dbg.subrange.type</a> = type {
734 i32, ;; Tag = 33 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_subrange_type)
741 <p>These descriptors are used to define ranges of array subscripts for an array
742 <a href="#format_composite_type">composite type</a>. The low value defines
743 the lower bounds typically zero for C/C++. The high value is the upper
744 bounds. Values are 64 bit. High - low + 1 is the size of the array. If low
745 == high the array will be unbounded.</p>
749 <!-- ======================================================================= -->
750 <div class="doc_subsubsection">
751 <a name="format_enumeration">Enumerator descriptors</a>
754 <div class="doc_text">
756 <div class="doc_code">
758 %<a href="#format_enumeration">llvm.dbg.enumerator.type</a> = type {
759 i32, ;; Tag = 40 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_enumerator)
766 <p>These descriptors are used to define members of an
767 enumeration <a href="#format_composite_type">composite type</a>, it
768 associates the name to the value.</p>
772 <!-- ======================================================================= -->
773 <div class="doc_subsubsection">
774 <a name="format_variables">Local variables</a>
777 <div class="doc_text">
779 <div class="doc_code">
781 %<a href="#format_variables">llvm.dbg.variable.type</a> = type {
782 i32, ;; Tag (see below)
785 { }*, ;; Reference to compile unit where defined
786 i32, ;; Line number where defined
787 { }* ;; Type descriptor
792 <p>These descriptors are used to define variables local to a sub program. The
793 value of the tag depends on the usage of the variable:</p>
795 <div class="doc_code">
797 DW_TAG_auto_variable = 256
798 DW_TAG_arg_variable = 257
799 DW_TAG_return_variable = 258
803 <p>An auto variable is any variable declared in the body of the function. An
804 argument variable is any variable that appears as a formal argument to the
805 function. A return variable is used to track the result of a function and
806 has no source correspondent.</p>
808 <p>The context is either the subprogram or block where the variable is defined.
809 Name the source variable name. Compile unit and line indicate where the
810 variable was defined. Type descriptor defines the declared type of the
815 <!-- ======================================================================= -->
816 <div class="doc_subsection">
817 <a name="format_common_intrinsics">Debugger intrinsic functions</a>
820 <div class="doc_text">
822 <p>LLVM uses several intrinsic functions (name prefixed with "llvm.dbg") to
823 provide debug information at various points in generated code.</p>
827 <!-- ======================================================================= -->
828 <div class="doc_subsubsection">
829 <a name="format_common_stoppoint">llvm.dbg.stoppoint</a>
832 <div class="doc_text">
834 void %<a href="#format_common_stoppoint">llvm.dbg.stoppoint</a>( uint, uint, { }* )
837 <p>This intrinsic is used to provide correspondence between the source file and
838 the generated code. The first argument is the line number (base 1), second
839 argument is the column number (0 if unknown) and the third argument the
840 source <tt>%<a href="#format_compile_units">llvm.dbg.compile_unit</a>*</tt>
841 cast to a <tt>{ }*</tt>. Code following a call to this intrinsic will
842 have been defined in close proximity of the line, column and file. This
843 information holds until the next call
844 to <tt>%<a href="#format_common_stoppoint">lvm.dbg.stoppoint</a></tt>.</p>
848 <!-- ======================================================================= -->
849 <div class="doc_subsubsection">
850 <a name="format_common_func_start">llvm.dbg.func.start</a>
853 <div class="doc_text">
855 void %<a href="#format_common_func_start">llvm.dbg.func.start</a>( { }* )
858 <p>This intrinsic is used to link the debug information
859 in <tt>%<a href="#format_subprograms">llvm.dbg.subprogram</a></tt> to the
860 function. It defines the beginning of the function's declarative region
861 (scope). It also implies a call to
862 %<tt><a href="#format_common_stoppoint">llvm.dbg.stoppoint</a></tt> which
863 defines a source line "stop point". The intrinsic should be called early in
864 the function after the all the alloca instructions. It should be paired off
866 <tt>%<a href="#format_common_region_end">llvm.dbg.region.end</a></tt>.
867 The function's single argument is
868 the <tt>%<a href="#format_subprograms">llvm.dbg.subprogram.type</a></tt>.</p>
872 <!-- ======================================================================= -->
873 <div class="doc_subsubsection">
874 <a name="format_common_region_start">llvm.dbg.region.start</a>
877 <div class="doc_text">
879 void %<a href="#format_common_region_start">llvm.dbg.region.start</a>( { }* )
882 <p>This intrinsic is used to define the beginning of a declarative scope (ex.
883 block) for local language elements. It should be paired off with a closing
884 <tt>%<a href="#format_common_region_end">llvm.dbg.region.end</a></tt>. The
885 function's single argument is
886 the <tt>%<a href="#format_blocks">llvm.dbg.block</a></tt> which is
892 <!-- ======================================================================= -->
893 <div class="doc_subsubsection">
894 <a name="format_common_region_end">llvm.dbg.region.end</a>
897 <div class="doc_text">
899 void %<a href="#format_common_region_end">llvm.dbg.region.end</a>( { }* )
902 <p>This intrinsic is used to define the end of a declarative scope (ex. block)
903 for local language elements. It should be paired off with an
904 opening <tt>%<a href="#format_common_region_start">llvm.dbg.region.start</a></tt>
905 or <tt>%<a href="#format_common_func_start">llvm.dbg.func.start</a></tt>.
906 The function's single argument is either
907 the <tt>%<a href="#format_blocks">llvm.dbg.block</a></tt> or
908 the <tt>%<a href="#format_subprograms">llvm.dbg.subprogram.type</a></tt>
913 <!-- ======================================================================= -->
914 <div class="doc_subsubsection">
915 <a name="format_common_declare">llvm.dbg.declare</a>
918 <div class="doc_text">
920 void %<a href="#format_common_declare">llvm.dbg.declare</a>( { } *, { }* )
923 <p>This intrinsic provides information about a local element (ex. variable.) The
924 first argument is the alloca for the variable, cast to a <tt>{ }*</tt>. The
926 the <tt>%<a href="#format_variables">llvm.dbg.variable</a></tt> containing
927 the description of the variable, also cast to a <tt>{ }*</tt>.</p>
931 <!-- ======================================================================= -->
932 <div class="doc_subsection">
933 <a name="format_common_stoppoints">
934 Representing stopping points in the source program
938 <div class="doc_text">
940 <p>LLVM debugger "stop points" are a key part of the debugging representation
941 that allows the LLVM to maintain simple semantics
942 for <a href="#debugopt">debugging optimized code</a>. The basic idea is that
943 the front-end inserts calls to
944 the <a href="#format_common_stoppoint">%<tt>llvm.dbg.stoppoint</tt></a>
945 intrinsic function at every point in the program where a debugger should be
946 able to inspect the program (these correspond to places a debugger stops when
947 you "<tt>step</tt>" through it). The front-end can choose to place these as
948 fine-grained as it would like (for example, before every subexpression
949 evaluated), but it is recommended to only put them after every source
950 statement that includes executable code.</p>
952 <p>Using calls to this intrinsic function to demark legal points for the
953 debugger to inspect the program automatically disables any optimizations that
954 could potentially confuse debugging information. To
955 non-debug-information-aware transformations, these calls simply look like
956 calls to an external function, which they must assume to do anything
957 (including reading or writing to any part of reachable memory). On the other
958 hand, it does not impact many optimizations, such as code motion of
959 non-trapping instructions, nor does it impact optimization of subexpressions,
960 code duplication transformations, or basic-block reordering
965 <!-- ======================================================================= -->
966 <div class="doc_subsection">
967 <a name="format_common_lifetime">Object lifetimes and scoping</a>
970 <div class="doc_text">
971 <p>In many languages, the local variables in functions can have their lifetime
972 or scope limited to a subset of a function. In the C family of languages,
973 for example, variables are only live (readable and writable) within the
974 source block that they are defined in. In functional languages, values are
975 only readable after they have been defined. Though this is a very obvious
976 concept, it is also non-trivial to model in LLVM, because it has no notion of
977 scoping in this sense, and does not want to be tied to a language's scoping
980 <p>In order to handle this, the LLVM debug format uses the notion of "regions"
981 of a function, delineated by calls to intrinsic functions. These intrinsic
982 functions define new regions of the program and indicate when the region
983 lifetime expires. Consider the following C fragment, for example:</p>
985 <div class="doc_code">
999 <p>Compiled to LLVM, this function would be represented like this:</p>
1001 <div class="doc_code">
1011 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 )
1013 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 )
1015 call void @<a href="#format_common_declare">llvm.dbg.declare</a>({}* %X, ...)
1016 call void @<a href="#format_common_declare">llvm.dbg.declare</a>({}* %Y, ...)
1018 <i>;; Evaluate expression on line 2, assigning to X.</i>
1020 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 )
1022 <i>;; Evaluate expression on line 3, assigning to Y.</i>
1024 call void @<a href="#format_common_stoppoint">llvm.region.start</a>()
1025 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 )
1026 call void @<a href="#format_common_declare">llvm.dbg.declare</a>({}* %X, ...)
1028 <i>;; Evaluate expression on line 5, assigning to Z.</i>
1030 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 )
1031 call void @<a href="#format_common_region_end">llvm.region.end</a>()
1033 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 )
1035 call void @<a href="#format_common_region_end">llvm.region.end</a>()
1042 <p>This example illustrates a few important details about the LLVM debugging
1043 information. In particular, it shows how the various intrinsics are applied
1044 together to allow a debugger to analyze the relationship between statements,
1045 variable definitions, and the code used to implement the function.</p>
1048 intrinsic <tt>%<a href="#format_common_func_start">llvm.dbg.func.start</a></tt>
1049 provides a link with the <a href="#format_subprograms">subprogram
1050 descriptor</a> containing the details of this function. This call also
1051 defines the beginning of the function region, bounded by
1052 the <tt>%<a href="#format_common_region_end">llvm.region.end</a></tt> at the
1053 end of the function. This region is used to bracket the lifetime of
1054 variables declared within. For a function, this outer region defines a new
1055 stack frame whose lifetime ends when the region is ended.</p>
1057 <p>It is possible to define inner regions for short term variables by using the
1058 %<a href="#format_common_stoppoint"><tt>llvm.region.start</tt></a>
1059 and <a href="#format_common_region_end"><tt>%llvm.region.end</tt></a> to
1060 bound a region. The inner region in this example would be for the block
1061 containing the declaration of Z.</p>
1063 <p>Using regions to represent the boundaries of source-level functions allow
1064 LLVM interprocedural optimizations to arbitrarily modify LLVM functions
1065 without having to worry about breaking mapping information between the LLVM
1066 code and the and source-level program. In particular, the inliner requires
1067 no modification to support inlining with debugging information: there is no
1068 explicit correlation drawn between LLVM functions and their source-level
1069 counterparts (note however, that if the inliner inlines all instances of a
1070 non-strong-linkage function into its caller that it will not be possible for
1071 the user to manually invoke the inlined function from a debugger).</p>
1073 <p>Once the function has been defined,
1074 the <a href="#format_common_stoppoint"><tt>stopping point</tt></a>
1075 corresponding to line #2 (column #2) of the function is encountered. At this
1076 point in the function, <b>no</b> local variables are live. As lines 2 and 3
1077 of the example are executed, their variable definitions are introduced into
1079 %<a href="#format_common_declare"><tt>llvm.dbg.declare</tt></a>, without the
1080 need to specify a new region. These variables do not require new regions to
1081 be introduced because they go out of scope at the same point in the program:
1084 <p>In contrast, the <tt>Z</tt> variable goes out of scope at a different time,
1085 on line 7. For this reason, it is defined within the inner region, which
1086 kills the availability of <tt>Z</tt> before the code for line 8 is executed.
1087 In this way, regions can support arbitrary source-language scoping rules, as
1088 long as they can only be nested (ie, one scope cannot partially overlap with
1089 a part of another scope).</p>
1091 <p>It is worth noting that this scoping mechanism is used to control scoping of
1092 all declarations, not just variable declarations. For example, the scope of
1093 a C++ using declaration is controlled with this and could change how name
1094 lookup is performed.</p>
1098 <!-- *********************************************************************** -->
1099 <div class="doc_section">
1100 <a name="ccxx_frontend">C/C++ front-end specific debug information</a>
1102 <!-- *********************************************************************** -->
1104 <div class="doc_text">
1106 <p>The C and C++ front-ends represent information about the program in a format
1107 that is effectively identical
1108 to <a href="http://www.eagercon.com/dwarf/dwarf3std.htm">DWARF 3.0</a> in
1109 terms of information content. This allows code generators to trivially
1110 support native debuggers by generating standard dwarf information, and
1111 contains enough information for non-dwarf targets to translate it as
1114 <p>This section describes the forms used to represent C and C++ programs. Other
1115 languages could pattern themselves after this (which itself is tuned to
1116 representing programs in the same way that DWARF 3 does), or they could
1117 choose to provide completely different forms if they don't fit into the DWARF
1118 model. As support for debugging information gets added to the various LLVM
1119 source-language front-ends, the information used should be documented
1122 <p>The following sections provide examples of various C/C++ constructs and the
1123 debug information that would best describe those constructs.</p>
1127 <!-- ======================================================================= -->
1128 <div class="doc_subsection">
1129 <a name="ccxx_compile_units">C/C++ source file information</a>
1132 <div class="doc_text">
1134 <p>Given the source files <tt>MySource.cpp</tt> and <tt>MyHeader.h</tt> located
1135 in the directory <tt>/Users/mine/sources</tt>, the following code:</p>
1137 <div class="doc_code">
1139 #include "MyHeader.h"
1141 int main(int argc, char *argv[]) {
1147 <p>a C/C++ front-end would generate the following descriptors:</p>
1149 <div class="doc_code">
1153 ;; Define types used. In this case we need one for compile unit anchors and one
1154 ;; for compile units.
1156 %<a href="#format_anchors">llvm.dbg.anchor.type</a> = type { uint, uint }
1157 %<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> = type { uint, { }*, uint, uint, i8*, i8*, i8* }
1160 ;; Define the anchor for compile units. Note that the second field of the
1161 ;; anchor is 17, which is the same as the tag for compile units
1162 ;; (17 = DW_TAG_compile_unit.)
1164 %<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"
1167 ;; Define the compile unit for the source file "/Users/mine/sources/MySource.cpp".
1169 %<a href="#format_compile_units">llvm.dbg.compile_unit1</a> = internal constant %<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> {
1170 uint add(uint 17, uint 262144),
1171 { }* cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_units</a> to { }*),
1174 i8* getelementptr ([13 x i8]* %str1, i32 0, i32 0),
1175 i8* getelementptr ([21 x i8]* %str2, i32 0, i32 0),
1176 i8* getelementptr ([33 x i8]* %str3, i32 0, i32 0) }, section "llvm.metadata"
1179 ;; Define the compile unit for the header file "/Users/mine/sources/MyHeader.h".
1181 %<a href="#format_compile_units">llvm.dbg.compile_unit2</a> = internal constant %<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> {
1182 uint add(uint 17, uint 262144),
1183 { }* cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_units</a> to { }*),
1186 i8* getelementptr ([11 x i8]* %str4, int 0, int 0),
1187 i8* getelementptr ([21 x i8]* %str2, int 0, int 0),
1188 i8* getelementptr ([33 x i8]* %str3, int 0, int 0) }, section "llvm.metadata"
1191 ;; Define each of the strings used in the compile units.
1193 %str1 = internal constant [13 x i8] c"MySource.cpp\00", section "llvm.metadata";
1194 %str2 = internal constant [21 x i8] c"/Users/mine/sources/\00", section "llvm.metadata";
1195 %str3 = internal constant [33 x i8] c"4.0.1 LLVM (LLVM research group)\00", section "llvm.metadata";
1196 %str4 = internal constant [11 x i8] c"MyHeader.h\00", section "llvm.metadata";
1203 <!-- ======================================================================= -->
1204 <div class="doc_subsection">
1205 <a name="ccxx_global_variable">C/C++ global variable information</a>
1208 <div class="doc_text">
1210 <p>Given an integer global variable declared as follows:</p>
1212 <div class="doc_code">
1218 <p>a C/C++ front-end would generate the following descriptors:</p>
1220 <div class="doc_code">
1223 ;; Define types used. One for global variable anchors, one for the global
1224 ;; variable descriptor, one for the global's basic type and one for the global's
1227 %<a href="#format_anchors">llvm.dbg.anchor.type</a> = type { uint, uint }
1228 %<a href="#format_global_variables">llvm.dbg.global_variable.type</a> = type { uint, { }*, { }*, i8*, { }*, uint, { }*, bool, bool, { }*, uint }
1229 %<a href="#format_basic_type">llvm.dbg.basictype.type</a> = type { uint, { }*, i8*, { }*, int, uint, uint, uint, uint }
1230 %<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> = ...
1233 ;; Define the global itself.
1235 %MyGlobal = global int 100
1238 ;; Define the anchor for global variables. Note that the second field of the
1239 ;; anchor is 52, which is the same as the tag for global variables
1240 ;; (52 = DW_TAG_variable.)
1242 %<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"
1245 ;; Define the global variable descriptor. Note the reference to the global
1246 ;; variable anchor and the global variable itself.
1248 %<a href="#format_global_variables">llvm.dbg.global_variable</a> = internal constant %<a href="#format_global_variables">llvm.dbg.global_variable.type</a> {
1249 uint add(uint 52, uint 262144),
1250 { }* cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_global_variables">llvm.dbg.global_variables</a> to { }*),
1251 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1252 i8* getelementptr ([9 x i8]* %str1, int 0, int 0),
1253 i8* getelementptr ([1 x i8]* %str2, int 0, int 0),
1254 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1256 { }* cast (%<a href="#format_basic_type">llvm.dbg.basictype.type</a>* %<a href="#format_basic_type">llvm.dbg.basictype</a> to { }*),
1259 { }* cast (int* %MyGlobal to { }*) }, section "llvm.metadata"
1262 ;; Define the basic type of 32 bit signed integer. Note that since int is an
1263 ;; intrinsic type the source file is NULL and line 0.
1265 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1266 uint add(uint 36, uint 262144),
1267 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1268 i8* getelementptr ([4 x i8]* %str3, int 0, int 0),
1274 uint 5 }, section "llvm.metadata"
1277 ;; Define the names of the global variable and basic type.
1279 %str1 = internal constant [9 x i8] c"MyGlobal\00", section "llvm.metadata"
1280 %str2 = internal constant [1 x i8] c"\00", section "llvm.metadata"
1281 %str3 = internal constant [4 x i8] c"int\00", section "llvm.metadata"
1287 <!-- ======================================================================= -->
1288 <div class="doc_subsection">
1289 <a name="ccxx_subprogram">C/C++ function information</a>
1292 <div class="doc_text">
1294 <p>Given a function declared as follows:</p>
1296 <div class="doc_code">
1298 int main(int argc, char *argv[]) {
1304 <p>a C/C++ front-end would generate the following descriptors:</p>
1306 <div class="doc_code">
1309 ;; Define types used. One for subprogram anchors, one for the subprogram
1310 ;; descriptor, one for the global's basic type and one for the subprogram's
1313 %<a href="#format_subprograms">llvm.dbg.subprogram.type</a> = type { uint, { }*, { }*, i8*, { }*, bool, bool }
1314 %<a href="#format_anchors">llvm.dbg.anchor.type</a> = type { uint, uint }
1315 %<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> = ...
1318 ;; Define the anchor for subprograms. Note that the second field of the
1319 ;; anchor is 46, which is the same as the tag for subprograms
1320 ;; (46 = DW_TAG_subprogram.)
1322 %<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"
1325 ;; Define the descriptor for the subprogram. TODO - more details.
1327 %<a href="#format_subprograms">llvm.dbg.subprogram</a> = internal constant %<a href="#format_subprograms">llvm.dbg.subprogram.type</a> {
1328 uint add(uint 46, uint 262144),
1329 { }* cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_subprograms">llvm.dbg.subprograms</a> to { }*),
1330 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1331 i8* getelementptr ([5 x i8]* %str1, int 0, int 0),
1332 i8* getelementptr ([1 x i8]* %str2, int 0, int 0),
1333 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1337 bool true }, section "llvm.metadata"
1340 ;; Define the name of the subprogram.
1342 %str1 = internal constant [5 x i8] c"main\00", section "llvm.metadata"
1343 %str2 = internal constant [1 x i8] c"\00", section "llvm.metadata"
1346 ;; Define the subprogram itself.
1348 int %main(int %argc, i8** %argv) {
1356 <!-- ======================================================================= -->
1357 <div class="doc_subsection">
1358 <a name="ccxx_basic_types">C/C++ basic types</a>
1361 <div class="doc_text">
1363 <p>The following are the basic type descriptors for C/C++ core types:</p>
1367 <!-- ======================================================================= -->
1368 <div class="doc_subsubsection">
1369 <a name="ccxx_basic_type_bool">bool</a>
1372 <div class="doc_text">
1374 <div class="doc_code">
1376 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1377 uint add(uint 36, uint 262144),
1378 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1379 i8* getelementptr ([5 x i8]* %str1, int 0, int 0),
1385 uint 2 }, section "llvm.metadata"
1386 %str1 = internal constant [5 x i8] c"bool\00", section "llvm.metadata"
1392 <!-- ======================================================================= -->
1393 <div class="doc_subsubsection">
1394 <a name="ccxx_basic_char">char</a>
1397 <div class="doc_text">
1399 <div class="doc_code">
1401 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1402 uint add(uint 36, uint 262144),
1403 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1404 i8* getelementptr ([5 x i8]* %str1, int 0, int 0),
1410 uint 6 }, section "llvm.metadata"
1411 %str1 = internal constant [5 x i8] c"char\00", section "llvm.metadata"
1417 <!-- ======================================================================= -->
1418 <div class="doc_subsubsection">
1419 <a name="ccxx_basic_unsigned_char">unsigned char</a>
1422 <div class="doc_text">
1424 <div class="doc_code">
1426 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1427 uint add(uint 36, uint 262144),
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 i8* getelementptr ([14 x i8]* %str1, int 0, int 0),
1435 uint 8 }, section "llvm.metadata"
1436 %str1 = internal constant [14 x i8] c"unsigned char\00", section "llvm.metadata"
1442 <!-- ======================================================================= -->
1443 <div class="doc_subsubsection">
1444 <a name="ccxx_basic_short">short</a>
1447 <div class="doc_text">
1449 <div class="doc_code">
1451 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1452 uint add(uint 36, uint 262144),
1453 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1454 i8* getelementptr ([10 x i8]* %str1, int 0, int 0),
1460 uint 5 }, section "llvm.metadata"
1461 %str1 = internal constant [10 x i8] c"short int\00", section "llvm.metadata"
1467 <!-- ======================================================================= -->
1468 <div class="doc_subsubsection">
1469 <a name="ccxx_basic_unsigned_short">unsigned short</a>
1472 <div class="doc_text">
1474 <div class="doc_code">
1476 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1477 uint add(uint 36, uint 262144),
1478 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1479 i8* getelementptr ([19 x i8]* %str1, int 0, int 0),
1485 uint 7 }, section "llvm.metadata"
1486 %str1 = internal constant [19 x i8] c"short unsigned int\00", section "llvm.metadata"
1492 <!-- ======================================================================= -->
1493 <div class="doc_subsubsection">
1494 <a name="ccxx_basic_int">int</a>
1497 <div class="doc_text">
1499 <div class="doc_code">
1501 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1502 uint add(uint 36, uint 262144),
1503 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1504 i8* getelementptr ([4 x i8]* %str1, int 0, int 0),
1510 uint 5 }, section "llvm.metadata"
1511 %str1 = internal constant [4 x i8] c"int\00", section "llvm.metadata"
1516 <!-- ======================================================================= -->
1517 <div class="doc_subsubsection">
1518 <a name="ccxx_basic_unsigned_int">unsigned int</a>
1521 <div class="doc_text">
1523 <div class="doc_code">
1525 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1526 uint add(uint 36, uint 262144),
1527 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1528 i8* getelementptr ([13 x i8]* %str1, int 0, int 0),
1534 uint 7 }, section "llvm.metadata"
1535 %str1 = internal constant [13 x i8] c"unsigned int\00", section "llvm.metadata"
1541 <!-- ======================================================================= -->
1542 <div class="doc_subsubsection">
1543 <a name="ccxx_basic_long_long">long long</a>
1546 <div class="doc_text">
1548 <div class="doc_code">
1550 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1551 uint add(uint 36, uint 262144),
1552 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1553 i8* getelementptr ([14 x i8]* %str1, int 0, int 0),
1559 uint 5 }, section "llvm.metadata"
1560 %str1 = internal constant [14 x i8] c"long long int\00", section "llvm.metadata"
1566 <!-- ======================================================================= -->
1567 <div class="doc_subsubsection">
1568 <a name="ccxx_basic_unsigned_long_long">unsigned long long</a>
1571 <div class="doc_text">
1573 <div class="doc_code">
1575 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1576 uint add(uint 36, uint 262144),
1577 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1578 i8* getelementptr ([23 x i8]* %str1, int 0, int 0),
1584 uint 7 }, section "llvm.metadata"
1585 %str1 = internal constant [23 x 8] c"long long unsigned int\00", section "llvm.metadata"
1591 <!-- ======================================================================= -->
1592 <div class="doc_subsubsection">
1593 <a name="ccxx_basic_float">float</a>
1596 <div class="doc_text">
1598 <div class="doc_code">
1600 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1601 uint add(uint 36, uint 262144),
1602 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1603 i8* getelementptr ([6 x i8]* %str1, int 0, int 0),
1609 uint 4 }, section "llvm.metadata"
1610 %str1 = internal constant [6 x i8] c"float\00", section "llvm.metadata"
1616 <!-- ======================================================================= -->
1617 <div class="doc_subsubsection">
1618 <a name="ccxx_basic_double">double</a>
1621 <div class="doc_text">
1623 <div class="doc_code">
1625 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1626 uint add(uint 36, uint 262144),
1627 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1628 8* getelementptr ([7 x 8]* %str1, int 0, int 0),
1634 uint 4 }, section "llvm.metadata"
1635 %str1 = internal constant [7 x 8] c"double\00", section "llvm.metadata"
1641 <!-- ======================================================================= -->
1642 <div class="doc_subsection">
1643 <a name="ccxx_derived_types">C/C++ derived types</a>
1646 <div class="doc_text">
1648 <p>Given the following as an example of C/C++ derived type:</p>
1650 <div class="doc_code">
1652 typedef const int *IntPtr;
1656 <p>a C/C++ front-end would generate the following descriptors:</p>
1658 <div class="doc_code">
1661 ;; Define the typedef "IntPtr".
1663 %<a href="#format_derived_type">llvm.dbg.derivedtype1</a> = internal constant %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> {
1664 uint add(uint 22, uint 262144),
1665 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1666 i8* getelementptr ([7 x 8]* %str1, int 0, int 0),
1667 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1672 { }* cast (%<a href="#format_derived_type">llvm.dbg.derivedtype.type</a>* %<a href="#format_derived_type">llvm.dbg.derivedtype2</a> to { }*) }, section "llvm.metadata"
1673 %str1 = internal constant [7 x 8] c"IntPtr\00", section "llvm.metadata"
1676 ;; Define the pointer type.
1678 %<a href="#format_derived_type">llvm.dbg.derivedtype2</a> = internal constant %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> {
1679 uint add(uint 15, uint 262144),
1680 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1687 { }* cast (%<a href="#format_derived_type">llvm.dbg.derivedtype.type</a>* %<a href="#format_derived_type">llvm.dbg.derivedtype3</a> to { }*) }, section "llvm.metadata"
1690 ;; Define the const type.
1692 %<a href="#format_derived_type">llvm.dbg.derivedtype3</a> = internal constant %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> {
1693 uint add(uint 38, uint 262144),
1694 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1701 { }* cast (%<a href="#format_basic_type">llvm.dbg.basictype.type</a>* %<a href="#format_basic_type">llvm.dbg.basictype1</a> to { }*) }, section "llvm.metadata"
1704 ;; Define the int type.
1706 %<a href="#format_basic_type">llvm.dbg.basictype1</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1707 uint add(uint 36, uint 262144),
1708 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1709 8* getelementptr ([4 x 8]* %str2, int 0, int 0),
1715 uint 5 }, section "llvm.metadata"
1716 %str2 = internal constant [4 x 8] c"int\00", section "llvm.metadata"
1722 <!-- ======================================================================= -->
1723 <div class="doc_subsection">
1724 <a name="ccxx_composite_types">C/C++ struct/union types</a>
1727 <div class="doc_text">
1729 <p>Given the following as an example of C/C++ struct type:</p>
1731 <div class="doc_code">
1741 <p>a C/C++ front-end would generate the following descriptors:</p>
1743 <div class="doc_code">
1746 ;; Define basic type for unsigned int.
1748 %<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
1749 uint add(uint 36, uint 262144),
1750 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1751 i8* getelementptr ([13 x i8]* %str1, int 0, int 0),
1757 uint 7 }, section "llvm.metadata"
1758 %str1 = internal constant [13 x i8] c"unsigned int\00", section "llvm.metadata"
1761 ;; Define composite type for struct Color.
1763 %<a href="#format_composite_type">llvm.dbg.compositetype</a> = internal constant %<a href="#format_composite_type">llvm.dbg.compositetype.type</a> {
1764 uint add(uint 19, uint 262144),
1765 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1766 i8* getelementptr ([6 x i8]* %str2, int 0, int 0),
1767 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1773 { }* cast ([3 x { }*]* %llvm.dbg.array to { }*) }, section "llvm.metadata"
1774 %str2 = internal constant [6 x i8] c"Color\00", section "llvm.metadata"
1777 ;; Define the Red field.
1779 %<a href="#format_derived_type">llvm.dbg.derivedtype1</a> = internal constant %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> {
1780 uint add(uint 13, uint 262144),
1782 i8* getelementptr ([4 x i8]* %str3, int 0, int 0),
1783 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1788 { }* cast (%<a href="#format_basic_type">llvm.dbg.basictype.type</a>* %<a href="#format_basic_type">llvm.dbg.basictype</a> to { }*) }, section "llvm.metadata"
1789 %str3 = internal constant [4 x i8] c"Red\00", section "llvm.metadata"
1792 ;; Define the Green field.
1794 %<a href="#format_derived_type">llvm.dbg.derivedtype2</a> = internal constant %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> {
1795 uint add(uint 13, uint 262144),
1797 i8* getelementptr ([6 x i8]* %str4, int 0, int 0),
1798 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1803 { }* cast (%<a href="#format_basic_type">llvm.dbg.basictype.type</a>* %<a href="#format_basic_type">llvm.dbg.basictype</a> to { }*) }, section "llvm.metadata"
1804 %str4 = internal constant [6 x i8] c"Green\00", section "llvm.metadata"
1807 ;; Define the Blue field.
1809 %<a href="#format_derived_type">llvm.dbg.derivedtype3</a> = internal constant %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> {
1810 uint add(uint 13, uint 262144),
1812 i8* getelementptr ([5 x i8]* %str5, int 0, int 0),
1813 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1818 { }* cast (%<a href="#format_basic_type">llvm.dbg.basictype.type</a>* %<a href="#format_basic_type">llvm.dbg.basictype</a> to { }*) }, section "llvm.metadata"
1819 %str5 = internal constant [5 x 8] c"Blue\00", section "llvm.metadata"
1822 ;; Define the array of fields used by the composite type Color.
1824 %llvm.dbg.array = internal constant [3 x { }*] [
1825 { }* cast (%<a href="#format_derived_type">llvm.dbg.derivedtype.type</a>* %<a href="#format_derived_type">llvm.dbg.derivedtype1</a> to { }*),
1826 { }* cast (%<a href="#format_derived_type">llvm.dbg.derivedtype.type</a>* %<a href="#format_derived_type">llvm.dbg.derivedtype2</a> to { }*),
1827 { }* cast (%<a href="#format_derived_type">llvm.dbg.derivedtype.type</a>* %<a href="#format_derived_type">llvm.dbg.derivedtype3</a> to { }*) ], section "llvm.metadata"
1833 <!-- ======================================================================= -->
1834 <div class="doc_subsection">
1835 <a name="ccxx_enumeration_types">C/C++ enumeration types</a>
1838 <div class="doc_text">
1840 <p>Given the following as an example of C/C++ enumeration type:</p>
1842 <div class="doc_code">
1852 <p>a C/C++ front-end would generate the following descriptors:</p>
1854 <div class="doc_code">
1857 ;; Define composite type for enum Trees
1859 %<a href="#format_composite_type">llvm.dbg.compositetype</a> = internal constant %<a href="#format_composite_type">llvm.dbg.compositetype.type</a> {
1860 uint add(uint 4, uint 262144),
1861 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1862 i8* getelementptr ([6 x i8]* %str1, int 0, int 0),
1863 { }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
1869 { }* cast ([3 x { }*]* %llvm.dbg.array to { }*) }, section "llvm.metadata"
1870 %str1 = internal constant [6 x i8] c"Trees\00", section "llvm.metadata"
1873 ;; Define Spruce enumerator.
1875 %<a href="#format_enumeration">llvm.dbg.enumerator1</a> = internal constant %<a href="#format_enumeration">llvm.dbg.enumerator.type</a> {
1876 uint add(uint 40, uint 262144),
1877 i8* getelementptr ([7 x i8]* %str2, int 0, int 0),
1878 int 100 }, section "llvm.metadata"
1879 %str2 = internal constant [7 x i8] c"Spruce\00", section "llvm.metadata"
1882 ;; Define Oak enumerator.
1884 %<a href="#format_enumeration">llvm.dbg.enumerator2</a> = internal constant %<a href="#format_enumeration">llvm.dbg.enumerator.type</a> {
1885 uint add(uint 40, uint 262144),
1886 i8* getelementptr ([4 x i8]* %str3, int 0, int 0),
1887 int 200 }, section "llvm.metadata"
1888 %str3 = internal constant [4 x i8] c"Oak\00", section "llvm.metadata"
1891 ;; Define Maple enumerator.
1893 %<a href="#format_enumeration">llvm.dbg.enumerator3</a> = internal constant %<a href="#format_enumeration">llvm.dbg.enumerator.type</a> {
1894 uint add(uint 40, uint 262144),
1895 i8* getelementptr ([6 x i8]* %str4, int 0, int 0),
1896 int 300 }, section "llvm.metadata"
1897 %str4 = internal constant [6 x i8] c"Maple\00", section "llvm.metadata"
1900 ;; Define the array of enumerators used by composite type Trees.
1902 %llvm.dbg.array = internal constant [3 x { }*] [
1903 { }* cast (%<a href="#format_enumeration">llvm.dbg.enumerator.type</a>* %<a href="#format_enumeration">llvm.dbg.enumerator1</a> to { }*),
1904 { }* cast (%<a href="#format_enumeration">llvm.dbg.enumerator.type</a>* %<a href="#format_enumeration">llvm.dbg.enumerator2</a> to { }*),
1905 { }* cast (%<a href="#format_enumeration">llvm.dbg.enumerator.type</a>* %<a href="#format_enumeration">llvm.dbg.enumerator3</a> to { }*) ], section "llvm.metadata"
1911 <!-- *********************************************************************** -->
1915 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
1916 src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
1917 <a href="http://validator.w3.org/check/referer"><img
1918 src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
1920 <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
1921 <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
1922 Last modified: $Date$