diff gcc/doc/tree-ssa.texi @ 111:04ced10e8804

gcc 7
author kono
date Fri, 27 Oct 2017 22:46:09 +0900
parents b7f97abdc517
children 84e7813d76e9
line wrap: on
line diff
--- a/gcc/doc/tree-ssa.texi	Sun Aug 21 07:07:55 2011 +0900
+++ b/gcc/doc/tree-ssa.texi	Fri Oct 27 22:46:09 2017 +0900
@@ -1,5 +1,4 @@
-@c Copyright (c) 2004, 2005, 2007, 2008, 2010
-@c Free Software Foundation, Inc.
+@c Copyright (C) 2004-2017 Free Software Foundation, Inc.
 @c This is part of the GCC manual.
 @c For copying conditions, see the file gcc.texi.
 
@@ -54,9 +53,6 @@
 structures called annotations which are then linked to the field
 @code{ann} in @code{struct tree_common}.
 
-Presently, we define annotations for variables (@code{var_ann_t}).
-Annotations are defined and documented in @file{tree-flow.h}.
-
 
 @node SSA Operands
 @section SSA Operands
@@ -184,7 +180,7 @@
 call to @code{update_stmt}.
 
 @subsection Operand Iterators And Access Routines
-@cindex Operand Iterators 
+@cindex Operand Iterators
 @cindex Operand Access Routines
 
 Operands are collected by @file{tree-ssa-operands.c}.  They are stored
@@ -194,9 +190,9 @@
 The following access routines are available for examining operands:
 
 @enumerate
-@item @code{SINGLE_SSA_@{USE,DEF,TREE@}_OPERAND}: These accessors will return 
-NULL unless there is exactly one operand matching the specified flags.  If 
-there is exactly one operand, the operand is returned as either a @code{tree}, 
+@item @code{SINGLE_SSA_@{USE,DEF,TREE@}_OPERAND}: These accessors will return
+NULL unless there is exactly one operand matching the specified flags.  If
+there is exactly one operand, the operand is returned as either a @code{tree},
 @code{def_operand_p}, or @code{use_operand_p}.
 
 @smallexample
@@ -205,7 +201,7 @@
 def_operand_p d = SINGLE_SSA_DEF_OPERAND (stmt, SSA_OP_ALL_DEFS);
 @end smallexample
 
-@item @code{ZERO_SSA_OPERANDS}: This macro returns true if there are no 
+@item @code{ZERO_SSA_OPERANDS}: This macro returns true if there are no
 operands matching the specified flags.
 
 @smallexample
@@ -213,8 +209,8 @@
   return;
 @end smallexample
 
-@item @code{NUM_SSA_OPERANDS}: This macro Returns the number of operands 
-matching 'flags'.  This actually executes a loop to perform the count, so 
+@item @code{NUM_SSA_OPERANDS}: This macro Returns the number of operands
+matching 'flags'.  This actually executes a loop to perform the count, so
 only use this if it is really needed.
 
 @smallexample
@@ -266,15 +262,15 @@
 #define SSA_OP_USE              0x01    /* @r{Real USE operands.}  */
 #define SSA_OP_DEF              0x02    /* @r{Real DEF operands.}  */
 #define SSA_OP_VUSE             0x04    /* @r{VUSE operands.}  */
-#define SSA_OP_VMAYUSE          0x08    /* @r{USE portion of VDEFS.}  */
-#define SSA_OP_VDEF             0x10    /* @r{DEF portion of VDEFS.}  */
+#define SSA_OP_VDEF             0x08    /* @r{VDEF operands.}  */
 
 /* @r{These are commonly grouped operand flags.}  */
-#define SSA_OP_VIRTUAL_USES     (SSA_OP_VUSE | SSA_OP_VMAYUSE)
-#define SSA_OP_VIRTUAL_DEFS     (SSA_OP_VDEF)
-#define SSA_OP_ALL_USES         (SSA_OP_VIRTUAL_USES | SSA_OP_USE)
-#define SSA_OP_ALL_DEFS         (SSA_OP_VIRTUAL_DEFS | SSA_OP_DEF)
-#define SSA_OP_ALL_OPERANDS     (SSA_OP_ALL_USES | SSA_OP_ALL_DEFS)
+#define SSA_OP_VIRTUAL_USES	(SSA_OP_VUSE)
+#define SSA_OP_VIRTUAL_DEFS	(SSA_OP_VDEF)
+#define SSA_OP_ALL_VIRTUALS     (SSA_OP_VIRTUAL_USES | SSA_OP_VIRTUAL_DEFS)
+#define SSA_OP_ALL_USES		(SSA_OP_VIRTUAL_USES | SSA_OP_USE)
+#define SSA_OP_ALL_DEFS		(SSA_OP_VIRTUAL_DEFS | SSA_OP_DEF)
+#define SSA_OP_ALL_OPERANDS	(SSA_OP_ALL_USES | SSA_OP_ALL_DEFS)
 @end smallexample
 @end enumerate
 
