added visibility flag for types.
[libfirm] / ir / tr / type.h
index 903e9d6..464944c 100644 (file)
@@ -36,7 +36,7 @@
 # ifndef _TYPE_H_
 # define _TYPE_H_
 
-# include <stdbool.h>
+#include <stdbool.h>
 
 # include "tpop.h"
 # include "firm_common.h"
@@ -44,7 +44,6 @@
 # include "irmode.h"
 # include "dbginfo.h"
 
-
 /* to resolve recursion between entity.h and type.h */
 #ifndef _ENTITY_TYPEDEF_
 #define _ENTITY_TYPEDEF_
@@ -56,6 +55,8 @@ typedef struct entity entity;
 typedef struct ir_node ir_node;
 #endif
 
+# include "tr_inheritance.h"
+
 /**
  *  An abstract data type to represent types.
  *
@@ -82,9 +83,13 @@ typedef struct ir_node ir_node;
  *  - name:      An identifier specifying the name of the type.  To be
  *               set by the frontend.
  *  - size:      The size of the type, i.e. an entity of this type will
- *               occupy size bytes in memory.  In several cases this is
+ *               occupy size bits in memory.  In several cases this is
  *               determined when fixing the layout of this type (class,
  *               struct, union, array, enumeration).
+ *  - alignment  The alignment of the type, i.e. an entity of this type will
+ *               be allocated an an address in memory with this alignment.
+ *               In several cases this is determined when fixing the layout
+ *               of this type (class, struct, union, array)
  *  - state:     The state of the type.  The state represents whether the
  *               layout of the type is undefined or fixed (values: layout_undefined
  *               or layout_fixed).  Compound types can have an undefined
@@ -110,7 +115,7 @@ typedef struct ir_node ir_node;
  *  @link pointer_type pointer @endlink, @link primitive_type primitive @endlink
  *
  *  @todo
- *     mode maybe not global field??
+ *      mode maybe not global field??
  */
 #ifndef _TYPE_TYPEDEF_
 #define _TYPE_TYPEDEF_
@@ -125,38 +130,111 @@ typedef struct type type;
 */
 void        free_type_entities(type *tp);
 
-/** Frees the memory used by the type.   Does not free the entities
-    belonging to the type, except for the array element entity.
-    Does not free if tp is "none" or "unknown".
-    Frees entities in value param subtypes of method types!!! Make sure these
-    are not referenced any more. */
+/** Frees the memory used by the type.
+ *
+ * Removes the type from the type list. Does not free the entities
+ * belonging to the type, except for the array element entity.  Does
+ * not free if tp is "none" or "unknown".  Frees entities in value
+ * param subtypes of method types!!! Make sure these are not
+ * referenced any more.  Further make sure there is no pointer type
+ * that refers to this type.                           */
 void        free_type(type *tp);
 
-tp_op*      get_type_tpop(type *tp);
-ident*      get_type_tpop_nameid(type *tp);
-const char* get_type_tpop_name(type *tp);
-tp_opcode   get_type_tpop_code(type *tp);
+const tp_op*get_type_tpop(const type *tp);
+ident*      get_type_tpop_nameid(const type *tp);
+const char* get_type_tpop_name(const type *tp);
+tp_opcode   get_type_tpop_code(const type *tp);
 
-ident*      get_type_ident(type *tp);
+ident*      get_type_ident(const type *tp);
 void        set_type_ident(type *tp, ident* id);
