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