@@ -308,31 +304,16 @@
 
 @code{VDEF}s are broken into two flags, one for the
 @code{DEF} portion (@code{SSA_OP_VDEF}) and one for the USE portion
-(@code{SSA_OP_VMAYUSE}).  If all you want to look at are the
-@code{VDEF}s together, there is a fourth iterator macro for this,
-which returns both a def_operand_p and a use_operand_p for each
-@code{VDEF} in the statement.  Note that you don't need any flags for
-this one.
+(@code{SSA_OP_VUSE}).
 
-@smallexample
-  use_operand_p use_p;
-  def_operand_p def_p;
-  ssa_op_iter iter;
-
-  FOR_EACH_SSA_MAYDEF_OPERAND (def_p, use_p, stmt, iter)
-    @{
-      my_code;
-    @}
-@end smallexample
-
-There are many examples in the code as well, as well as the
-documentation in @file{tree-ssa-operands.h}.
+There are many examples in the code, in addition to the documentation
+in @file{tree-ssa-operands.h} and @file{ssa-iterators.h}.
 
 There are also a couple of variants on the stmt iterators regarding PHI
 nodes.
 
-@code{FOR_EACH_PHI_ARG} Works exactly like 
-@code{FOR_EACH_SSA_USE_OPERAND}, except it works over @code{PHI} arguments 
+@code{FOR_EACH_PHI_ARG} Works exactly like
+@code{FOR_EACH_SSA_USE_OPERAND}, except it works over @code{PHI} arguments
 instead of statement operands.
 
 @smallexample
@@ -351,10 +332,10 @@
   my_code;
 @end smallexample
 
-@code{FOR_EACH_PHI_OR_STMT_@{USE,DEF@}} works exactly like 
+@code{FOR_EACH_PHI_OR_STMT_@{USE,DEF@}} works exactly like
 @code{FOR_EACH_SSA_@{USE,DEF@}_OPERAND}, except it will function on
 either a statement or a @code{PHI} node.  These should be used when it is
-appropriate but they are not quite as efficient as the individual 
+appropriate but they are not quite as efficient as the individual
 @code{FOR_EACH_PHI} and @code{FOR_EACH_SSA} routines.
 
 @smallexample
@@ -372,7 +353,7 @@
 @subsection Immediate Uses
 @cindex Immediate Uses
 
-Immediate use information is now always available.  Using the immediate use 
+Immediate use information is now always available.  Using the immediate use
 iterators, you may examine every use of any @code{SSA_NAME}. For instance,
 to change each use of @code{ssa_var} to @code{ssa_var2} and call fold_stmt on
 each stmt after that is done:
@@ -393,18 +374,18 @@
 
 There are 2 iterators which can be used. @code{FOR_EACH_IMM_USE_FAST} is
 used when the immediate uses are not changed, i.e., you are looking at the
-uses, but not setting them.  
+uses, but not setting them.
 
-If they do get changed, then care must be taken that things are not changed 
-under the iterators, so use the @code{FOR_EACH_IMM_USE_STMT} and 
-@code{FOR_EACH_IMM_USE_ON_STMT} iterators.  They attempt to preserve the 
-sanity of the use list by moving all the uses for a statement into 
-a controlled position, and then iterating over those uses.  Then the 
+If they do get changed, then care must be taken that things are not changed
+under the iterators, so use the @code{FOR_EACH_IMM_USE_STMT} and
+@code{FOR_EACH_IMM_USE_ON_STMT} iterators.  They attempt to preserve the
+sanity of the use list by moving all the uses for a statement into
+a controlled position, and then iterating over those uses.  Then the
 optimization can manipulate the stmt when all the uses have been