-const char* get_type_name(type *tp);
+const char* get_type_name(const type *tp);
+
+/** This enumeration flags the visibility of entities and types.
+ *
+ * This is necessary for partial compilation.
+ * We rely on the ordering of the flags.
+ */
+typedef enum {
+  visibility_local,              /**< The entity is only visible locally.  This is the default for
+                                     entities.
+                                     The type is only visible locally.  All instances are allocated
+                                     locally, and no pointer to entities of this type are passed
+                                     out of this compilation unit. */
+  visibility_external_visible,   /**< The entity is visible to other external program parts, but
+                                     it is defined here.  It may not be optimized away.  The entity must
+                                     be static_allocated.
+                                     For types:  entities of this type can be accessed externaly.  No
+                                     instances of this type are allocated externally.  */
+  visibility_external_allocated  /**< The entity is defined and allocated externally.  This compilation
+                                     must not allocate memory for this entity. The entity must
+                                     be static_allocated.  This can also be an external defined
+                                     method.
+                                     For types:  entities of this type are allocated and accessed from
+                                     external code.  Default for types.  */
+} visibility;
+
+/** The visibility of a type.
+ *
+ *  The visibility of a type indicates, whether entities of this type
+ *  are accessed or allocated in external code.
+ *
+ *  An entity of a type is allocated in external code, if the external
+ *  code declares a variable of this type, or dynamically allocates
+ *  an entity of this type.  If the external code declares a (compound)
+ *  type, that contains entities of this type, the visibility also
+ *  must be external_allocated.
+ *
+ *  The visibility must be higher than that of all entities, if the
+ *  type is a compound.  Here it is questionable, what happens with
+ *  static entities.  If these are accessed external by direct reference,
+ *  (a static call to a method, that is also in the dispatch table)
+ *  it should not affect the visibility of the type.
+ *
+ *
+ * @@@ Do we need a visibility for types?
+ * I change the layout of types radically when doing type splitting.
+ * I need to know, which fields of classes are accessed in the rts,
+ * e.g., [_length.  I may not move [_length to the split part.
+ * The layout though, is a property of the type.
+ *
+ * One could also think of changing the mode of a type ...
+ *
+ * But, we could also output macros to access the fields, e.g.,
+ *  ACCESS_[_length (X)   X->length              // conventional
+ *  ACCESS_[_length (X)   X->_split_ref->length  // with type splitting
+ *
+ * For now I implement this function, that returns the visibility
+ * based on the visibility of the entities of a compound ...
+ *
+ * This function returns visibility_external_visible if one or more
+ * entities of a compound type have visibility_external_visible.
+ * Entities of types are never visibility_external_allocated (right?).
+ * Else returns visibility_local.
+ */
+visibility get_type_visibility (const type *tp);
+void       set_type_visibility (type *tp, visibility v);
+
+
 
 /** The state of the type layout. */
 typedef enum {
   layout_undefined,    /**< The layout of this type is not defined.
-                         Address computation to access fields is not
-                         possible, fields must be accessed by Sel
-                         nodes.  This is the default value except for
-                         pointer, primitive and method types. */
+              Address computation to access fields is not
+              possible, fields must be accessed by Sel
+              nodes.  This is the default value except for
+              pointer, primitive and method types. */
   layout_fixed         /**< The layout is fixed, all component/member entities
-                         have an offset assigned.  Size of the type is known.
-                         Arrays can be accessed by explicit address
-                         computation. Default for pointer, primitive and method
-                         types.  */
+              have an offset assigned.  Size of the type is known.
+              Arrays can be accessed by explicit address
+              computation. Default for pointer, primitive and method
+              types.  */
 } type_state;
 
+/** Returns a human readable string for the enum entry. */
+const char *get_type_state_name(type_state s);
+
 /** Returns the type layout state of a type. */
-type_state  get_type_state(type *tp);
+type_state  get_type_state(const type *tp);
 
 /** Sets the type layout state of a type.
  *
@@ -169,7 +247,7 @@ void        set_type_state(type *tp, type_state state);
  *
  * Returns NULL for all non atomic types.
  */
-ir_mode*    get_type_mode(type *tp);
+ir_mode*    get_type_mode(const type *tp);
 
 /** Sets the mode of a type.
  *
@@ -177,12 +255,12 @@ ir_mode*    get_type_mode(type *tp);
  */
 void        set_type_mode(type *tp, ir_mode* m);
 
-/** Returns the size of a type in bytes, retuns -1 if the size is NOT
+/** Returns the size of a type in bytes, returns -1 if the size is NOT
  *  a byte size, ie not dividable by 8. */
-int         get_type_size_bytes(type *tp);
+int         get_type_size_bytes(const type *tp);
 
 /** Returns the size of a type in bits. */
-int         get_type_size_bits(type *tp);
+int         get_type_size_bits(const type *tp);
 
 /** Sets the size of a type in bytes.
  *
@@ -198,15 +276,42 @@ void        set_type_size_bytes(type *tp, int size);
  */
 void        set_type_size_bits(type *tp, int size);
 
+/** Returns the alignment of a type in bytes.
+ *
+ *  Returns -1 if the alignment is NOT
+ *  a byte size, i.e. not dividable by 8. Calls get_type_alignment_bits(). */
+int         get_type_alignment_bytes(type *tp);
 
