[llvm-commits] CVS: llvm/docs/SourceLevelDebugging.html
Jim Laskey
jlaskey at apple.com
Thu Mar 23 09:54:45 PST 2006
Changes in directory llvm/docs:
SourceLevelDebugging.html updated: 1.15 -> 1.16
---
Log message:
Updated information related to local variables and scopes.
---
Diffs of the changes: (+106 -34)
SourceLevelDebugging.html | 140 ++++++++++++++++++++++++++++++++++------------
1 files changed, 106 insertions(+), 34 deletions(-)
Index: llvm/docs/SourceLevelDebugging.html
diff -u llvm/docs/SourceLevelDebugging.html:1.15 llvm/docs/SourceLevelDebugging.html:1.16
--- llvm/docs/SourceLevelDebugging.html:1.15 Wed Mar 15 13:10:52 2006
+++ llvm/docs/SourceLevelDebugging.html Thu Mar 23 11:54:33 2006
@@ -16,6 +16,7 @@
<li><a href="#introduction">Introduction</a>
<ol>
<li><a href="#phil">Philosophy behind LLVM debugging information</a></li>
+ <li><a href="#consumers">Debug information consumers</a></li>
<li><a href="#debugopt">Debugging optimized code</a></li>
</ol></li>
<li><a href="#format">Debugging information format</a>
@@ -32,6 +33,7 @@
<li><a href="#format_composite_type">Composite type descriptors</a></li>
<li><a href="#format_subrange">Subrange descriptors</a></li>
<li><a href="#format_enumeration">Enumerator descriptors</a></li>
+ <li><a href="#format_variables">Local variables</a></li>
</ul></li>
<li><a href="#format_common_intrinsics">Debugger intrinsic functions</a>
<ul>
@@ -134,6 +136,29 @@
<!-- ======================================================================= -->
<div class="doc_subsection">
+ <a name="consumers">Debug information consumers</a>
+</div>
+
+<div class="doc_text">
+<p>The role of debug information is to provide meta information normally
+stripped away during the compilation process. This meta information provides an
+llvm user a relationship between generated code and the original program source
+code.</p>
+
+<p>Currently, debug information is consumed by the DwarfWriter to produce dwarf
+information used by the gdb debugger. Other targets could use the same
+information to produce stabs or other debug forms.</p>
+
+<p>It would also be reasonable to use debug information to feed profiling tools
+for analysis of generated code, or, tools for reconstructing the original source
+from generated code.</p>
+
+<p>TODO - expound a bit more.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
<a name="debugopt">Debugging optimized code</a>
</div>
@@ -248,12 +273,13 @@
<p>Consumers of LLVM debug information expect the descriptors for program
objects to start in a canonical format, but the descriptors can include
-additional information appended at the end that is source-language specific.
-All LLVM debugging information is versioned, allowing backwards compatibility in
-the case that the core structures need to change in some way. Also, all
-debugging information objects start with a tag to indicate what type of object
-it is. The source-language is allowed to define its own objects, by using
-unreserved tag numbers.</p>
+additional information appended at the end that is source-language specific. All
+LLVM debugging information is versioned, allowing backwards compatibility in the
+case that the core structures need to change in some way. Also, all debugging
+information objects start with a tag to indicate what type of object it is. The
+source-language is allowed to define its own objects, by using unreserved tag
+numbers. We recommend using with tags in the range 0x1000 thru 0x2000 (there is
+a defined enum DW_TAG_user_base = 0x1000.)</p>
<p>The fields of debug descriptors used internally by LLVM (MachineDebugInfo)
are restricted to only the simple data types <tt>int</tt>, <tt>uint</tt>,
@@ -328,7 +354,7 @@
%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> = type {
uint, ;; Tag = 17 (DW_TAG_compile_unit)
{ }*, ;; Compile unit anchor = cast = (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_units</a> to { }*)
- uint, ;; LLVM debug version number = 2
+ uint, ;; LLVM debug version number = 3
uint, ;; Dwarf language identifier (ex. DW_LANG_C89)
sbyte*, ;; Source file name
sbyte*, ;; Source file directory (includes trailing slash)
@@ -337,7 +363,7 @@
</pre>
<p>These descriptors contain the version number for the debug info (currently
-2), a source language ID for the file (we use the Dwarf 3.0 ID numbers, such as
+3), a source language ID for the file (we use the Dwarf 3.0 ID numbers, such as
<tt>DW_LANG_C89</tt>, <tt>DW_LANG_C_plus_plus</tt>, <tt>DW_LANG_Cobol74</tt>,
etc), three strings describing the filename, working directory of the compiler,
and an identifier string for the compiler that produced it.</p>
@@ -363,7 +389,7 @@
{ }*, ;; Reference to context descriptor
sbyte*, ;; Name
{ }*, ;; Reference to compile unit where defined
- int, ;; Line number where defined
+ uint, ;; Line number where defined
{ }*, ;; Reference to type descriptor
bool, ;; True if the global is local to compile unit (static)
bool, ;; True if the global is defined in the compile unit (not extern)
@@ -390,20 +416,16 @@
{ }*, ;; Reference to context descriptor
sbyte*, ;; Name
{ }*, ;; Reference to compile unit where defined
- int, ;; Line number where defined
+ uint, ;; Line number where defined
{ }*, ;; Reference to type descriptor
bool, ;; True if the global is local to compile unit (static)
- bool, ;; True if the global is defined in the compile unit (not extern)
- { }* ;; Reference to array of member descriptors
+ bool ;; True if the global is defined in the compile unit (not extern)
}
</pre>
<p>These descriptors provide debug information about functions, methods and
-subprograms. The provide details such as name, return and argument types and
-where the subprogram is defined.</p>
-
-<p>The array of member descriptors is used to define arguments local variables
-and nested blocks.</p>
+subprograms. They provide details such as name, return types and the source
+location where the subprogram is defined.</p>
</div>
<!-- ======================================================================= -->
@@ -416,7 +438,7 @@
<pre>
%<a href="#format_blocks">llvm.dbg.block</a> = type {
uint, ;; Tag = 13 (DW_TAG_lexical_block)
- { }* ;; Reference to array of member descriptors
+ { }* ;; Reference to context descriptor
}
</pre>
@@ -439,7 +461,7 @@
{ }*, ;; Reference to context (typically a compile unit)
sbyte*, ;; Name (may be "" for anonymous types)
{ }*, ;; Reference to compile unit where defined (may be NULL)
- int, ;; Line number where defined (may be 0)
+ uint, ;; Line number where defined (may be 0)
uint, ;; Size in bits
uint, ;; Alignment in bits
uint, ;; Offset in bits
@@ -485,7 +507,7 @@
{ }*, ;; Reference to context
sbyte*, ;; Name (may be "" for anonymous types)
{ }*, ;; Reference to compile unit where defined (may be NULL)
- int, ;; Line number where defined (may be 0)
+ uint, ;; Line number where defined (may be 0)
uint, ;; Size in bits
uint, ;; Alignment in bits
uint, ;; Offset in bits
@@ -549,7 +571,7 @@
{ }*, ;; Reference to context
sbyte*, ;; Name (may be "" for anonymous types)
{ }*, ;; Reference to compile unit where defined (may be NULL)
- int, ;; Line number where defined (may be 0)
+ uint, ;; Line number where defined (may be 0)
uint, ;; Size in bits
uint, ;; Alignment in bits
uint, ;; Offset in bits
@@ -638,6 +660,44 @@
</div>
<!-- ======================================================================= -->
+<div class="doc_subsubsection">
+ <a name="format_variables">Local variables</a>
+</div>
+
+<div class="doc_text">
+<pre>
+ %<a href="#format_variables">llvm.dbg.variable.type</a> = type {
+ uint, ;; Tag (see below)
+ { }*, ;; Context
+ sbyte*, ;; Name
+ { }*, ;; Reference to compile unit where defined
+ uint, ;; Line number where defined
+ { }* ;; Type descriptor
+ }
+</pre>
+
+<p>These descriptors are used to define variables local to a sub program. The
+value of the tag depends on the usage of the variable;</p>
+
+<pre>
+ DW_TAG_auto_variable = 256
+ DW_TAG_arg_variable = 257
+ DW_TAG_return_variable = 258
+</pre>
+
+<p>An auto variable is any variable declared in the body of the function. An
+argument variable is any variable that appears as a formal argument to the
+function. A return variable is used to track the result of a function and has
+no source correspondent.</p>
+
+<p>The context is eitehr the subprogram or block where the variable is defined.
+Name the source variable name. Compile unit and line indicate where the
+variable was defined. Type descriptor defines the declared type of the
+variable.</p>
+
+</div>
+
+<!-- ======================================================================= -->
<div class="doc_subsection">
<a name="format_common_intrinsics">Debugger intrinsic functions</a>
</div>
@@ -664,7 +724,8 @@
argument si the column number (0 if unknown) and the third argument the source
compile unit. Code following a call to this intrinsic will have been defined in
close proximity of the line, column and file. This information holds until the
-next call to <a href="#format_common_stoppoint">lvm.dbg.stoppoint</a>.</p>
+next call to <tt>%<a
+href="#format_common_stoppoint">lvm.dbg.stoppoint</a></tt>.</p>
</div>
@@ -675,14 +736,17 @@
<div class="doc_text">
<pre>
- void %<a href="#format_common_func_start">llvm.dbg.func.start</a>( %<a href="#format_subprograms">llvm.dbg.subprogram.type</a>* )
+ void %<a href="#format_common_func_start">llvm.dbg.func.start</a>( { }* )
</pre>
<p>This intrinsic is used to link the debug information in <tt>%<a
href="#format_subprograms">llvm.dbg.subprogram</a></tt> to the function. It also
defines the beginning of the function's declarative region (scope.) The
intrinsic should be called early in the function after the all the alloca
-instructions.</p>
+instructions. It should be paired off with a closing <tt>%<a
+href="#format_common_region_end">llvm.dbg.region.end</a></tt>. The function's
+single argument is the <tt>%<a
+href="#format_subprograms">llvm.dbg.subprogram.type</a></tt>.</p>
</div>
@@ -693,12 +757,15 @@
<div class="doc_text">
<pre>
- void %<a href="#format_common_region_start">llvm.dbg.region.start</a>()
+ void %<a href="#format_common_region_start">llvm.dbg.region.start</a>( { }* )
</pre>
<p>This intrinsic is used to define the beginning of a declarative scope (ex.
block) for local language elements. It should be paired off with a closing
-<tt>%<a href="#format_common_region_end">llvm.dbg.region.end</a></tt>.</p>
+<tt>%<a href="#format_common_region_end">llvm.dbg.region.end</a></tt>. The
+function's single argument is the <tt>%<a
+href="#format_blocks">llvm.dbg.block</a></tt> which is starting.</p>
+
</div>
@@ -709,13 +776,17 @@
<div class="doc_text">
<pre>
- void %<a href="#format_common_region_end">llvm.dbg.region.end</a>()
+ void %<a href="#format_common_region_end">llvm.dbg.region.end</a>( { }* )
</pre>
<p>This intrinsic is used to define the end of a declarative scope (ex. block)
for local language elements. It should be paired off with an opening <tt>%<a
href="#format_common_region_start">llvm.dbg.region.start</a></tt> or <tt>%<a
-href="#format_common_func_start">llvm.dbg.func.start</a></tt>.</p>
+href="#format_common_func_start">llvm.dbg.func.start</a></tt>. The function's
+single argument is either the <tt>%<a
+href="#format_blocks">llvm.dbg.block</a></tt> or the <tt>%<a
+href="#format_subprograms">llvm.dbg.subprogram.type</a></tt> which is
+ending.</p>
</div>
@@ -726,11 +797,13 @@
<div class="doc_text">
<pre>
- void %<a href="#format_common_declare">llvm.dbg.declare</a>( {} *, ... )
+ void %<a href="#format_common_declare">llvm.dbg.declare</a>( { } *, { }* )
</pre>
<p>This intrinsic provides information about a local element (ex. variable.)
-TODO - details.</p>
+The first argument as a AllocA for the variable cast to a <tt>{ }*</tt>. The second
+argument is the <tt>%<a href="#format_variables">llvm.dbg.variable</a></tt>
+containing the description of the variable, also cast to a <tt>{ }*</tt>.</p>
</div>
@@ -1097,7 +1170,7 @@
;; descriptor, one for the global's basic type and one for the subprogram's
;; compile unit.
;;
-%<a href="#format_subprograms">llvm.dbg.subprogram.type</a> = type { uint, { }*, { }*, sbyte*, { }*, bool, bool, { }* }
+%<a href="#format_subprograms">llvm.dbg.subprogram.type</a> = type { uint, { }*, { }*, sbyte*, { }*, bool, bool }
%<a href="#format_anchors">llvm.dbg.anchor.type</a> = type { uint, uint }
%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> = ...
@@ -1120,8 +1193,7 @@
uint 1,
{ }* null,
bool false,
- bool true,
- null }, section "llvm.metadata"
+ bool true }, section "llvm.metadata"
;;
;; Define the name of the subprogram.
@@ -1671,7 +1743,7 @@
<a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
<a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
- Last modified: $Date: 2006/03/15 19:10:52 $
+ Last modified: $Date: 2006/03/23 17:54:33 $
</address>
</body>
More information about the llvm-commits
mailing list