-processed.  This is a little slower than the FAST version since it adds a 
-placeholder element and must sort through the list a bit for each statement.  
-This placeholder element must be also be removed if the loop is 
-terminated early.  The macro @code{BREAK_FROM_IMM_USE_SAFE} is provided 
+processed.  This is a little slower than the FAST version since it adds a
+placeholder element and must sort through the list a bit for each statement.
+This placeholder element must be also be removed if the loop is
+terminated early.  The macro @code{BREAK_FROM_IMM_USE_SAFE} is provided
 to do this :
 
 @smallexample
@@ -420,15 +401,15 @@
 @end smallexample
 
 There are checks in @code{verify_ssa} which verify that the immediate use list
-is up to date, as well as checking that an optimization didn't break from the 
-loop without using this macro.  It is safe to simply 'break'; from a 
+is up to date, as well as checking that an optimization didn't break from the
+loop without using this macro.  It is safe to simply 'break'; from a
 @code{FOR_EACH_IMM_USE_FAST} traverse.
 
 Some useful functions and macros:
 @enumerate
 @item  @code{has_zero_uses (ssa_var)} : Returns true if there are no uses of
 @code{ssa_var}.
-@item   @code{has_single_use (ssa_var)} : Returns true if there is only a 
+@item   @code{has_single_use (ssa_var)} : Returns true if there is only a
 single use of @code{ssa_var}.
 @item   @code{single_imm_use (ssa_var, use_operand_p *ptr, tree *stmt)} :
 Returns true if there is only a single use of @code{ssa_var}, and also returns
@@ -443,18 +424,18 @@
 @end enumerate
 
 Note that uses are not put into an immediate use list until their statement is
-actually inserted into the instruction stream via a @code{bsi_*} routine.  
+actually inserted into the instruction stream via a @code{bsi_*} routine.
 
-It is also still possible to utilize lazy updating of statements, but this 
-should be used only when absolutely required.  Both alias analysis and the 
-dominator optimizations currently do this.  
+It is also still possible to utilize lazy updating of statements, but this
+should be used only when absolutely required.  Both alias analysis and the
+dominator optimizations currently do this.
 
-When lazy updating is being used, the immediate use information is out of date 
+When lazy updating is being used, the immediate use information is out of date
 and cannot be used reliably.  Lazy updating is achieved by simply marking
-statements modified via calls to @code{mark_stmt_modified} instead of 
-@code{update_stmt}.  When lazy updating is no longer required, all the 
-modified statements must have @code{update_stmt} called in order to bring them 
-up to date.  This must be done before the optimization is finished, or 
+statements modified via calls to @code{gimple_set_modified} instead of
+@code{update_stmt}.  When lazy updating is no longer required, all the
+modified statements must have @code{update_stmt} called in order to bring them
+up to date.  This must be done before the optimization is finished, or
 @code{verify_ssa} will trigger an abort.
 
 This is done with a simple loop over the instruction stream:
@@ -527,31 +508,29 @@
 Hence, PHI nodes mean ``one of these operands.  I don't know
 which''.
 
-The following macros can be used to examine PHI nodes
+The following functions can be used to examine PHI nodes
 