-unsigned long get_type_visited(type *tp);
+/** Returns the alignment of a type in bits.
+ *
+ *  If the alignment of a type is
+ *  not set, it is calculated here according to the following rules:
+ *  1.) if a type has a mode, the alignment is the mode size.
+ *  2.) compound types have the alignment of it's biggest member.
+ *  3.) array types have the alignment of its element type.
+ *  4.) method types return 0 here.
+ *  5.) all other types return 8 here (i.e. aligned at byte).
+ */
+int         get_type_alignment_bits(type *tp);
+
+/** Sets the alignment of a type in bytes. */
+void        set_type_alignment_bytes(type *tp, int size);
+
+/** Sets the alignment of a type in bits.
+ *
+ * For method types the alignment is always fixed.
+ * This call is legal but has no effect.
+ */
+void        set_type_alignment_bits(type *tp, int size);
+
+unsigned long get_type_visited(const type *tp);
 void          set_type_visited(type *tp, unsigned long num);
 /* Sets visited field in type to type_visited. */
 void          mark_type_visited(type *tp);
-/* @@@ name clash!! int           type_visited(type *tp); */
-int           type_not_visited(type *tp);
+/* @@@ name clash!! int           type_visited(const type *tp); */
+int           type_not_visited(const type *tp);
 
-void*         get_type_link(type *tp);
+void*         get_type_link(const type *tp);
 void          set_type_link(type *tp, void *l);
 
 /**
@@ -233,10 +338,10 @@ void          inc_master_type_visited(void);
  * @return
  *     true if the thing is a type, else false
  */
-int is_type            (void *thing);
+int is_type            (const void *thing);
 
 /**
- *   Checks whether two types are structural equal.
+ *   Checks whether two types are structurally equal.
  *
  *   @param st pointer type
  *   @param lt pointer type
@@ -270,7 +375,7 @@ int is_type            (void *thing);
  *       This is to avoid endless recursions; with pointer types circlic
  *       type graphs are possible.)
  */
-bool equal_type(type *tpy1, type *typ2);
+int equal_type(type *tpy1, type *typ2);
 
 /**
  *   Checks whether two types are structural comparable.
@@ -307,10 +412,10 @@ bool equal_type(type *tpy1, type *typ2);
  *      @return smaller than the points_to type of lt.
  *
  */
-bool smaller_type (type *st, type *lt);
+int smaller_type (type *st, type *lt);
 
 /**
- *  @page class_type   Representation of a class type
+ *  @page class_type    Representation of a class type
  *
  *  If the type opcode is set to type_class the type represents class
  *  types.  A list of fields and methods is associated with a class.
@@ -330,9 +435,9 @@ bool smaller_type (type *st, type *lt);
  *  - supertypes: A list of direct superclasses.
  *
  *  - peculiarity: The peculiarity of this class.  If the class is of peculiarity
- *                 "description" it only is a description of requirememts to a class,
+ *                 "description" it only is a description of requirements to a class,
  *                 as, e.g., a Java interface.  The class will never be allocated.
- *                 Peculiatity inherited is only possible for entities.  An entity
+ *                 Peculiarity inherited is only possible for entities.  An entity
  *                 is of peculiarity inherited if the compiler generated the entity
  *                 to explicitly resolve inheritance.  An inherited method entity has
  *                 no value for irg.
@@ -352,48 +457,58 @@ type   *new_d_type_class (ident *name, dbg_info *db);
 void    add_class_member   (type *clss, entity *member);
 
 /** Returns the number of members of this class. */
-int     get_class_n_members (type *clss);
+int     get_class_n_members (const type *clss);
 
 /** Returns the member at position pos, 0 <= pos < n_member */
-entity *get_class_member   (type *clss, int pos);
+entity *get_class_member   (const type *clss, int pos);
 
 /** Returns index of mem in clss, -1 if not contained. */
 int     get_class_member_index(type *clss, entity *mem);
 
 /** Finds the member with name 'name'. If several members with the same
   name returns one of them.  Returns NULL if no member found. */
