Correct documentation of return value.
[libfirm] / include / libfirm / typerep.h
index 6c01a9d..760f53f 100644 (file)
@@ -46,7 +46,9 @@
  *
  *   - owner:      A compound type this entity is a part of.
  *   - type:       The type of this entity.
- *   - name:       The string that represents this entity in the source program. *   - allocation: A flag saying whether the entity is dynamically or statically *                 allocated (values: dynamic_allocated,  static_allocated,
+ *   - name:       The string that represents this entity in the source program.
+ *   - allocation: A flag saying whether the entity is dynamically or statically
+ *                 allocated (values: dynamic_allocated,  static_allocated,
  *                 automatic_allocated).
  *   - visibility: A flag indicating the visibility of this entity (values: local,
  *                 external_visible,  external_allocated)
@@ -120,38 +122,6 @@ typedef enum {
                              This serves better as opposition to description _and_ inherited.*/
 } ir_peculiarity;
 
-/**
- * Additional method type properties:
- * Tell about special properties of a method type. Some
- * of these may be discovered by analyses.
- */
-typedef enum {
-       mtp_no_property        = 0x00000000, /**< no additional properties, default */
-       mtp_property_const     = 0x00000001, /**< This method did not access memory and calculates
-                                              its return values solely from its parameters.
-                                              GCC: __attribute__((const)). */
-       mtp_property_pure      = 0x00000002, /**< This method did NOT write to memory and calculates
-                                              its return values solely from its parameters and
-                                              the memory they points to (or global vars).
-                                              GCC: __attribute__((pure)). */
-       mtp_property_noreturn  = 0x00000004, /**< This method did not return due to an aborting system
-                                              call.
-                                              GCC: __attribute__((noreturn)). */
-       mtp_property_nothrow   = 0x00000008, /**< This method cannot throw an exception.
-                                              GCC: __attribute__((nothrow)). */
-       mtp_property_naked     = 0x00000010, /**< This method is naked.
-                                              GCC: __attribute__((naked)). */
-       mtp_property_malloc    = 0x00000020, /**< This method returns newly allocate memory.
-                                              GCC: __attribute__((malloc)). */
-       mtp_property_intrinsic = 0x00000040, /**< This method is intrinsic. It is expected that
-                                              a lowering phase will remove all calls to it. */
-       mtp_property_runtime   = 0x00000080, /**< This method represents a runtime routine. */
-       mtp_property_private   = 0x00000100, /**< All method invocations are known, the backend is free to
-                                              optimize the call in any possible way. */
-       mtp_property_inherited = (1<<31)     /**< Internal. Used only in irg's, means property is
-                                              inherited from type. */
-} mtp_additional_property;
-
 /**
  * Creates a new entity.
  *
@@ -326,11 +296,12 @@ const char *get_align_name(ir_align a);
 
 /** This enumeration flags the stickyness of an entity. */
 typedef enum {
-       stickyness_unsticky,          /**< The entity can be removed from
-                                        the program, unless contraindicated
-                                        by other attributes. Default. */
-       stickyness_sticky             /**< The entity must remain in the
-                                        program in any case. */
+       stickyness_unsticky,  /**< The entity can be removed from
+                                  the program, unless contraindicated
+                                  by other attributes. Default. */
+       stickyness_sticky     /**< The entity must remain in the
+                                  program in any case. There might be external
+                                  callers. */
 } ir_stickyness;
 
 /** Get the entity's stickyness. */
@@ -396,22 +367,26 @@ int is_entity_backend_marked(const ir_entity *ent);
 void set_entity_backend_marked(ir_entity *ent, int flag);
 
 /**
- * The state of the address_taken flag.
+ * Bitfield type indicating the way an entity is used.
  */
 typedef enum {
-       ir_address_not_taken     = 0,  /**< The address is NOT taken. */
-       ir_address_taken_unknown = 1,  /**< The state of the address taken flag is unknown. */
-       ir_address_taken         = 2   /**< The address IS taken. */
-} ir_address_taken_state;
-
-/** Return the state of the address taken flag of an entity. */
-ir_address_taken_state get_entity_address_taken(const ir_entity *ent);
+       ir_usage_none             = 0,      /**< This entity is unused. */
+       ir_usage_address_taken    = 1 << 0, /**< The address of this entity was taken. */
+       ir_usage_write            = 1 << 1, /**< The entity was written to. */
+       ir_usage_read             = 1 << 2, /**< The entity was read. */
+       ir_usage_reinterpret_cast = 1 << 3, /**< The entity was read but with a wrong mode
+                                                (an implicit reinterpret cast) */
+       /** Unknown access */
+       ir_usage_unknown
+               = ir_usage_address_taken | ir_usage_write | ir_usage_read
+               | ir_usage_reinterpret_cast
+} ir_entity_usage;
+
+/** Return the entity usage */
+ir_entity_usage get_entity_usage(const ir_entity *ent);
 
 /** Sets/resets the state of the address taken flag of an entity. */