-@defmac PHI_RESULT (@var{phi})
+@defun gimple_phi_result (@var{phi})
 Returns the @code{SSA_NAME} created by PHI node @var{phi} (i.e.,
 @var{phi}'s LHS)@.
-@end defmac
+@end defun
 
-@defmac PHI_NUM_ARGS (@var{phi})
+@defun gimple_phi_num_args (@var{phi})
 Returns the number of arguments in @var{phi}.  This number is exactly
 the number of incoming edges to the basic block holding @var{phi}@.
-@end defmac
+@end defun
 
-@defmac PHI_ARG_ELT (@var{phi}, @var{i})
-Returns a tuple representing the @var{i}th argument of @var{phi}@.
-Each element of this tuple contains an @code{SSA_NAME} @var{var} and
-the incoming edge through which @var{var} flows.
-@end defmac
+@defun gimple_phi_arg (@var{phi}, @var{i})
+Returns @var{i}th argument of @var{phi}@.
+@end defun
 
-@defmac PHI_ARG_EDGE (@var{phi}, @var{i})
+@defun gimple_phi_arg_edge (@var{phi}, @var{i})
 Returns the incoming edge for the @var{i}th argument of @var{phi}.
-@end defmac
+@end defun
 
-@defmac PHI_ARG_DEF (@var{phi}, @var{i})
+@defun gimple_phi_arg_def (@var{phi}, @var{i})
 Returns the @code{SSA_NAME} for the @var{i}th argument of @var{phi}.
-@end defmac
+@end defun
 
 
 @subsection Preserving the SSA form
@@ -561,7 +540,7 @@
 invalidate the SSA property.  This can happen when a pass has
 added new symbols or changed the program so that variables that
 were previously aliased aren't anymore.  Whenever something like this
-happens, the affected symbols must be renamed into SSA form again.  
+happens, the affected symbols must be renamed into SSA form again.
 Transformations that emit new code or replicate existing statements
 will also need to update the SSA form@.
 
@@ -628,10 +607,7 @@
 between the old and the new names are registered by calling
 @code{register_new_name_mapping} (note that if your pass creates new
 code by duplicating basic blocks, the call to @code{tree_duplicate_bb}
-will set up the necessary mappings automatically).  On the other hand,
-if your pass exposes a new symbol that should be put in SSA form for
-the first time, the new symbol should be registered with
-@code{mark_sym_for_renaming}.
+will set up the necessary mappings automatically).
 
 After the replacement mappings have been registered and new symbols
 marked for renaming, a call to @code{update_ssa} makes the registered
@@ -678,40 +654,6 @@
 renaming are processed@.
 @end itemize
 
-@subsection Preserving the virtual SSA form
-@cindex preserving virtual SSA form
-
-The virtual SSA form is harder to preserve than the non-virtual SSA form
-mainly because the set of virtual operands for a statement may change at
-what some would consider unexpected times.  In general, statement
-modifications should be bracketed between calls to
-@code{push_stmt_changes} and @code{pop_stmt_changes}.  For example,
-
-@smallexample
-    munge_stmt (tree stmt)
-    @{
-       push_stmt_changes (&stmt);
-       @dots{} rewrite STMT @dots{}
-       pop_stmt_changes (&stmt);
-    @}
-@end smallexample
-
-The call to @code{push_stmt_changes} saves the current state of the
-statement operands and the call to @code{pop_stmt_changes} compares
-the saved state with the current one and does the appropriate symbol
-marking for the SSA renamer.
-
-It is possible to modify several statements at a time, provided that
-@code{push_stmt_changes} and @code{pop_stmt_changes} are called in
-LIFO order, as when processing a stack of statements.
-
-Additionally, if the pass discovers that it did not need to make
-changes to the statement after calling @code{push_stmt_changes}, it
-can simply discard the topmost change buffer by calling
-@code{discard_stmt_changes}.  This will avoid the expensive operand
-re-scan operation and the buffer comparison that determines if symbols
-need to be marked for renaming.
-
 @subsection Examining @code{SSA_NAME} nodes
 @cindex examining SSA_NAMEs
 
@@ -729,33 +671,6 @@
 @end defmac
 
 
-@subsection Walking use-def chains
-
-@deftypefn {Tree SSA function} void walk_use_def_chains (@var{var}, @var{fn}, @var{data})
-
-Walks use-def chains starting at the @code{SSA_NAME} node @var{var}.
-Calls function @var{fn} at each reaching definition found.  Function
-@var{FN} takes three arguments: @var{var}, its defining statement
-(@var{def_stmt}) and a generic pointer to whatever state information
-that @var{fn} may want to maintain (@var{data}).  Function @var{fn} is
-able to stop the walk by returning @code{true}, otherwise in order to
-continue the walk, @var{fn} should return @code{false}.
-
-Note, that if @var{def_stmt} is a @code{PHI} node, the semantics are
-slightly different.  For each argument @var{arg} of the PHI node, this
-function will:
-
-@enumerate
-@item Walk the use-def chains for @var{arg}.
-@item Call @code{FN (@var{arg}, @var{phi}, @var{data})}.
-@end enumerate
-
-Note how the first argument to @var{fn} is no longer the original
-variable @var{var}, but the PHI argument currently being examined.
-If @var{fn} wants to get at @var{var}, it should call
-@code{PHI_RESULT} (@var{phi}).
-@end deftypefn
-
 @subsection Walking the dominator tree
 
 @deftypefn {Tree SSA function} void walk_dominator_tree (@var{walk_data}, @var{bb})