*  name returns one of them.  Returns NULL if no member found. */
 entity *get_class_member_by_name(type *clss, ident *name);
 
 /** Overwrites the member at position pos, 0 <= pos < n_member with
-   the passed entity. */
*  the passed entity. */
 void    set_class_member   (type *clss, entity *member, int pos);
 
 /** Replaces complete member list in class type by the list passed.
-   Copies the list passed. This function is necessary to reduce the number of members.
-   members is an array of entities, num the size of this array.  Sets all
-   owners of the members passed to clss. */
+ *
+ *  Copies the list passed. This function is necessary to reduce the number of members.
+ *  members is an array of entities, num the size of this array.  Sets all
+ *  owners of the members passed to clss. */
 void    set_class_members  (type *clss, entity *members[], int arity);
 
 /** Finds member in the list of members and removes it.
-   Shrinks the member list, so iterate from the end!!!
-   Does not deallocate the entity.  */
+ *
+ *  Shrinks the member list, so iterate from the end!!!
+ *  Does not deallocate the entity.  */
 void    remove_class_member(type *clss, entity *member);
 
 
 /** Adds subtype as subtype to clss.
-   Checks whether clss is a supertype of subtype.  If not
-   adds also clss as supertype to subtype.  */
+ *
+ *  Checks whether clss is a supertype of subtype.  If not
+ *  adds also clss as supertype to subtype.  */
 void    add_class_subtype   (type *clss, type *subtype);
 
 /** Returns the number of subtypes */
-int     get_class_n_subtypes (type *clss);
+int     get_class_n_subtypes (const type *clss);
 
 /** Gets the subtype at position pos, 0 <= pos < n_subtype. */
 type   *get_class_subtype   (type *clss, int pos);
 
-/** Sets the subtype at positioin pos, 0 <= pos < n_subtype.
-   Does not set the corresponding supertype relation for subtype: this might
-   be a different position! */
+/** Returns the index to access subclass as subtype of class.
+ *
+ *  If subclass is no direct subtype of class returns -1.
+ */
+int get_class_subtype_index(type *clss, const type *subclass);
+
+/** Sets the subtype at position pos, 0 <= pos < n_subtype.
+ *
+ *  Does not set the corresponding supertype relation for subtype: this might
+ *  be a different position! */
 void    set_class_subtype   (type *clss, type *subtype, int pos);
 
 /** Finds subtype in the list of subtypes and removes it  */
@@ -401,22 +516,27 @@ void    remove_class_subtype(type *clss, type *subtype);
 
 
 /** Adds supertype as supertype to class.
-   Checks whether clss is a subtype of supertype.  If not
-   adds also clss as subtype to supertype.  */
+ *
+ *  Checks whether clss is a subtype of supertype.  If not
+ *  adds also clss as subtype to supertype.  */
 void    add_class_supertype   (type *clss, type *supertype);
 
 /** Returns the number of supertypes */
-int     get_class_n_supertypes (type *clss);
+int     get_class_n_supertypes (const type *clss);
 
-/** Returns the index of an supertype in a type. */
+/** Returns the index to access superclass as supertype of class.
+ *
+ *  If superclass is no direct supertype of class returns -1.
+ */
 int     get_class_supertype_index(type *clss, type *super_clss);
 
 /** Gets the supertype at position pos,  0 <= pos < n_supertype. */
 type   *get_class_supertype   (type *clss, int pos);
 
-/** Sets the supertype at postition pos, 0 <= pos < n_subtype.
-   Does not set the corresponding subtype relation for supertype: this might
-   be a different position! */
+/** Sets the supertype at position pos, 0 <= pos < n_supertype.
+ *
+ *  Does not set the corresponding subtype relation for supertype: this might
+ *  be at a different position! */
 void    set_class_supertype   (type *clss, type *supertype, int pos);
 
 /** Finds supertype in the list of supertypes and removes it */
@@ -425,39 +545,36 @@ void    remove_class_supertype(type *clss, type *supertype);
 /** This enumeration flags the peculiarity of entities and types. */
 typedef enum peculiarity {
   peculiarity_description,     /**< Represents only a description.  The entity/type is never
-                                   allocated, no code/data exists for this entity/type.
-                                   @@@ eventually rename to descriptive (adjectiv as the others!)*/
+                            allocated, no code/data exists for this entity/type.
+                        @@@ eventually rename to descriptive (adjective as the others!)*/
   peculiarity_inherited,       /**< Describes explicitly that other entities are
-                                   inherited to the owner of this entity.
-                                   Overwrites must refer to at least one other
-                                   entity.  If this is a method entity there exists
-                                   no irg for this entity, only for one of the
-                                   overwritten ones.
-                                   Only for entity. */
+                            inherited to the owner of this entity.
+                            Overwrites must refer to at least one other
+                            entity.  If this is a method entity there exists
+                            no irg for this entity, only for one of the
+                            overwritten ones.
+                        Only for entity. */
   peculiarity_existent         /**< The entity/type (can) exist.
-                                   @@@ eventually rename to 'real' i.e., 'echt'
-                                   This serves better as opposition to description _and_ inherited.*/
+                    @@@ eventually rename to 'real' i.e., 'echt'
+                        This serves better as opposition to description _and_ inherited.*/
 } peculiarity;
