VTA docs (was: VTA/debugging vs reload-v2, on gcc@)
diff mbox

Message ID orvd8x4l8t.fsf_-_@livre.localdomain
State New
Headers show

Commit Message

Alexandre Oliva July 2, 2010, 9:38 p.m. UTC
On Apr  5, 2010, Jeff Law <law@redhat.com> wrote:

> FWIW, I don't see any references to debug_insn or var_location in
> gcc/doc/*.texi.   Somehow I think this must be unintentional.

Indeed.  Thanks for pointing that out, sorry that it took me so long to
get to it.  How does this look?  Ok to install?  Ok for 4.5?


Richard Biener July 3, 2010, 10:07 a.m. UTC | #1
On Fri, Jul 2, 2010 at 11:38 PM, Alexandre Oliva <aoliva@redhat.com> wrote:
> On Apr  5, 2010, Jeff Law <law@redhat.com> wrote:
>> FWIW, I don't see any references to debug_insn or var_location in
>> gcc/doc/*.texi.   Somehow I think this must be unintentional.
> Indeed.  Thanks for pointing that out, sorry that it took me so long to
> get to it.  How does this look?  Ok to install?  Ok for 4.5?



> --
> Alexandre Oliva, freedom fighter    http://FSFLA.org/~lxoliva/
> You must be the change you wish to see in the world. -- Gandhi
> Be Free! -- http://FSFLA.org/   FSF Latin America board member
> Free Software Evangelist      Red Hat Brazil Compiler Engineer

diff mbox

for  gcc/ChangeLog
from  Alexandre Oliva  <aoliva@redhat.com>

	* doc/gimple.texi (GIMPLE_DEBUG): Document.
	* doc/rtl.texi (Debug Information): New node.
	(debug_insn): Likewise.
	* doc/generic.texi (DEBUG_EXPR_DECL): Document.

Index: gcc/doc/gimple.texi
--- gcc/doc/gimple.texi.orig	2010-06-25 18:09:09.000000000 -0300
+++ gcc/doc/gimple.texi	2010-07-02 18:32:04.000000000 -0300
@@ -333,6 +333,7 @@  The following table briefly describes th
 @item @code{GIMPLE_CALL}		@tab x			@tab x
 @item @code{GIMPLE_CATCH}		@tab x			@tab
 @item @code{GIMPLE_COND}		@tab x			@tab x
+@item @code{GIMPLE_DEBUG}		@tab x			@tab x
 @item @code{GIMPLE_EH_FILTER}		@tab x			@tab
 @item @code{GIMPLE_GOTO}		@tab x			@tab x
 @item @code{GIMPLE_LABEL}		@tab x			@tab x
@@ -902,6 +903,7 @@  Return a deep copy of statement @code{ST
 * @code{GIMPLE_CALL}::
 * @code{GIMPLE_CATCH}::
 * @code{GIMPLE_COND}::
+* @code{GIMPLE_DEBUG}::
 * @code{GIMPLE_EH_FILTER}::
 * @code{GIMPLE_LABEL}::
 * @code{GIMPLE_NOP}::
@@ -1392,6 +1394,83 @@  Set the conditional @code{COND_STMT} to 
 Set the conditional @code{COND_STMT} to be of the form 'if (1 == 1)'. 
 @end deftypefn
+@node @code{GIMPLE_DEBUG}
+@subsection @code{GIMPLE_DEBUG}
+@cindex @code{GIMPLE_DEBUG}
+@cindex @code{GIMPLE_DEBUG_BIND}
+@deftypefn {GIMPLE function} gimple gimple_build_debug_bind (tree var, tree value, gimple stmt)
+Build a @code{GIMPLE_DEBUG} statement with @code{GIMPLE_DEBUG_BIND} of
+@code{subcode}.  The effect of this statement is to tell debug
+information generation machinery that the value of user variable
+@code{var} is given by @code{value} at that point, and to remain with
+that value until @code{var} runs out of scope, a
+dynamically-subsequent debug bind statement overrides the binding, or
+conflicting values reach a control flow merge point.  Even if
+components of the @code{value} expression change afterwards, the
+variable is supposed to retain the same value, though not necessarily
+the same location.
+It is expected that @code{var} be most often a tree for automatic user
+variables (@code{VAR_DECL} or @code{PARM_DECL}) that satisfy the
+requirements for gimple registers, but it may also be a tree for a
+scalarized component of a user variable (@code{ARRAY_REF},
+@code{COMPONENT_REF}), or a debug temporary (@code{DEBUG_EXPR_DECL}).
+As for @code{value}, it can be an arbitrary tree expression, but it is
+recommended that it be in a suitable form for a gimple assignment
+@code{RHS}.  It is not expected that user variables that could appear
+as @code{var} ever appear in @code{value}, because in the latter we'd
+have their @code{SSA_NAME}s instead, but even if they were not in SSA
+form, user variables appearing in @code{value} are to be regarded as
+part of the executable code space, whereas those in @code{var} are to
+be regarded as part of the source code space.  There is no way to
+refer to the value bound to a user variable within a @code{value}
+If @code{value} is @code{GIMPLE_DEBUG_BIND_NOVALUE}, debug information
+generation machinery is informed that the variable @code{var} is
+unbound, i.e., that its value is indeterminate, which sometimes means
+it is really unavailable, and other times that the compiler could not
+keep track of it.
+Block and location information for the newly-created stmt are
+taken from @code{stmt}, if given.
+@end deftypefn
+@deftypefn {GIMPLE function} tree gimple_debug_bind_get_var (gimple stmt)
+Return the user variable @var{var} that is bound at @code{stmt}.
+@end deftypefn
+@deftypefn {GIMPLE function} tree gimple_debug_bind_get_value (gimple stmt)
+Return the value expression that is bound to a user variable at
+@end deftypefn
+@deftypefn {GIMPLE function} tree *gimple_debug_bind_get_value_ptr (gimple stmt)
+Return a pointer to the value expression that is bound to a user
+variable at @code{stmt}.
+@end deftypefn
+@deftypefn {GIMPLE function} void gimple_debug_bind_set_var (gimple stmt, tree var)
+Modify the user variable bound at @code{stmt} to @var{var}.
+@end deftypefn
+@deftypefn {GIMPLE function} void gimple_debug_bind_set_value (gimple stmt, tree var)
+Modify the value bound to the user variable bound at @code{stmt} to
+@end deftypefn
+@deftypefn {GIMPLE function} void gimple_debug_bind_reset_value (gimple stmt)
+Modify the value bound to the user variable bound at @code{stmt} so
+that the variable becomes unbound.
+@end deftypefn
+@deftypefn {GIMPLE function} bool gimple_debug_bind_has_value_p (gimple stmt)
+Return @code{TRUE} if @code{stmt} binds a user variable to a value,
+and @code{FALSE} if it unbinds the variable.
+@end deftypefn
 @node @code{GIMPLE_EH_FILTER}
 @subsection @code{GIMPLE_EH_FILTER}
 @cindex @code{GIMPLE_EH_FILTER}
Index: gcc/doc/rtl.texi
--- gcc/doc/rtl.texi.orig	2010-04-14 21:45:24.000000000 -0300
+++ gcc/doc/rtl.texi	2010-07-02 18:31:30.000000000 -0300
@@ -38,6 +38,7 @@  form uses nested parentheses to indicate
 * Side Effects::      Expressions for storing in registers, etc.
 * Incdec::            Embedded side-effects for autoincrement addressing.
 * Assembler::         Representing @code{asm} with operands.
+* Debug Information:: Expressions representing debugging information.
 * Insns::             Expression types for entire insns.
 * Calls::             RTL representation of function call insns.
 * Sharing::           Some expressions are unique; others *must* be copied.
@@ -3285,6 +3286,38 @@  template and vectors, but each contains 
 output operand.  They are also distinguished by the output-operand index
 number, which is 0, 1, @dots{} for successive output operands.
+@node Debug Information
+@section Variable Location Debug Information in RTL
+@cindex Variable Location Debug Information in RTL
+Variable tracking relies on @code{MEM_EXPR} and @code{REG_EXPR}
+annotations to determine what user variables memory and register
+references refer to.
+Variable tracking at assignments uses these notes only when they refer
+to variables that live at fixed locations (e.g., addressable
+variables, global non-automatic variables).  For variables whose
+location may vary, it relies on the following types of notes.
+@table @code
+@findex var_location
+@item (var_location:@var{mode} @var{var} @var{exp} @var{stat})
+Binds variable @code{var}, a tree, to value @var{exp}, an RTL
+expression.  It appears only in @code{NOTE_INSN_VAR_LOCATION} and
+@code{DEBUG_INSN}s, with slightly different meanings.  @var{mode}, if
+present, represents the mode of @var{exp}, which is useful if it is a
+modeless expression.  @var{stat} is only meaningful in notes,
+indicating whether the variable is known to be initialized or
+@findex debug_expr
+@item (debug_expr:@var{mode} @var{decl})
+Stands for the value bound to the @code{DEBUG_EXPR_DECL} @var{decl},
+that points back to it, within value expressions in
+@code{VAR_LOCATION} nodes.
+@end table
 @node Insns
 @section Insns
 @cindex insns
@@ -3360,7 +3393,7 @@  of @code{PREV_INSN (NEXT_INSN (@var{insn
 insn in the @code{sequence} expression.  You can use these expressions
 to find the containing @code{sequence} expression.
-Every insn has one of the following six expression codes:
+Every insn has one of the following expression codes:
 @table @code
 @findex insn
@@ -3551,9 +3584,54 @@  invariants.
 Appears at the start of the function body, after the function
+This note is used to generate variable location debugging information.
+It indicates that the user variable in its @code{VAR_LOCATION} operand
+is at the location given in the RTL expression, or holds a value that
+can be computed by evaluating the RTL expression from that static
+point in the program up to the next such note for the same user
 @end table
 These codes are printed symbolically when they appear in debugging dumps.
+@findex debug_insn
+@item debug_insn
+The expression code @code{debug_insn} is used for pseudo-instructions
+that hold debugging information for variable tracking at assignments
+(see @option{-fvar-tracking-assignments} option).  They are the RTL
+representation of @code{GIMPLE_DEBUG} statements
+(@ref{@code{GIMPLE_DEBUG}}), with a @code{VAR_LOCATION} operand that
+binds a user variable tree to an RTL representation of the
+@code{value} in the corresponding statement.  A @code{DEBUG_EXPR} in
+it stands for the value bound to the corresponding
+Throughout optimization passes, binding information is kept in
+pseudo-instruction form, so that, unlike notes, it gets the same
+treatment and adjustments that regular instructions would.  It is the
+variable tracking pass that turns these pseudo-instructions into var
+location notes, analyzing control flow, value equivalences and changes
+to registers and memory referenced in value expressions, propagating
+the values of debug temporaries and determining expressions that can
+be used to compute the value of each user variable at as many points
+(ranges, actually) in the program as possible.
+Unlike @code{NOTE_INSN_VAR_LOCATION}, the value expression in an
+@code{INSN_VAR_LOCATION} denotes a value at that specific point in the
+program, rather than an expression that can be evaluated at any later
+point before an overriding @code{VAR_LOCATION} is encountered.  E.g.,
+if a user variable is bound to a @code{REG} and then a subsequent insn
+modifies the @code{REG}, the note location would keep mapping the user
+variable to the register across the insn, whereas the insn location
+would keep the variable bound to the value, so that the variable
+tracking pass would emit another location note for the variable at the
+point in which the register is modified.
 @end table
 @cindex @code{TImode}, in @code{insn}
Index: gcc/doc/generic.texi
--- gcc/doc/generic.texi.orig	2010-07-02 16:03:20.000000000 -0300
+++ gcc/doc/generic.texi	2010-07-02 18:21:10.000000000 -0300
@@ -601,6 +601,7 @@  in hand, using @code{same_type_p}.
 @tindex TYPE_DECL
 @tindex VAR_DECL
 @tindex PARM_DECL
 @tindex FIELD_DECL
 @tindex RESULT_DECL
@@ -726,6 +727,11 @@  wider type than the @code{TREE_TYPE} of 
 ordinary type might be @code{short} while the @code{DECL_ARG_TYPE} is
+Used to represent an anonymous debug-information temporary created to
+hold an expression as it is optimized away, so that its value can be
+referenced in debug bind statements.
 These nodes represent non-static data members.  The @code{DECL_SIZE} and
 @code{DECL_ALIGN} behave as for @code{VAR_DECL} nodes.