gimple.texi (GIMPLE_DEBUG): Document.

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

From-SVN: r161899

gcc/ChangeLog

@@ -1,3 +1,11 @@
+2010-07-06  Alexandre Oliva  <aoliva@redhat.com>
+
+	* doc/gimple.texi (GIMPLE_DEBUG): Document.
+	* doc/rtl.texi (Debug Information): New node.
+	(NOTE_INSN_VAR_LOCATION): Document.
+	(debug_insn): Likewise.
+	* doc/generic.texi (DEBUG_EXPR_DECL): Document.
+
 2010-07-07  Jan Hubicka  <jh@suse.cz>
 
 	With parts by Richard Guenther

gcc/doc/generic.texi

@@ -601,6 +601,7 @@ in hand, using @code{same_type_p}.
 @tindex TYPE_DECL
 @tindex VAR_DECL
 @tindex PARM_DECL
+@tindex DEBUG_EXPR_DECL
 @tindex FIELD_DECL
 @tindex NAMESPACE_DECL
 @tindex RESULT_DECL
@@ -726,6 +727,11 @@ wider type than the @code{TREE_TYPE} of the parameter; for example, the
 ordinary type might be @code{short} while the @code{DECL_ARG_TYPE} is
 @code{int}.
 
+@item DEBUG_EXPR_DECL
+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.
+
 @item FIELD_DECL
 These nodes represent non-static data members.  The @code{DECL_SIZE} and
 @code{DECL_ALIGN} behave as for @code{VAR_DECL} nodes.  

gcc/doc/gimple.texi

@@ -333,6 +333,7 @@ The following table briefly describes the GIMPLE instruction set.
 @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
@@ -907,6 +908,7 @@ Return a deep copy of statement @code{STMT}.
 * @code{GIMPLE_CALL}::
 * @code{GIMPLE_CATCH}::
 * @code{GIMPLE_COND}::
+* @code{GIMPLE_DEBUG}::
 * @code{GIMPLE_EH_FILTER}::
 * @code{GIMPLE_LABEL}::
 * @code{GIMPLE_NOP}::
@@ -1397,6 +1399,83 @@ Set the conditional @code{COND_STMT} to be of the form 'if (1 == 0)'.
 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}
+expression.
+
+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
+@code{stmt}.
+@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
+@var{value}.
+@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}

gcc/doc/rtl.texi

@@ -38,6 +38,7 @@ form uses nested parentheses to indicate the pointers in the internal form.
 * 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 the constraint for the respective
 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
+uninitialized.
+
+@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}))} if @var{insn} is the last
 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
 prologue.
 
+@findex NOTE_INSN_VAR_LOCATION
+@findex NOTE_VAR_LOCATION
+@item NOTE_INSN_VAR_LOCATION
+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
+variable.
+
 @end table
 
 These codes are printed symbolically when they appear in debugging dumps.
+
+@findex debug_insn
+@findex INSN_VAR_LOCATION
+@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
+@code{DEBUG_EXPR_DECL}.
+
+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}