-void set_entity_address_taken(ir_entity *ent, ir_address_taken_state flag);
-
-/** Return the name of the address_taken state. */
-const char *get_address_taken_state_name(ir_address_taken_state state);
+void set_entity_usage(ir_entity *ent, ir_entity_usage flag);
 
 /**
  * Returns the debug information of an entity.
@@ -456,13 +431,13 @@ void set_atomic_ent_value(ir_entity *ent, ir_node *val);
 
 /** the kind (type) of an initializer */
 typedef enum ir_initializer_kind_t {
-       /* initializer containing an ir_node from the const-code irg */
+       /** initializer containing an ir_node from the const-code irg */
        IR_INITIALIZER_CONST,
-       /* initializer containing a tarval */
+       /** initializer containing a tarval */
        IR_INITIALIZER_TARVAL,
-       /* initializes type with default values (usually 0) */
+       /** initializes type with default values (usually 0) */
        IR_INITIALIZER_NULL,
-       /* list of initializers used to initializer a compound or array type */
+       /** list of initializers used to initializer a compound or array type */
        IR_INITIALIZER_COMPOUND
 } ir_initializer_kind_t;
 
@@ -515,10 +490,16 @@ void free_compound_graph_path(compound_graph_path *gr);
 /** Returns the length of a graph path */
 int get_compound_graph_path_length(const compound_graph_path *gr);
 
+/** Get the entity node of an compound graph path at position pos. */
 ir_entity *get_compound_graph_path_node(const compound_graph_path *gr, int pos);
-void set_compound_graph_path_node(compound_graph_path *gr, int pos, ir_entity *node);
-int get_compound_graph_path_array_index(const compound_graph_path *gr, int pos);
-void set_compound_graph_path_array_index(compound_graph_path *gr, int pos, int index);
+/** Set the entity node of an compound graph path at position pos. */
+void      set_compound_graph_path_node(compound_graph_path *gr, int pos, ir_entity *node);
+/** Get the index of an compound graph path at position pos. */
+int       get_compound_graph_path_array_index(const compound_graph_path *gr, int pos);
+/** Set the index of an compound graph path at position pos. */
+void      set_compound_graph_path_array_index(compound_graph_path *gr, int pos, int index);
+/** Get the type of an compound graph path. */
+ir_type   *get_compound_graph_path_type(const compound_graph_path *gr);
 
 /** Checks whether the path up to pos is correct. If the path contains a NULL,
  *  assumes the path is not complete and returns non-zero. */
@@ -564,8 +545,10 @@ ir_entity *get_compound_ent_value_member(ir_entity *ent, int pos);
 /** Sets the path at pos 0 */
 void set_compound_ent_value(ir_entity *ent, ir_node *val, ir_entity *member, int pos);
 
+/** Sets the new style initializers of an entity. */
 void set_entity_initializer(ir_entity *entity, ir_initializer_t *initializer);
 
+/** Return the new style initializers of an entity. */
 ir_initializer_t *get_entity_initializer(const ir_entity *entity);
 
 /** Initializes the entity ent which must be of a one dimensional
@@ -656,10 +639,10 @@ int equal_entity(ir_entity *ent1, ir_entity *ent2);
 long get_entity_nr(const ir_entity *ent);
 
 /** Returns the entities visited count. */
-unsigned long get_entity_visited(ir_entity *ent);
+ir_visited_t get_entity_visited(ir_entity *ent);
 
 /** Sets the entities visited count. */
