From b7361986b768bb5038e052bd428481de56eeb906 Mon Sep 17 00:00:00 2001 From: =?utf8?q?G=C3=B6tz=20Lindenmaier?= Date: Fri, 25 May 2001 14:36:36 +0000 Subject: [PATCH] added commentsdded some [r153] --- ir/ir/ircons.h | 40 ++++---------------------- ir/ir/irgraph.h | 40 +++++++++++++++++++++++++- ir/ir/irnode.h | 74 ++++++++++++++++++++++++++++++++++++------------- ir/ir/irprog.h | 10 ++++++- 4 files changed, 108 insertions(+), 56 deletions(-) diff --git a/ir/ir/ircons.h b/ir/ir/ircons.h index 4cbdc3e2f..240b8d4bf 100644 --- a/ir/ir/ircons.h +++ b/ir/ir/ircons.h @@ -194,7 +194,7 @@ * ------------------ * Not yet documented. See irmode.h. * - * GLOBAL VARIABLES + * GLOBAL VARIABLES -- now also fields of ir_graph. * ================ * * current_ir_graph Points to the current ir_graph. All constructors for @@ -209,41 +209,11 @@ * * * - * CONSTRUCTOR FOR IR_GRAPH + * CONSTRUCTOR FOR IR_GRAPH --> see irgraph.h * ======================== * - * ir_graph *new_ir_graph (entity *ent, int params); - * ------------------------------------------------- - * - * This constructor generates the basic infrastructure needed to - * represent a procedure in FIRM. - * - * The parameters of new_ir_graph are: - * - * *ent A pointer to an entity representing the procedure. - * - * params An integer giving the number of local variables in the - * procedure. - * - * It allocates an ir_graph and sets current_ir_graph to point to this - * graph. Further it allocates the following nodes needed for every - * procedure: - * - * * The start block containing a start node and Proj nodes for it's - * five results (X, M, P, P, T). - * * The end block containing an end node. This block is not matured - * after executing new_ir_graph as predecessors need to be added to it. - * (Maturing a block means fixing it's number of predecessors.) - * * The current block, which is empty and also not matured. - * - * Further it enters the global store into the datastructure of the start - * block that contanis all valid values in this block (set_store()). This - * datastructure is used to build the Phi nodes and removed after completion - * of the graph. - * There is no path from end to start in the graph after calling ir_graph. - * * - * PROCEDURE TO CONSTRUCT AN IR GRAPH + * PROCEDURE TO CONSTRUCT AN IR GRAPH --> see also Firm tutorial * ================================== * * This library supplies several interfaces to construct a FIRM graph for @@ -269,7 +239,7 @@ * First the Frontend needs to decide which variables and values used in * a procedure can be represented by dataflow edges. These are variables * that need not be saved to memory as they cause no side effects visible - * out of the procedure. In general these are all compiler generated + * out of the procedure. Often these are all compiler generated * variables and simple local variables of the procedure as integers, * reals and pointers. The frontend has to count and number these variables. * @@ -1197,7 +1167,7 @@ ir_node *new_Return (ir_node *store, int arity, ir_node **in); ir_node *new_Raise (ir_node *store, ir_node *obj); ir_node *new_Const (ir_mode *mode, tarval *con); ir_node *new_SymConst (type_or_id_p value, symconst_kind kind); -ir_node *new_simpleSel (ir_node *store, ir_node *objptr, entity *ent); +ir_node *new_simpleSel(ir_node *store, ir_node *objptr, entity *ent); ir_node *new_Sel (ir_node *store, ir_node *objptr, int arity, ir_node **in, entity *ent); ir_node *new_Call (ir_node *store, ir_node *callee, int arity, ir_node **in, diff --git a/ir/ir/irgraph.h b/ir/ir/irgraph.h index 11329dbe1..dcca7be46 100644 --- a/ir/ir/irgraph.h +++ b/ir/ir/irgraph.h @@ -22,6 +22,43 @@ typedef struct ir_node ir_node; typedef struct ir_graph ir_graph; #endif +/***** irgraph/irgraph + * + * NAME Datastructure that holds central information about a procedure + * + * NOTE + ** ir_graph *new_ir_graph (entity *ent, int params); + * ------------------------------------------------- + * + * This constructor generates the basic infrastructure needed to + * represent a procedure in FIRM. + * + * The parameters of new_ir_graph are: + * + * *ent A pointer to an entity representing the procedure. + * + * params An integer giving the number of local variables in the + * procedure. + * + * It allocates an ir_graph and sets current_ir_graph to point to this + * graph. Further it allocates the following nodes needed for every + * procedure: + * + * * The start block containing a start node and Proj nodes for it's + * five results (X, M, P, P, T). + * * The end block containing an end node. This block is not matured + * after executing new_ir_graph as predecessors need to be added to it. + * (Maturing a block means fixing it's number of predecessors.) + * * The current block, which is empty and also not matured. + * + * Further it enters the global store into the datastructure of the start + * block that contanis all valid values in this block (set_store()). This + * datastructure is used to build the Phi nodes and removed after + * completion of the graph. There is no path from end to start in the + * graph after calling ir_graph. + * SOURCE + */ + /* Global variable holding the current_ir_graph. This global variable is used by the ir construction interface in ircons and by the optimizations. */ @@ -30,7 +67,7 @@ extern ir_graph *current_ir_graph; /* Create a new ir graph to built ir for a procedure. ent is the entity representing this procedure, i.e., the type of the entity must be of a method type. The constructor automatically sets the - field irg of the entity to the new ir graph. + field irg of the entity as well as current_ir_graph to the new ir graph. n_loc is the number of local variables in this procedure including the procedure parameters. */ ir_graph *new_ir_graph (entity *ent, int n_loc); @@ -83,5 +120,6 @@ void set_irg_visited(ir_graph *irg, unsigned long i); void inc_irg_block_visited(ir_graph *irg); unsigned long get_irg_block_visited (ir_graph *irg); void set_irg_block_visited(ir_graph *irg, unsigned long i); +/*****/ # endif /* _IRGRAPH_H_ */ diff --git a/ir/ir/irnode.h b/ir/ir/irnode.h index 5df68e6e1..477e5704e 100644 --- a/ir/ir/irnode.h +++ b/ir/ir/irnode.h @@ -21,22 +21,32 @@ recursion between irnode.h and irgraph.h */ #ifndef _IR_NODE_TYPEDEF_ #define _IR_NODE_TYPEDEF_ +/****s* irnode/irnode + * + * NAME ir_node - a datatype representing a Firm node + * + * NOTE Not properly documented ;-) + * + * ATTRIBUTES + * The common fields are: + * + * firm_kind A firm_kind tag containing k_type. This is useful + * for dynamically checking whether a node is a ir_node. + * arity The number of predecessors in the Firm graph. + * in A list with the predecessors in the Firm graph. There are + * routines to access individual elements and to obtain the + * array. The method returning the array should not be used. + * mode The mode of the node. There are routines to get the mode but + * also to access the mode's fields directly. + * opcode The opcode of the node. There are routines to get the opcode but + * also to access the opcode's fields directly. + * node_nr A unique number for the node. Available only if debugging is + * turned on. + * SOURCE + */ typedef struct ir_node ir_node; #endif -/* irnode constructor */ -/* Create a new irnode in irg, with an op, mode, arity and */ -/* some incoming irnodes. */ -/* If arity is negative, a node with a dynamic array is created. */ - -inline ir_node * -new_ir_node (ir_graph *irg, - ir_node *block, - ir_op *op, - ir_mode *mode, - int arity, - ir_node **in); - /** Manipulate the fields of ir_node. With these access routines you can work on the graph without considering the different types of nodes, it's just a big graph. **/ @@ -75,8 +85,29 @@ inline ir_node *get_irn_link (ir_node *node); /* Outputs a unique number for this node */ inline long get_irn_node_nr(ir_node *node); #endif +/*****/ + +/* irnode constructor */ +/* Create a new irnode in irg, with an op, mode, arity and */ +/* some incoming irnodes. */ +/* If arity is negative, a node with a dynamic array is created. */ + +inline ir_node * +new_ir_node (ir_graph *irg, + ir_node *block, + ir_op *op, + ir_mode *mode, + int arity, + ir_node **in); -/** Manipulate fields of individual nodes. **/ +/****s* irnode/other + * + * NAME access functions for node fields. + * + * NOTE Not properly documented ;-) + * + * SOURCE + */ /* this works for all except Block */ inline ir_node *get_nodes_Block (ir_node *node); @@ -375,11 +406,16 @@ inline void set_Tuple_pred (ir_node *node, int pos, ir_node *pred); inline ir_node *get_Id_pred (ir_node *node); inline void set_Id_pred (ir_node *node, ir_node *pred); +/*****/ - -/******************************************************************/ -/* Auxiliary routines */ -/******************************************************************/ +/****s* irnode/other2 + * + * NAME Auxiliary routines + * + * NOTE Not properly documented ;-) + * + * SOURCE + */ /* returns operand of node if node is a Proj. */ inline ir_node *skip_Proj (ir_node *node); @@ -396,7 +432,7 @@ int is_cfop(ir_node *node); of an exception. */ int is_fragile_op(ir_node *node); - +/*****/ /* Makros for debugging the libfirm */ #ifdef DEBUG_libfirm diff --git a/ir/ir/irprog.h b/ir/ir/irprog.h index bd487df8f..ab9f5a19a 100644 --- a/ir/ir/irprog.h +++ b/ir/ir/irprog.h @@ -21,7 +21,14 @@ # include "irnode.h" # include "type.h" - +/***** irprog/irprog + * + * NAME Datastructure that holds central information about a program + * + * NOTE Preliminary documentation ;-) + * + * SOURCE + */ typedef struct ir_prog ir_prog; /* A variable from where everything in the ir can be accessed. */ @@ -57,5 +64,6 @@ type *get_glob_type(void); /* Returns a new, unique number to number nodes or the like. */ int get_irp_new_node_nr(); #endif +/*****/ #endif /* ifndef _IRPROG_H_ */ -- 2.20.1