<div class="doc_author">
<p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>
- and <a href="mailto:jlaskey@apple.com">Jim Laskey</a></p>
+ and <a href="mailto:jlaskey@mac.com">Jim Laskey</a></p>
</div>
<p>When a program is being debugged, a debugger interacts with the user and
turns the stored debug information into source-language specific information.
As such, a debugger must be aware of the source-language, and is thus tied to
-a specific language of family of languages.</p>
+a specific language or family of languages.</p>
</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
+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
have been run, and without any modification to the optimizations themselves.
However, some optimizations may impact the ability to modify the current state
of the program with a debugger, such as setting program variables, or calling
-function that have been deleted.</li>
+functions that have been deleted.</li>
<li>LLVM optimizations gracefully interact with debugging information. If they
are not aware of debug information, they are automatically disabled as necessary
in the cases that would invalidate the debug info. This retains the LLVM
-features making it easy to write new transformations.</li>
+features, making it easy to write new transformations.</li>
<li>As desired, LLVM optimizations can be upgraded to be aware of the LLVM
debugging information, allowing them to update the debugging information as they
and call functions where were optimized out of the program, or inlined away
completely.</p>
+<p><a href="TestingGuide.html#quicktestsuite">LLVM test suite</a> provides a
+framework to test optimizer's handling of debugging information. It can be run
+like this:</p>
+
+<div class="doc_code">
+<pre>
+% cd llvm/projects/test-suite/MultiSource/Benchmarks # or some other level
+% make TEST=dbgopt
+</pre>
+</div>
+
+<p>
+This will test impact of debugging information on optimization passes. If
+debugging information influences optimization passes then it will be reported
+as a failure. See <a href="TestingGuide.html">TestingGuide</a>
+for more information on LLVM test infrastructure and how to run various tests.
+</p>
+
</div>
<!-- *********************************************************************** -->
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)
+<p>The fields of debug descriptors used internally by LLVM (MachineModuleInfo)
are restricted to only the simple data types <tt>int</tt>, <tt>uint</tt>,
<tt>bool</tt>, <tt>float</tt>, <tt>double</tt>, <tt>sbyte*</tt> and <tt> { }*
</tt>. References to arbitrary values are handled using a <tt> { }* </tt> and a
sbyte*, ;; Source file name
sbyte*, ;; Source file directory (includes trailing slash)
sbyte* ;; Producer (ex. "4.0.1 LLVM (LLVM research group)")
+ bool ;; True if this is a main compile unit.
}
</pre>
using this context. Compile unit descriptors also provide context for source
line correspondence.</p>
+<p> Each input file is encoded as a separate compile unit in LLVM debugging
+information output. However, many target specific tool chains prefer to encode
+only one compile unit in an object file. In this situation, the LLVM code
+generator will include debugging information entities in the compile unit
+that is marked as main compile unit. The code generator accepts maximum one main
+compile unit per module. If a module does not contain any main compile unit
+then the code generator will emit multiple compile units in the output object
+file.
</div>
<!-- ======================================================================= -->
type</a>.</p>
<p>The type encoding provides the details of the type. The values are typically
-one of the following;</p>
+one of the following:</p>
<pre>
DW_ATE_address = 1
<p>These descriptors are used to define types derived from other types. The
value of the tag varies depending on the meaning. The following are possible
-tag values;</p>
+tag values:</p>
<pre>
DW_TAG_formal_parameter = 5
<p>These descriptors are used to define types that are composed of 0 or more
elements. The value of the tag varies depending on the meaning. The following
-are possible tag values;</p>
+are possible tag values:</p>
<pre>
DW_TAG_array_type = 1
</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>
+value of the tag depends on the usage of the variable:</p>
<pre>
DW_TAG_auto_variable = 256
<p>This intrinsic is used to provide correspondence between the source file and
the generated code. The first argument is the line number (base 1), second
-argument si the column number (0 if unknown) and the third argument the source
+argument is the column number (0 if unknown) and the third argument the source
<tt>%<a href="#format_compile_units">llvm.dbg.compile_unit</a>*</tt> cast to a
<tt>{ }*</tt>. Code following a call to this intrinsic will have been defined
in close proximity of the line, column and file. This information holds until
</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. It should be paired off with a closing <tt>%<a
+href="#format_subprograms">llvm.dbg.subprogram</a></tt> to the function. It
+defines the beginning of the function's declarative region (scope). It also
+implies a call to %<tt><a
+href="#format_common_stoppoint">llvm.dbg.stoppoint</a></tt> which defines a
+source line "stop point". The intrinsic should be called early in the function
+after the all the alloca 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>
<p>It is worth noting that this scoping mechanism is used to control scoping of
all declarations, not just variable declarations. For example, the scope of a
-C++ using declaration is controlled with this couldchange how name lookup is
+C++ using declaration is controlled with this and could change how name lookup is
performed.</p>
</div>
<div class="doc_text">
<p>Given the source files "MySource.cpp" and "MyHeader.h" located in the
-directory "/Users/mine/sources", the following code;</p>
+directory "/Users/mine/sources", the following code:</p>
<pre>
#include "MyHeader.h"
}
</pre>
-<p>a C/C++ front-end would generate the following descriptors;</p>
+<p>a C/C++ front-end would generate the following descriptors:</p>
<pre>
...
<div class="doc_text">
-<p>Given an integer global variable declared as follows;</p>
+<p>Given an integer global variable declared as follows:</p>
<pre>
int MyGlobal = 100;
</pre>
-<p>a C/C++ front-end would generate the following descriptors;</p>
+<p>a C/C++ front-end would generate the following descriptors:</p>
<pre>
;;
<div class="doc_text">
-<p>Given a function declared as follows;</p>
+<p>Given a function declared as follows:</p>
<pre>
int main(int argc, char *argv[]) {
}
</pre>
-<p>a C/C++ front-end would generate the following descriptors;</p>
+<p>a C/C++ front-end would generate the following descriptors:</p>
<pre>
;;
<div class="doc_text">
-<p>The following are the basic type descriptors for C/C++ core types;</p>
+<p>The following are the basic type descriptors for C/C++ core types:</p>
</div>
<div class="doc_text">
-<p>Given the following as an example of C/C++ derived type;</p>
+<p>Given the following as an example of C/C++ derived type:</p>
<pre>
typedef const int *IntPtr;
</pre>
-<p>a C/C++ front-end would generate the following descriptors;</p>
+<p>a C/C++ front-end would generate the following descriptors:</p>
<pre>
;;
<div class="doc_text">
-<p>Given the following as an example of C/C++ struct type;</p>
+<p>Given the following as an example of C/C++ struct type:</p>
<pre>
struct Color {
};
</pre>
-<p>a C/C++ front-end would generate the following descriptors;</p>
+<p>a C/C++ front-end would generate the following descriptors:</p>
<pre>
;;
<div class="doc_text">
-<p>Given the following as an example of C/C++ enumeration type;</p>
+<p>Given the following as an example of C/C++ enumeration type:</p>
<pre>
enum Trees {
};
</pre>
-<p>a C/C++ front-end would generate the following descriptors;</p>
+<p>a C/C++ front-end would generate the following descriptors:</p>
<pre>
;;
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
- src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
- src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
<a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
projects / oota-llvm.git / blobdiff