for gcc/ChangeLog
from 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.
===================================================================
@@ -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}
+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}
===================================================================
@@ -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
+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
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}
===================================================================
@@ -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
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.