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