-char *get_peculiarity_string(peculiarity p);
+const char *get_peculiarity_string(peculiarity p);
 
 /* The peculiarity of the class.  The enumeration peculiarity is defined
    in entity.h */
-peculiarity get_class_peculiarity (type *clss);
+peculiarity get_class_peculiarity (const type *clss);
 void        set_class_peculiarity (type *clss, peculiarity pec);
 
 /* Set and get a class' dfn --
    @todo This is an undocumented field, subject to change! */
 void set_class_dfn (type *clss, int dfn);
-int  get_class_dfn (type *clss);
+int  get_class_dfn (const type *clss);
 
 /** Returns true if a type is a class type. */
-int is_class_type(type *clss);
-
-/** Returns true if low is subclass of high. */
-bool is_subclass_of(type *low, type *high);
+int is_Class_type(const type *clss);
 
 /**
- *  @page struct_type  Representation of a struct type
+ *  @page struct_type   Representation of a struct type
  *
  *  Type_strct represents aggregate types that consist of a list
  *  of fields.
@@ -465,7 +582,7 @@ bool is_subclass_of(type *low, type *high);
  *  - member:  All entities belonging to this class.  This are the fields
  *             that can have any of the following types:  type_class,
  *             type_struct, type_union, type_array, type_enumeration,
- *            type_pointer, type_primitive.
+ *             type_pointer, type_primitive.
  *             This is a dynamic list that can be grown with an "add_" function,
  *             but not shrinked.
  *             This is a dynamic list that can be grown with an "add_" function,
@@ -482,10 +599,10 @@ type   *new_d_type_struct (ident *name, dbg_info* db);
 void    add_struct_member   (type *strct, entity *member);
 
 /** Returns the number of members of this struct. */
-int     get_struct_n_members (type *strct);
+int     get_struct_n_members (const type *strct);
 
 /** Returns the member at position pos, 0 <= pos < n_member */
-entity *get_struct_member   (type *strct, int pos);
+entity *get_struct_member   (const type *strct, int pos);
 
 /** Returns index of member in strct, -1 if not contained. */
 int     get_struct_member_index(type *strct, entity *member);
@@ -498,10 +615,10 @@ void    set_struct_member   (type *strct, int pos, entity *member);
 void    remove_struct_member (type *strct, entity *member);
 
 /** Returns true if a type is a struct type. */
-int     is_struct_type(type *strct);
+int     is_Struct_type(const type *strct);
 
 /**
- * @page method_type   Representation of a method type
+ * @page method_type    Representation of a method type
  *
  * A method type represents a method, function or procedure type.
  * It contains a list of the parameter and result types, as these
@@ -534,7 +651,7 @@ int     is_struct_type(type *strct);
  *               method type) that represent results passed by value.
  */
 
-/* These makros define the suffixes for the types and entities used
+/* These macros define the suffixes for the types and entities used
    to represent value parameters / results. */
 #define VALUE_PARAMS_SUFFIX  "val_param"
 #define VALUE_RESS_SUFFIX    "val_res"
@@ -565,7 +682,7 @@ type *new_d_type_method (ident *name, int n_param, int n_res, dbg_info* db);
 /* -- manipulate private fields of method. -- */
 
 /** Returns the number of parameters of this method. */
-int   get_method_n_params  (type *method);
+int   get_method_n_params  (const type *method);
 
 /** Returns the type of the parameter at position pos of a method. */
 type *get_method_param_type(type *method, int pos);
@@ -579,9 +696,9 @@ entity *get_method_value_param_ent(type *method, int pos);
 /**
  * Returns a type that represents the copied value arguments.
  */
-type *get_method_value_param_type(type *method);
+type *get_method_value_param_type(const type *method);
 
-int   get_method_n_ress   (type *method);
+int   get_method_n_ress   (const type *method);
 type *get_method_res_type(type *method, int pos);
 /** Sets the type of the result at position pos of a method.
     Also changes the type in the pass-by-value representation by just
@@ -590,10 +707,11 @@ void  set_method_res_type(type *method, int pos, type* tp);
 /** Returns an entity that represents the copied value result.  Only necessary
    for compounds passed by value. This information is constructed only on demand. */
 entity *get_method_value_res_ent(type *method, int pos);