-void set_entity_visited(ir_entity *ent, unsigned long num);
+void set_entity_visited(ir_entity *ent, ir_visited_t num);
 
 /** Sets visited field in entity to entity_visited. */
 void mark_entity_visited(ir_entity *ent);
@@ -1378,10 +1361,7 @@ unsigned get_type_size_bytes(const ir_type *tp);
  */
 void set_type_size_bytes(ir_type *tp, unsigned 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(). */
+/** Returns the alignment of a type in bytes. */
 unsigned get_type_alignment_bytes(ir_type *tp);
 
 /** Returns the alignment of a type in bits.
@@ -1397,9 +1377,9 @@ unsigned get_type_alignment_bytes(ir_type *tp);
 void set_type_alignment_bytes(ir_type *tp, unsigned align);
 
 /** Returns the visited count of a type. */
-unsigned long get_type_visited(const ir_type *tp);
+ir_visited_t get_type_visited(const ir_type *tp);
 /** Sets the visited count of a type to num. */
-void set_type_visited(ir_type *tp, unsigned long num);
+void set_type_visited(ir_type *tp, ir_visited_t num);
 /** Sets visited field in type to type_visited. */
 void mark_type_visited(ir_type *tp);
 /** Returns non-zero if the type is already visited */
@@ -1424,9 +1404,9 @@ void set_type_link(ir_type *tp, void *l);
  *
  * @see  typewalk
  */
-void          set_master_type_visited(unsigned long val);
-unsigned long get_master_type_visited(void);
-void          inc_master_type_visited(void);
+void         set_master_type_visited(ir_visited_t val);
+ir_visited_t get_master_type_visited(void);
+void         inc_master_type_visited(void);
 
 /**
  * Sets the debug information of a type.
@@ -1695,14 +1675,6 @@ void remove_class_supertype(ir_type *clss, ir_type *supertype);
 #define set_class_base_type(clss, basetype, pos)   set_class_supertype(clss, basetype, pos)
 #define remove_class_base_type(clss, basetype)     remove_class_supertype(clss, basetype)
 
-/** Convenience macro */
-#define add_class_base_type(clss, basetype)        add_class_supertype(clss, basetype)
-#define get_class_n_base_types(clss)               get_class_n_supertypes(clss)
-#define get_class_base_type_index(clss, base_clss) get_class_supertype_index(clss, base_clss)
-#define get_class_base_type(clss, pos)             get_class_supertype(clss, pos)
-#define set_class_base_type(clss, basetype, pos)   set_class_supertype(clss, basetype, pos)
-#define remove_class_base_type(clss, basetype)     remove_class_supertype(clss, basetype)
-
 /** Returns a human readable string for a peculiarity. */
 const char *get_peculiarity_name(ir_peculiarity p);
 
@@ -1974,6 +1946,7 @@ typedef enum {
        cc_compound_ret        = 0x10000000, /**< The method returns a compound type. */
        cc_frame_on_caller_stk = 0x20000000, /**< The method did not allocate an own stack frame, instead the
                                                  caller must reserve size on its own stack. */
+       cc_fpreg_param         = 0x40000000, /**< Transmit floating point parameters in registers, else the stack is used. */
        cc_bits                = (0xFF << 24)/**< The calling convention bits. */
 } calling_convention;
 
@@ -2537,12 +2510,12 @@ ir_type *mature_type_free_entities(ir_type *tp);
 /**
  * The interface type for the type identify module;
  */
-typedef struct _type_identify_if_t {
+struct type_identify_if_t {
        compare_types_func_t *cmp;    /**< The function that should be used to compare two types.
                                           If NULL, compare_strict() will be used. */
        hash_types_func_t *hash;      /**< The function that should be used to calculate a hash
                                           value of a type. If NULL, hash_name() will be used. */
-} type_identify_if_t;
+};
 
 /**
  * Initialise the type identifier module.
@@ -2565,7 +2538,7 @@ typedef union {
  * @param tore    points to the visited type or entity
  * @param env     free environment pointer
  */
-typedef void type_walk_func(type_or_ent *tore, void *env);
+typedef void type_walk_func(type_or_ent tore, void *env);
 
 /**  The class walk function
  *