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 <h1>Source Level Debugging with LLVM</h1>
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_compile_units">Compile unit descriptors</a></li>
28 <li><a href="#format_files">File 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_declare">llvm.dbg.declare</a></li>
42 <li><a href="#format_common_value">llvm.dbg.value</a></li>
45 <li><a href="#format_common_lifetime">Object lifetimes and scoping</a></li>
46 <li><a href="#ccxx_frontend">C/C++ front-end specific debug information</a>
48 <li><a href="#ccxx_compile_units">C/C++ source file information</a></li>
49 <li><a href="#ccxx_global_variable">C/C++ global variable information</a></li>
50 <li><a href="#ccxx_subprogram">C/C++ function information</a></li>
51 <li><a href="#ccxx_basic_types">C/C++ basic types</a></li>
52 <li><a href="#ccxx_derived_types">C/C++ derived types</a></li>
53 <li><a href="#ccxx_composite_types">C/C++ struct/union types</a></li>
54 <li><a href="#ccxx_enumeration_types">C/C++ enumeration types</a></li>
56 <li><a href="#llvmdwarfextension">LLVM Dwarf Extensions</a>
58 <li><a href="#objcproperty">Debugging Information Extension
59 for Objective C Properties</a></li>
61 <li><a href="#objcpropertyintroduction">Introduction</a></li>
62 <li><a href="#objcpropertyproposal">Proposal</a></li>
63 <li><a href="#objcpropertynewattributes">New DWARF Attributes</a></li>
64 <li><a href="#objcpropertynewconstants">New DWARF Constants</a></li>
72 <img src="img/venusflytrap.jpg" alt="A leafy and green bug eater" width="247"
77 <div class="doc_author">
78 <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>
79 and <a href="mailto:jlaskey@mac.com">Jim Laskey</a></p>
83 <!-- *********************************************************************** -->
84 <h2><a name="introduction">Introduction</a></h2>
85 <!-- *********************************************************************** -->
89 <p>This document is the central repository for all information pertaining to
90 debug information in LLVM. It describes the <a href="#format">actual format
91 that the LLVM debug information</a> takes, which is useful for those
92 interested in creating front-ends or dealing directly with the information.
93 Further, this document provides specific examples of what debug information
94 for C/C++ looks like.</p>
96 <!-- ======================================================================= -->
98 <a name="phil">Philosophy behind LLVM debugging information</a>
103 <p>The idea of the LLVM debugging information is to capture how the important
104 pieces of the source-language's Abstract Syntax Tree map onto LLVM code.
105 Several design aspects have shaped the solution that appears here. The
106 important ones are:</p>
109 <li>Debugging information should have very little impact on the rest of the
110 compiler. No transformations, analyses, or code generators should need to
111 be modified because of debugging information.</li>
113 <li>LLVM optimizations should interact in <a href="#debugopt">well-defined and
114 easily described ways</a> with the debugging information.</li>
116 <li>Because LLVM is designed to support arbitrary programming languages,
117 LLVM-to-LLVM tools should not need to know anything about the semantics of
118 the source-level-language.</li>
120 <li>Source-level languages are often <b>widely</b> different from one another.
121 LLVM should not put any restrictions of the flavor of the source-language,
122 and the debugging information should work with any language.</li>
124 <li>With code generator support, it should be possible to use an LLVM compiler
125 to compile a program to native machine code and standard debugging
126 formats. This allows compatibility with traditional machine-code level
127 debuggers, like GDB or DBX.</li>
130 <p>The approach used by the LLVM implementation is to use a small set
131 of <a href="#format_common_intrinsics">intrinsic functions</a> to define a
132 mapping between LLVM program objects and the source-level objects. The
133 description of the source-level program is maintained in LLVM metadata
134 in an <a href="#ccxx_frontend">implementation-defined format</a>
135 (the C/C++ front-end currently uses working draft 7 of
136 the <a href="http://www.eagercon.com/dwarf/dwarf3std.htm">DWARF 3
139 <p>When a program is being debugged, a debugger interacts with the user and
140 turns the stored debug information into source-language specific information.
141 As such, a debugger must be aware of the source-language, and is thus tied to
142 a specific language or family of languages.</p>
146 <!-- ======================================================================= -->
148 <a name="consumers">Debug information consumers</a>
153 <p>The role of debug information is to provide meta information normally
154 stripped away during the compilation process. This meta information provides
155 an LLVM user a relationship between generated code and the original program
158 <p>Currently, debug information is consumed by DwarfDebug to produce dwarf
159 information used by the gdb debugger. Other targets could use the same
160 information to produce stabs or other debug forms.</p>
162 <p>It would also be reasonable to use debug information to feed profiling tools
163 for analysis of generated code, or, tools for reconstructing the original
164 source from generated code.</p>
166 <p>TODO - expound a bit more.</p>
170 <!-- ======================================================================= -->
172 <a name="debugopt">Debugging optimized code</a>
177 <p>An extremely high priority of LLVM debugging information is to make it
178 interact well with optimizations and analysis. In particular, the LLVM debug
179 information provides the following guarantees:</p>
182 <li>LLVM debug information <b>always provides information to accurately read
183 the source-level state of the program</b>, regardless of which LLVM
184 optimizations have been run, and without any modification to the
185 optimizations themselves. However, some optimizations may impact the
186 ability to modify the current state of the program with a debugger, such
187 as setting program variables, or calling functions that have been
190 <li>As desired, LLVM optimizations can be upgraded to be aware of the LLVM
191 debugging information, allowing them to update the debugging information
192 as they perform aggressive optimizations. This means that, with effort,
193 the LLVM optimizers could optimize debug code just as well as non-debug
196 <li>LLVM debug information does not prevent optimizations from
197 happening (for example inlining, basic block reordering/merging/cleanup,
198 tail duplication, etc).</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>
235 <!-- *********************************************************************** -->
237 <a name="format">Debugging information format</a>
239 <!-- *********************************************************************** -->
243 <p>LLVM debugging information has been carefully designed to make it possible
244 for the optimizer to optimize the program and debugging information without
245 necessarily having to know anything about debugging information. In
246 particular, the use of metadata avoids duplicated debugging information from
247 the beginning, and the global dead code elimination pass automatically
248 deletes debugging information for a function if it decides to delete the
251 <p>To do this, most of the debugging information (descriptors for types,
252 variables, functions, source files, etc) is inserted by the language
253 front-end in the form of LLVM metadata. </p>
255 <p>Debug information is designed to be agnostic about the target debugger and
256 debugging information representation (e.g. DWARF/Stabs/etc). It uses a
257 generic pass to decode the information that represents variables, types,
258 functions, namespaces, etc: this allows for arbitrary source-language
259 semantics and type-systems to be used, as long as there is a module
260 written for the target debugger to interpret the information. </p>
262 <p>To provide basic functionality, the LLVM debugger does have to make some
263 assumptions about the source-level language being debugged, though it keeps
264 these to a minimum. The only common features that the LLVM debugger assumes
265 exist are <a href="#format_files">source files</a>,
266 and <a href="#format_global_variables">program objects</a>. These abstract
267 objects are used by a debugger to form stack traces, show information about
268 local variables, etc.</p>
270 <p>This section of the documentation first describes the representation aspects
271 common to any source-language. The <a href="#ccxx_frontend">next section</a>
272 describes the data layout conventions used by the C and C++ front-ends.</p>
274 <!-- ======================================================================= -->
276 <a name="debug_info_descriptors">Debug information descriptors</a>
281 <p>In consideration of the complexity and volume of debug information, LLVM
282 provides a specification for well formed debug descriptors. </p>
284 <p>Consumers of LLVM debug information expect the descriptors for program
285 objects to start in a canonical format, but the descriptors can include
286 additional information appended at the end that is source-language
287 specific. All LLVM debugging information is versioned, allowing backwards
288 compatibility in the case that the core structures need to change in some
289 way. Also, all debugging information objects start with a tag to indicate
290 what type of object it is. The source-language is allowed to define its own
291 objects, by using unreserved tag numbers. We recommend using with tags in
292 the range 0x1000 through 0x2000 (there is a defined enum DW_TAG_user_base =
295 <p>The fields of debug descriptors used internally by LLVM
296 are restricted to only the simple data types <tt>i32</tt>, <tt>i1</tt>,
297 <tt>float</tt>, <tt>double</tt>, <tt>mdstring</tt> and <tt>mdnode</tt>. </p>
299 <div class="doc_code">
308 <p><a name="LLVMDebugVersion">The first field of a descriptor is always an
309 <tt>i32</tt> containing a tag value identifying the content of the
310 descriptor. The remaining fields are specific to the descriptor. The values
311 of tags are loosely bound to the tag values of DWARF information entries.
312 However, that does not restrict the use of the information supplied to DWARF
313 targets. To facilitate versioning of debug information, the tag is augmented
314 with the current debug version (LLVMDebugVersion = 8 << 16 or
315 0x80000 or 524288.)</a></p>
317 <p>The details of the various descriptors follow.</p>
319 <!-- ======================================================================= -->
321 <a name="format_compile_units">Compile unit descriptors</a>
326 <div class="doc_code">
329 i32, ;; Tag = 17 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
330 ;; (DW_TAG_compile_unit)
331 i32, ;; Unused field.
332 i32, ;; DWARF language identifier (ex. DW_LANG_C89)
333 metadata, ;; Source file name
334 metadata, ;; Source file directory (includes trailing slash)
335 metadata ;; Producer (ex. "4.0.1 LLVM (LLVM research group)")
336 i1, ;; True if this is a main compile unit.
337 i1, ;; True if this is optimized.
339 i32 ;; Runtime version
340 metadata ;; List of enums types
341 metadata ;; List of retained types
342 metadata ;; List of subprograms
343 metadata ;; List of global variables
348 <p>These descriptors contain a source language ID for the file (we use the DWARF
349 3.0 ID numbers, such as <tt>DW_LANG_C89</tt>, <tt>DW_LANG_C_plus_plus</tt>,
350 <tt>DW_LANG_Cobol74</tt>, etc), three strings describing the filename,
351 working directory of the compiler, and an identifier string for the compiler
352 that produced it.</p>
354 <p>Compile unit descriptors provide the root context for objects declared in a
355 specific compilation unit. File descriptors are defined using this context.
356 These descriptors are collected by a named metadata
357 <tt>!llvm.dbg.cu</tt>. Compile unit descriptor keeps track of subprograms,
358 global variables and type information.
362 <!-- ======================================================================= -->
364 <a name="format_files">File descriptors</a>
369 <div class="doc_code">
372 i32, ;; Tag = 41 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
373 ;; (DW_TAG_file_type)
374 metadata, ;; Source file name
375 metadata, ;; Source file directory (includes trailing slash)
381 <p>These descriptors contain information for a file. Global variables and top
382 level functions would be defined using this context.k File descriptors also
383 provide context for source line correspondence. </p>
385 <p>Each input file is encoded as a separate file descriptor in LLVM debugging
386 information output. </p>
390 <!-- ======================================================================= -->
392 <a name="format_global_variables">Global variable descriptors</a>
397 <div class="doc_code">
400 i32, ;; Tag = 52 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
402 i32, ;; Unused field.
403 metadata, ;; Reference to context descriptor
405 metadata, ;; Display name (fully qualified C++ name)
406 metadata, ;; MIPS linkage name (for C++)
407 metadata, ;; Reference to file where defined
408 i32, ;; Line number where defined
409 metadata, ;; Reference to type descriptor
410 i1, ;; True if the global is local to compile unit (static)
411 i1, ;; True if the global is defined in the compile unit (not extern)
412 {}* ;; Reference to the global variable
417 <p>These descriptors provide debug information about globals variables. The
418 provide details such as name, type and where the variable is defined. All
419 global variables are collected by named metadata <tt>!llvm.dbg.gv</tt>.</p>
423 <!-- ======================================================================= -->
425 <a name="format_subprograms">Subprogram descriptors</a>
430 <div class="doc_code">
433 i32, ;; Tag = 46 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
434 ;; (DW_TAG_subprogram)
435 i32, ;; Unused field.
436 metadata, ;; Reference to context descriptor
438 metadata, ;; Display name (fully qualified C++ name)
439 metadata, ;; MIPS linkage name (for C++)
440 metadata, ;; Reference to file where defined
441 i32, ;; Line number where defined
442 metadata, ;; Reference to type descriptor
443 i1, ;; True if the global is local to compile unit (static)
444 i1, ;; True if the global is defined in the compile unit (not extern)
445 i32, ;; Virtuality, e.g. dwarf::DW_VIRTUALITY__virtual
446 i32, ;; Index into a virtual function
447 metadata, ;; indicates which base type contains the vtable pointer for the
451 Function *,;; Pointer to LLVM function
452 metadata, ;; Lists function template parameters
453 metadata ;; Function declaration descriptor
454 metadata ;; List of function variables
459 <p>These descriptors provide debug information about functions, methods and
460 subprograms. They provide details such as name, return types and the source
461 location where the subprogram is defined.
462 All subprogram descriptors are collected by a named metadata
463 <tt>!llvm.dbg.sp</tt>.
468 <!-- ======================================================================= -->
470 <a name="format_blocks">Block descriptors</a>
475 <div class="doc_code">
478 i32, ;; Tag = 11 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_lexical_block)
479 metadata,;; Reference to context descriptor
481 i32, ;; Column number
482 metadata,;; Reference to source file
483 i32 ;; Unique ID to identify blocks from a template function
488 <p>This descriptor provides debug information about nested blocks within a
489 subprogram. The line number and column numbers are used to dinstinguish
490 two lexical blocks at same depth. </p>
492 <div class="doc_code">
495 i32, ;; Tag = 11 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_lexical_block)
496 metadata ;; Reference to the scope we're annotating with a file change
497 metadata,;; Reference to the file the scope is enclosed in.
502 <p>This descriptor provides a wrapper around a lexical scope to handle file
503 changes in the middle of a lexical block.</p>
507 <!-- ======================================================================= -->
509 <a name="format_basic_type">Basic type descriptors</a>
514 <div class="doc_code">
517 i32, ;; Tag = 36 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
518 ;; (DW_TAG_base_type)
519 metadata, ;; Reference to context
520 metadata, ;; Name (may be "" for anonymous types)
521 metadata, ;; Reference to file where defined (may be NULL)
522 i32, ;; Line number where defined (may be 0)
524 i64, ;; Alignment in bits
525 i64, ;; Offset in bits
527 i32 ;; DWARF type encoding
532 <p>These descriptors define primitive types used in the code. Example int, bool
533 and float. The context provides the scope of the type, which is usually the
534 top level. Since basic types are not usually user defined the context
535 and line number can be left as NULL and 0. The size, alignment and offset
536 are expressed in bits and can be 64 bit values. The alignment is used to
537 round the offset when embedded in a
538 <a href="#format_composite_type">composite type</a> (example to keep float
539 doubles on 64 bit boundaries.) The offset is the bit offset if embedded in
540 a <a href="#format_composite_type">composite type</a>.</p>
542 <p>The type encoding provides the details of the type. The values are typically
543 one of the following:</p>
545 <div class="doc_code">
551 DW_ATE_signed_char = 6
553 DW_ATE_unsigned_char = 8
559 <!-- ======================================================================= -->
561 <a name="format_derived_type">Derived type descriptors</a>
566 <div class="doc_code">
569 i32, ;; Tag (see below)
570 metadata, ;; Reference to context
571 metadata, ;; Name (may be "" for anonymous types)
572 metadata, ;; Reference to file where defined (may be NULL)
573 i32, ;; Line number where defined (may be 0)
575 i64, ;; Alignment in bits
576 i64, ;; Offset in bits
577 metadata, ;; Reference to type derived from
578 metadata, ;; (optional) Name of the Objective C property assoicated with
579 ;; Objective-C an ivar
580 metadata, ;; (optional) Name of the Objective C property getter selector.
581 metadata, ;; (optional) Name of the Objective C property setter selector.
582 i32 ;; (optional) Objective C property attributes.
587 <p>These descriptors are used to define types derived from other types. The
588 value of the tag varies depending on the meaning. The following are possible
591 <div class="doc_code">
593 DW_TAG_formal_parameter = 5
595 DW_TAG_pointer_type = 15
596 DW_TAG_reference_type = 16
598 DW_TAG_const_type = 38
599 DW_TAG_volatile_type = 53
600 DW_TAG_restrict_type = 55
604 <p><tt>DW_TAG_member</tt> is used to define a member of
605 a <a href="#format_composite_type">composite type</a>
606 or <a href="#format_subprograms">subprogram</a>. The type of the member is
607 the <a href="#format_derived_type">derived
608 type</a>. <tt>DW_TAG_formal_parameter</tt> is used to define a member which
609 is a formal argument of a subprogram.</p>
611 <p><tt>DW_TAG_typedef</tt> is used to provide a name for the derived type.</p>
613 <p><tt>DW_TAG_pointer_type</tt>,<tt>DW_TAG_reference_type</tt>,
614 <tt>DW_TAG_const_type</tt>, <tt>DW_TAG_volatile_type</tt>
615 and <tt>DW_TAG_restrict_type</tt> are used to qualify
616 the <a href="#format_derived_type">derived type</a>. </p>
618 <p><a href="#format_derived_type">Derived type</a> location can be determined
619 from the context and line number. The size, alignment and offset are
620 expressed in bits and can be 64 bit values. The alignment is used to round
621 the offset when embedded in a <a href="#format_composite_type">composite
622 type</a> (example to keep float doubles on 64 bit boundaries.) The offset is
623 the bit offset if embedded in a <a href="#format_composite_type">composite
626 <p>Note that the <tt>void *</tt> type is expressed as a type derived from NULL.
631 <!-- ======================================================================= -->
633 <a name="format_composite_type">Composite type descriptors</a>
638 <div class="doc_code">
641 i32, ;; Tag (see below)
642 metadata, ;; Reference to context
643 metadata, ;; Name (may be "" for anonymous types)
644 metadata, ;; Reference to file where defined (may be NULL)
645 i32, ;; Line number where defined (may be 0)
647 i64, ;; Alignment in bits
648 i64, ;; Offset in bits
650 metadata, ;; Reference to type derived from
651 metadata, ;; Reference to array of member descriptors
652 i32 ;; Runtime languages
657 <p>These descriptors are used to define types that are composed of 0 or more
658 elements. The value of the tag varies depending on the meaning. The following
659 are possible tag values:</p>
661 <div class="doc_code">
663 DW_TAG_array_type = 1
664 DW_TAG_enumeration_type = 4
665 DW_TAG_structure_type = 19
666 DW_TAG_union_type = 23
667 DW_TAG_vector_type = 259
668 DW_TAG_subroutine_type = 21
669 DW_TAG_inheritance = 28
673 <p>The vector flag indicates that an array type is a native packed vector.</p>
675 <p>The members of array types (tag = <tt>DW_TAG_array_type</tt>) or vector types
676 (tag = <tt>DW_TAG_vector_type</tt>) are <a href="#format_subrange">subrange
677 descriptors</a>, each representing the range of subscripts at that level of
680 <p>The members of enumeration types (tag = <tt>DW_TAG_enumeration_type</tt>) are
681 <a href="#format_enumeration">enumerator descriptors</a>, each representing
682 the definition of enumeration value for the set. All enumeration type
683 descriptors are collected by named metadata <tt>!llvm.dbg.enum</tt>.</p>
685 <p>The members of structure (tag = <tt>DW_TAG_structure_type</tt>) or union (tag
686 = <tt>DW_TAG_union_type</tt>) types are any one of
687 the <a href="#format_basic_type">basic</a>,
688 <a href="#format_derived_type">derived</a>
689 or <a href="#format_composite_type">composite</a> type descriptors, each
690 representing a field member of the structure or union.</p>
692 <p>For C++ classes (tag = <tt>DW_TAG_structure_type</tt>), member descriptors
693 provide information about base classes, static members and member
694 functions. If a member is a <a href="#format_derived_type">derived type
695 descriptor</a> and has a tag of <tt>DW_TAG_inheritance</tt>, then the type
696 represents a base class. If the member of is
697 a <a href="#format_global_variables">global variable descriptor</a> then it
698 represents a static member. And, if the member is
699 a <a href="#format_subprograms">subprogram descriptor</a> then it represents
700 a member function. For static members and member
701 functions, <tt>getName()</tt> returns the members link or the C++ mangled
702 name. <tt>getDisplayName()</tt> the simplied version of the name.</p>
704 <p>The first member of subroutine (tag = <tt>DW_TAG_subroutine_type</tt>) type
705 elements is the return type for the subroutine. The remaining elements are
706 the formal arguments to the subroutine.</p>
708 <p><a href="#format_composite_type">Composite type</a> location can be
709 determined from the context and line number. The size, alignment and
710 offset are expressed in bits and can be 64 bit values. The alignment is used
711 to round the offset when embedded in
712 a <a href="#format_composite_type">composite type</a> (as an example, to keep
713 float doubles on 64 bit boundaries.) The offset is the bit offset if embedded
714 in a <a href="#format_composite_type">composite type</a>.</p>
718 <!-- ======================================================================= -->
720 <a name="format_subrange">Subrange descriptors</a>
725 <div class="doc_code">
728 i32, ;; Tag = 33 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_subrange_type)
735 <p>These descriptors are used to define ranges of array subscripts for an array
736 <a href="#format_composite_type">composite type</a>. The low value defines
737 the lower bounds typically zero for C/C++. The high value is the upper
738 bounds. Values are 64 bit. High - low + 1 is the size of the array. If low
739 > high the array bounds are not included in generated debugging information.
744 <!-- ======================================================================= -->
746 <a name="format_enumeration">Enumerator descriptors</a>
751 <div class="doc_code">
754 i32, ;; Tag = 40 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
755 ;; (DW_TAG_enumerator)
762 <p>These descriptors are used to define members of an
763 enumeration <a href="#format_composite_type">composite type</a>, it
764 associates the name to the value.</p>
768 <!-- ======================================================================= -->
770 <a name="format_variables">Local variables</a>
775 <div class="doc_code">
778 i32, ;; Tag (see below)
781 metadata, ;; Reference to file where defined
782 i32, ;; 24 bit - Line number where defined
783 ;; 8 bit - Argument number. 1 indicates 1st argument.
784 metadata, ;; Type descriptor
786 metadata ;; (optional) Reference to inline location
791 <p>These descriptors are used to define variables local to a sub program. The
792 value of the tag depends on the usage of the variable:</p>
794 <div class="doc_code">
796 DW_TAG_auto_variable = 256
797 DW_TAG_arg_variable = 257
798 DW_TAG_return_variable = 258
802 <p>An auto variable is any variable declared in the body of the function. An
803 argument variable is any variable that appears as a formal argument to the
804 function. A return variable is used to track the result of a function and
805 has no source correspondent.</p>
807 <p>The context is either the subprogram or block where the variable is defined.
808 Name the source variable name. Context and line indicate where the
809 variable was defined. Type descriptor defines the declared type of the
816 <!-- ======================================================================= -->
818 <a name="format_common_intrinsics">Debugger intrinsic functions</a>
823 <p>LLVM uses several intrinsic functions (name prefixed with "llvm.dbg") to
824 provide debug information at various points in generated code.</p>
826 <!-- ======================================================================= -->
828 <a name="format_common_declare">llvm.dbg.declare</a>
833 void %<a href="#format_common_declare">llvm.dbg.declare</a>(metadata, metadata)
836 <p>This intrinsic provides information about a local element (ex. variable.) The
837 first argument is metadata holding alloca for the variable. The
838 second argument is metadata containing description of the variable. </p>
841 <!-- ======================================================================= -->
843 <a name="format_common_value">llvm.dbg.value</a>
848 void %<a href="#format_common_value">llvm.dbg.value</a>(metadata, i64, metadata)
851 <p>This intrinsic provides information when a user source variable is set to a
852 new value. The first argument is the new value (wrapped as metadata). The
853 second argument is the offset in the user source variable where the new value
854 is written. The third argument is metadata containing description of the
855 user source variable. </p>
860 <!-- ======================================================================= -->
862 <a name="format_common_lifetime">Object lifetimes and scoping</a>
866 <p>In many languages, the local variables in functions can have their lifetimes
867 or scopes limited to a subset of a function. In the C family of languages,
868 for example, variables are only live (readable and writable) within the
869 source block that they are defined in. In functional languages, values are
870 only readable after they have been defined. Though this is a very obvious
871 concept, it is non-trivial to model in LLVM, because it has no notion of
872 scoping in this sense, and does not want to be tied to a language's scoping
875 <p>In order to handle this, the LLVM debug format uses the metadata attached to
876 llvm instructions to encode line number and scoping information. Consider
877 the following C fragment, for example:</p>
879 <div class="doc_code">
893 <p>Compiled to LLVM, this function would be represented like this:</p>
895 <div class="doc_code">
897 define void @foo() nounwind ssp {
899 %X = alloca i32, align 4 ; <i32*> [#uses=4]
900 %Y = alloca i32, align 4 ; <i32*> [#uses=4]
901 %Z = alloca i32, align 4 ; <i32*> [#uses=3]
902 %0 = bitcast i32* %X to {}* ; <{}*> [#uses=1]
903 call void @llvm.dbg.declare(metadata !{i32 * %X}, metadata !0), !dbg !7
904 store i32 21, i32* %X, !dbg !8
905 %1 = bitcast i32* %Y to {}* ; <{}*> [#uses=1]
906 call void @llvm.dbg.declare(metadata !{i32 * %Y}, metadata !9), !dbg !10
907 store i32 22, i32* %Y, !dbg !11
908 %2 = bitcast i32* %Z to {}* ; <{}*> [#uses=1]
909 call void @llvm.dbg.declare(metadata !{i32 * %Z}, metadata !12), !dbg !14
910 store i32 23, i32* %Z, !dbg !15
911 %tmp = load i32* %X, !dbg !16 ; <i32> [#uses=1]
912 %tmp1 = load i32* %Y, !dbg !16 ; <i32> [#uses=1]
913 %add = add nsw i32 %tmp, %tmp1, !dbg !16 ; <i32> [#uses=1]
914 store i32 %add, i32* %Z, !dbg !16
915 %tmp2 = load i32* %Y, !dbg !17 ; <i32> [#uses=1]
916 store i32 %tmp2, i32* %X, !dbg !17
920 declare void @llvm.dbg.declare(metadata, metadata) nounwind readnone
922 !0 = metadata !{i32 459008, metadata !1, metadata !"X",
923 metadata !3, i32 2, metadata !6}; [ DW_TAG_auto_variable ]
924 !1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ]
925 !2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo", metadata !"foo",
926 metadata !"foo", metadata !3, i32 1, metadata !4,
927 i1 false, i1 true}; [DW_TAG_subprogram ]
928 !3 = metadata !{i32 458769, i32 0, i32 12, metadata !"foo.c",
929 metadata !"/private/tmp", metadata !"clang 1.1", i1 true,
930 i1 false, metadata !"", i32 0}; [DW_TAG_compile_unit ]
931 !4 = metadata !{i32 458773, metadata !3, metadata !"", null, i32 0, i64 0, i64 0,
932 i64 0, i32 0, null, metadata !5, i32 0}; [DW_TAG_subroutine_type ]
933 !5 = metadata !{null}
934 !6 = metadata !{i32 458788, metadata !3, metadata !"int", metadata !3, i32 0,
935 i64 32, i64 32, i64 0, i32 0, i32 5}; [DW_TAG_base_type ]
936 !7 = metadata !{i32 2, i32 7, metadata !1, null}
937 !8 = metadata !{i32 2, i32 3, metadata !1, null}
938 !9 = metadata !{i32 459008, metadata !1, metadata !"Y", metadata !3, i32 3,
939 metadata !6}; [ DW_TAG_auto_variable ]
940 !10 = metadata !{i32 3, i32 7, metadata !1, null}
941 !11 = metadata !{i32 3, i32 3, metadata !1, null}
942 !12 = metadata !{i32 459008, metadata !13, metadata !"Z", metadata !3, i32 5,
943 metadata !6}; [ DW_TAG_auto_variable ]
944 !13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ]
945 !14 = metadata !{i32 5, i32 9, metadata !13, null}
946 !15 = metadata !{i32 5, i32 5, metadata !13, null}
947 !16 = metadata !{i32 6, i32 5, metadata !13, null}
948 !17 = metadata !{i32 8, i32 3, metadata !1, null}
949 !18 = metadata !{i32 9, i32 1, metadata !2, null}
953 <p>This example illustrates a few important details about LLVM debugging
954 information. In particular, it shows how the <tt>llvm.dbg.declare</tt>
955 intrinsic and location information, which are attached to an instruction,
956 are applied together to allow a debugger to analyze the relationship between
957 statements, variable definitions, and the code used to implement the
960 <div class="doc_code">
962 call void @llvm.dbg.declare(metadata, metadata !0), !dbg !7
966 <p>The first intrinsic
967 <tt>%<a href="#format_common_declare">llvm.dbg.declare</a></tt>
968 encodes debugging information for the variable <tt>X</tt>. The metadata
969 <tt>!dbg !7</tt> attached to the intrinsic provides scope information for the
970 variable <tt>X</tt>.</p>
972 <div class="doc_code">
974 !7 = metadata !{i32 2, i32 7, metadata !1, null}
975 !1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ]
976 !2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo",
977 metadata !"foo", metadata !"foo", metadata !3, i32 1,
978 metadata !4, i1 false, i1 true}; [DW_TAG_subprogram ]
982 <p>Here <tt>!7</tt> is metadata providing location information. It has four
983 fields: line number, column number, scope, and original scope. The original
984 scope represents inline location if this instruction is inlined inside a
985 caller, and is null otherwise. In this example, scope is encoded by
986 <tt>!1</tt>. <tt>!1</tt> represents a lexical block inside the scope
987 <tt>!2</tt>, where <tt>!2</tt> is a
988 <a href="#format_subprograms">subprogram descriptor</a>. This way the
989 location information attached to the intrinsics indicates that the
990 variable <tt>X</tt> is declared at line number 2 at a function level scope in
991 function <tt>foo</tt>.</p>
993 <p>Now lets take another example.</p>
995 <div class="doc_code">
997 call void @llvm.dbg.declare(metadata, metadata !12), !dbg !14
1001 <p>The second intrinsic
1002 <tt>%<a href="#format_common_declare">llvm.dbg.declare</a></tt>
1003 encodes debugging information for variable <tt>Z</tt>. The metadata
1004 <tt>!dbg !14</tt> attached to the intrinsic provides scope information for
1005 the variable <tt>Z</tt>.</p>
1007 <div class="doc_code">
1009 !13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ]
1010 !14 = metadata !{i32 5, i32 9, metadata !13, null}
1014 <p>Here <tt>!14</tt> indicates that <tt>Z</tt> is declared at line number 5 and
1015 column number 9 inside of lexical scope <tt>!13</tt>. The lexical scope
1016 itself resides inside of lexical scope <tt>!1</tt> described above.</p>
1018 <p>The scope information attached with each instruction provides a
1019 straightforward way to find instructions covered by a scope.</p>
1025 <!-- *********************************************************************** -->
1027 <a name="ccxx_frontend">C/C++ front-end specific debug information</a>
1029 <!-- *********************************************************************** -->
1033 <p>The C and C++ front-ends represent information about the program in a format
1034 that is effectively identical
1035 to <a href="http://www.eagercon.com/dwarf/dwarf3std.htm">DWARF 3.0</a> in
1036 terms of information content. This allows code generators to trivially
1037 support native debuggers by generating standard dwarf information, and
1038 contains enough information for non-dwarf targets to translate it as
1041 <p>This section describes the forms used to represent C and C++ programs. Other
1042 languages could pattern themselves after this (which itself is tuned to
1043 representing programs in the same way that DWARF 3 does), or they could
1044 choose to provide completely different forms if they don't fit into the DWARF
1045 model. As support for debugging information gets added to the various LLVM
1046 source-language front-ends, the information used should be documented
1049 <p>The following sections provide examples of various C/C++ constructs and the
1050 debug information that would best describe those constructs.</p>
1052 <!-- ======================================================================= -->
1054 <a name="ccxx_compile_units">C/C++ source file information</a>
1059 <p>Given the source files <tt>MySource.cpp</tt> and <tt>MyHeader.h</tt> located
1060 in the directory <tt>/Users/mine/sources</tt>, the following code:</p>
1062 <div class="doc_code">
1064 #include "MyHeader.h"
1066 int main(int argc, char *argv[]) {
1072 <p>a C/C++ front-end would generate the following descriptors:</p>
1074 <div class="doc_code">
1078 ;; Define the compile unit for the main source file "/Users/mine/sources/MySource.cpp".
1083 i32 4, ;; Language Id
1084 metadata !"MySource.cpp",
1085 metadata !"/Users/mine/sources",
1086 metadata !"4.2.1 (Based on Apple Inc. build 5649) (LLVM build 00)",
1087 i1 true, ;; Main Compile Unit
1088 i1 false, ;; Optimized compile unit
1089 metadata !"", ;; Compiler flags
1090 i32 0} ;; Runtime version
1093 ;; Define the file for the file "/Users/mine/sources/MySource.cpp".
1097 metadata !"MySource.cpp",
1098 metadata !"/Users/mine/sources",
1099 metadata !2 ;; Compile unit
1103 ;; Define the file for the file "/Users/mine/sources/Myheader.h"
1107 metadata !"Myheader.h"
1108 metadata !"/Users/mine/sources",
1109 metadata !2 ;; Compile unit
1116 <p>llvm::Instruction provides easy access to metadata attached with an
1117 instruction. One can extract line number information encoded in LLVM IR
1118 using <tt>Instruction::getMetadata()</tt> and
1119 <tt>DILocation::getLineNumber()</tt>.
1121 if (MDNode *N = I->getMetadata("dbg")) { // Here I is an LLVM instruction
1122 DILocation Loc(N); // DILocation is in DebugInfo.h
1123 unsigned Line = Loc.getLineNumber();
1124 StringRef File = Loc.getFilename();
1125 StringRef Dir = Loc.getDirectory();
1130 <!-- ======================================================================= -->
1132 <a name="ccxx_global_variable">C/C++ global variable information</a>
1137 <p>Given an integer global variable declared as follows:</p>
1139 <div class="doc_code">
1145 <p>a C/C++ front-end would generate the following descriptors:</p>
1147 <div class="doc_code">
1150 ;; Define the global itself.
1152 %MyGlobal = global int 100
1155 ;; List of debug info of globals
1157 !llvm.dbg.gv = !{!0}
1160 ;; Define the global variable descriptor. Note the reference to the global
1161 ;; variable anchor and the global variable itself.
1166 metadata !1, ;; Context
1167 metadata !"MyGlobal", ;; Name
1168 metadata !"MyGlobal", ;; Display Name
1169 metadata !"MyGlobal", ;; Linkage Name
1170 metadata !3, ;; Compile Unit
1171 i32 1, ;; Line Number
1172 metadata !4, ;; Type
1173 i1 false, ;; Is a local variable
1174 i1 true, ;; Is this a definition
1175 i32* @MyGlobal ;; The global variable
1179 ;; Define the basic type of 32 bit signed integer. Note that since int is an
1180 ;; intrinsic type the source file is NULL and line 0.
1184 metadata !1, ;; Context
1185 metadata !"int", ;; Name
1186 metadata !1, ;; File
1187 i32 0, ;; Line number
1188 i64 32, ;; Size in Bits
1189 i64 32, ;; Align in Bits
1190 i64 0, ;; Offset in Bits
1200 <!-- ======================================================================= -->
1202 <a name="ccxx_subprogram">C/C++ function information</a>
1207 <p>Given a function declared as follows:</p>
1209 <div class="doc_code">
1211 int main(int argc, char *argv[]) {
1217 <p>a C/C++ front-end would generate the following descriptors:</p>
1219 <div class="doc_code">
1222 ;; Define the anchor for subprograms. Note that the second field of the
1223 ;; anchor is 46, which is the same as the tag for subprograms
1224 ;; (46 = DW_TAG_subprogram.)
1229 metadata !1, ;; Context
1230 metadata !"main", ;; Name
1231 metadata !"main", ;; Display name
1232 metadata !"main", ;; Linkage name
1233 metadata !1, ;; File
1234 i32 1, ;; Line number
1235 metadata !4, ;; Type
1236 i1 false, ;; Is local
1237 i1 true, ;; Is definition
1238 i32 0, ;; Virtuality attribute, e.g. pure virtual function
1239 i32 0, ;; Index into virtual table for C++ methods
1240 i32 0, ;; Type that holds virtual table.
1242 i1 false, ;; True if this function is optimized
1243 Function *, ;; Pointer to llvm::Function
1244 null ;; Function template parameters
1247 ;; Define the subprogram itself.
1249 define i32 @main(i32 %argc, i8** %argv) {
1257 <!-- ======================================================================= -->
1259 <a name="ccxx_basic_types">C/C++ basic types</a>
1264 <p>The following are the basic type descriptors for C/C++ core types:</p>
1266 <!-- ======================================================================= -->
1268 <a name="ccxx_basic_type_bool">bool</a>
1273 <div class="doc_code">
1277 metadata !1, ;; Context
1278 metadata !"bool", ;; Name
1279 metadata !1, ;; File
1280 i32 0, ;; Line number
1281 i64 8, ;; Size in Bits
1282 i64 8, ;; Align in Bits
1283 i64 0, ;; Offset in Bits
1292 <!-- ======================================================================= -->
1294 <a name="ccxx_basic_char">char</a>
1299 <div class="doc_code">
1303 metadata !1, ;; Context
1304 metadata !"char", ;; Name
1305 metadata !1, ;; File
1306 i32 0, ;; Line number
1307 i64 8, ;; Size in Bits
1308 i64 8, ;; Align in Bits
1309 i64 0, ;; Offset in Bits
1318 <!-- ======================================================================= -->
1320 <a name="ccxx_basic_unsigned_char">unsigned char</a>
1325 <div class="doc_code">
1329 metadata !1, ;; Context
1330 metadata !"unsigned char",
1331 metadata !1, ;; File
1332 i32 0, ;; Line number
1333 i64 8, ;; Size in Bits
1334 i64 8, ;; Align in Bits
1335 i64 0, ;; Offset in Bits
1344 <!-- ======================================================================= -->
1346 <a name="ccxx_basic_short">short</a>
1351 <div class="doc_code">
1355 metadata !1, ;; Context
1356 metadata !"short int",
1357 metadata !1, ;; File
1358 i32 0, ;; Line number
1359 i64 16, ;; Size in Bits
1360 i64 16, ;; Align in Bits
1361 i64 0, ;; Offset in Bits
1370 <!-- ======================================================================= -->
1372 <a name="ccxx_basic_unsigned_short">unsigned short</a>
1377 <div class="doc_code">
1381 metadata !1, ;; Context
1382 metadata !"short unsigned int",
1383 metadata !1, ;; File
1384 i32 0, ;; Line number
1385 i64 16, ;; Size in Bits
1386 i64 16, ;; Align in Bits
1387 i64 0, ;; Offset in Bits
1396 <!-- ======================================================================= -->
1398 <a name="ccxx_basic_int">int</a>
1403 <div class="doc_code">
1407 metadata !1, ;; Context
1408 metadata !"int", ;; Name
1409 metadata !1, ;; File
1410 i32 0, ;; Line number
1411 i64 32, ;; Size in Bits
1412 i64 32, ;; Align in Bits
1413 i64 0, ;; Offset in Bits
1421 <!-- ======================================================================= -->
1423 <a name="ccxx_basic_unsigned_int">unsigned int</a>
1428 <div class="doc_code">
1432 metadata !1, ;; Context
1433 metadata !"unsigned int",
1434 metadata !1, ;; File
1435 i32 0, ;; Line number
1436 i64 32, ;; Size in Bits
1437 i64 32, ;; Align in Bits
1438 i64 0, ;; Offset in Bits
1447 <!-- ======================================================================= -->
1449 <a name="ccxx_basic_long_long">long long</a>
1454 <div class="doc_code">
1458 metadata !1, ;; Context
1459 metadata !"long long int",
1460 metadata !1, ;; File
1461 i32 0, ;; Line number
1462 i64 64, ;; Size in Bits
1463 i64 64, ;; Align in Bits
1464 i64 0, ;; Offset in Bits
1473 <!-- ======================================================================= -->
1475 <a name="ccxx_basic_unsigned_long_long">unsigned long long</a>
1480 <div class="doc_code">
1484 metadata !1, ;; Context
1485 metadata !"long long unsigned int",
1486 metadata !1, ;; File
1487 i32 0, ;; Line number
1488 i64 64, ;; Size in Bits
1489 i64 64, ;; Align in Bits
1490 i64 0, ;; Offset in Bits
1499 <!-- ======================================================================= -->
1501 <a name="ccxx_basic_float">float</a>
1506 <div class="doc_code">
1510 metadata !1, ;; Context
1512 metadata !1, ;; File
1513 i32 0, ;; Line number
1514 i64 32, ;; Size in Bits
1515 i64 32, ;; Align in Bits
1516 i64 0, ;; Offset in Bits
1525 <!-- ======================================================================= -->
1527 <a name="ccxx_basic_double">double</a>
1532 <div class="doc_code">
1536 metadata !1, ;; Context
1537 metadata !"double",;; Name
1538 metadata !1, ;; File
1539 i32 0, ;; Line number
1540 i64 64, ;; Size in Bits
1541 i64 64, ;; Align in Bits
1542 i64 0, ;; Offset in Bits
1553 <!-- ======================================================================= -->
1555 <a name="ccxx_derived_types">C/C++ derived types</a>
1560 <p>Given the following as an example of C/C++ derived type:</p>
1562 <div class="doc_code">
1564 typedef const int *IntPtr;
1568 <p>a C/C++ front-end would generate the following descriptors:</p>
1570 <div class="doc_code">
1573 ;; Define the typedef "IntPtr".
1577 metadata !1, ;; Context
1578 metadata !"IntPtr", ;; Name
1579 metadata !3, ;; File
1580 i32 0, ;; Line number
1581 i64 0, ;; Size in bits
1582 i64 0, ;; Align in bits
1583 i64 0, ;; Offset in bits
1585 metadata !4 ;; Derived From type
1589 ;; Define the pointer type.
1593 metadata !1, ;; Context
1594 metadata !"", ;; Name
1595 metadata !1, ;; File
1596 i32 0, ;; Line number
1597 i64 64, ;; Size in bits
1598 i64 64, ;; Align in bits
1599 i64 0, ;; Offset in bits
1601 metadata !5 ;; Derived From type
1604 ;; Define the const type.
1608 metadata !1, ;; Context
1609 metadata !"", ;; Name
1610 metadata !1, ;; File
1611 i32 0, ;; Line number
1612 i64 32, ;; Size in bits
1613 i64 32, ;; Align in bits
1614 i64 0, ;; Offset in bits
1616 metadata !6 ;; Derived From type
1619 ;; Define the int type.
1623 metadata !1, ;; Context
1624 metadata !"int", ;; Name
1625 metadata !1, ;; File
1626 i32 0, ;; Line number
1627 i64 32, ;; Size in bits
1628 i64 32, ;; Align in bits
1629 i64 0, ;; Offset in bits
1638 <!-- ======================================================================= -->
1640 <a name="ccxx_composite_types">C/C++ struct/union types</a>
1645 <p>Given the following as an example of C/C++ struct type:</p>
1647 <div class="doc_code">
1657 <p>a C/C++ front-end would generate the following descriptors:</p>
1659 <div class="doc_code">
1662 ;; Define basic type for unsigned int.
1666 metadata !1, ;; Context
1667 metadata !"unsigned int",
1668 metadata !1, ;; File
1669 i32 0, ;; Line number
1670 i64 32, ;; Size in Bits
1671 i64 32, ;; Align in Bits
1672 i64 0, ;; Offset in Bits
1677 ;; Define composite type for struct Color.
1681 metadata !1, ;; Context
1682 metadata !"Color", ;; Name
1683 metadata !1, ;; Compile unit
1684 i32 1, ;; Line number
1685 i64 96, ;; Size in bits
1686 i64 32, ;; Align in bits
1687 i64 0, ;; Offset in bits
1689 null, ;; Derived From
1690 metadata !3, ;; Elements
1691 i32 0 ;; Runtime Language
1695 ;; Define the Red field.
1699 metadata !1, ;; Context
1700 metadata !"Red", ;; Name
1701 metadata !1, ;; File
1702 i32 2, ;; Line number
1703 i64 32, ;; Size in bits
1704 i64 32, ;; Align in bits
1705 i64 0, ;; Offset in bits
1707 metadata !5 ;; Derived From type
1711 ;; Define the Green field.
1715 metadata !1, ;; Context
1716 metadata !"Green", ;; Name
1717 metadata !1, ;; File
1718 i32 3, ;; Line number
1719 i64 32, ;; Size in bits
1720 i64 32, ;; Align in bits
1721 i64 32, ;; Offset in bits
1723 metadata !5 ;; Derived From type
1727 ;; Define the Blue field.
1731 metadata !1, ;; Context
1732 metadata !"Blue", ;; Name
1733 metadata !1, ;; File
1734 i32 4, ;; Line number
1735 i64 32, ;; Size in bits
1736 i64 32, ;; Align in bits
1737 i64 64, ;; Offset in bits
1739 metadata !5 ;; Derived From type
1743 ;; Define the array of fields used by the composite type Color.
1745 !3 = metadata !{metadata !4, metadata !6, metadata !7}
1751 <!-- ======================================================================= -->
1753 <a name="ccxx_enumeration_types">C/C++ enumeration types</a>
1758 <p>Given the following as an example of C/C++ enumeration type:</p>
1760 <div class="doc_code">
1770 <p>a C/C++ front-end would generate the following descriptors:</p>
1772 <div class="doc_code">
1775 ;; Define composite type for enum Trees
1779 metadata !1, ;; Context
1780 metadata !"Trees", ;; Name
1781 metadata !1, ;; File
1782 i32 1, ;; Line number
1783 i64 32, ;; Size in bits
1784 i64 32, ;; Align in bits
1785 i64 0, ;; Offset in bits
1787 null, ;; Derived From type
1788 metadata !3, ;; Elements
1789 i32 0 ;; Runtime language
1793 ;; Define the array of enumerators used by composite type Trees.
1795 !3 = metadata !{metadata !4, metadata !5, metadata !6}
1798 ;; Define Spruce enumerator.
1800 !4 = metadata !{i32 524328, metadata !"Spruce", i64 100}
1803 ;; Define Oak enumerator.
1805 !5 = metadata !{i32 524328, metadata !"Oak", i64 200}
1808 ;; Define Maple enumerator.
1810 !6 = metadata !{i32 524328, metadata !"Maple", i64 300}
1820 <!-- *********************************************************************** -->
1822 <a name="llvmdwarfextension">Debugging information format</a>
1824 <!-- *********************************************************************** -->
1826 <!-- ======================================================================= -->
1828 <a name="objcproperty">Debugging Information Extension for Objective C
1832 <!-- *********************************************************************** -->
1834 <a name="objcpropertyintroduction">Introduction</a>
1836 <!-- *********************************************************************** -->
1839 <p>Objective C provides a simpler way to declare and define accessor methods
1840 using declared properties. The language provides features to declare a
1841 property and to let compiler synthesize accessor methods.
1844 <p>The debugger lets developer inspect Objective C interfaces and their
1845 instance variables and class variables. However, the debugger does not know
1846 anything about the properties defined in Objective C interfaces. The debugger
1847 consumes information generated by compiler in DWARF format. The format does
1848 not support encoding of Objective C properties. This proposal describes DWARF
1849 extensions to encode Objective C properties, which the debugger can use to let
1850 developers inspect Objective C properties.
1856 <!-- *********************************************************************** -->
1858 <a name="objcpropertyproposal">Proposal</a>
1860 <!-- *********************************************************************** -->
1863 <p>Objective C properties are always backed by an instance variable. The
1864 instance variables backing properties are identified using
1865 DW_AT_APPLE_property_name attribute. The instance variables with this
1866 attribute may not have data location attributes. The location of instance
1867 variables is determined by debugger only after consulting Objective C runtime.
1870 <div class="doc_code">
1882 @synthesize p2 = n2;
1886 TAG_structure_type [7] *
1887 AT_APPLE_runtime_class( 0x10 )
1889 AT_decl_file( "Objc_Property.m" )
1894 AT_APPLE_property_name(“p1”)
1895 AT_type( {0x00000147} ( int ) )
1899 AT_APPLE_property_name(“p2”)
1900 AT_type( {0x00000147} ( int ) )
1904 <p> Developers can decorate a property with attributes which are encoded using
1905 DW_AT_APPLE_property_attribute.
1908 <div class="doc_code">
1910 @property (readonly, nonatomic) int pr;
1915 AT_APPLE_property_name(“pr”)
1916 AT_type ( {0x00000147} (int) )
1917 AT_APPLE_property_attribute (DW_APPLE_PROPERTY_readonly, DW_APPLE_PROPERTY_nonatomic)
1921 <p> The setter and getter method names are attached to the property using
1922 DW_AT_APPLE_property_setter and DW_AT_APPLE_property_getter attributes.
1924 <div class="doc_code">
1927 @property (setter=myOwnP3Setter:) int p3;
1928 -(void)myOwnP3Setter:(int)a;
1933 -(void)myOwnP3Setter:(int)a{ }
1936 0x000003bd: TAG_structure_type [7] *
1937 AT_APPLE_runtime_class( 0x10 )
1939 AT_decl_file( "Objc_Property.m" )
1941 0x000003f3: TAG_member [8]
1943 AT_APPLE_property_name(“p3”)
1944 AT_APPLE_property_setter(“myOwnP3Setter:”)
1945 AT_type( {0x00000147} ( int ) )
1951 <!-- *********************************************************************** -->
1953 <a name="objcpropertynewattributes">New DWARF Attributes</a>
1955 <!-- *********************************************************************** -->
1958 <table border="1" cellspacing="0">
1960 <th width=200 >Attribute</th>
1961 <th width=200 >Value</th>
1962 <th width=200 >Classes</th>
1965 <td width=200 >DW_AT_APPLE_property_name</td>
1966 <td width=200 >0x3fe8</td>
1967 <td width=200 >String</td>
1970 <td width=200 >DW_AT_APPLE_property_getter</td>
1971 <td width=200 >0x3fe9</td>
1972 <td width=200 >String</td>
1975 <td width=200 >DW_AT_APPLE_property_setter</td>
1976 <td width=200 >0x3fea</td>
1977 <td width=200 >String</td>
1980 <td width=200 >DW_AT_APPLE_property_attribute</td>
1981 <td width=200 >0x3feb</td>
1982 <td width=200 >Constant</td>
1988 <!-- *********************************************************************** -->
1990 <a name="objcpropertynewconstants">New DWARF Constants</a>
1992 <!-- *********************************************************************** -->
1995 <table border="1" cellspacing="0">
1997 <th width=200 >Name</th>
1998 <th width=200 >Value</th>
2001 <td width=200 >DW_AT_APPLE_PROPERTY_readonly</td>
2002 <td width=200 >0x1</td>
2005 <td width=200 >DW_AT_APPLE_PROPERTY_readwrite</td>
2006 <td width=200 >0x2</td>
2009 <td width=200 >DW_AT_APPLE_PROPERTY_assign</td>
2010 <td width=200 >0x4</td>
2013 <td width=200 >DW_AT_APPLE_PROPERTY_retain</td>
2014 <td width=200 >0x8</td>
2017 <td width=200 >DW_AT_APPLE_PROPERTY_copy</td>
2018 <td width=200 >0x10</td>
2021 <td width=200 >DW_AT_APPLE_PROPERTY_nonatomic</td>
2022 <td width=200 >0x20</td>
2030 <!-- *********************************************************************** -->
2034 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
2035 src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
2036 <a href="http://validator.w3.org/check/referer"><img
2037 src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
2039 <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
2040 <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
2041 Last modified: $Date$