[llvm-branch-commits] [llvm-branch] r90177 - /llvm/branches/Apple/Zoidberg/docs/SourceLevelDebugging.html
Devang Patel
dpatel at apple.com
Mon Nov 30 16:15:56 PST 2009
Author: dpatel
Date: Mon Nov 30 18:15:56 2009
New Revision: 90177
URL: http://llvm.org/viewvc/llvm-project?rev=90177&view=rev
Log:
Merge r89896 from trunk.
Modified:
llvm/branches/Apple/Zoidberg/docs/SourceLevelDebugging.html
Modified: llvm/branches/Apple/Zoidberg/docs/SourceLevelDebugging.html
URL: http://llvm.org/viewvc/llvm-project/llvm/branches/Apple/Zoidberg/docs/SourceLevelDebugging.html?rev=90177&r1=90176&r2=90177&view=diff
==============================================================================
--- llvm/branches/Apple/Zoidberg/docs/SourceLevelDebugging.html (original)
+++ llvm/branches/Apple/Zoidberg/docs/SourceLevelDebugging.html Mon Nov 30 18:15:56 2009
@@ -37,15 +37,10 @@
</ul></li>
<li><a href="#format_common_intrinsics">Debugger intrinsic functions</a>
<ul>
- <li><a href="#format_common_stoppoint">llvm.dbg.stoppoint</a></li>
- <li><a href="#format_common_func_start">llvm.dbg.func.start</a></li>
- <li><a href="#format_common_region_start">llvm.dbg.region.start</a></li>
- <li><a href="#format_common_region_end">llvm.dbg.region.end</a></li>
<li><a href="#format_common_declare">llvm.dbg.declare</a></li>
</ul></li>
- <li><a href="#format_common_stoppoints">Representing stopping points in the
- source program</a></li>
</ol></li>
+ <li><a href="#format_common_lifetime">Object lifetimes and scoping</a></li>
<li><a href="#ccxx_frontend">C/C++ front-end specific debug information</a>
<ol>
<li><a href="#ccxx_compile_units">C/C++ source file information</a></li>
@@ -763,92 +758,6 @@
<!-- ======================================================================= -->
<div class="doc_subsubsection">
- <a name="format_common_stoppoint">llvm.dbg.stoppoint</a>
-</div>
-
-<div class="doc_text">
-<pre>
- void %<a href="#format_common_stoppoint">llvm.dbg.stoppoint</a>( uint, uint, metadata)
-</pre>
-
-<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 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>.
- 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 <tt>%<a href="#format_common_stoppoint">lvm.dbg.stoppoint</a></tt>.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<div class="doc_subsubsection">
- <a name="format_common_func_start">llvm.dbg.func.start</a>
-</div>
-
-<div class="doc_text">
-<pre>
- void %<a href="#format_common_func_start">llvm.dbg.func.start</a>( metadata )
-</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 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>
-
-</div>
-
-<!-- ======================================================================= -->
-<div class="doc_subsubsection">
- <a name="format_common_region_start">llvm.dbg.region.start</a>
-</div>
-
-<div class="doc_text">
-<pre>
- void %<a href="#format_common_region_start">llvm.dbg.region.start</a>( metadata )
-</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>. The
- function's single argument is
- the <tt>%<a href="#format_blocks">llvm.dbg.block</a></tt> which is
- starting.</p>
-
-
-</div>
-
-<!-- ======================================================================= -->
-<div class="doc_subsubsection">
- <a name="format_common_region_end">llvm.dbg.region.end</a>
-</div>
-
-<div class="doc_text">
-<pre>
- void %<a href="#format_common_region_end">llvm.dbg.region.end</a>( metadata )
-</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>.
- 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>
-
-<!-- ======================================================================= -->
-<div class="doc_subsubsection">
<a name="format_common_declare">llvm.dbg.declare</a>
</div>
@@ -867,40 +776,6 @@
<!-- ======================================================================= -->
<div class="doc_subsection">
- <a name="format_common_stoppoints">
- Representing stopping points in the source program
- </a>
-</div>
-
-<div class="doc_text">
-
-<p>LLVM debugger "stop points" are a key part of the debugging representation
- that allows the LLVM to maintain simple semantics
- for <a href="#debugopt">debugging optimized code</a>. The basic idea is that
- the front-end inserts calls to
- the <a href="#format_common_stoppoint">%<tt>llvm.dbg.stoppoint</tt></a>
- intrinsic function at every point in the program where a debugger should be
- able to inspect the program (these correspond to places a debugger stops when
- you "<tt>step</tt>" through it). The front-end can choose to place these as
- fine-grained as it would like (for example, before every subexpression
- evaluated), but it is recommended to only put them after every source
- statement that includes executable code.</p>
-
-<p>Using calls to this intrinsic function to demark legal points for the
- debugger to inspect the program automatically disables any optimizations that
- could potentially confuse debugging information. To
- non-debug-information-aware transformations, these calls simply look like
- calls to an external function, which they must assume to do anything
- (including reading or writing to any part of reachable memory). On the other
- hand, it does not impact many optimizations, such as code motion of
- non-trapping instructions, nor does it impact optimization of subexpressions,
- code duplication transformations, or basic-block reordering
- transformations.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<div class="doc_subsection">
<a name="format_common_lifetime">Object lifetimes and scoping</a>
</div>
@@ -914,21 +789,20 @@
scoping in this sense, and does not want to be tied to a language's scoping
rules.</p>
-<p>In order to handle this, the LLVM debug format uses the notion of "regions"
- of a function, delineated by calls to intrinsic functions. These intrinsic
- functions define new regions of the program and indicate when the region
- lifetime expires. Consider the following C fragment, for example:</p>
+<p>In order to handle this, the LLVM debug format uses the metadata attached
+ with llvm instructions to encode line nuber and scoping information.
+ Consider the following C fragment, for example:</p>
<div class="doc_code">
<pre>
1. void foo() {
-2. int X = ...;
-3. int Y = ...;
+2. int X = 21;
+3. int Y = 22;
4. {
-5. int Z = ...;
-6. ...
+5. int Z = 23;
+6. Z = X;
7. }
-8. ...
+8. X = Y;
9. }
</pre>
</div>
@@ -937,99 +811,124 @@
<div class="doc_code">
<pre>
-void %foo() {
+nounwind ssp {
entry:
- %X = alloca int
- %Y = alloca int
- %Z = alloca int
-
- ...
-
- call void @<a href="#format_common_func_start">llvm.dbg.func.start</a>( metadata !0)
-
- call void @<a href="#format_common_stoppoint">llvm.dbg.stoppoint</a>( uint 2, uint 2, metadata !1)
-
- call void @<a href="#format_common_declare">llvm.dbg.declare</a>({}* %X, ...)
- call void @<a href="#format_common_declare">llvm.dbg.declare</a>({}* %Y, ...)
-
- <i>;; Evaluate expression on line 2, assigning to X.</i>
-
- call void @<a href="#format_common_stoppoint">llvm.dbg.stoppoint</a>( uint 3, uint 2, metadata !1)
-
- <i>;; Evaluate expression on line 3, assigning to Y.</i>
-
- call void @<a href="#format_common_stoppoint">llvm.region.start</a>()
- call void @<a href="#format_common_stoppoint">llvm.dbg.stoppoint</a>( uint 5, uint 4, metadata !1)
- call void @<a href="#format_common_declare">llvm.dbg.declare</a>({}* %X, ...)
-
- <i>;; Evaluate expression on line 5, assigning to Z.</i>
-
- call void @<a href="#format_common_stoppoint">llvm.dbg.stoppoint</a>( uint 7, uint 2, metadata !1)
- call void @<a href="#format_common_region_end">llvm.region.end</a>()
-
- call void @<a href="#format_common_stoppoint">llvm.dbg.stoppoint</a>( uint 9, uint 2, metadata !1)
-
- call void @<a href="#format_common_region_end">llvm.region.end</a>()
-
- ret void
-}
+ %X = alloca i32, align 4 ; <i32*> [#uses=4]
+ %Y = alloca i32, align 4 ; <i32*> [#uses=4]
+ %Z = alloca i32, align 4 ; <i32*> [#uses=3]
+ %0 = bitcast i32* %X to { }* ; <{ }*> [#uses=1]
+ call void @llvm.dbg.declare({ }* %0, metadata !0), !dbg !7
+ store i32 21, i32* %X, !dbg !8
+ %1 = bitcast i32* %Y to { }* ; <{ }*> [#uses=1]
+ call void @llvm.dbg.declare({ }* %1, metadata !9), !dbg !10
+ store i32 22, i32* %Y, !dbg !11
+ %2 = bitcast i32* %Z to { }* ; <{ }*> [#uses=1]
+ call void @llvm.dbg.declare({ }* %2, metadata !12), !dbg !14
+ store i32 23, i32* %Z, !dbg !15
+ %tmp = load i32* %X, !dbg !16 ; <i32> [#uses=1]
+ %tmp1 = load i32* %Y, !dbg !16 ; <i32> [#uses=1]
+ %add = add nsw i32 %tmp, %tmp1, !dbg !16 ; <i32> [#uses=1]
+ store i32 %add, i32* %Z, !dbg !16
+ %tmp2 = load i32* %Y, !dbg !17 ; <i32> [#uses=1]
+ store i32 %tmp2, i32* %X, !dbg !17
+ ret void, !dbg !18
+}
+
+declare void @llvm.dbg.declare({ }*, metadata) nounwind readnone
+
+!0 = metadata !{i32 459008, metadata !1, metadata !"X",
+ metadata !3, i32 2, metadata !6}; [ DW_TAG_auto_variable ]
+!1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ]
+!2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo", metadata !"foo",
+ metadata !"foo", metadata !3, i32 1, metadata !4,
+ i1 false, i1 true}; [DW_TAG_subprogram ]
+!3 = metadata !{i32 458769, i32 0, i32 12, metadata !"foo.c",
+ metadata !"/private/tmp", metadata !"clang 1.1", i1 true,
+ i1 false, metadata !"", i32 0}; [DW_TAG_compile_unit ]
+!4 = metadata !{i32 458773, metadata !3, metadata !"", null, i32 0, i64 0, i64 0,
+ i64 0, i32 0, null, metadata !5, i32 0}; [DW_TAG_subroutine_type ]
+!5 = metadata !{null}
+!6 = metadata !{i32 458788, metadata !3, metadata !"int", metadata !3, i32 0,
+ i64 32, i64 32, i64 0, i32 0, i32 5}; [DW_TAG_base_type ]
+!7 = metadata !{i32 2, i32 7, metadata !1, null}
+!8 = metadata !{i32 2, i32 3, metadata !1, null}
+!9 = metadata !{i32 459008, metadata !1, metadata !"Y", metadata !3, i32 3,
+ metadata !6}; [ DW_TAG_auto_variable ]
+!10 = metadata !{i32 3, i32 7, metadata !1, null}
+!11 = metadata !{i32 3, i32 3, metadata !1, null}
+!12 = metadata !{i32 459008, metadata !13, metadata !"Z", metadata !3, i32 5,
+ metadata !6}; [ DW_TAG_auto_variable ]
+!13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ]
+!14 = metadata !{i32 5, i32 9, metadata !13, null}
+!15 = metadata !{i32 5, i32 5, metadata !13, null}
+!16 = metadata !{i32 6, i32 5, metadata !13, null}
+!17 = metadata !{i32 8, i32 3, metadata !1, null}
+!18 = metadata !{i32 9, i32 1, metadata !2, null}
</pre>
</div>
<p>This example illustrates a few important details about the LLVM debugging
- information. In particular, it shows how the various intrinsics are applied
+ information. In particular, it shows how the llvm.dbg.declare intrinsic
+ and location information, attached with an instruction, are applied
together to allow a debugger to analyze the relationship between statements,
variable definitions, and the code used to implement the function.</p>
-<p>The first
- intrinsic <tt>%<a href="#format_common_func_start">llvm.dbg.func.start</a></tt>
- provides a link with the <a href="#format_subprograms">subprogram
- descriptor</a> containing the details of this function. This call also
- defines the beginning of the function region, bounded by
- the <tt>%<a href="#format_common_region_end">llvm.region.end</a></tt> at the
- end of the function. This region is used to bracket the lifetime of
- variables declared within. For a function, this outer region defines a new
- stack frame whose lifetime ends when the region is ended.</p>
-
-<p>It is possible to define inner regions for short term variables by using the
- %<a href="#format_common_stoppoint"><tt>llvm.region.start</tt></a>
- and <a href="#format_common_region_end"><tt>%llvm.region.end</tt></a> to
- bound a region. The inner region in this example would be for the block
- containing the declaration of Z.</p>
-
-<p>Using regions to represent the boundaries of source-level functions allow
- LLVM interprocedural optimizations to arbitrarily modify LLVM functions
- without having to worry about breaking mapping information between the LLVM
- code and the and source-level program. In particular, the inliner requires
- no modification to support inlining with debugging information: there is no
- explicit correlation drawn between LLVM functions and their source-level
- counterparts (note however, that if the inliner inlines all instances of a
- non-strong-linkage function into its caller that it will not be possible for
- the user to manually invoke the inlined function from a debugger).</p>
-
-<p>Once the function has been defined,
- the <a href="#format_common_stoppoint"><tt>stopping point</tt></a>
- corresponding to line #2 (column #2) of the function is encountered. At this
- point in the function, <b>no</b> local variables are live. As lines 2 and 3
- of the example are executed, their variable definitions are introduced into
- the program using
- %<a href="#format_common_declare"><tt>llvm.dbg.declare</tt></a>, without the
- need to specify a new region. These variables do not require new regions to
- be introduced because they go out of scope at the same point in the program:
- line 9.</p>
-
-<p>In contrast, the <tt>Z</tt> variable goes out of scope at a different time,
- on line 7. For this reason, it is defined within the inner region, which
- kills the availability of <tt>Z</tt> before the code for line 8 is executed.
- In this way, regions can support arbitrary source-language scoping rules, as
- long as they can only be nested (ie, one scope cannot partially overlap with
- a part of another scope).</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 and could change how name
- lookup is performed.</p>
+ <div class="doc_code">
+ <pre>
+ call void @llvm.dbg.declare({ }* %0, metadata !0), !dbg !7
+ </pre>
+ </div>
+<p>This first intrinsic
+ <tt>%<a href="#format_common_declare">llvm.dbg.declare</a></tt>
+ encodes debugging information for variable <tt>X</tt>. The metadata,
+ <tt>!dbg !7</tt> attached with the intrinsic provides scope information for
+ the variable <tt>X</tt>. </p>
+ <div class="doc_code">
+ <pre>
+ !7 = metadata !{i32 2, i32 7, metadata !1, null}
+ !1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ]
+ !2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo",
+ metadata !"foo", metadata !"foo", metadata !3, i32 1,
+ metadata !4, i1 false, i1 true}; [DW_TAG_subprogram ]
+ </pre>
+ </div>
+
+<p> Here <tt>!7</tt> is a metadata providing location information. It has four
+ fields : line number, column number, scope and original scope. The original
+ scope represents inline location if this instruction is inlined inside
+ a caller. It is null otherwise. In this example scope is encoded by
+ <tt>!1</tt>. <tt>!1</tt> represents a lexical block inside the scope
+ <tt>!2</tt>, where <tt>!2</tt> is a
+ <a href="#format_subprograms">subprogram descriptor</a>.
+ This way the location information attched with the intrinsics indicates
+ that the variable <tt>X</tt> is declared at line number 2 at a function level
+ scope in function <tt>foo</tt>.</p>
+
+<p>Now lets take another example.</p>
+
+ <div class="doc_code">
+ <pre>
+ call void @llvm.dbg.declare({ }* %2, metadata !12), !dbg !14
+ </pre>
+ </div>
+<p>This intrinsic
+ <tt>%<a href="#format_common_declare">llvm.dbg.declare</a></tt>
+ encodes debugging information for variable <tt>Z</tt>. The metadata,
+ <tt>!dbg !14</tt> attached with the intrinsic provides scope information for
+ the variable <tt>Z</tt>. </p>
+ <div class="doc_code">
+ <pre>
+ !13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ]
+ !14 = metadata !{i32 5, i32 9, metadata !13, null}
+ </pre>
+ </div>
+
+<p> Here <tt>!14</tt> indicates that <tt>Z</tt> is declaread at line number 5,
+ column number 9 inside a lexical scope <tt>!13</tt>. This lexical scope
+ itself resides inside lexcial scope <tt>!1</tt> described above.</p>
+<p>The scope information attached with each instruction provides a straight
+ forward way to find instructions covered by a scope. </p>
</div>
<!-- *********************************************************************** -->
More information about the llvm-branch-commits
mailing list