+
 /**
  * Returns a type that represents the copied value results.
  */
-type *get_method_value_res_type(type *method);
+type *get_method_value_res_type(const type *method);
 
 /**
  * this enum flags the variadicity of methods (methods with a
@@ -601,15 +719,15 @@ type *get_method_value_res_type(type *method);
  * non_variadic.
  */
 typedef enum variadicity {
-  variadicity_non_variadic,    /**< non variadic */
-  variadicity_variadic         /**< variadic */
+  variadicity_non_variadic, /**< non variadic */
+  variadicity_variadic      /**< variadic */
 } variadicity;
 
 /** Returns the null-terminated name of this variadicity. */
 const char *get_variadicity_name(variadicity vari);
 
 /** Returns the variadicity of a method. */
-variadicity get_method_variadicity(type *method);
+variadicity get_method_variadicity(const type *method);
 
 /** Sets the variadicity of a method. */
 void set_method_variadicity(type *method, variadicity vari);
@@ -620,7 +738,7 @@ void set_method_variadicity(type *method, variadicity vari);
  * of the method type plus one is returned for variadic functions.
  * Non-variadic function types always return -1 here.
  */
-int get_method_first_variadic_param_index(type *method);
+int get_method_first_variadic_param_index(const type *method);
 
 /**
  * Sets the first variadic parameter index. This allows to specify
@@ -631,10 +749,10 @@ int get_method_first_variadic_param_index(type *method);
 void set_method_first_variadic_param_index(type *method, int index);
 
 /** Returns true if a type is a method type. */
-int   is_method_type     (type *method);
+int   is_Method_type     (const type *method);
 
 /**
- *   @page union_type  Representation of a union type.
+ *   @page union_type   Representation of a union type.
  *
  *   The union type represents union types.
  *   - n_types:     Number of unioned types.
@@ -651,13 +769,13 @@ type   *new_d_type_union (ident *name, dbg_info* db);
 /* --- manipulate private fields of struct --- */
 
 /** Returns the number of unioned types of this union */
-int     get_union_n_members      (type *uni);
+int     get_union_n_members      (const type *uni);
 
 /** Adds a new entity to a union type */
 void    add_union_member (type *uni, entity *member);
 
 /** Returns the entity at position pos of a union */
-entity *get_union_member (type *uni, int pos);
+entity *get_union_member (const type *uni, int pos);
 
 /** Overwrites a entity at position pos in a union type. */
 void    set_union_member (type *uni, int pos, entity *member);
@@ -666,10 +784,10 @@ void    set_union_member (type *uni, int pos, entity *member);
 void    remove_union_member (type *uni, entity *member);
 
 /** Returns true if a type is a union type. */
-int     is_union_type          (type *uni);
+int     is_Union_type          (const type *uni);
 
 /**
- * @page array_type    Representation of an array type
+ * @page array_type Representation of an array type
  *
  * The array type represents rectangular multi dimensional arrays.
  * The constants representing the bounds must be allocated to
@@ -683,7 +801,8 @@ int     is_union_type          (type *uni);
  *                      element selection with Sel.
  * @todo
  *   Do we need several entities?  One might want
- *   to select a dimension and not a single element in case of multidim arrays.
+ *   to select a dimension and not a single element in case of multi
+ *   dimensional arrays.
  */
 
 /** Create a new type array.
@@ -694,7 +813,7 @@ int     is_union_type          (type *uni);
  * Set dimension sizes after call to constructor with set_* routines.
  */
 type *new_type_array         (ident *name, int n_dimensions,
-                             type *element_type);
+                  type *element_type);
 
 /** Create a new type array with debug information.
  *
@@ -702,44 +821,79 @@ type *new_type_array         (ident *name, int n_dimensions,
  * Initializes order to the order of the dimensions.
  * The entity for array elements is built automatically.
  * Set dimension sizes after call to constructor with set_* routines.
+ * A legal array type must have at least one dimension set.
  */
 type *new_d_type_array         (ident *name, int n_dimensions,
-                             type *element_type, dbg_info* db);
+                  type *element_type, dbg_info* db);
 
 /* --- manipulate private fields of array type --- */
 
 /** Returns the number of array dimensions of this type. */
-int   get_array_n_dimensions (type *array);
+int   get_array_n_dimensions (const type *array);
 
