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