gccint: Loop querying

1 
1 16.2 Loop querying
1 ==================
1 
1 The functions to query the information about loops are declared in
1 'cfgloop.h'.  Some of the information can be taken directly from the
1 structures.  'loop_father' field of each basic block contains the
1 innermost loop to that the block belongs.  The most useful fields of
1 loop structure (that are kept up-to-date at all times) are:
1 
1    * 'header', 'latch': Header and latch basic blocks of the loop.
1    * 'num_nodes': Number of basic blocks in the loop (including the
1      basic blocks of the sub-loops).
1    * 'outer', 'inner', 'next': The super-loop, the first sub-loop, and
1      the sibling of the loop in the loops tree.
1 
1  There are other fields in the loop structures, many of them used only
1 by some of the passes, or not updated during CFG changes; in general,
1 they should not be accessed directly.
1 
1  The most important functions to query loop structures are:
1 
1    * 'loop_depth': The depth of the loop in the loops tree, i.e., the
1      number of super-loops of the loop.
1    * 'flow_loops_dump': Dumps the information about loops to a file.
1    * 'verify_loop_structure': Checks consistency of the loop structures.
1    * 'loop_latch_edge': Returns the latch edge of a loop.
1    * 'loop_preheader_edge': If loops have preheaders, returns the
1      preheader edge of a loop.
1    * 'flow_loop_nested_p': Tests whether loop is a sub-loop of another
1      loop.
1    * 'flow_bb_inside_loop_p': Tests whether a basic block belongs to a
1      loop (including its sub-loops).
1    * 'find_common_loop': Finds the common super-loop of two loops.
1    * 'superloop_at_depth': Returns the super-loop of a loop with the
1      given depth.
1    * 'tree_num_loop_insns', 'num_loop_insns': Estimates the number of
1      insns in the loop, on GIMPLE and on RTL.
1    * 'loop_exit_edge_p': Tests whether edge is an exit from a loop.
1    * 'mark_loop_exit_edges': Marks all exit edges of all loops with
1      'EDGE_LOOP_EXIT' flag.
1    * 'get_loop_body', 'get_loop_body_in_dom_order',
1      'get_loop_body_in_bfs_order': Enumerates the basic blocks in the
1      loop in depth-first search order in reversed CFG, ordered by
1      dominance relation, and breath-first search order, respectively.
1    * 'single_exit': Returns the single exit edge of the loop, or 'NULL'
1      if the loop has more than one exit.  You can only use this function
1      if LOOPS_HAVE_MARKED_SINGLE_EXITS property is used.
1    * 'get_loop_exit_edges': Enumerates the exit edges of a loop.
1    * 'just_once_each_iteration_p': Returns true if the basic block is
1      executed exactly once during each iteration of a loop (that is, it
1      does not belong to a sub-loop, and it dominates the latch of the
1      loop).
1