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
449 i32, ;; Flags - Artifical, Private, Protected, Explicit, Prototyped.
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.
466 <!-- ======================================================================= -->
468 <a name="format_blocks">Block descriptors</a>
473 <div class="doc_code">
476 i32, ;; Tag = 11 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_lexical_block)
477 metadata,;; Reference to context descriptor
479 i32, ;; Column number
480 metadata,;; Reference to source file
481 i32 ;; Unique ID to identify blocks from a template function
486 <p>This descriptor provides debug information about nested blocks within a
487 subprogram. The line number and column numbers are used to dinstinguish
488 two lexical blocks at same depth. </p>
490 <div class="doc_code">
493 i32, ;; Tag = 11 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_lexical_block)
494 metadata ;; Reference to the scope we're annotating with a file change
495 metadata,;; Reference to the file the scope is enclosed in.
500 <p>This descriptor provides a wrapper around a lexical scope to handle file
501 changes in the middle of a lexical block.</p>
505 <!-- ======================================================================= -->
507 <a name="format_basic_type">Basic type descriptors</a>
512 <div class="doc_code">
515 i32, ;; Tag = 36 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
516 ;; (DW_TAG_base_type)
517 metadata, ;; Reference to context
518 metadata, ;; Name (may be "" for anonymous types)
519 metadata, ;; Reference to file where defined (may be NULL)
520 i32, ;; Line number where defined (may be 0)
522 i64, ;; Alignment in bits
523 i64, ;; Offset in bits
525 i32 ;; DWARF type encoding
530 <p>These descriptors define primitive types used in the code. Example int, bool
531 and float. The context provides the scope of the type, which is usually the
532 top level. Since basic types are not usually user defined the context
533 and line number can be left as NULL and 0. The size, alignment and offset
534 are expressed in bits and can be 64 bit values. The alignment is used to
535 round the offset when embedded in a
536 <a href="#format_composite_type">composite type</a> (example to keep float
537 doubles on 64 bit boundaries.) The offset is the bit offset if embedded in
538 a <a href="#format_composite_type">composite type</a>.</p>
540 <p>The type encoding provides the details of the type. The values are typically
541 one of the following:</p>
543 <div class="doc_code">
549 DW_ATE_signed_char = 6
551 DW_ATE_unsigned_char = 8
557 <!-- ======================================================================= -->
559 <a name="format_derived_type">Derived type descriptors</a>
564 <div class="doc_code">
567 i32, ;; Tag (see below)
568 metadata, ;; Reference to context
569 metadata, ;; Name (may be "" for anonymous types)
570 metadata, ;; Reference to file where defined (may be NULL)
571 i32, ;; Line number where defined (may be 0)
573 i64, ;; Alignment in bits
574 i64, ;; Offset in bits
575 i32, ;; Flags to encode attributes, e.g. private
576 metadata, ;; Reference to type derived from
577 metadata, ;; (optional) Name of the Objective C property associated with
578 ;; Objective-C an ivar
579 metadata, ;; (optional) Name of the Objective C property getter selector.
580 metadata, ;; (optional) Name of the Objective C property setter selector.
581 i32 ;; (optional) Objective C property attributes.
586 <p>These descriptors are used to define types derived from other types. The
587 value of the tag varies depending on the meaning. The following are possible
590 <div class="doc_code">
592 DW_TAG_formal_parameter = 5
594 DW_TAG_pointer_type = 15
595 DW_TAG_reference_type = 16
597 DW_TAG_const_type = 38
598 DW_TAG_volatile_type = 53
599 DW_TAG_restrict_type = 55
603 <p><tt>DW_TAG_member</tt> is used to define a member of
604 a <a href="#format_composite_type">composite type</a>
605 or <a href="#format_subprograms">subprogram</a>. The type of the member is
606 the <a href="#format_derived_type">derived
607 type</a>. <tt>DW_TAG_formal_parameter</tt> is used to define a member which
608 is a formal argument of a subprogram.</p>
610 <p><tt>DW_TAG_typedef</tt> is used to provide a name for the derived type.</p>
612 <p><tt>DW_TAG_pointer_type</tt>, <tt>DW_TAG_reference_type</tt>,
613 <tt>DW_TAG_const_type</tt>, <tt>DW_TAG_volatile_type</tt> and
614 <tt>DW_TAG_restrict_type</tt> are used to qualify
615 the <a href="#format_derived_type">derived type</a>. </p>
617 <p><a href="#format_derived_type">Derived type</a> location can be determined
618 from the context and line number. The size, alignment and offset are
619 expressed in bits and can be 64 bit values. The alignment is used to round
620 the offset when embedded in a <a href="#format_composite_type">composite
621 type</a> (example to keep float doubles on 64 bit boundaries.) The offset is
622 the bit offset if embedded in a <a href="#format_composite_type">composite
625 <p>Note that the <tt>void *</tt> type is expressed as a type derived from NULL.
630 <!-- ======================================================================= -->
632 <a name="format_composite_type">Composite type descriptors</a>
637 <div class="doc_code">
640 i32, ;; Tag (see below)
641 metadata, ;; Reference to context
642 metadata, ;; Name (may be "" for anonymous types)
643 metadata, ;; Reference to file where defined (may be NULL)
644 i32, ;; Line number where defined (may be 0)
646 i64, ;; Alignment in bits
647 i64, ;; Offset in bits
649 metadata, ;; Reference to type derived from
650 metadata, ;; Reference to array of member descriptors
651 i32 ;; Runtime languages
656 <p>These descriptors are used to define types that are composed of 0 or more
657 elements. The value of the tag varies depending on the meaning. The following
658 are possible tag values:</p>
660 <div class="doc_code">
662 DW_TAG_array_type = 1
663 DW_TAG_enumeration_type = 4
664 DW_TAG_structure_type = 19
665 DW_TAG_union_type = 23
666 DW_TAG_vector_type = 259
667 DW_TAG_subroutine_type = 21
668 DW_TAG_inheritance = 28
672 <p>The vector flag indicates that an array type is a native packed vector.</p>
674 <p>The members of array types (tag = <tt>DW_TAG_array_type</tt>) or vector types
675 (tag = <tt>DW_TAG_vector_type</tt>) are <a href="#format_subrange">subrange
676 descriptors</a>, each representing the range of subscripts at that level of
679 <p>The members of enumeration types (tag = <tt>DW_TAG_enumeration_type</tt>) are
680 <a href="#format_enumeration">enumerator descriptors</a>, each representing
681 the definition of enumeration value for the set. All enumeration type
682 descriptors are collected by named metadata <tt>!llvm.dbg.enum</tt>.</p>
684 <p>The members of structure (tag = <tt>DW_TAG_structure_type</tt>) or union (tag
685 = <tt>DW_TAG_union_type</tt>) types are any one of
686 the <a href="#format_basic_type">basic</a>,
687 <a href="#format_derived_type">derived</a>
688 or <a href="#format_composite_type">composite</a> type descriptors, each
689 representing a field member of the structure or union.</p>
691 <p>For C++ classes (tag = <tt>DW_TAG_structure_type</tt>), member descriptors
692 provide information about base classes, static members and member
693 functions. If a member is a <a href="#format_derived_type">derived type
694 descriptor</a> and has a tag of <tt>DW_TAG_inheritance</tt>, then the type
695 represents a base class. If the member of is
696 a <a href="#format_global_variables">global variable descriptor</a> then it
697 represents a static member. And, if the member is
698 a <a href="#format_subprograms">subprogram descriptor</a> then it represents
699 a member function. For static members and member
700 functions, <tt>getName()</tt> returns the members link or the C++ mangled
701 name. <tt>getDisplayName()</tt> the simplied version of the name.</p>
703 <p>The first member of subroutine (tag = <tt>DW_TAG_subroutine_type</tt>) type
704 elements is the return type for the subroutine. The remaining elements are
705 the formal arguments to the subroutine.</p>
707 <p><a href="#format_composite_type">Composite type</a> location can be
708 determined from the context and line number. The size, alignment and
709 offset are expressed in bits and can be 64 bit values. The alignment is used
710 to round the offset when embedded in
711 a <a href="#format_composite_type">composite type</a> (as an example, to keep
712 float doubles on 64 bit boundaries.) The offset is the bit offset if embedded
713 in a <a href="#format_composite_type">composite type</a>.</p>
717 <!-- ======================================================================= -->
719 <a name="format_subrange">Subrange descriptors</a>
724 <div class="doc_code">
727 i32, ;; Tag = 33 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_subrange_type)
734 <p>These descriptors are used to define ranges of array subscripts for an array
735 <a href="#format_composite_type">composite type</a>. The low value defines
736 the lower bounds typically zero for C/C++. The high value is the upper
737 bounds. Values are 64 bit. High - low + 1 is the size of the array. If low
738 > high the array bounds are not included in generated debugging information.
743 <!-- ======================================================================= -->
745 <a name="format_enumeration">Enumerator descriptors</a>
750 <div class="doc_code">
753 i32, ;; Tag = 40 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
754 ;; (DW_TAG_enumerator)
761 <p>These descriptors are used to define members of an
762 enumeration <a href="#format_composite_type">composite type</a>, it
763 associates the name to the value.</p>
767 <!-- ======================================================================= -->
769 <a name="format_variables">Local variables</a>
774 <div class="doc_code">
777 i32, ;; Tag (see below)
780 metadata, ;; Reference to file where defined
781 i32, ;; 24 bit - Line number where defined
782 ;; 8 bit - Argument number. 1 indicates 1st argument.
783 metadata, ;; Type descriptor
785 metadata ;; (optional) Reference to inline location
790 <p>These descriptors are used to define variables local to a sub program. The
791 value of the tag depends on the usage of the variable:</p>
793 <div class="doc_code">
795 DW_TAG_auto_variable = 256
796 DW_TAG_arg_variable = 257
797 DW_TAG_return_variable = 258
801 <p>An auto variable is any variable declared in the body of the function. An
802 argument variable is any variable that appears as a formal argument to the
803 function. A return variable is used to track the result of a function and
804 has no source correspondent.</p>
806 <p>The context is either the subprogram or block where the variable is defined.
807 Name the source variable name. Context and line indicate where the
808 variable was defined. Type descriptor defines the declared type of the
815 <!-- ======================================================================= -->
817 <a name="format_common_intrinsics">Debugger intrinsic functions</a>
822 <p>LLVM uses several intrinsic functions (name prefixed with "llvm.dbg") to
823 provide debug information at various points in generated code.</p>
825 <!-- ======================================================================= -->
827 <a name="format_common_declare">llvm.dbg.declare</a>
832 void %<a href="#format_common_declare">llvm.dbg.declare</a>(metadata, metadata)
835 <p>This intrinsic provides information about a local element (e.g., variable). The
836 first argument is metadata holding the alloca for the variable. The
837 second argument is metadata containing a description of the variable.</p>
840 <!-- ======================================================================= -->
842 <a name="format_common_value">llvm.dbg.value</a>
847 void %<a href="#format_common_value">llvm.dbg.value</a>(metadata, i64, metadata)
850 <p>This intrinsic provides information when a user source variable is set to a
851 new value. The first argument is the new value (wrapped as metadata). The
852 second argument is the offset in the user source variable where the new value
853 is written. The third argument is metadata containing a description of the
854 user source variable.</p>
859 <!-- ======================================================================= -->
861 <a name="format_common_lifetime">Object lifetimes and scoping</a>
865 <p>In many languages, the local variables in functions can have their lifetimes
866 or scopes limited to a subset of a function. In the C family of languages,
867 for example, variables are only live (readable and writable) within the
868 source block that they are defined in. In functional languages, values are
869 only readable after they have been defined. Though this is a very obvious
870 concept, it is non-trivial to model in LLVM, because it has no notion of
871 scoping in this sense, and does not want to be tied to a language's scoping
874 <p>In order to handle this, the LLVM debug format uses the metadata attached to
875 llvm instructions to encode line number and scoping information. Consider
876 the following C fragment, for example:</p>
878 <div class="doc_code">
892 <p>Compiled to LLVM, this function would be represented like this:</p>
894 <div class="doc_code">
896 define void @foo() nounwind ssp {
898 %X = alloca i32, align 4 ; <i32*> [#uses=4]
899 %Y = alloca i32, align 4 ; <i32*> [#uses=4]
900 %Z = alloca i32, align 4 ; <i32*> [#uses=3]
901 %0 = bitcast i32* %X to {}* ; <{}*> [#uses=1]
902 call void @llvm.dbg.declare(metadata !{i32 * %X}, metadata !0), !dbg !7
903 store i32 21, i32* %X, !dbg !8
904 %1 = bitcast i32* %Y to {}* ; <{}*> [#uses=1]
905 call void @llvm.dbg.declare(metadata !{i32 * %Y}, metadata !9), !dbg !10
906 store i32 22, i32* %Y, !dbg !11
907 %2 = bitcast i32* %Z to {}* ; <{}*> [#uses=1]
908 call void @llvm.dbg.declare(metadata !{i32 * %Z}, metadata !12), !dbg !14
909 store i32 23, i32* %Z, !dbg !15
910 %tmp = load i32* %X, !dbg !16 ; <i32> [#uses=1]
911 %tmp1 = load i32* %Y, !dbg !16 ; <i32> [#uses=1]
912 %add = add nsw i32 %tmp, %tmp1, !dbg !16 ; <i32> [#uses=1]
913 store i32 %add, i32* %Z, !dbg !16
914 %tmp2 = load i32* %Y, !dbg !17 ; <i32> [#uses=1]
915 store i32 %tmp2, i32* %X, !dbg !17
919 declare void @llvm.dbg.declare(metadata, metadata) nounwind readnone
921 !0 = metadata !{i32 459008, metadata !1, metadata !"X",
922 metadata !3, i32 2, metadata !6}; [ DW_TAG_auto_variable ]
923 !1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ]
924 !2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo", metadata !"foo",
925 metadata !"foo", metadata !3, i32 1, metadata !4,
926 i1 false, i1 true}; [DW_TAG_subprogram ]
927 !3 = metadata !{i32 458769, i32 0, i32 12, metadata !"foo.c",
928 metadata !"/private/tmp", metadata !"clang 1.1", i1 true,
929 i1 false, metadata !"", i32 0}; [DW_TAG_compile_unit ]
930 !4 = metadata !{i32 458773, metadata !3, metadata !"", null, i32 0, i64 0, i64 0,
931 i64 0, i32 0, null, metadata !5, i32 0}; [DW_TAG_subroutine_type ]
932 !5 = metadata !{null}
933 !6 = metadata !{i32 458788, metadata !3, metadata !"int", metadata !3, i32 0,
934 i64 32, i64 32, i64 0, i32 0, i32 5}; [DW_TAG_base_type ]
935 !7 = metadata !{i32 2, i32 7, metadata !1, null}
936 !8 = metadata !{i32 2, i32 3, metadata !1, null}
937 !9 = metadata !{i32 459008, metadata !1, metadata !"Y", metadata !3, i32 3,
938 metadata !6}; [ DW_TAG_auto_variable ]
939 !10 = metadata !{i32 3, i32 7, metadata !1, null}
940 !11 = metadata !{i32 3, i32 3, metadata !1, null}
941 !12 = metadata !{i32 459008, metadata !13, metadata !"Z", metadata !3, i32 5,
942 metadata !6}; [ DW_TAG_auto_variable ]
943 !13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ]
944 !14 = metadata !{i32 5, i32 9, metadata !13, null}
945 !15 = metadata !{i32 5, i32 5, metadata !13, null}
946 !16 = metadata !{i32 6, i32 5, metadata !13, null}
947 !17 = metadata !{i32 8, i32 3, metadata !1, null}
948 !18 = metadata !{i32 9, i32 1, metadata !2, null}
952 <p>This example illustrates a few important details about LLVM debugging
953 information. In particular, it shows how the <tt>llvm.dbg.declare</tt>
954 intrinsic and location information, which are attached to an instruction,
955 are applied together to allow a debugger to analyze the relationship between
956 statements, variable definitions, and the code used to implement the
959 <div class="doc_code">
961 call void @llvm.dbg.declare(metadata, metadata !0), !dbg !7
965 <p>The first intrinsic
966 <tt>%<a href="#format_common_declare">llvm.dbg.declare</a></tt>
967 encodes debugging information for the variable <tt>X</tt>. The metadata
968 <tt>!dbg !7</tt> attached to the intrinsic provides scope information for the
969 variable <tt>X</tt>.</p>
971 <div class="doc_code">
973 !7 = metadata !{i32 2, i32 7, metadata !1, null}
974 !1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ]
975 !2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo",
976 metadata !"foo", metadata !"foo", metadata !3, i32 1,
977 metadata !4, i1 false, i1 true}; [DW_TAG_subprogram ]
981 <p>Here <tt>!7</tt> is metadata providing location information. It has four
982 fields: line number, column number, scope, and original scope. The original
983 scope represents inline location if this instruction is inlined inside a
984 caller, and is null otherwise. In this example, scope is encoded by
985 <tt>!1</tt>. <tt>!1</tt> represents a lexical block inside the scope
986 <tt>!2</tt>, where <tt>!2</tt> is a
987 <a href="#format_subprograms">subprogram descriptor</a>. This way the
988 location information attached to the intrinsics indicates that the
989 variable <tt>X</tt> is declared at line number 2 at a function level scope in
990 function <tt>foo</tt>.</p>
992 <p>Now lets take another example.</p>
994 <div class="doc_code">
996 call void @llvm.dbg.declare(metadata, metadata !12), !dbg !14
1000 <p>The second intrinsic
1001 <tt>%<a href="#format_common_declare">llvm.dbg.declare</a></tt>
1002 encodes debugging information for variable <tt>Z</tt>. The metadata
1003 <tt>!dbg !14</tt> attached to the intrinsic provides scope information for
1004 the variable <tt>Z</tt>.</p>
1006 <div class="doc_code">
1008 !13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ]
1009 !14 = metadata !{i32 5, i32 9, metadata !13, null}
1013 <p>Here <tt>!14</tt> indicates that <tt>Z</tt> is declared at line number 5 and
1014 column number 9 inside of lexical scope <tt>!13</tt>. The lexical scope
1015 itself resides inside of lexical scope <tt>!1</tt> described above.</p>
1017 <p>The scope information attached with each instruction provides a
1018 straightforward way to find instructions covered by a scope.</p>
1024 <!-- *********************************************************************** -->
1026 <a name="ccxx_frontend">C/C++ front-end specific debug information</a>
1028 <!-- *********************************************************************** -->
1032 <p>The C and C++ front-ends represent information about the program in a format
1033 that is effectively identical
1034 to <a href="http://www.eagercon.com/dwarf/dwarf3std.htm">DWARF 3.0</a> in
1035 terms of information content. This allows code generators to trivially
1036 support native debuggers by generating standard dwarf information, and
1037 contains enough information for non-dwarf targets to translate it as
1040 <p>This section describes the forms used to represent C and C++ programs. Other
1041 languages could pattern themselves after this (which itself is tuned to
1042 representing programs in the same way that DWARF 3 does), or they could
1043 choose to provide completely different forms if they don't fit into the DWARF
1044 model. As support for debugging information gets added to the various LLVM
1045 source-language front-ends, the information used should be documented
1048 <p>The following sections provide examples of various C/C++ constructs and the
1049 debug information that would best describe those constructs.</p>
1051 <!-- ======================================================================= -->
1053 <a name="ccxx_compile_units">C/C++ source file information</a>
1058 <p>Given the source files <tt>MySource.cpp</tt> and <tt>MyHeader.h</tt> located
1059 in the directory <tt>/Users/mine/sources</tt>, the following code:</p>
1061 <div class="doc_code">
1063 #include "MyHeader.h"
1065 int main(int argc, char *argv[]) {
1071 <p>a C/C++ front-end would generate the following descriptors:</p>
1073 <div class="doc_code">
1077 ;; Define the compile unit for the main source file "/Users/mine/sources/MySource.cpp".
1082 i32 4, ;; Language Id
1083 metadata !"MySource.cpp",
1084 metadata !"/Users/mine/sources",
1085 metadata !"4.2.1 (Based on Apple Inc. build 5649) (LLVM build 00)",
1086 i1 true, ;; Main Compile Unit
1087 i1 false, ;; Optimized compile unit
1088 metadata !"", ;; Compiler flags
1089 i32 0} ;; Runtime version
1092 ;; Define the file for the file "/Users/mine/sources/MySource.cpp".
1096 metadata !"MySource.cpp",
1097 metadata !"/Users/mine/sources",
1098 metadata !2 ;; Compile unit
1102 ;; Define the file for the file "/Users/mine/sources/Myheader.h"
1106 metadata !"Myheader.h"
1107 metadata !"/Users/mine/sources",
1108 metadata !2 ;; Compile unit
1115 <p>llvm::Instruction provides easy access to metadata attached with an
1116 instruction. One can extract line number information encoded in LLVM IR
1117 using <tt>Instruction::getMetadata()</tt> and
1118 <tt>DILocation::getLineNumber()</tt>.
1120 if (MDNode *N = I->getMetadata("dbg")) { // Here I is an LLVM instruction
1121 DILocation Loc(N); // DILocation is in DebugInfo.h
1122 unsigned Line = Loc.getLineNumber();
1123 StringRef File = Loc.getFilename();
1124 StringRef Dir = Loc.getDirectory();
1129 <!-- ======================================================================= -->
1131 <a name="ccxx_global_variable">C/C++ global variable information</a>
1136 <p>Given an integer global variable declared as follows:</p>
1138 <div class="doc_code">
1144 <p>a C/C++ front-end would generate the following descriptors:</p>
1146 <div class="doc_code">
1149 ;; Define the global itself.
1151 %MyGlobal = global int 100
1154 ;; List of debug info of globals
1156 !llvm.dbg.gv = !{!0}
1159 ;; Define the global variable descriptor. Note the reference to the global
1160 ;; variable anchor and the global variable itself.
1165 metadata !1, ;; Context
1166 metadata !"MyGlobal", ;; Name
1167 metadata !"MyGlobal", ;; Display Name
1168 metadata !"MyGlobal", ;; Linkage Name
1169 metadata !3, ;; Compile Unit
1170 i32 1, ;; Line Number
1171 metadata !4, ;; Type
1172 i1 false, ;; Is a local variable
1173 i1 true, ;; Is this a definition
1174 i32* @MyGlobal ;; The global variable
1178 ;; Define the basic type of 32 bit signed integer. Note that since int is an
1179 ;; intrinsic type the source file is NULL and line 0.
1183 metadata !1, ;; Context
1184 metadata !"int", ;; Name
1185 metadata !1, ;; File
1186 i32 0, ;; Line number
1187 i64 32, ;; Size in Bits
1188 i64 32, ;; Align in Bits
1189 i64 0, ;; Offset in Bits
1199 <!-- ======================================================================= -->
1201 <a name="ccxx_subprogram">C/C++ function information</a>
1206 <p>Given a function declared as follows:</p>
1208 <div class="doc_code">
1210 int main(int argc, char *argv[]) {
1216 <p>a C/C++ front-end would generate the following descriptors:</p>
1218 <div class="doc_code">
1221 ;; Define the anchor for subprograms. Note that the second field of the
1222 ;; anchor is 46, which is the same as the tag for subprograms
1223 ;; (46 = DW_TAG_subprogram.)
1228 metadata !1, ;; Context
1229 metadata !"main", ;; Name
1230 metadata !"main", ;; Display name
1231 metadata !"main", ;; Linkage name
1232 metadata !1, ;; File
1233 i32 1, ;; Line number
1234 metadata !4, ;; Type
1235 i1 false, ;; Is local
1236 i1 true, ;; Is definition
1237 i32 0, ;; Virtuality attribute, e.g. pure virtual function
1238 i32 0, ;; Index into virtual table for C++ methods
1239 i32 0, ;; Type that holds virtual table.
1241 i1 false, ;; True if this function is optimized
1242 Function *, ;; Pointer to llvm::Function
1243 null ;; Function template parameters
1246 ;; Define the subprogram itself.
1248 define i32 @main(i32 %argc, i8** %argv) {
1256 <!-- ======================================================================= -->
1258 <a name="ccxx_basic_types">C/C++ basic types</a>
1263 <p>The following are the basic type descriptors for C/C++ core types:</p>
1265 <!-- ======================================================================= -->
1267 <a name="ccxx_basic_type_bool">bool</a>
1272 <div class="doc_code">
1276 metadata !1, ;; Context
1277 metadata !"bool", ;; Name
1278 metadata !1, ;; File
1279 i32 0, ;; Line number
1280 i64 8, ;; Size in Bits
1281 i64 8, ;; Align in Bits
1282 i64 0, ;; Offset in Bits
1291 <!-- ======================================================================= -->
1293 <a name="ccxx_basic_char">char</a>
1298 <div class="doc_code">
1302 metadata !1, ;; Context
1303 metadata !"char", ;; Name
1304 metadata !1, ;; File
1305 i32 0, ;; Line number
1306 i64 8, ;; Size in Bits
1307 i64 8, ;; Align in Bits
1308 i64 0, ;; Offset in Bits
1317 <!-- ======================================================================= -->
1319 <a name="ccxx_basic_unsigned_char">unsigned char</a>
1324 <div class="doc_code">
1328 metadata !1, ;; Context
1329 metadata !"unsigned char",
1330 metadata !1, ;; File
1331 i32 0, ;; Line number
1332 i64 8, ;; Size in Bits
1333 i64 8, ;; Align in Bits
1334 i64 0, ;; Offset in Bits
1343 <!-- ======================================================================= -->
1345 <a name="ccxx_basic_short">short</a>
1350 <div class="doc_code">
1354 metadata !1, ;; Context
1355 metadata !"short int",
1356 metadata !1, ;; File
1357 i32 0, ;; Line number
1358 i64 16, ;; Size in Bits
1359 i64 16, ;; Align in Bits
1360 i64 0, ;; Offset in Bits
1369 <!-- ======================================================================= -->
1371 <a name="ccxx_basic_unsigned_short">unsigned short</a>
1376 <div class="doc_code">
1380 metadata !1, ;; Context
1381 metadata !"short unsigned int",
1382 metadata !1, ;; File
1383 i32 0, ;; Line number
1384 i64 16, ;; Size in Bits
1385 i64 16, ;; Align in Bits
1386 i64 0, ;; Offset in Bits
1395 <!-- ======================================================================= -->
1397 <a name="ccxx_basic_int">int</a>
1402 <div class="doc_code">
1406 metadata !1, ;; Context
1407 metadata !"int", ;; Name
1408 metadata !1, ;; File
1409 i32 0, ;; Line number
1410 i64 32, ;; Size in Bits
1411 i64 32, ;; Align in Bits
1412 i64 0, ;; Offset in Bits
1420 <!-- ======================================================================= -->
1422 <a name="ccxx_basic_unsigned_int">unsigned int</a>
1427 <div class="doc_code">
1431 metadata !1, ;; Context
1432 metadata !"unsigned int",
1433 metadata !1, ;; File
1434 i32 0, ;; Line number
1435 i64 32, ;; Size in Bits
1436 i64 32, ;; Align in Bits
1437 i64 0, ;; Offset in Bits
1446 <!-- ======================================================================= -->
1448 <a name="ccxx_basic_long_long">long long</a>
1453 <div class="doc_code">
1457 metadata !1, ;; Context
1458 metadata !"long long int",
1459 metadata !1, ;; File
1460 i32 0, ;; Line number
1461 i64 64, ;; Size in Bits
1462 i64 64, ;; Align in Bits
1463 i64 0, ;; Offset in Bits
1472 <!-- ======================================================================= -->
1474 <a name="ccxx_basic_unsigned_long_long">unsigned long long</a>
1479 <div class="doc_code">
1483 metadata !1, ;; Context
1484 metadata !"long long unsigned int",
1485 metadata !1, ;; File
1486 i32 0, ;; Line number
1487 i64 64, ;; Size in Bits
1488 i64 64, ;; Align in Bits
1489 i64 0, ;; Offset in Bits
1498 <!-- ======================================================================= -->
1500 <a name="ccxx_basic_float">float</a>
1505 <div class="doc_code">
1509 metadata !1, ;; Context
1511 metadata !1, ;; File
1512 i32 0, ;; Line number
1513 i64 32, ;; Size in Bits
1514 i64 32, ;; Align in Bits
1515 i64 0, ;; Offset in Bits
1524 <!-- ======================================================================= -->
1526 <a name="ccxx_basic_double">double</a>
1531 <div class="doc_code">
1535 metadata !1, ;; Context
1536 metadata !"double",;; Name
1537 metadata !1, ;; File
1538 i32 0, ;; Line number
1539 i64 64, ;; Size in Bits
1540 i64 64, ;; Align in Bits
1541 i64 0, ;; Offset in Bits
1552 <!-- ======================================================================= -->
1554 <a name="ccxx_derived_types">C/C++ derived types</a>
1559 <p>Given the following as an example of C/C++ derived type:</p>
1561 <div class="doc_code">
1563 typedef const int *IntPtr;
1567 <p>a C/C++ front-end would generate the following descriptors:</p>
1569 <div class="doc_code">
1572 ;; Define the typedef "IntPtr".
1576 metadata !1, ;; Context
1577 metadata !"IntPtr", ;; Name
1578 metadata !3, ;; File
1579 i32 0, ;; Line number
1580 i64 0, ;; Size in bits
1581 i64 0, ;; Align in bits
1582 i64 0, ;; Offset in bits
1584 metadata !4 ;; Derived From type
1588 ;; Define the pointer type.
1592 metadata !1, ;; Context
1593 metadata !"", ;; Name
1594 metadata !1, ;; File
1595 i32 0, ;; Line number
1596 i64 64, ;; Size in bits
1597 i64 64, ;; Align in bits
1598 i64 0, ;; Offset in bits
1600 metadata !5 ;; Derived From type
1603 ;; Define the const type.
1607 metadata !1, ;; Context
1608 metadata !"", ;; Name
1609 metadata !1, ;; File
1610 i32 0, ;; Line number
1611 i64 32, ;; Size in bits
1612 i64 32, ;; Align in bits
1613 i64 0, ;; Offset in bits
1615 metadata !6 ;; Derived From type
1618 ;; Define the int type.
1622 metadata !1, ;; Context
1623 metadata !"int", ;; Name
1624 metadata !1, ;; File
1625 i32 0, ;; Line number
1626 i64 32, ;; Size in bits
1627 i64 32, ;; Align in bits
1628 i64 0, ;; Offset in bits
1637 <!-- ======================================================================= -->
1639 <a name="ccxx_composite_types">C/C++ struct/union types</a>
1644 <p>Given the following as an example of C/C++ struct type:</p>
1646 <div class="doc_code">
1656 <p>a C/C++ front-end would generate the following descriptors:</p>
1658 <div class="doc_code">
1661 ;; Define basic type for unsigned int.
1665 metadata !1, ;; Context
1666 metadata !"unsigned int",
1667 metadata !1, ;; File
1668 i32 0, ;; Line number
1669 i64 32, ;; Size in Bits
1670 i64 32, ;; Align in Bits
1671 i64 0, ;; Offset in Bits
1676 ;; Define composite type for struct Color.
1680 metadata !1, ;; Context
1681 metadata !"Color", ;; Name
1682 metadata !1, ;; Compile unit
1683 i32 1, ;; Line number
1684 i64 96, ;; Size in bits
1685 i64 32, ;; Align in bits
1686 i64 0, ;; Offset in bits
1688 null, ;; Derived From
1689 metadata !3, ;; Elements
1690 i32 0 ;; Runtime Language
1694 ;; Define the Red field.
1698 metadata !1, ;; Context
1699 metadata !"Red", ;; Name
1700 metadata !1, ;; File
1701 i32 2, ;; Line number
1702 i64 32, ;; Size in bits
1703 i64 32, ;; Align in bits
1704 i64 0, ;; Offset in bits
1706 metadata !5 ;; Derived From type
1710 ;; Define the Green field.
1714 metadata !1, ;; Context
1715 metadata !"Green", ;; Name
1716 metadata !1, ;; File
1717 i32 3, ;; Line number
1718 i64 32, ;; Size in bits
1719 i64 32, ;; Align in bits
1720 i64 32, ;; Offset in bits
1722 metadata !5 ;; Derived From type
1726 ;; Define the Blue field.
1730 metadata !1, ;; Context
1731 metadata !"Blue", ;; Name
1732 metadata !1, ;; File
1733 i32 4, ;; Line number
1734 i64 32, ;; Size in bits
1735 i64 32, ;; Align in bits
1736 i64 64, ;; Offset in bits
1738 metadata !5 ;; Derived From type
1742 ;; Define the array of fields used by the composite type Color.
1744 !3 = metadata !{metadata !4, metadata !6, metadata !7}
1750 <!-- ======================================================================= -->
1752 <a name="ccxx_enumeration_types">C/C++ enumeration types</a>
1757 <p>Given the following as an example of C/C++ enumeration type:</p>
1759 <div class="doc_code">
1769 <p>a C/C++ front-end would generate the following descriptors:</p>
1771 <div class="doc_code">
1774 ;; Define composite type for enum Trees
1778 metadata !1, ;; Context
1779 metadata !"Trees", ;; Name
1780 metadata !1, ;; File
1781 i32 1, ;; Line number
1782 i64 32, ;; Size in bits
1783 i64 32, ;; Align in bits
1784 i64 0, ;; Offset in bits
1786 null, ;; Derived From type
1787 metadata !3, ;; Elements
1788 i32 0 ;; Runtime language
1792 ;; Define the array of enumerators used by composite type Trees.
1794 !3 = metadata !{metadata !4, metadata !5, metadata !6}
1797 ;; Define Spruce enumerator.
1799 !4 = metadata !{i32 524328, metadata !"Spruce", i64 100}
1802 ;; Define Oak enumerator.
1804 !5 = metadata !{i32 524328, metadata !"Oak", i64 200}
1807 ;; Define Maple enumerator.
1809 !6 = metadata !{i32 524328, metadata !"Maple", i64 300}
1819 <!-- *********************************************************************** -->
1821 <a name="llvmdwarfextension">Debugging information format</a>
1823 <!-- *********************************************************************** -->
1825 <!-- ======================================================================= -->
1827 <a name="objcproperty">Debugging Information Extension for Objective C
1831 <!-- *********************************************************************** -->
1833 <a name="objcpropertyintroduction">Introduction</a>
1835 <!-- *********************************************************************** -->
1838 <p>Objective C provides a simpler way to declare and define accessor methods
1839 using declared properties. The language provides features to declare a
1840 property and to let compiler synthesize accessor methods.
1843 <p>The debugger lets developer inspect Objective C interfaces and their
1844 instance variables and class variables. However, the debugger does not know
1845 anything about the properties defined in Objective C interfaces. The debugger
1846 consumes information generated by compiler in DWARF format. The format does
1847 not support encoding of Objective C properties. This proposal describes DWARF
1848 extensions to encode Objective C properties, which the debugger can use to let
1849 developers inspect Objective C properties.
1855 <!-- *********************************************************************** -->
1857 <a name="objcpropertyproposal">Proposal</a>
1859 <!-- *********************************************************************** -->
1862 <p>Objective C properties exist separately from class members. A property
1863 can be defined only by "setter" and "getter" selectors, and
1864 be calculated anew on each access. Or a property can just be a direct access
1865 to some declared ivar. Finally it can have an ivar "automatically
1866 synthesized" for it by the compiler, in which case the property can be
1867 referred to in user code directly using the standard C dereference syntax as
1868 well as through the property "dot" syntax, but there is no entry in
1869 the @interface declaration corresponding to this ivar.
1872 To facilitate debugging, these properties we will add a new DWARF TAG into the
1873 DW_TAG_structure_type definition for the class to hold the description of a
1874 given property, and a set of DWARF attributes that provide said description.
1875 The property tag will also contain the name and declared type of the property.
1878 If there is a related ivar, there will also be a DWARF property attribute placed
1879 in the DW_TAG_member DIE for that ivar referring back to the property TAG for
1880 that property. And in the case where the compiler synthesizes the ivar directly,
1881 the compiler is expected to generate a DW_TAG_member for that ivar (with the
1882 DW_AT_artificial set to 1), whose name will be the name used to access this
1883 ivar directly in code, and with the property attribute pointing back to the
1884 property it is backing.
1887 The following examples will serve as illustration for our discussion:
1890 <div class="doc_code">
1902 @synthesize p2 = n2;
1908 This produces the following DWARF (this is a "pseudo dwarfdump" output):
1910 <div class="doc_code">
1912 0x00000100: TAG_structure_type [7] *
1913 AT_APPLE_runtime_class( 0x10 )
1915 AT_decl_file( "Objc_Property.m" )
1918 0x00000110 TAG_APPLE_property
1920 AT_type ( {0x00000150} ( int ) )
1922 0x00000120: TAG_APPLE_property
1924 AT_type ( {0x00000150} ( int ) )
1926 0x00000130: TAG_member [8]
1928 AT_APPLE_property ( {0x00000110} "p1" )
1929 AT_type( {0x00000150} ( int ) )
1930 AT_artificial ( 0x1 )
1932 0x00000140: TAG_member [8]
1934 AT_APPLE_property ( {0x00000120} "p2" )
1935 AT_type( {0x00000150} ( int ) )
1937 0x00000150: AT_type( ( int ) )
1941 <p> Note, the current convention is that the name of the ivar for an
1942 auto-synthesized property is the name of the property from which it derives with
1943 an underscore prepended, as is shown in the example.
1944 But we actually don't need to know this convention, since we are given the name
1945 of the ivar directly.
1949 Also, it is common practice in ObjC to have different property declarations in
1950 the @interface and @implementation - e.g. to provide a read-only property in
1951 the interface,and a read-write interface in the implementation. In that case,
1952 the compiler should emit whichever property declaration will be in force in the
1953 current translation unit.
1956 <p> Developers can decorate a property with attributes which are encoded using
1957 DW_AT_APPLE_property_attribute.
1960 <div class="doc_code">
1962 @property (readonly, nonatomic) int pr;
1966 Which produces a property tag:
1968 <div class="doc_code">
1970 TAG_APPLE_property [8]
1972 AT_type ( {0x00000147} (int) )
1973 AT_APPLE_property_attribute (DW_APPLE_PROPERTY_readonly, DW_APPLE_PROPERTY_nonatomic)
1977 <p> The setter and getter method names are attached to the property using
1978 DW_AT_APPLE_property_setter and DW_AT_APPLE_property_getter attributes.
1980 <div class="doc_code">
1983 @property (setter=myOwnP3Setter:) int p3;
1984 -(void)myOwnP3Setter:(int)a;
1989 -(void)myOwnP3Setter:(int)a{ }
1995 The DWARF for this would be:
1997 <div class="doc_code">
1999 0x000003bd: TAG_structure_type [7] *
2000 AT_APPLE_runtime_class( 0x10 )
2002 AT_decl_file( "Objc_Property.m" )
2005 0x000003cd TAG_APPLE_property
2007 AT_APPLE_property_setter ( "myOwnP3Setter:" )
2008 AT_type( {0x00000147} ( int ) )
2010 0x000003f3: TAG_member [8]
2012 AT_type ( {0x00000147} ( int ) )
2013 AT_APPLE_property ( {0x000003cd} )
2014 AT_artificial ( 0x1 )
2020 <!-- *********************************************************************** -->
2022 <a name="objcpropertynewtags">New DWARF Tags</a>
2024 <!-- *********************************************************************** -->
2027 <table border="1" cellspacing="0">
2029 <th width=200 >TAG</th>
2030 <th width=200 >Value</th>
2033 <td width=200 >DW_TAG_APPLE_property</td>
2034 <td width=200 >0x4200</td>
2040 <!-- *********************************************************************** -->
2042 <a name="objcpropertynewattributes">New DWARF Attributes</a>
2044 <!-- *********************************************************************** -->
2047 <table border="1" cellspacing="0">
2049 <th width=200 >Attribute</th>
2050 <th width=200 >Value</th>
2051 <th width=200 >Classes</th>
2054 <td width=200 >DW_AT_APPLE_property</td>
2055 <td width=200 >0x3fed</td>
2056 <td width=200 >Reference</td>
2059 <td width=200 >DW_AT_APPLE_property_getter</td>
2060 <td width=200 >0x3fe9</td>
2061 <td width=200 >String</td>
2064 <td width=200 >DW_AT_APPLE_property_setter</td>
2065 <td width=200 >0x3fea</td>
2066 <td width=200 >String</td>
2069 <td width=200 >DW_AT_APPLE_property_attribute</td>
2070 <td width=200 >0x3feb</td>
2071 <td width=200 >Constant</td>
2077 <!-- *********************************************************************** -->
2079 <a name="objcpropertynewconstants">New DWARF Constants</a>
2081 <!-- *********************************************************************** -->
2084 <table border="1" cellspacing="0">
2086 <th width=200 >Name</th>
2087 <th width=200 >Value</th>
2090 <td width=200 >DW_AT_APPLE_PROPERTY_readonly</td>
2091 <td width=200 >0x1</td>
2094 <td width=200 >DW_AT_APPLE_PROPERTY_readwrite</td>
2095 <td width=200 >0x2</td>
2098 <td width=200 >DW_AT_APPLE_PROPERTY_assign</td>
2099 <td width=200 >0x4</td>
2102 <td width=200 >DW_AT_APPLE_PROPERTY_retain</td>
2103 <td width=200 >0x8</td>
2106 <td width=200 >DW_AT_APPLE_PROPERTY_copy</td>
2107 <td width=200 >0x10</td>
2110 <td width=200 >DW_AT_APPLE_PROPERTY_nonatomic</td>
2111 <td width=200 >0x20</td>
2119 <!-- *********************************************************************** -->
2123 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
2124 src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
2125 <a href="http://validator.w3.org/check/referer"><img
2126 src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
2128 <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
2129 <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
2130 Last modified: $Date$