Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / 8ff759072f5dd1fd4158944c90d1f1c93cc2f047 / . / docs / SourceLevelDebugging.html
blob: a7037f237190049dbce7a5b2232d033d8953838b [file] [log] [blame]
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<html>
4<head>
5 <title>Source Level Debugging with LLVM</title>
6 <link rel="stylesheet" href="llvm.css" type="text/css">
7</head>
8<body>
9
10<div class="doc_title">Source Level Debugging with LLVM</div>
11
12<ul>
13
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]14<img src="venusflytrap.jpg" alt="A leafy and green bug eater"
15 width=247 height=369 align=right>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]16
17 <li><a href="#introduction">Introduction</a></li>
18 <ol>
19 <li><a href="#phil">Philosophy behind LLVM debugging information</a></li>
20 <li><a href="#debugopt">Debugging optimized code</a></li>
21 <li><a href="#future">Future work</a></li>
22 </ol>
23 <li><a href="#llvm-db">Using the <tt>llvm-db</tt> tool</a>
24 <ol>
25 <li><a href="#limitations">Limitations of <tt>llvm-db</tt></a></li>
26 <li><a href="#sample">A sample <tt>llvm-db</tt> session</a></li>
27 <li><a href="#startup">Starting the debugger</a></li>
28 <li><a href="#commands">Commands recognized by the debugger</a></li>
29 </ol></li>
30
31 <li><a href="#architecture">Architecture of the LLVM debugger</a></li>
32 <ol>
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]33 <li><a href="#arch_debugger">The Debugger and InferiorProcess classes</a></li>
34 <li><a href="#arch_info">The RuntimeInfo, ProgramInfo, and SourceLanguage classes</a></li>
35 <li><a href="#arch_llvm-db">The <tt>llvm-db</tt> tool</a></li>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]36 <li><a href="#arch_todo">Short-term TODO list</a></li>
37 </ol>
38
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]39 <li><a href="#format">Debugging information format</a></li>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]40 <ol>
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]41 <li><a href="#format_common_anchors">Anchors for global objects</a></li>
42 <li><a href="#format_common_stoppoint">Representing stopping points in the source program</a></li>
43 <li><a href="#format_common_lifetime">Object lifetimes and scoping</a></li>
44 <li><a href="#format_common_descriptors">Object descriptor formats</a></li>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]45 <ul>
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]46 <li><a href="#format_common_source_files">Representation of source files</a></li>
47 <li><a href="#format_common_program_objects">Representation of program objects</a></li>
48 <li><a href="#format_common_object_contexts">Program object contexts</a></li>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]49 </ul>
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]50 <li><a href="#format_common_intrinsics">Debugger intrinsic functions</a></li>
51 <li><a href="#format_common_tags">Values for debugger tags</a></li>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]52 </ol>
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]53 <li><a href="#ccxx_frontend">C/C++ front-end specific debug information</a></li>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]54 <ol>
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]55 <li><a href="#ccxx_pse">Program Scope Entries</a></li>
56 <ul>
57 <li><a href="#ccxx_compilation_units">Compilation unit entries</a></li>
58 <li><a href="#ccxx_modules">Module, namespace, and importing entries</a></li>
59 </ul>
60 <li><a href="#ccxx_dataobjects">Data objects (program variables)</a></li>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]61 </ol>
62</ul>
63
64<!-- *********************************************************************** -->
65<div class="doc_section"><a name="introduction">Introduction</a></div>
66<!-- *********************************************************************** -->
67
68<div class="doc_text">
69
70<p>This document is the central repository for all information pertaining to
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]71debug information in LLVM. It describes the <a href="#llvm-db">user
72interface</a> for the <a href="CommandGuide/llvm-db.html"><tt>llvm-db</tt>
73tool</a>, which provides a powerful <a href="#llvm-db">source-level debugger</a>
74to users of LLVM-based compilers. It then describes the <a
75href="#architecture">various components</a> that make up the debugger and the
76libraries which future clients may use. Finally, it describes the <a
77href="#format">actual format that the LLVM debug information</a> takes,
78which is useful for those interested in creating front-ends or dealing directly
79with the information.</p>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]80
81</div>
82
83<!-- ======================================================================= -->
84<div class="doc_subsection">
85 <a name="phil">Philosophy behind LLVM debugging information</a>
86</div>
87
88<div class="doc_text">
89
90<p>
91The idea of the LLVM debugging information is to capture how the important
92pieces of the source-language's Abstract Syntax Tree map onto LLVM code.
93Several design aspects have shaped the solution that appears here. The
94important ones are:</p>
95
96<p><ul>
97<li>Debugging information should have very little impact on the rest of the
98compiler. No transformations, analyses, or code generators should need to be
99modified because of debugging information.</li>
100
101<li>LLVM optimizations should interact in <a href="#debugopt">well-defined and
102easily described ways</a> with the debugging information.</li>
103
104<li>Because LLVM is designed to support arbitrary programming languages,
105LLVM-to-LLVM tools should not need to know anything about the semantics of the
106source-level-language.</li>
107
108<li>Source-level languages are often <b>widely</b> different from one another.
109LLVM should not put any restrictions of the flavor of the source-language, and
110the debugging information should work with any language.</li>
111
112<li>With code generator support, it should be possible to use an LLVM compiler
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]113to compile a program to native machine code and standard debugging formats.
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]114This allows compatibility with traditional machine-code level debuggers, like
115GDB or DBX.</li>
116
117</ul></p>
118
119<p>
120The approach used by the LLVM implementation is to use a small set of <a
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]121href="#format_common_intrinsics">intrinsic functions</a> to define a mapping
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]122between LLVM program objects and the source-level objects. The description of
123the source-level program is maintained in LLVM global variables in an <a
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]124href="#ccxx_frontend">implementation-defined format</a> (the C/C++ front-end
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]125currently uses working draft 7 of the <a
126href="http://www.eagercon.com/dwarf/dwarf3std.htm">Dwarf 3 standard</a>).</p>
127
128<p>
129When a program is debugged, the debugger interacts with the user and turns the
130stored debug information into source-language specific information. As such,
131the debugger must be aware of the source-language, and is thus tied to a
132specific language of family of languages. The <a href="#llvm-db">LLVM
133debugger</a> is designed to be modular in its support for source-languages.
134</p>
135
136</div>
137
138
139<!-- ======================================================================= -->
140<div class="doc_subsection">
141 <a name="debugopt">Debugging optimized code</a>
142</div>
143
144<div class="doc_text">
145<p>
146An extremely high priority of LLVM debugging information is to make it interact
147well with optimizations and analysis. In particular, the LLVM debug information
148provides the following guarantees:</p>
149
150<p><ul>
151
152<li>LLVM debug information <b>always provides information to accurately read the
153source-level state of the program</b>, regardless of which LLVM optimizations
154have been run, and without any modification to the optimizations themselves.
155However, some optimizations may impact the ability to modify the current state
156of the program with a debugger, such as setting program variables, or calling
157function that have been deleted.</li>
158
159<li>LLVM optimizations gracefully interact with debugging information. If they
160are not aware of debug information, they are automatically disabled as necessary
161in the cases that would invalidate the debug info. This retains the LLVM
162features making it easy to write new transformations.</li>
163
164<li>As desired, LLVM optimizations can be upgraded to be aware of the LLVM
165debugging information, allowing them to update the debugging information as they
166perform aggressive optimizations. This means that, with effort, the LLVM
167optimizers could optimize debug code just as well as non-debug code.</li>
168
169<li>LLVM debug information does not prevent many important optimizations from
170happening (for example inlining, basic block reordering/merging/cleanup, tail
171duplication, etc), further reducing the amount of the compiler that eventually
172is "aware" of debugging information.</li>
173
174<li>LLVM debug information is automatically optimized along with the rest of the
175program, using existing facilities. For example, duplicate information is
176automatically merged by the linker, and unused information is automatically
177removed.</li>
178
179</ul></p>
180
181<p>
182Basically, the debug information allows you to compile a program with "<tt>-O0
183-g</tt>" and get full debug information, allowing you to arbitrarily modify the
184program as it executes from the debugger. Compiling a program with "<tt>-O3
185-g</tt>" gives you full debug information that is always available and accurate
186for reading (e.g., you get accurate stack traces despite tail call elimination
187and inlining), but you might lose the ability to modify the program and call
188functions where were optimized out of the program, or inlined away completely.
189</p>
190
191</div>
192
193
194<!-- ======================================================================= -->
195<div class="doc_subsection">
196 <a name="future">Future work</a>
197</div>
198
199<div class="doc_text">
200<p>
201There are several important extensions that could be eventually added to the
202LLVM debugger. The most important extension would be to upgrade the LLVM code
203generators to support debugging information. This would also allow, for
204example, the X86 code generator to emit native objects that contain debugging
205information consumable by traditional source-level debuggers like GDB or
206DBX.</p>
207
208<p>
209Additionally, LLVM optimizations can be upgraded to incrementally update the
210debugging information, <a href="#commands">new commands</a> can be added to the
211debugger, and thread support could be added to the debugger.</p>
212
213<p>
214The "SourceLanguage" modules provided by <tt>llvm-db</tt> could be substantially
215improved to provide good support for C++ language features like namespaces and
216scoping rules.</p>
217
218<p>
219After working with the debugger for a while, perhaps the nicest improvement
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]220would be to add some sort of line editor, such as GNU readline (but one that is
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]221compatible with the LLVM license).</p>
222
223<p>
224For someone so inclined, it should be straight-forward to write different
225front-ends for the LLVM debugger, as the LLVM debugging engine is cleanly
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]226separated from the <tt>llvm-db</tt> front-end. A new LLVM GUI debugger or IDE
227would be nice. :)
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]228</p>
229
230</div>
231
232
233<!-- *********************************************************************** -->
234<div class="doc_section">
235 <a name="llvm-db">Using the <tt>llvm-db</tt> tool</a>
236</div>
237<!-- *********************************************************************** -->
238
239<div class="doc_text">
240
241<p>
242The <tt>llvm-db</tt> tool provides a GDB-like interface for source-level
243debugging of programs. This tool provides many standard commands for inspecting
244and modifying the program as it executes, loading new programs, single stepping,
245placing breakpoints, etc. This section describes how to use the debugger.
246</p>
247
248<p><tt>llvm-db</tt> has been designed to be as similar to GDB in its user
249interface as possible. This should make it extremely easy to learn
250<tt>llvm-db</tt> if you already know <tt>GDB</tt>. In general, <tt>llvm-db</tt>
251provides the subset of GDB commands that are applicable to LLVM debugging users.
252If there is a command missing that make a reasonable amount of sense within the
253<a href="#limitations">limitations of <tt>llvm-db</tt></a>, please report it as
254a bug or, better yet, submit a patch to add it. :)</p>
255
256</div>
257
258<!-- ======================================================================= -->
259<div class="doc_subsection">
260 <a name="limitations">Limitations of <tt>llvm-db</tt></a>
261</div>
262
263<div class="doc_text">
264
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]265<p><tt>llvm-db</tt> is designed to be modular and easy to extend. This
266extensibility was key to getting the debugger up-and-running quickly, because we
267can start with simple-but-unsophisicated implementations of various components.
268Because of this, it is currently missing many features, though they should be
269easy to add over time (patches welcomed!). The biggest inherent limitations of
270<tt>llvm-db</tt> are currently due to extremely simple <a
271href="#arch_debugger">debugger backend</a> (implemented in
272"lib/Debugger/UnixLocalInferiorProcess.cpp") which is designed to work without
273any cooperation from the code generators. Because it is so simple, it suffers
274from the following inherent limitations:</p>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]275
276<p><ul>
277
278<li>Running a program in <tt>llvm-db</tt> is a bit slower than running it with
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]279<tt>lli</tt> (i.e., in the JIT).</li>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]280
281<li>Inspection of the target hardware is not supported. This means that you
282cannot, for example, print the contents of X86 registers.</li>
283
284<li>Inspection of LLVM code is not supported. This means that you cannot print
285the contents of arbitrary LLVM values, or use commands such as <tt>stepi</tt>.
286This also means that you cannot debug code without debug information.</li>
287
288<li>Portions of the debugger run in the same address space as the program being
289debugged. This means that memory corruption by the program could trample on
290portions of the debugger.</li>
291
292<li>Attaching to existing processes and core files is not currently
293supported.</li>
294
295</ul></p>
296
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]297<p>That said, the debugger is still quite useful, and all of these limitations
298can be eliminated by integrating support for the debugger into the code
299generators, and writing a new <a href="#arch_debugger">InferiorProcess</a>
300subclass to use it. See the <a href="#future">future work</a> section for ideas
301of how to extend the LLVM debugger despite these limitations.</p>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]302
303</div>
304
305
306<!-- ======================================================================= -->
307<div class="doc_subsection">
308 <a name="sample">A sample <tt>llvm-db</tt> session</a>
309</div>
310
311<div class="doc_text">
312
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]313<p>TODO: this is obviously lame, when more is implemented, this can be much
314better.</p>
315
316<p><pre>
317$ <b>llvm-db funccall</b>
318llvm-db: The LLVM source-level debugger
319Loading program... successfully loaded 'funccall.bc'!
320(llvm-db) <b>create</b>
321Starting program: funccall.bc
322main at funccall.c:9:2
3239 -> q = 0;
324(llvm-db) <b>list main</b>
3254 void foo() {
3265 int t = q;
3276 q = t + 1;
3287 }
3298 int main() {
3309 -> q = 0;
33110 foo();
33211 q = q - 1;
33312
33413 return q;
335(llvm-db) <b>list</b>
33614 }
337(llvm-db) <b>step</b>
33810 -> foo();
339(llvm-db) <b>s</b>
340foo at funccall.c:5:2
3415 -> int t = q;
342(llvm-db) <b>bt</b>
343#0 -> 0x85ffba0 in foo at funccall.c:5:2
344#1 0x85ffd98 in main at funccall.c:10:2
345(llvm-db) <b>finish</b>
346main at funccall.c:11:2
34711 -> q = q - 1;
348(llvm-db) <b>s</b>
34913 -> return q;
350(llvm-db) <b>s</b>
351The program stopped with exit code 0
352(llvm-db) <b>quit</b>
353$
354</pre></p>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]355
356</div>
357
358
359
360<!-- ======================================================================= -->
361<div class="doc_subsection">
362 <a name="startup">Starting the debugger</a>
363</div>
364
365<div class="doc_text">
366
367<p>There are three ways to start up the <tt>llvm-db</tt> debugger:</p>
368
369<p>When run with no options, just <tt>llvm-db</tt>, the debugger starts up
370without a program loaded at all. You must use the <a
371href="#c_file"><tt>file</tt> command</a> to load a program, and the <a
372href="c_set_args"><tt>set args</tt></a> or <a href="#c_run"><tt>run</tt></a>
373commands to specify the arguments for the program.</p>
374
375<p>If you start the debugger with one argument, as <tt>llvm-db
376&lt;program&gt;</tt>, the debugger will start up and load in the specified
377program. You can then optionally specify arguments to the program with the <a
378href="c_set_args"><tt>set args</tt></a> or <a href="#c_run"><tt>run</tt></a>
379commands.</p>
380
381<p>The third way to start the program is with the <tt>--args</tt> option. This
382option allows you to specify the program to load and the arguments to start out
383with. <!-- No options to <tt>llvm-db</tt> may be specified after the
384<tt>-args</tt> option. --> Example use: <tt>llvm-db --args ls /home</tt></p>
385
386</div>
387
388<!-- ======================================================================= -->
389<div class="doc_subsection">
390 <a name="commands">Commands recognized by the debugger</a>
391</div>
392
393<div class="doc_text">
394
395<p>FIXME: this needs work obviously. See the <a
396href="http://sources.redhat.com/gdb/documentation/">GDB documentation</a> for
397information about what these do, or try '<tt>help [command]</tt>' within
398<tt>llvm-db</tt> to get information.</p>
399
400<p>
401<h2>General usage:</h2>
402<ul>
403<li>help [command]</li>
404<li>quit</li>
405<li><a name="c_file">file</a> [program]</li>
406</ul>
407
408<h2>Program inspection and interaction:</h2>
409<ul>
410<li>create (start the program, stopping it ASAP in <tt>main</tt>)</li>
411<li>kill</li>
412<li>run [args]</li>
413<li>step [num]</li>
414<li>next [num]</li>
415<li>cont</li>
416<li>finish</li>
417
418<li>list [start[, end]]</li>
419<li>info source</li>
420<li>info sources</li>
421<li>info functions</li>
422</ul>
423
424<h2>Call stack inspection:</h2>
425<ul>
426<li>backtrace</li>
427<li>up [n]</li>
428<li>down [n]</li>
429<li>frame [n]</li>
430</ul>
431
432
433<h2>Debugger inspection and interaction:</h2>
434<ul>
435<li>info target</li>
436<li>show prompt</li>
437<li>set prompt</li>
438<li>show listsize</li>
439<li>set listsize</li>
440<li>show language</li>
441<li>set language</li>
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]442<li>show args</li>
443<li>set args [args]</li>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]444</ul>
445
446<h2>TODO:</h2>
447<ul>
448<li>info frame</li>
449<li>break</li>
450<li>print</li>
451<li>ptype</li>
452
453<li>info types</li>
454<li>info variables</li>
455<li>info program</li>
456
457<li>info args</li>
458<li>info locals</li>
459<li>info catch</li>
460<li>... many others</li>
461</ul>
462</p>
463</div>
464
465<!-- *********************************************************************** -->
466<div class="doc_section">
467 <a name="architecture">Architecture of the LLVM debugger</a>
468</div>
469<!-- *********************************************************************** -->
470
471<div class="doc_text">
472
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]473<p>
474The LLVM debugger is built out of three distinct layers of software. These
475layers provide clients with different interface options depending on what pieces
476of they want to implement themselves, and it also promotes code modularity and
477good design. The three layers are the <a href="#arch_debugger">Debugger
478interface</a>, the <a href="#arch_info">"info" interfaces</a>, and the
479<a href="#arch_llvm-db"><tt>llvm-db</tt> tool</a> itself.
480</p>
481</div>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]482
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]483<!-- ======================================================================= -->
484<div class="doc_subsection">
485 <a name="arch_debugger">The Debugger and InferiorProcess classes</a>
486</div>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]487
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]488<div class="doc_text">
489<p>
490The Debugger class (defined in the <tt>include/llvm/Debugger/</tt> directory) is
491a low-level class which is used to maintain information about the loaded
492program, as well as start and stop the program running as necessary. This class
493does not provide any high-level analysis or control over the program, only
494exposing simple interfaces like <tt>load/unloadProgram</tt>,
495<tt>create/killProgram</tt>, <tt>step/next/finish/contProgram</tt>, and
496low-level methods for installing breakpoints.
497</p>
498
499<p>
500The Debugger class is itself a wrapper around the lowest-level InferiorProcess
501class. This class is used to represent an instance of the program running under
502debugger control. The InferiorProcess class can be implemented in different
503ways for different targets and execution scenarios (e.g., remote debugging).
504The InferiorProcess class exposes a small and simple collection of interfaces
505which are useful for inspecting the current state of the program (such as
506collecting stack trace information, reading the memory image of the process,
507etc). The interfaces in this class are designed to be as low-level and simple
508as possible, to make it easy to create new instances of the class.
509</p>
510
511<p>
512The Debugger class exposes the currently active instance of InferiorProcess
513through the <tt>Debugger::getRunningProcess</tt> method, which returns a
514<tt>const</tt> reference to the class. This means that clients of the Debugger
515class can only <b>inspect</b> the running instance of the program directly. To
516change the executing process in some way, they must use the interces exposed by
517the Debugger class.
518</p>
519</div>
520
521<!-- ======================================================================= -->
522<div class="doc_subsection">
523 <a name="arch_info">The RuntimeInfo, ProgramInfo, and SourceLanguage classes</a>
524</div>
525
526<div class="doc_text">
527<p>
528The next-highest level of debugger abstraction is provided through the
529ProgramInfo, RuntimeInfo, SourceLanguage and related classes (also defined in
530the <tt>include/llvm/Debugger/</tt> directory). These classes efficiently
531decode the debugging information and low-level interfaces exposed by
532InferiorProcess into a higher-level representation, suitable for analysis by the
533debugger.
534</p>
535
536<p>
537The ProgramInfo class exposes a variety of different kinds of information about
538the program objects in the source-level-language. The SourceFileInfo class
539represents a source-file in the program (e.g. a .cpp or .h file). The
540SourceFileInfo class captures information such as which SourceLanguage was used
541to compile the file, where the debugger can get access to the actual file text
542(which is lazily loaded on demand), etc. The SourceFunctionInfo class
543represents a... <b>FIXME: finish</b>. The ProgramInfo class provides interfaces
544to lazily find and decode the information needed to create the Source*Info
545classes requested by the debugger.
546</p>
547
548<p>
549The RuntimeInfo class exposes information about the currently executed program,
550by decoding information from the InferiorProcess and ProgramInfo classes. It
551provides a StackFrame class which provides an easy-to-use interface for
552inspecting the current and suspended stack frames in the program.
553</p>
554
555<p>
556The SourceLanguage class is an abstract interface used by the debugger to
557perform all source-language-specific tasks. For example, this interface is used
558by the ProgramInfo class to decode language-specific types and functions and by
559the debugger front-end (such as <a href="#arch_llvm-db"><tt>llvm-db</tt></a> to
560evaluate source-langauge expressions typed into the debugger. This class uses
561the RuntimeInfo &amp; ProgramInfo classes to get information about the current
562execution context and the loaded program, respectively.
563</p>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]564
565</div>
566
567<!-- ======================================================================= -->
568<div class="doc_subsection">
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]569 <a name="arch_llvm-db">The <tt>llvm-db</tt> tool</a>
570</div>
571
572<div class="doc_text">
573<p>
574The <tt>llvm-db</tt> is designed to be a debugger providing an interface as <a
575href="#llvm-db">similar to GDB</a> as reasonable, but no more so than that.
576Because the <a href="#arch_debugger">Debugger</a> and <a
577href="#arch_info">info</a> classes implement all of the heavy lifting and
578analysis, <tt>llvm-db</tt> (which lives in <tt>llvm/tools/llvm-db</tt>) consists
579mainly of of code to interact with the user and parse commands. The CLIDebugger
580constructor registers all of the builtin commands for the debugger, and each
581command is implemented as a CLIDebugger::[name]Command method.
582</p>
583</div>
584
585
586<!-- ======================================================================= -->
587<div class="doc_subsection">
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]588 <a name="arch_todo">Short-term TODO list</a>
589</div>
590
591<div class="doc_text">
592
593<p>
594FIXME: this section will eventually go away. These are notes to myself of
595things that should be implemented, but haven't yet.
596</p>
597
598<p>
599<b>Breakpoints:</b> Support is already implemented in the 'InferiorProcess'
600class, though it hasn't been tested yet. To finish breakpoint support, we need
601to implement breakCommand (which should reuse the linespec parser from the list
602command), and handle the fact that 'break foo' or 'break file.c:53' may insert
603multiple breakpoints. Also, if you say 'break file.c:53' and there is no
604stoppoint on line 53, the breakpoint should go on the next available line. My
605idea was to have the Debugger class provide a "Breakpoint" class which
606encapsulated this messiness, giving the debugger front-end a simple interface.
607The debugger front-end would have to map the really complex semantics of
608temporary breakpoints and 'conditional' breakpoints onto this intermediate
609level. Also, breakpoints should survive as much as possible across program
610reloads.
611</p>
612
613<p>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]614<b>UnixLocalInferiorProcess.cpp speedup</b>: There is no reason for the debugged
615process to code gen the globals corresponding to debug information. The
616IntrinsicLowering object could instead change descriptors into constant expr
617casts of the constant address of the LLVM objects for the descriptors. This
618would also allow us to eliminate the mapping back and forth between physical
619addresses that must be done.</p>
620
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]621<p>
622<b>Process deaths</b>: The InferiorProcessDead exception should be extended to
623know "how" a process died, i.e., it was killed by a signal. This is easy to
624collect in the UnixLocalInferiorProcess, we just need to represent it.</p>
625
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]626</div>
627
628<!-- *********************************************************************** -->
629<div class="doc_section">
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]630 <a name="format">Debugging information format</a>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]631</div>
632<!-- *********************************************************************** -->
633
634<div class="doc_text">
635
636<p>LLVM debugging information has been carefully designed to make it possible
637for the optimizer to optimize the program and debugging information without
638necessarily having to know anything about debugging information. In particular,
639the global constant merging pass automatically eliminates duplicated debugging
640information (often caused by header files), the global dead code elimination
641pass automatically deletes debugging information for a function if it decides to
642delete the function, and the linker eliminates debug information when it merges
643<tt>linkonce</tt> functions.</p>
644
645<p>To do this, most of the debugging information (descriptors for types,
646variables, functions, source files, etc) is inserted by the language front-end
647in the form of LLVM global variables. These LLVM global variables are no
648different from any other global variables, except that they have a web of LLVM
649intrinsic functions that point to them. If the last references to a particular
650piece of debugging information are deleted (for example, by the
651<tt>-globaldce</tt> pass), the extraneous debug information will automatically
652become dead and be removed by the optimizer.</p>
653
654<p>The debugger is designed to be agnostic about the contents of most of the
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]655debugging information. It uses a <a href="#arch_info">source-language-specific
656module</a> to decode the information that represents variables, types,
657functions, namespaces, etc: this allows for arbitrary source-language semantics
658and type-systems to be used, as long as there is a module written for the
659debugger to interpret the information.
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]660</p>
661
662<p>
663To provide basic functionality, the LLVM debugger does have to make some
664assumptions about the source-level language being debugged, though it keeps
665these to a minimum. The only common features that the LLVM debugger assumes
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]666exist are <a href="#format_common_source_files">source files</a>, and <a
667href="#format_program_objects">program objects</a>. These abstract objects are
668used by the debugger to form stack traces, show information about local
669variables, etc.
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]670
671<p>This section of the documentation first describes the representation aspects
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]672common to any source-language. The <a href="#ccxx_frontend">next section</a>
673describes the data layout conventions used by the C and C++ front-ends.</p>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]674
675</div>
676
677<!-- ======================================================================= -->
678<div class="doc_subsection">
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]679 <a name="format_common_anchors">Anchors for global objects</a>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]680</div>
681
682<div class="doc_text">
683<p>
684One important aspect of the LLVM debug representation is that it allows the LLVM
685debugger to efficiently index all of the global objects without having the scan
686the program. To do this, all of the global objects use "anchor" globals of type
687"<tt>{}</tt>", with designated names. These anchor objects obviously do not
688contain any content or meaning by themselves, but all of the global objects of a
689particular type (e.g., source file descriptors) contain a pointer to the anchor.
690This pointer allows the debugger to use def-use chains to find all global
691objects of that type.
692</p>
693
694<p>
695So far, the following names are recognized as anchors by the LLVM debugger:
696</p>
697
698<p><pre>
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]699 %<a href="#format_common_source_files">llvm.dbg.translation_units</a> = linkonce global {} {}
700 %<a href="#format_program_objects">llvm.dbg.globals</a> = linkonce global {} {}
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]701</pre></p>
702
703<p>
704Using anchors in this way (where the source file descriptor points to the
705anchors, as opposed to having a list of source file descriptors) allows for the
706standard dead global elimination and merging passes to automatically remove
707unused debugging information. If the globals were kept track of through lists,
708there would always be an object pointing to the descriptors, thus would never be
709deleted.
710</p>
711
712</div>
713
714
715<!-- ======================================================================= -->
716<div class="doc_subsection">
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]717 <a name="format_common_stoppoint">
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]718 Representing stopping points in the source program
719 </a>
720</div>
721
722<div class="doc_text">
723
724<p>LLVM debugger "stop points" are a key part of the debugging representation
725that allows the LLVM to maintain simple semantics for <a
726href="#debugopt">debugging optimized code</a>. The basic idea is that the
727front-end inserts calls to the <tt>%llvm.dbg.stoppoint</tt> intrinsic function
728at every point in the program where the debugger should be able to inspect the
729program (these correspond to places the debugger stops when you "<tt>step</tt>"
730through it). The front-end can choose to place these as fine-grained as it
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]731would like (for example, before every subexpression evaluated), but it is
732recommended to only put them after every source statement that includes
733executable code.</p>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]734
735<p>
736Using calls to this intrinsic function to demark legal points for the debugger
737to inspect the program automatically disables any optimizations that could
738potentially confuse debugging information. To non-debug-information-aware
739transformations, these calls simply look like calls to an external function,
740which they must assume to do anything (including reading or writing to any part
741of reachable memory). On the other hand, it does not impact many optimizations,
742such as code motion of non-trapping instructions, nor does it impact
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]743optimization of subexpressions, code duplication transformations, or basic-block
744reordering transformations.</p>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]745
746<p>
747An important aspect of the calls to the <tt>%llvm.dbg.stoppoint</tt> intrinsic
748is that the function-local debugging information is woven together with use-def
749chains. This makes it easy for the debugger to, for example, locate the 'next'
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]750stop point. For a concrete example of stop points, see the example in <a
751href="#format_common_lifetime">the next section</a>.</p>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]752
753</div>
754
755
756<!-- ======================================================================= -->
757<div class="doc_subsection">
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]758 <a name="format_common_lifetime">Object lifetimes and scoping</a>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]759</div>
760
761<div class="doc_text">
762<p>
763In many languages, the local variables in functions can have their lifetime or
764scope limited to a subset of a function. In the C family of languages, for
765example, variables are only live (readable and writable) within the source block
766that they are defined in. In functional languages, values are only readable
767after they have been defined. Though this is a very obvious concept, it is also
768non-trivial to model in LLVM, because it has no notion of scoping in this sense,
769and does not want to be tied to a language's scoping rules.
770</p>
771
772<p>
773In order to handle this, the LLVM debug format uses the notion of "regions" of a
774function, delineated by calls to intrinsic functions. These intrinsic functions
775define new regions of the program and indicate when the region lifetime expires.
776Consider the following C fragment, for example:
777</p>
778
779<p><pre>
7801. void foo() {
7812. int X = ...;
7823. int Y = ...;
7834. {
7845. int Z = ...;
7856. ...
7867. }
7878. ...
7889. }
789</pre></p>
790
791<p>
792Compiled to LLVM, this function would be represented like this (FIXME: CHECK AND
793UPDATE THIS):
794</p>
795
796<p><pre>
797void %foo() {
798 %X = alloca int
799 %Y = alloca int
800 %Z = alloca int
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]801 <a name="#icl_ex_D1">%D1</a> = call {}* %llvm.dbg.func.start(<a href="#format_program_objects">%lldb.global</a>* %d.foo)
802 %D2 = call {}* <a href="#format_common_stoppoint">%llvm.dbg.stoppoint</a>({}* %D1, uint 2, uint 2, <a href="#format_common_source_files">%lldb.compile_unit</a>* %file)
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]803
804 %D3 = call {}* %llvm.dbg.DEFINEVARIABLE({}* %D2, ...)
805 <i>;; Evaluate expression on line 2, assigning to X.</i>
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]806 %D4 = call {}* <a href="#format_common_stoppoint">%llvm.dbg.stoppoint</a>({}* %D3, uint 3, uint 2, <a href="#format_common_source_files">%lldb.compile_unit</a>* %file)
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]807
808 %D5 = call {}* %llvm.dbg.DEFINEVARIABLE({}* %D4, ...)
809 <i>;; Evaluate expression on line 3, assigning to Y.</i>
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]810 %D6 = call {}* <a href="#format_common_stoppoint">%llvm.dbg.stoppoint</a>({}* %D5, uint 5, uint 4, <a href="#format_common_source_files">%lldb.compile_unit</a>* %file)
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]811
812 <a name="#icl_ex_D1">%D7</a> = call {}* %llvm.region.start({}* %D6)
813 %D8 = call {}* %llvm.dbg.DEFINEVARIABLE({}* %D7, ...)
814 <i>;; Evaluate expression on line 5, assigning to Z.</i>
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]815 %D9 = call {}* <a href="#format_common_stoppoint">%llvm.dbg.stoppoint</a>({}* %D8, uint 6, uint 4, <a href="#format_common_source_files">%lldb.compile_unit</a>* %file)
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]816
817 <i>;; Code for line 6.</i>
818 %D10 = call {}* %llvm.region.end({}* %D9)
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]819 %D11 = call {}* <a href="#format_common_stoppoint">%llvm.dbg.stoppoint</a>({}* %D10, uint 8, uint 2, <a href="#format_common_source_files">%lldb.compile_unit</a>* %file)
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]820
821 <i>;; Code for line 8.</i>
822 <a name="#icl_ex_D1">%D12</a> = call {}* %llvm.region.end({}* %D11)
823 ret void
824}
825</pre></p>
826
827<p>
828This example illustrates a few important details about the LLVM debugging
829information. In particular, it shows how the various intrinsics used are woven
830together with def-use and use-def chains, similar to how <a
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]831href="#format_common_anchors">anchors</a> are used with globals. This allows the
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]832debugger to analyze the relationship between statements, variable definitions,
833and the code used to implement the function.</p>
834
835<p>
836In this example, two explicit regions are defined, one with the <a
837href="#icl_ex_D1">definition of the <tt>%D1</tt> variable</a> and one with the
838<a href="#icl_ex_D7">definition of <tt>%D7</tt></a>. In the case of
839<tt>%D1</tt>, the debug information indicates that the function whose <a
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]840href="#format_program_objects">descriptor</a> is specified as an argument to the
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]841intrinsic. This defines a new stack frame whose lifetime ends when the region
842is ended by <a href="#icl_ex_D12">the <tt>%D12</tt> call</a>.</p>
843
844<p>
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]845Using regions to represent the boundaries of source-level functions allow LLVM
846interprocedural optimizations to arbitrarily modify LLVM functions without
847having to worry about breaking mapping information between the LLVM code and the
848and source-level program. In particular, the inliner requires no modification
849to support inlining with debugging information: there is no explicit correlation
850drawn between LLVM functions and their source-level counterparts (note however,
851that if the inliner inlines all instances of a non-strong-linkage function into
852its caller that it will not be possible for the user to manually invoke the
853inlined function from the debugger).</p>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]854
855<p>
856Once the function has been defined, the <a
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]857href="#format_common_stoppoint">stopping point</a> corresponding to line #2 of the
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]858function is encountered. At this point in the function, <b>no</b> local
859variables are live. As lines 2 and 3 of the example are executed, their
860variable definitions are automatically introduced into the program, without the
861need to specify a new region. These variables do not require new regions to be
862introduced because they go out of scope at the same point in the program: line
8639.
864</p>
865
866<p>
867In contrast, the <tt>Z</tt> variable goes out of scope at a different time, on
868line 7. For this reason, it is defined within <a href="#icl_ex_D7">the
869<tt>%D7</tt> region</a>, which kills the availability of <tt>Z</tt> before the
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]870code for line 8 is executed. In this way, regions can support arbitrary
871source-language scoping rules, as long as they can only be nested (ie, one scope
872cannot partially overlap with a part of another scope).
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]873</p>
874
875<p>
876It is worth noting that this scoping mechanism is used to control scoping of all
877declarations, not just variable declarations. For example, the scope of a C++
878using declaration is controlled with this, and the <tt>llvm-db</tt> C++ support
879routines could use this to change how name lookup is performed (though this is
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]880not implemented yet).
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]881</p>
882
883</div>
884
885
886<!-- ======================================================================= -->
887<div class="doc_subsection">
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]888 <a name="format_common_descriptors">Object descriptor formats</a>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]889</div>
890
891<div class="doc_text">
892<p>
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]893The LLVM debugger expects the descriptors for program objects to start in a
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]894canonical format, but the descriptors can include additional information
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]895appended at the end that is source-language specific. All LLVM debugging
896information is versioned, allowing backwards compatibility in the case that the
897core structures need to change in some way. Also, all debugging information
898objects start with a <a href="#format_common_tags">tag</a> to indicate what type
899of object it is. The source-language is allows to define its own objects, by
900using unreserved tag numbers.</p>
901
902<p>The lowest-level descriptor are those describing <a
903href="#format_common_source_files">the files containing the program source
904code</a>, as most other descriptors (sometimes indirectly) refer to them.
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]905</p>
906</div>
907
908
909<!----------------------------------------------------------------------------->
910<div class="doc_subsubsection">
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]911 <a name="format_common_source_files">Representation of source files</a>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]912</div>
913
914<div class="doc_text">
915<p>
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]916Source file descriptors are patterned after the Dwarf "compile_unit" object.
917The descriptor currently is defined to have at least the following LLVM
918type entries:</p>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]919
920<p><pre>
921%lldb.compile_unit = type {
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]922 uint, <i>;; Tag: <a href="#tag_compile_unit">LLVM_COMPILE_UNIT</a></i>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]923 ushort, <i>;; LLVM debug version number</i>
924 ushort, <i>;; Dwarf language identifier</i>
925 sbyte*, <i>;; Filename</i>
926 sbyte*, <i>;; Working directory when compiled</i>
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]927 sbyte* <i>;; Producer of the debug information</i>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]928}
929</pre></p>
930
931<p>
932These descriptors contain the version number for the debug info, a source
933language ID for the file (we use the Dwarf 3.0 ID numbers, such as
934<tt>DW_LANG_C89</tt>, <tt>DW_LANG_C_plus_plus</tt>, <tt>DW_LANG_Cobol74</tt>,
935etc), three strings describing the filename, working directory of the compiler,
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]936and an identifier string for the compiler that produced it. Note that actual
937compile_unit declarations must also include an <a
938href="#format_common_anchors">anchor</a> to <tt>llvm.dbg.translation_units</tt>,
939but it is not specified where the anchor is to be located. Here is an example
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]940descriptor:
941</p>
942
943<p><pre>
944%arraytest_source_file = internal constant %lldb.compile_unit {
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]945 <a href="#tag_compile_unit">uint 17</a>, ; Tag value
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]946 ushort 0, ; Version #0
947 ushort 1, ; DW_LANG_C89
948 sbyte* getelementptr ([12 x sbyte]* %.str_1, long 0, long 0), ; filename
949 sbyte* getelementptr ([12 x sbyte]* %.str_2, long 0, long 0), ; working dir
950 sbyte* getelementptr ([12 x sbyte]* %.str_3, long 0, long 0), ; producer
951 {}* %llvm.dbg.translation_units ; Anchor
952}
953%.str_1 = internal constant [12 x sbyte] c"arraytest.c\00"
954%.str_2 = internal constant [12 x sbyte] c"/home/sabre\00"
955%.str_3 = internal constant [12 x sbyte] c"llvmgcc 3.4\00"
956</pre></p>
957
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]958<p>
959Note that the LLVM constant merging pass should eliminate duplicate copies of
960the strings that get emitted to each translation unit, such as the producer.
961</p>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]962
963</div>
964
965
966<!----------------------------------------------------------------------------->
967<div class="doc_subsubsection">
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]968 <a name="format_program_objects">Representation of program objects</a>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]969</div>
970
971<div class="doc_text">
972<p>
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]973The LLVM debugger needs to know about some source-language program objects, in
974order to build stack traces, print information about local variables, and other
975related activities. The LLVM debugger differentiates between three different
976types of program objects: subprograms (functions, messages, methods, etc),
977variables (locals and globals), and others. Because source-languages have
978widely varying forms of these objects, the LLVM debugger expects only a few
979fields in the descriptor for each object:
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]980</p>
981
982<p><pre>
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]983%lldb.object = type {
984 uint, <i>;; <a href="#format_common_tag">A tag</a></i>
985 <i>any</i>*, <i>;; The <a href="#format_common_object_contexts">context</a> for the object</i>
986 sbyte* <i>;; The object 'name'</i>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]987}
988</pre></p>
989
990<p>
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]991The first field contains a tag for the descriptor. The second field contains
992either a pointer to the descriptor for the containing <a
993href="#format_common_source_files">source file</a>, or it contains a pointer to
994another program object whose context pointer eventually reaches a source file.
995Through this <a href="#format_common_object_contexts">context</a> pointer, the
996LLVM debugger can establish the debug version number of the object.</p>
997
998<p>
999The third field contains a string that the debugger can use to identify the
1000object if it does not contain explicit support for the source-language in use
1001(ie, the 'unknown' source language handler uses this string). This should be
1002some sort of unmangled string that corresponds to the object, but it is a
1003quality of implementation issue what exactly it contains (it is legal, though
1004not useful, for all of these strings to be null).
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]1005</p>
1006
1007<p>
1008Note again that descriptors can be extended to include source-language-specific
1009information in addition to the fields required by the LLVM debugger. See the <a
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]1010href="#ccxx_descriptors">section on the C/C++ front-end</a> for more
1011information. Also remember that global objects (functions, selectors, global
1012variables, etc) must contain an <a href="format_common_anchors">anchor</a> to
1013the <tt>llvm.dbg.globals</tt> variable.
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]1014</p>
1015</div>
1016
1017
1018<!-- ======================================================================= -->
1019<div class="doc_subsection">
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]1020 <a name="format_common_object_contexts">Program object contexts</a>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]1021</div>
1022
1023<div class="doc_text">
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]1024<p><pre>
1025Allow source-language specific contexts, use to identify namespaces etc
1026Must end up in a source file descriptor.
1027Debugger core ignores all unknown context objects.
1028</pre></p>
1029</div>
1030
1031
1032
1033<!-- ======================================================================= -->
1034<div class="doc_subsection">
1035 <a name="format_common_intrinsics">Debugger intrinsic functions</a>
1036</div>
1037
1038<div class="doc_text">
1039<p><pre>
1040Define each intrinsics, as an extension of the language reference manual.
1041
1042llvm.dbg.stoppoint
1043llvm.dbg.region.start
1044llvm.dbg.region.end
1045llvm.dbg.function.start
1046llvm.dbg.declare
1047</pre></p>
1048</div>
1049
1050
1051
1052<!-- ======================================================================= -->
1053<div class="doc_subsection">
1054 <a name="format_common_tags">Values for debugger tags</a>
1055</div>
1056
1057<div class="doc_text">
1058
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]1059<p>
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]1060Happen to be the same value as the similarly named Dwarf-3 tags, this may change
1061in the future.
1062</p>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]1063
1064</p>
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]1065<p><pre>
1066 <a name="tag_compile_unit">LLVM_COMPILE_UNIT</a> : 17
1067 <a name="tag_subprogram">LLVM_SUBPROGRAM</a> : 46
1068 <a name="tag_variable">LLVM_VARIABLE</a> : 52
1069<!-- <a name="tag_formal_parameter">LLVM_FORMAL_PARAMETER : 5-->
1070</pre></p>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]1071</div>
1072
1073
1074
1075<!-- *********************************************************************** -->
1076<div class="doc_section">
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]1077 <a name="ccxx_frontend">C/C++ front-end specific debug information</a>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]1078</div>
1079
1080<div class="doc_text">
1081
1082<p>
1083The C and C++ front-ends represent information about the program in a format
1084that is effectively identical to <a
1085href="http://www.eagercon.com/dwarf/dwarf3std.htm">Dwarf 3.0</a> in terms of
1086information content. This allows code generators to trivially support native
1087debuggers by generating standard dwarf information, and contains enough
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]1088information for non-dwarf targets to translate it as needed.</p>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]1089
1090<p>
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]1091The basic debug information required by the debugger is (intentionally) designed
1092to be as minimal as possible. This basic information is so minimal that it is
1093unlikely that <b>any</b> source-language could be adequately described by it.
1094Because of this, the debugger format was designed for extension to support
1095source-language-specific information. The extended descriptors are read and
1096interpreted by the <a href="#arch_info">language-specific</a> modules in the
1097debugger if there is support available, otherwise it is ignored.
1098</p>
1099
1100<p>
1101This section describes the extensions used to represent C and C++ programs.
1102Other languages could pattern themselves after this (which itself is tuned to
1103representing programs in the same way that Dwarf 3 does), or they could choose
1104to provide completely different extensions if they don't fit into the Dwarf
1105model. As support for debugging information gets added to the various LLVM
1106source-language front-ends, the information used should be documented here.
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]1107</p>
1108
1109</div>
1110
1111<!-- ======================================================================= -->
1112<div class="doc_subsection">
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]1113 <a name="ccxx_pse">Program Scope Entries</a>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]1114</div>
1115
1116<div class="doc_text">
1117<p>
1118
1119</p>
1120</div>
1121
Chris Lattner8ff75902004-01-06 05:31:32 +0000[diff] [blame^]1122<!----------------------------------------------------------------------------->
1123<div class="doc_subsubsection">
1124 <a name="ccxx_compilation_units">Compilation unit entries</a>
1125</div>
1126
1127<div class="doc_text">
1128<p>
1129Translation units do not add any information over the standard <a
1130href="#format_common_source_files">source file representation</a> already
1131expected by the debugger. As such, it uses descriptors of the type specified,
1132with a trailing <a href="#format_common_anchors">anchor</a>.
1133</p>
1134</div>
1135
1136<!----------------------------------------------------------------------------->
1137<div class="doc_subsubsection">
1138 <a name="ccxx_modules">Module, namespace, and importing entries</a>
1139</div>
1140
1141<div class="doc_text">
1142<p>
1143
1144</p>
1145</div>
1146
1147<!-- ======================================================================= -->
1148<div class="doc_subsection">
1149 <a name="ccxx_dataobjects">Data objects (program variables)</a>
1150</div>
1151
1152<div class="doc_text">
1153<p>
1154
1155</p>
1156</div>
Chris Lattnerbdfb3392004-01-05 05:06:33 +0000[diff] [blame]1157
1158
1159<!-- *********************************************************************** -->
1160<hr>
1161<div class="doc_footer">
1162 <address><a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
1163 <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a>
1164 <br>
1165 Last modified: $Date$
1166</div>
1167
1168</body>
1169</html>