-/** Allocates Const nodes of mode_I for the array dimensions */
+/**
+ * Allocates Const nodes of mode_I for one array dimension.
+ * Upper bound in Firm is the element next to the last, ie [lower,upper[
+ */
 void  set_array_bounds_int   (type *array, int dimension, int lower_bound,
                                                           int upper_bound);
+/**
+ * Sets the bounds for one array dimension.
+ * Upper bound in Firm is the element next to the last, ie [lower,upper[
+ */
 void  set_array_bounds       (type *array, int dimension, ir_node *lower_bound,
                                                           ir_node *upper_bound);
+/** Sets the lower bound for one array dimension, ie [lower,upper[ */
 void  set_array_lower_bound  (type *array, int dimension, ir_node *lower_bound);
+
+/** Allocates Const nodes of mode_I for the lower bound of an array
+    dimension, ie [lower,upper[ */
 void  set_array_lower_bound_int (type *array, int dimension, int lower_bound);
+
+/** Sets the upper bound for one array dimension, ie [lower,upper[ */
 void  set_array_upper_bound  (type *array, int dimension, ir_node *upper_bound);
-void  set_array_upper_bound_int (type *array, int dimension, int lower_bound);
-/* returns true if lower bound != Unknown */
-int       has_array_lower_bound  (type *array, int dimension);
-ir_node * get_array_lower_bound  (type *array, int dimension);
-int       has_array_upper_bound  (type *array, int dimension);
-ir_node * get_array_upper_bound  (type *array, int dimension);
 
+/** Allocates Const nodes of mode_I for the upper bound of an array
+    dimension, ie [lower,upper[ */
+void  set_array_upper_bound_int (type *array, int dimension, int upper_bound);
+
+/** returns true if lower bound != Unknown */
+int       has_array_lower_bound     (const type *array, int dimension);
+ir_node * get_array_lower_bound     (const type *array, int dimension);
+/** Works only if bound is Const node with tarval that can be converted to long. */
+long      get_array_lower_bound_int (const type *array, int dimension);
+/** returns true if lower bound != Unknown */
+int       has_array_upper_bound     (const type *array, int dimension);
+ir_node * get_array_upper_bound     (const type *array, int dimension);
+/** Works only if bound is Const node with tarval that can be converted to long. */
+long      get_array_upper_bound_int (const type *array, int dimension);
+
+/** Sets an array dimension to a specific order. */
 void set_array_order (type *array, int dimension, int order);
-int  get_array_order (type *array, int dimension);
 
+/** Returns the order of an array dimension. */
+int  get_array_order (const type *array, int dimension);
+
+/** Find the array dimension that is placed at order ord. */
+int find_array_dimension(const type *array, int order);
+
+/** Sets the array element type. */
 void  set_array_element_type (type *array, type *tp);
+
+/** Gets the array element type. */
 type *get_array_element_type (type *array);
 
+/** Sets the array element entity. */
 void  set_array_element_entity (type *array, entity *ent);
-entity *get_array_element_entity (type *array);
+
+/** Get the array element entity. */
+entity *get_array_element_entity (const type *array);
 
 /** Returns true if a type is an array type. */
-int    is_array_type(type *array);
+int    is_Array_type(const type *array);
 
 /**
- * @page enumeration_type      Representation of an enumeration type
+ * @page enumeration_type   Representation of an enumeration type
  *
  * Enumeration types need not necessarily be represented explicitly
  * by Firm types, as the frontend can lower them to integer constants as
@@ -748,7 +902,7 @@ int    is_array_type(type *array);
  * - *enum:         The target values representing the constants used to
  *                  represent individual enumerations.
  * - *enum_nameid:  Idents containing the source program name of the enumeration
- *          constants
+ *                  constants
  */
 /** Create a new type enumeration -- set the enumerators independently. */
 type   *new_type_enumeration    (ident *name, int n_enums);
@@ -759,28 +913,28 @@ type   *new_d_type_enumeration    (ident *name, int n_enums, dbg_info* db);
 /* --- manipulate fields of enumeration type. --- */
 
 /** Returns the number of enumeration values of this enumeration */
-int     get_enumeration_n_enums (type *enumeration);
+int     get_enumeration_n_enums (const type *enumeration);
 
 /** Sets the enumeration value at a given position. */
 void    set_enumeration_enum    (type *enumeration, int pos, tarval *con);
 
 /** Returns the enumeration value at a given position. */
