SSA operand iterator how-to

[Andrew MacLeod <amacleod at redhat dot com>]

Due to popular request, here's a shorter summary of how to use the new
operand iterators.  (which has just been checked in, btw) 

(1) Determine whether you are need to see the operand pointers, or just
the trees, and choose the appropriate macro: 

Need 		Macro: 
---- 		------- 
use_operand_p 	FOR_EACH_SSA_USE_OPERAND 
def_operand_p 	FOR_EACH_SSA_DEF_OPERAND 
tree 		FOR_EACH_SSA_TREE_OPERAND 

(2) You need to declare a variable of the type you are interested in,
and an ssa_op_iter structure which serves as the loop controlling
variable. 

(3) Determine which operands you wish to use, and specify the flags of
those you are intrested in. They are documented in tree-ssa-operands.h: 

#define SSA_OP_USE              0x01    /* Real USE operands.  */
#define SSA_OP_DEF              0x02    /* Real DEF operands.  */
#define SSA_OP_VUSE             0x04    /* VUSE operands.  */
#define SSA_OP_VMAYUSE          0x08    /* USE portion of V_MAY_DEFS.  */
#define SSA_OP_VMAYDEF          0x10    /* DEF portion of V_MAY_DEFS.  */
#define SSA_OP_VMUSTDEF         0x20    /* V_MUST_DEF defintions.  */

/* These are commonly grouped operand flags.  */
#define SSA_OP_VIRTUAL_USES     (SSA_OP_VUSE | SSA_OP_VMAYUSE)
#define SSA_OP_VIRTUAL_DEFS     (SSA_OP_VMAYDEF | SSA_OP_VMUSTDEF)
#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)

So if you want to look at the use pointers for all the USE and VUSE
operands, you would do something like: 

use_operand_p use_p; 
ssa_op_iter iter; 

FOR_EACH_SSA_USE_OPERAND (use_p, stmt, iter, (SSA_OP_USE | SSA_OP_VUSE))
  { 
    process_use_ptr (use_p); 
  } 

The _TREE_ macro is basically the same as the USE and DEF macros, only
with the use or def dereferenced via USE_FROM_PTR (use_p) and
DEF_FROM_PTR (def_p). Since we aren't using operand pointers, use and
defs flags can be mixed. 

tree var;
ssa_op_iter iter;

FOR_EACH_SSA_TREE_OPERAND (var, stmt, iter, SSA_OP_VUSE | SSA_OP_VMUSTDEF)
  {
     print_generic_expr (stderr, var, TDF_SLIM);
  }

Note that V_MAY_DEFS are broken into 2 flags, one for the DEf portion
(SSA_OP_VMAYDEF) and one for the USE portion (SSA_OP_VMAYUSE). If all
you want to look at are the V_MAY_DEFS together, there is a fourth
iterator macro for this, which returns both a def_operand_p and a
use_operand_p for each V_MAY_DEF in the stmt. NOte you dont need any
flags for this one. 

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; 
  } 


There are many examples in the code as well, as well as the
documentation in ssa-operands.h. 

The previous mechanism is still available, as there are occasionally
times it is more useful.

Andrew