added commentsdded some

[r153]

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,

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_ */

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

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_ */