-tarval *get_enumeration_enum    (type *enumeration, int pos);
+tarval *get_enumeration_enum    (const type *enumeration, int pos);
 
 /** Assign an ident to an enumeration value at a given position. */
 void    set_enumeration_nameid  (type *enumeration, int pos, ident *id);
 
 /** Returns the assigned ident of an enumeration value at a given position. */
-ident  *get_enumeration_nameid  (type *enumeration, int pos);
+ident  *get_enumeration_nameid  (const type *enumeration, int pos);
 
 /** Returns the assigned name of an enumeration value at a given position. */
-const char *get_enumeration_name(type *enumeration, int pos);
+const char *get_enumeration_name(const type *enumeration, int pos);
 
 /** Returns true if a type is a enumeration type. */
-int     is_enumeration_type     (type *enumeration);
+int     is_Enumeration_type     (const type *enumeration);
 
 /**
- * @page pointer_type  Representation of a pointer type
+ * @page pointer_type   Representation of a pointer type
  *
  * The mode of the pointer type must be a mode_reference.
  *
@@ -806,7 +960,7 @@ void  set_pointer_points_to_type (type *pointer, type *tp);
 type *get_pointer_points_to_type (type *pointer);
 
 /** Returns true if a type is a pointer type. */
-int   is_pointer_type            (type *pointer);
+int   is_Pointer_type            (const type *pointer);
 
 /** Returns the first pointer type that has as points_to tp.
  *  Not efficient: O(#types).
@@ -827,7 +981,7 @@ type *new_type_primitive (ident *name, ir_mode *mode);
 type *new_d_type_primitive (ident *name, ir_mode *mode, dbg_info* db);
 
 /** Returns true if a type is a primitive type. */
-int  is_primitive_type  (type *primitive);
+int  is_Primitive_type  (const type *primitive);
 
 
 /**
@@ -848,7 +1002,7 @@ int  is_primitive_type  (type *primitive);
  *    size:  0
  */
 /* A variable that contains the only none type. */
-extern type *none_type;
+extern type *firm_none_type;
 /* Returns the none type */
 type *get_none_type(void);
 
@@ -870,8 +1024,8 @@ type *get_none_type(void);
  *    size:  0
  */
 /* A variable that contains the only unknown type. */
-extern type *unknown_type;
-/* Returns the none type */
+extern type *firm_unknown_type;
+/* Returns the unknown type */
 type *get_unknown_type(void);
 
 
@@ -880,14 +1034,14 @@ type *get_unknown_type(void);
  *  @param tp - any type
  *  @return true if type is primitive, pointer or enumeration
  */
-int is_atomic_type(type *tp);
+int is_atomic_type(const type *tp);
 
 /* --- Support for compound types --- */
 
 /**
  * Gets the number of elements in a firm compound type.
  *
- * This is just a comforability function, because structs and
+ * This is just a comfortability function, because structs and
  * classes can often be treated be the same code, but they have
  * different access functions to their members.
  *
@@ -895,7 +1049,7 @@ int is_atomic_type(type *tp);
  *
  * @return Number of members in the compound type.
  */
-int get_compound_n_members(type *tp);
+int get_compound_n_members(const type *tp);
 
 /**
  * Gets the member of a firm compound type at position pos.
@@ -907,7 +1061,7 @@ int get_compound_n_members(type *tp);
  *
  * @see get_compound_n_members() for justifaction of existence.
  */
-entity *get_compound_member(type *tp, int pos);
+entity *get_compound_member(const type *tp, int pos);
 
 /**
  *  Checks whether a type is compound.
@@ -916,7 +1070,7 @@ entity *get_compound_member(type *tp, int pos);
  *
  *  @return true if the type is class, structure, union or array type.
  */
-int is_compound_type(type *tp);
+int is_compound_type(const type *tp);
 
 
 /**
@@ -924,18 +1078,13 @@ int is_compound_type(type *tp);
  *  debugging, (configure with --enable-debug) else returns the address
  *  of the type cast to long.
  */
-long get_type_nr(type *tp);
+long get_type_nr(const type *tp);
 
 /*******************************************************************/
 /** Debug aides                                                   **/
 /*******************************************************************/
 
 
-/** Write the type and all its attributes to stdout.
- *
- *  Writes the type and all its attributes to stdout if DEBUG_libfirm
- *  is set.  Else does nothing. */
-void    dump_type (type *tp);
 
 
 # endif /* _TYPE_H_ */