From: Michael Beck Date: Tue, 23 Jan 2007 16:44:55 +0000 (+0000) Subject: more doxygen comments added X-Git-Url: http://nsz.repo.hu/git/?a=commitdiff_plain;h=9021faf43bff4e1c424d5d2693c15616323c9d84;p=libfirm more doxygen comments added [r8550] --- diff --git a/ir/ana/callgraph.h b/ir/ana/callgraph.h index 010206e9e..d6feb151a 100644 --- a/ir/ana/callgraph.h +++ b/ir/ana/callgraph.h @@ -6,72 +6,84 @@ * Modified by: * Created: 21.7.2004 * CVS-ID: $Id$ - * Copyright: (c) 2004 Universität Karlsruhe + * Copyright: (c) 2004-2007 Universität Karlsruhe * Licence: This file protected by GPL - GNU GENERAL PUBLIC LICENSE. */ - #ifndef _CALLGRAPH_H_ #define _CALLGRAPH_H_ /** * @file callgraph.h * - * This file contains the representation of the callgraph. - * The nodes of the call graph are ir_graphs. The edges between - * the nodes are calling relations. I.e., if method a calls method - * b at some point, there is an edge between a and b. - * - * Further this file contains an algorithm to construct the call - * graph. The construction of the callgraph uses the callee - * information in Call nodes to determine which methods are called. + * This file contains the representation of the callgraph. + * The nodes of the call graph are ir_graphs. The edges between + * the nodes are calling relations. I.e., if method a calls method + * b at some point, there is an edge between a and b. * - * Finally this file contains an algorithm that computes backedges - * in the callgraph, i.e., the algorithm finds possibly recursive calls. - * The algorithm computes an upper bound of all recursive calls. + * Further this file contains an algorithm to construct the call + * graph. The construction of the callgraph uses the callee + * information in Call nodes to determine which methods are called. * + * Finally this file contains an algorithm that computes backedges + * in the callgraph, i.e., the algorithm finds possibly recursive calls. + * The algorithm computes an upper bound of all recursive calls. */ - -#include "irgraph.h" +#include "firm_types.h" /** Flag to indicate state of callgraph. */ typedef enum { - irp_callgraph_none, - irp_callgraph_consistent, /* calltree is inconsistent */ - irp_callgraph_inconsistent, - irp_callgraph_and_calltree_consistent + irp_callgraph_none, /**< No callgraph allocated. */ + irp_callgraph_consistent, /**< Callgraph constistent but calltree is inconsistent */ + irp_callgraph_inconsistent, /**< Callgraph is allocated but inconsistent. */ + irp_callgraph_and_calltree_consistent /**< Both callgraph and calltree are consistent. */ } irp_callgraph_state; + +/** Returns the callgraph state of the program representation. */ irp_callgraph_state get_irp_callgraph_state(void); + +/** Sets the callgraph state of the program representation. */ void set_irp_callgraph_state(irp_callgraph_state s); -/** The functions that call irg. */ +/** Returns the number of procedures that call the given irg. */ int get_irg_n_callers(ir_graph *irg); + +/** Returns the caller at position pos. */ ir_graph *get_irg_caller(ir_graph *irg, int pos); +/** Returns non-zero if the caller at position pos is "a backedge", i.e. a recursion. */ int is_irg_caller_backedge(ir_graph *irg, int pos); + +/** Returns non-zero if the irg has a backedge caller. */ int has_irg_caller_backedge(ir_graph *irg); -/** maximal loop depth of call nodes that call along this edge. */ +/** Returns the maximal loop depth of call nodes that call along this edge. */ int get_irg_caller_loop_depth(ir_graph *irg, int pos); -/** The functions called by irg. */ +/** Returns the number of procedures that are called by the given irg. */ int get_irg_n_callees(ir_graph *irg); + +/** Returns the callee at position pos. */ ir_graph *get_irg_callee(ir_graph *irg, int pos); +/** Returns non-zero if the callee at position pos is "a backedge", i.e. a recursion. */ int is_irg_callee_backedge(ir_graph *irg, int pos); + +/** Returns non-zero if the irg has a backedge callee. */ int has_irg_callee_backedge(ir_graph *irg); -/** maximal loop depth of call nodes that call along this edge. */ +/** Returns the maximal loop depth of call nodes that call along this edge. */ int get_irg_callee_loop_depth(ir_graph *irg, int pos); -/** Maximal loop depth of all paths from an external visible method to +/** Returns the maximal loop depth of all paths from an external visible method to this irg. */ int get_irg_loop_depth(ir_graph *irg); -/** Maximal recursion depth of all paths from an external visible method to +/** Returns the maximal recursion depth of all paths from an external visible method to this irg. */ int get_irg_recursion_depth(ir_graph *irg); -double get_irg_method_execution_frequency (ir_graph *irg); +/** Returns the method execution frequency of a graph. */ +double get_irg_method_execution_frequency(ir_graph *irg); /** * Construct the callgraph. Expects callee information, i.e., @@ -87,9 +99,25 @@ void free_callgraph(void); /** A function type for functions passed to the callgraph walker. */ typedef void callgraph_walk_func(ir_graph *g, void *env); +/** + * Walks over the callgraph. + * + * Walks over the callgraph, starting at the irp main graph. + * Visits ALL graphs in the irp, even if not reached by the main irg, but for + * those the call order is not guaranteed. + * + * Executes pre before visiting the predecessor of a node, post after. + * The void* env can be used to pass status information between the + * pre and post functions. + * + * @param pre - walker function, executed before the predecessor of a node are visited + * @param post - walker function, executed after the predecessor of a node are visited + * @param env - environment, passed to pre and post + */ void callgraph_walk(callgraph_walk_func *pre, callgraph_walk_func *post, void *env); -/** Compute the backedges that represent recursions and a looptree. +/** + * Compute the backedges that represent recursions and a looptree. */ void find_callgraph_recursions(void); @@ -105,6 +133,8 @@ void find_callgraph_recursions(void); * on all paths reaching this method. * - The execution frequency. As loop depth, but the edge weight is the sum * of the execution frequencies of all Calls along the edge. + * + * Expects the main irg is set, see set_irp_main_irg(); **/ void compute_performance_estimates(void); @@ -115,20 +145,27 @@ void compute_performance_estimates(void); * * Computes callee info and the callgraph if * this information is not available. + * + * Expects the main irg is set, see set_irp_main_irg(); */ void analyse_loop_nesting_depth(void); -/** State of loop nesting depth. */ +/** The state of loop nesting depth. */ typedef enum { - loop_nesting_depth_none, /**< Loop nesting depths are not computed, no memory is - allocated, access fails. */ - loop_nesting_depth_consistent, /**< Loop nesting depth information is computed and correct. */ - loop_nesting_depth_inconsistent /**< Loop nesting depth is computed but the graphs have been - changed since. */ + loop_nesting_depth_none, /**< Loop nesting depths are not computed, no memory is + allocated, access fails. */ + loop_nesting_depth_consistent, /**< Loop nesting depth information is computed and correct. */ + loop_nesting_depth_inconsistent /**< Loop nesting depth is computed but the graphs have been + changed since. */ } loop_nesting_depth_state; +/** Returns the nesting depth state of the program representation. */ loop_nesting_depth_state get_irp_loop_nesting_depth_state(void); + +/** Sets the nesting depth state of the program representation. */ void set_irp_loop_nesting_depth_state(loop_nesting_depth_state s); + +/** Marks the nesting depth state of the program representation as inconsistent. */ void set_irp_loop_nesting_depth_state_inconsistent(void);