This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
[PATCH]: Add documentation for functions in tree-flow-inline.h
On Jun 15, 2004, at 11:06 AM, Mark Mitchell wrote:
Daniel --
These functions are all missing comments. There should be a comment
for every parameter and an explanation of the value returned.
Okey.
As penance, I also added comments for all the other functions in that
file, which were all missing this documentation.
I've attached the patch for review
2004-06-14 Daniel Berlin <dberlin@dberlin.org>
* tree-flow-inline.h: Add documentation for all functions.
Index: tree-flow-inline.h
===================================================================
RCS file: /cvs/gcc/gcc/gcc/tree-flow-inline.h,v
retrieving revision 2.5
diff -u -3 -p -r2.5 tree-flow-inline.h
--- tree-flow-inline.h 12 Jun 2004 00:18:31 -0000 2.5
+++ tree-flow-inline.h 15 Jun 2004 17:53:56 -0000
@@ -25,6 +25,8 @@ Boston, MA 02111-1307, USA. */
/* Inline functions for manipulating various data structures defined in
tree-flow.h. See tree-flow.h for documentation. */
+/* Return the variable annotation for T, which must be a _DECL node.
+ Return NULL if the variable annotation doesn't already exist. */
static inline var_ann_t
var_ann (tree t)
{
@@ -39,6 +41,8 @@ var_ann (tree t)
return (var_ann_t) t->common.ann;
}
+/* Return the variable annotation for T, which must be a _DECL node.
+ Create the variable annotation if it doesn't exist. */
static inline var_ann_t
get_var_ann (tree var)
{
@@ -47,6 +51,8 @@ get_var_ann (tree var)
}
+/* Return the constant annotation for T, which must be a _CST node.
+ Return NULL if the constant annotation doesn't already exist. */
static inline cst_ann_t
cst_ann (tree t)
{
@@ -60,6 +66,8 @@ cst_ann (tree t)
return (cst_ann_t) t->common.ann;
}
+/* Return the constant annotation for T, which must be a _CST node.
+ Create the constant annotation if it doesn't exist. */
static inline cst_ann_t
get_cst_ann (tree var)
{
@@ -67,6 +75,9 @@ get_cst_ann (tree var)
return (ann) ? ann : create_cst_ann (var);
}
+/* Return the expression annotation for T, which must be an expression
+ node. Return NULL if the expression annotation doesn't already
+ exist. */
static inline expr_ann_t
expr_ann (tree t)
{
@@ -80,24 +91,30 @@ expr_ann (tree t)
return (expr_ann_t) t->common.ann;
}
+/* Return the expression annotation for T, which must be an expression
+ node. Create the expression annotation if it doesn't exist. */
static inline expr_ann_t
-get_expr_ann (tree var)
+get_expr_ann (tree t)
{
- expr_ann_t ann = expr_ann (var);
- return (ann) ? ann : create_expr_ann (var);
+ expr_ann_t ann = expr_ann (t);
+ return (ann) ? ann : create_expr_ann (t);
}
+/* Return the statement annotation for T, which must be a statement
+ node. Return NULL if the statement annotation doesn't exist. */
static inline stmt_ann_t
stmt_ann (tree t)
{
#if defined ENABLE_CHECKING
if (!is_gimple_stmt (t) && !is_essa_node (t))
abort ();
#endif
return (stmt_ann_t) t->common.ann;
}
+/* Return the statement annotation for T, which must be a statement
+ node. Create the statement annotation if it doesn't exist. */
static inline stmt_ann_t
get_stmt_ann (tree stmt)
{
@@ -106,12 +123,14 @@ get_stmt_ann (tree stmt)
}
+/* Return the annotation type for annotation ANN. */
static inline enum tree_ann_type
ann_type (tree_ann ann)
{
return ann->common.type;
}
+/* Return the basic block for statement T. */
static inline basic_block
bb_for_stmt (tree t)
{
@@ -119,6 +138,8 @@ bb_for_stmt (tree t)
return ann ? ann->bb : NULL;
}
+/* Return the may_aliases varray for variable VAR, or NULL if it has
+ no may aliases. */
static inline varray_type
may_aliases (tree var)
{
@@ -126,6 +147,7 @@ may_aliases (tree var)
return ann ? ann->may_aliases : NULL;
}
+/* Return true if VAR has a hidden use, false if it does not. */
static inline bool
has_hidden_use (tree var)
{
@@ -133,6 +155,7 @@ has_hidden_use (tree var)
return ann ? ann->has_hidden_use : false;
}
+/* Set the hidden use flag on VAR. */
static inline void
set_has_hidden_use (tree var)
{
@@ -142,6 +165,8 @@ set_has_hidden_use (tree var)
ann->has_hidden_use = 1;
}
+/* Return the line number for EXPR, or return -1 if we have no line
+ number information for it. */
static inline int
get_lineno (tree expr)
{
@@ -157,6 +182,8 @@ get_lineno (tree expr)
return EXPR_LINENO (expr);
}
+/* Return the file name for EXPR, or return "???" if we have no
+ filename information. */
static inline const char *
get_filename (tree expr)
{
@@ -172,6 +199,7 @@ get_filename (tree expr)
return "???";
}
+/* Mark statement T as modified. */
static inline void
modify_stmt (tree t)
{
@@ -181,6 +209,7 @@ modify_stmt (tree t)
ann->modified = 1;
}
+/* Mark statement T as unmodified. */
static inline void
unmodify_stmt (tree t)
{
@@ -190,6 +219,7 @@ unmodify_stmt (tree t)
ann->modified = 0;
}
+/* Return true if T is marked as modified, false otherwise. */
static inline bool
stmt_modified_p (tree t)
{
@@ -201,36 +231,48 @@ stmt_modified_p (tree t)
return ann ? ann->modified : true;
}
+/* Return the definitions present in ANN, a statement annotation.
+ Return NULL if this annotation contains no definitions. */
static inline def_optype
get_def_ops (stmt_ann_t ann)
{
return ann ? ann->def_ops : NULL;
}
+/* Return the uses present in ANN, a statement annotation.
+ Return NULL if this annotation contains no uses. */
static inline use_optype
get_use_ops (stmt_ann_t ann)
{
return ann ? ann->use_ops : NULL;
}
+/* Return the virtual may-defs present in ANN, a statement
+ annotation.
+ Return NULL if this annotation contains no virtual may-defs. */
static inline v_may_def_optype
get_v_may_def_ops (stmt_ann_t ann)
{
return ann ? ann->v_may_def_ops : NULL;
}
+/* Return the virtual uses present in ANN, a statement annotation.
+ Return NULL if this annotation contains no virtual uses. */
static inline vuse_optype
get_vuse_ops (stmt_ann_t ann)
{
return ann ? ann->vuse_ops : NULL;
}
+/* Return the virtual must-defs present in ANN, a statement
+ annotation. Return NULL if this annotation contains no must-defs.*/
static inline v_must_def_optype
get_v_must_def_ops (stmt_ann_t ann)
{
return ann ? ann->v_must_def_ops : NULL;
}
+/* Return a pointer to the tree that is at INDEX in the USES array. */
static inline tree *
get_use_op_ptr (use_optype uses, unsigned int index)
{
@@ -241,6 +283,7 @@ get_use_op_ptr (use_optype uses, unsigne
return uses->uses[index];
}
+/* Return a pointer to the tree that is at INDEX in the DEFS array. */
static inline tree *
get_def_op_ptr (def_optype defs, unsigned int index)
{
@@ -251,6 +294,9 @@ get_def_op_ptr (def_optype defs, unsigne
return defs->defs[index];
}
+
+/* Return a pointer to the tree that is the V_MAY_DEF_RESULT for the
V_MAY_DEF
+ at INDEX in the V_MAY_DEFS array. */
static inline tree *
get_v_may_def_result_ptr(v_may_def_optype v_may_defs, unsigned int
index)
{
@@ -261,6 +307,8 @@ get_v_may_def_result_ptr(v_may_def_optyp
return &(v_may_defs->v_may_defs[index * 2]);
}
+/* Return a pointer to the tree that is the V_MAY_DEF_OP for the
V_MAY_DEF at
+ INDEX in the V_MAY_DEFS array. */
static inline tree *
get_v_may_def_op_ptr(v_may_def_optype v_may_defs, unsigned int index)
{
@@ -271,6 +319,7 @@ get_v_may_def_op_ptr(v_may_def_optype v_
return &(v_may_defs->v_may_defs[index * 2 + 1]);
}
+/* Return a pointer to the tree that is at INDEX in the VUSES array.
*/
static inline tree *
get_vuse_op_ptr(vuse_optype vuses, unsigned int index)
{
@@ -281,6 +330,8 @@ get_vuse_op_ptr(vuse_optype vuses, unsig
return &(vuses->vuses[index]);
}
+/* Return a pointer to the tree that is the V_MUST_DEF_OP for the
+ V_MUST_DEF at INDEX in the V_MUST_DEFS array. */
static inline tree *
get_v_must_def_op_ptr (v_must_def_optype v_must_defs, unsigned int
index)
{
@@ -291,6 +342,7 @@ get_v_must_def_op_ptr (v_must_def_optype
return &(v_must_defs->v_must_defs[index]);
}
+/* Mark the beginning of changes to the SSA operands for STMT. */
static inline void
start_ssa_stmt_operands (tree stmt ATTRIBUTE_UNUSED)
{
@@ -299,6 +351,8 @@ start_ssa_stmt_operands (tree stmt ATTRI
#endif
}
+/* Return the bitmap of addresses taken by STMT, or NULL if it takes
+ no addresses. */
static inline bitmap
addresses_taken (tree stmt)
{
@@ -306,6 +360,8 @@ addresses_taken (tree stmt)
return ann ? ann->addresses_taken : NULL;
}
+/* Return the immediate uses of STMT, or NULL if this information is
+ not computed. */
static dataflow_t
get_immediate_uses (tree stmt)
{
@@ -313,6 +369,8 @@ get_immediate_uses (tree stmt)
return ann ? ann->df : NULL;
}
+/* Return the number of immediate uses present in the dataflow
+ information at DF. */
static inline int
num_immediate_uses (dataflow_t df)
{
@@ -328,6 +386,7 @@ num_immediate_uses (dataflow_t df)
return VARRAY_ACTIVE_SIZE (imm) + 2;
}
+/* Return the tree that is at NUM in the immediate use DF array. */
static inline tree
immediate_use (dataflow_t df, int num)
{
@@ -343,12 +402,15 @@ immediate_use (dataflow_t df, int num)
return VARRAY_TREE (df->immediate_uses, num - 2);
}
+/* Return the basic_block annotation for BB. */
static inline bb_ann_t
bb_ann (basic_block bb)
{
return (bb_ann_t)bb->tree_annotations;
}
+/* Return the PHI nodes for basic block BB, or NULL if there are no
+ PHI nodes. */
static inline tree
phi_nodes (basic_block bb)
{
@@ -402,6 +464,7 @@ phi_element_for_edge (tree phi, edge e)
/*
-----------------------------------------------------------------------
*/
+/* Return true if T is an executable statement. */
static inline bool
is_exec_stmt (tree t)
{
@@ -427,6 +490,7 @@ is_label_stmt (tree t)
return false;
}
+/* Return true if we may propagate ORIG into DEST, false otherwise. */
static inline bool
may_propagate_copy (tree dest, tree orig)
{
@@ -507,6 +571,7 @@ may_propagate_copy (tree dest, tree orig
&& !DECL_HARD_REGISTER (SSA_NAME_VAR (dest)));
}
+/* Set the default definition for VAR to DEF. */
static inline void
set_default_def (tree var, tree def)
{
@@ -516,6 +581,8 @@ set_default_def (tree var, tree def)
ann->default_def = def;
}
+/* Return the default definition for variable VAR, or NULL if none
+ exists. */
static inline tree
default_def (tree var)
{
@@ -541,6 +608,8 @@ phi_ssa_name_p (tree t)
/*
-----------------------------------------------------------------------
*/
+/* Return a block_stmt_iterator that points to beginning of basic
+ block BB. */
static inline block_stmt_iterator
bsi_start (basic_block bb)
{
@@ -560,6 +629,8 @@ bsi_start (basic_block bb)
return bsi;
}
+/* Return a block statement iterator that points to the end of basic
+ block BB. */
static inline block_stmt_iterator
bsi_last (basic_block bb)
{
@@ -579,36 +650,47 @@ bsi_last (basic_block bb)
return bsi;
}
+/* Return true if block statement iterator I has reached the end of
+ the basic block. */
static inline bool
bsi_end_p (block_stmt_iterator i)
{
return tsi_end_p (i.tsi);
}
+/* Modify block statement iterator I so that it is at the next
+ statement in the basic block. */
static inline void
bsi_next (block_stmt_iterator *i)
{
tsi_next (&i->tsi);
}
+/* Modify block statement iterator I so that it is at the previous
+ statement in the basic block. */
static inline void
bsi_prev (block_stmt_iterator *i)
{
tsi_prev (&i->tsi);
}
+/* Return the statement that block statement iterator I is currently
+ at. */
static inline tree
bsi_stmt (block_stmt_iterator i)
{
return tsi_stmt (i.tsi);
}
+/* Return a pointer to the statement that block statement iterator I
+ is currently at. */
static inline tree *
bsi_stmt_ptr (block_stmt_iterator i)
{
return tsi_stmt_ptr (i.tsi);
}
+/* Return true if VAR may be aliased. */
static inline bool
may_be_aliased (tree var)
{
@@ -616,6 +698,7 @@ may_be_aliased (tree var)
|| decl_function_context (var) != current_function_decl);
}
+/* Return true if VAR is a clobbered by function calls. */
static inline bool
is_call_clobbered (tree var)
{
@@ -623,6 +706,7 @@ is_call_clobbered (tree var)
|| bitmap_bit_p (call_clobbered_vars, var_ann (var)->uid);
}
+/* Mark variable VAR as being clobbered by function calls. */
static inline void
mark_call_clobbered (tree var)
{
@@ -632,6 +716,7 @@ mark_call_clobbered (tree var)
bitmap_set_bit (call_clobbered_vars, ann->uid);
}
+/* Mark variable VAR as being non-addressable. */
static inline void
mark_non_addressable (tree var)
{