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