X-Git-Url: http://nsz.repo.hu/git/?a=blobdiff_plain;f=ir%2Fana%2Firloop.h;h=21e96a8917899f3f8c15da236f376e9038d92e31;hb=e8b49f5a1399b14137f0053ef1675686146351fe;hp=f84547dc77925531815fb8df0d3d3f940cbd530a;hpb=c19953ed6384686c23fb9d720a7cfdda3d443d19;p=libfirm

diff --git a/ir/ana/irloop.h b/ir/ana/irloop.h
index f84547dc7..21e96a891 100644
--- a/ir/ana/irloop.h
+++ b/ir/ana/irloop.h
@@ -72,7 +72,7 @@ void clear_backedges (ir_node *n);
 /* ------------------------------------------------------------------- */
 typedef struct ir_loop ir_loop;
 
-/* Loop elements are loop nodes and ir nodes */
+/** Loop elements: loop nodes and ir nodes */
 typedef union {
     firm_kind *kind;    /**< is either k_ir_node or k_ir_loop */
     ir_node *node;      /**< Pointer to an ir_node element */
@@ -83,6 +83,8 @@ int      is_ir_loop(const void *thing);
 
 /** Set the outermost loop in ir graph as basic access to loop tree. */
 void     set_irg_loop(ir_graph *irg, ir_loop *l);
+
+/* Returns the root loop info (if exists) for an irg. */
 ir_loop *get_irg_loop(ir_graph *irg);
 
 /** Returns the loop n is contained in.  NULL if node is in no loop. */
@@ -96,9 +98,16 @@ int      get_loop_depth (ir_loop *loop);
 /* Sons are the inner loops contained in this loop. */
 /** Returns the number of inner loops */
 int      get_loop_n_sons (ir_loop *loop);
+
+/** Returns the pos`th son loop (inner loop) of a loop.
+    Returns NULL if there is not a pos`th loop_node. */
 ir_loop *get_loop_son (ir_loop *loop, int pos);
+
 /** Returns the number of nodes contained in loop.  */
 int      get_loop_n_nodes (ir_loop *loop);
+
+/** Returns the pos`th ir_node of a loop.
+    Returns NULL if there is not a pos`th ir_node. */
 ir_node *get_loop_node (ir_loop *loop, int pos);
 
 /** Returns the number of elements contained in loop.  */
@@ -125,10 +134,16 @@ void *get_loop_link (const ir_loop *loop);
 /* Constructing and destructing the loop/backedge information.         */
 /* ------------------------------------------------------------------- */
 
-/** Constructs backedge information for irg in intraprocedural view.
+/** Constructs backedge information and loop tree for a graph in intraprocedural view.
+ *
+ *  The algorithm views the program representation as a pure graph.
+ *  It assumes that only block and phi nodes may be loop headers.
+ *  The resulting loop tree is a possible visiting order for dataflow
+ *  analysis.
+ *
  *  @returns Maximal depth of loop tree.
  *
- *  ATTENTION:
+ *  @remark
  *  One assumes, the Phi nodes in a block with a backedge have backedges
  *  at the same positions as the block.  This is not the case, as
  *  the scc algorithms does not respect the program semantics in this case.
@@ -140,21 +155,41 @@ void *get_loop_link (const ir_loop *loop);
 /* @@@ Well, maybe construct_loop_information or analyze_loops ? */
 int construct_backedges(ir_graph *irg);
 
-/** Constructs backedges for all irgs in interprocedural view.  All
-    loops in the graph will be marked as such, not only realizeable
-    loops and recursions in the program.  E.g., if the same funcion is
-    called twice, there is a loop between the first function return and
-    the second call.
- *  @returns Maximal depth of loop tree. */
+/** Constructs backedges for all irgs in interprocedural view.
+ *
+ *  @see As construct_backedges(), but for interprocedural view.
+ *
+ *  @remark
+ *  All loops in the graph will be marked as such, not only
+ *  realizeable loops and recursions in the program.  E.g., if the
+ *  same funcion is called twice, there is a loop between the first
+ *  function return and the second call.
+ *
+ *  @returns Maximal depth of loop tree.
+*/
 int construct_ip_backedges(void);
 
-/* Construct loop tree only for control flow.
+/** Construct loop tree only for control flow.
+ *
+ *  This constructs loop information resembling the program structure.
+ *  It is useful for loop optimizations and analyses, as, e.g., finding
+ *  iteration variables or loop invariant code motion.
+ *
+ *  This algorithm computes only back edge information for Block nodes, not
+ *  for Phi nodes.
+ *
  * @returns Maximal depth of loop tree. */
 int construct_cf_backedges(ir_graph *irg);
+
+/** Construct interprocedural loop tree for control flow.
+ *
+ *  @see construct_cf_backedges() and construct_ip_backedges().
+ */
 int construct_ip_cf_backedges (void);
 
 /** Removes all loop information.
-    Resets all backedges */
+ *  Resets all backedges.  Works for any construction algorithm.
+ */
 void free_loop_information(ir_graph *irg);
 void free_all_loop_information (void);