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