From d217f68a9e53ec6e800ae31ca3af8ed8b6f9ece9 Mon Sep 17 00:00:00 2001 From: Matthias Braun Date: Mon, 12 Dec 2011 16:27:24 +0100 Subject: [PATCH] Added missing API docu, improved existing API docu Now every bit in the public API is documented so we can enable doxygen warnings for undocumented members. --- Doxyfile | 16 +- Makefile | 12 +- NEWS.md | 5 + include/libfirm/adt/array.h | 15 +- include/libfirm/adt/bipartite.h | 19 ++ include/libfirm/adt/cpset.h | 16 ++ include/libfirm/adt/gaussjordan.h | 9 + include/libfirm/adt/hashptr.h | 30 ++- include/libfirm/adt/hungarian.h | 18 +- include/libfirm/adt/list.h | 66 ++++-- include/libfirm/adt/obst.h | 6 +- include/libfirm/adt/obstack.h | 16 ++ include/libfirm/adt/pdeq.h | 9 + include/libfirm/adt/plist.h | 27 +-- include/libfirm/adt/pmap.h | 19 +- include/libfirm/adt/pqueue.h | 11 + include/libfirm/adt/pset.h | 22 +- include/libfirm/adt/pset_new.h | 7 + include/libfirm/adt/set.h | 16 +- include/libfirm/adt/unionfind.h | 17 +- include/libfirm/adt/xmalloc.h | 27 ++- include/libfirm/be.h | 21 +- include/libfirm/cdep.h | 18 +- include/libfirm/cgana.h | 5 +- include/libfirm/compound_path.h | 24 ++- include/libfirm/dbginfo.h | 2 +- include/libfirm/execfreq.h | 14 +- include/libfirm/firm.h | 18 +- include/libfirm/firm_types.h | 116 ++++++++-- include/libfirm/heights.h | 12 +- include/libfirm/ident.h | 16 +- include/libfirm/irarch.h | 8 +- include/libfirm/ircgopt.h | 11 +- include/libfirm/ircons.h | 78 +++++-- include/libfirm/irdom.h | 14 +- include/libfirm/irdump.h | 14 +- include/libfirm/iredges.h | 40 ++-- include/libfirm/irextbb.h | 12 +- include/libfirm/irflag.h | 18 +- include/libfirm/irgraph.h | 62 ++++-- include/libfirm/irhooks.h | 90 +++++--- include/libfirm/irloop.h | 24 ++- include/libfirm/irmemory.h | 16 +- include/libfirm/irmode.h | 69 +++--- include/libfirm/irnode.h | 342 +++++++++++++++++++----------- include/libfirm/irop.h | 22 +- include/libfirm/iroptimize.h | 42 ++-- include/libfirm/irouts.h | 18 +- include/libfirm/irpass.h | 24 +-- include/libfirm/irprog.h | 56 +++-- include/libfirm/irtypeinfo.h | 16 +- include/libfirm/lowering.h | 13 +- include/libfirm/timing.h | 13 +- include/libfirm/trouts.h | 52 ++--- include/libfirm/tv.h | 19 +- include/libfirm/typerep.h | 263 +++++++++++++++-------- include/libfirm/vrp.h | 13 +- scripts/gen_ir.py | 19 +- 58 files changed, 1339 insertions(+), 658 deletions(-) diff --git a/Doxyfile b/Doxyfile index 28b92c480..09915193b 100644 --- a/Doxyfile +++ b/Doxyfile @@ -38,7 +38,7 @@ PROJECT_NUMBER = # If a relative path is entered, it will be relative to the location # where doxygen was started. If left blank the current directory will be used. -OUTPUT_DIRECTORY = ./firm-doc +OUTPUT_DIRECTORY = build/firm-doc # If the CREATE_SUBDIRS tag is set to YES, then doxygen will create # 4096 sub-directories (in 2 levels) under the output directory of each output @@ -245,7 +245,7 @@ SIP_SUPPORT = NO # setting a simple type. If this is not the case, or you want to show the # methods anyway, you should set this option to NO. -IDL_PROPERTY_SUPPORT = YES +IDL_PROPERTY_SUPPORT = NO # If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC # tag is set to YES, then doxygen will reuse the documentation of the first @@ -286,7 +286,7 @@ TYPEDEF_HIDES_STRUCT = YES # 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0, # corresponding to a cache size of 2^16 = 65536 symbols -SYMBOL_CACHE_SIZE = 0 +SYMBOL_CACHE_SIZE = 2 #--------------------------------------------------------------------------- # Build related configuration options @@ -297,7 +297,7 @@ SYMBOL_CACHE_SIZE = 0 # Private class members and static file members will be hidden unless # the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES -EXTRACT_ALL = yes +EXTRACT_ALL = no # If the EXTRACT_PRIVATE tag is set to YES all private members of a class # will be included in the documentation. @@ -307,7 +307,7 @@ EXTRACT_PRIVATE = no # If the EXTRACT_STATIC tag is set to YES all static members of a file # will be included in the documentation. -EXTRACT_STATIC = NO +EXTRACT_STATIC = YES # If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) # defined locally in source files will be included in the documentation. @@ -527,7 +527,7 @@ WARNINGS = YES # for undocumented members. If EXTRACT_ALL is set to YES then this flag will # automatically be disabled. -WARN_IF_UNDOCUMENTED = NO +WARN_IF_UNDOCUMENTED = YES # If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for # potential errors in the documentation, such as not documenting some @@ -557,7 +557,7 @@ WARN_FORMAT = "$file:$line: $text" # and error messages should be written. If left blank the output is written # to stderr. -WARN_LOGFILE = ./firm-doc/warnings +WARN_LOGFILE = #--------------------------------------------------------------------------- # configuration options related to the input files @@ -1302,7 +1302,7 @@ TAGFILES = # When a file name is specified after GENERATE_TAGFILE, doxygen will create # a tag file that is based on the input files it reads. -GENERATE_TAGFILE = firm-doc/libfirm.tag +GENERATE_TAGFILE = build/firm-doc/libfirm.tag # If the ALLEXTERNALS tag is set to YES all external classes will be listed # in the class index. If set to NO only the inherited external classes diff --git a/Makefile b/Makefile index 66f91d1f1..49433fee8 100644 --- a/Makefile +++ b/Makefile @@ -14,6 +14,7 @@ variant ?= debug srcdir ?= $(top_srcdir) builddir ?= $(top_builddir)/$(variant) +docdir ?= $(top_builddir)/firm-doc # This hides the noisy commandline outputs. You can see them with "make Q=" Q ?= @ @@ -177,18 +178,18 @@ $(builddir)/%.o: %.c $(IR_SPEC_GENERATED_FILES) config.h @echo CC $@ $(Q)$(CC) $(CFLAGS) $(CPPFLAGS) $(libfirm_CPPFLAGS) -MMD -c -o $@ $< -firm-doc/libfirm.tag: $(IR_SPEC_GENERATED_FILES) Doxyfile $(wildcard include/libfirm/*.h) $(wildcard include/libfirm/adt/*.h) +$(docdir)/libfirm.tag: $(IR_SPEC_GENERATED_FILES) Doxyfile $(wildcard include/libfirm/*.h) $(wildcard include/libfirm/adt/*.h) @echo Doxygen $(Q)$(DOXYGEN) DOCU_GENERATOR := scripts/gen_docu.py -firm-doc/html/nodes.html: firm-doc/libfirm.tag $(DOCU_GENERATOR) $(IR_SPEC) scripts/spec_util.py scripts/style.css +$(docdir)/html/nodes.html: $(docdir)/libfirm.tag $(DOCU_GENERATOR) $(IR_SPEC) scripts/spec_util.py scripts/style.css @echo gen_docu.py - $(Q)$(DOCU_GENERATOR) firm-doc/libfirm.tag "" $@ - $(Q)cp scripts/style.css firm-doc/html + $(Q)$(DOCU_GENERATOR) $(docdir)/libfirm.tag "" $@ + $(Q)cp scripts/style.css $(docdir)/html .PHONY: documentation -documentation: firm-doc/libfirm.tag firm-doc/html/nodes.html +documentation: $(docdir)/libfirm.tag $(docdir)/html/nodes.html .PHONY: clean clean: @@ -196,4 +197,3 @@ clean: $(Q)rm -f $(libfirm_OBJECTS) $(Q)rm -f $(libfirm_TARGET) $(Q)rm -f $(shell find ir/ -name "gen_*.[ch]") - $(Q)rm -rf firm-docu diff --git a/NEWS.md b/NEWS.md index ce9d1fd74..7079c9d25 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,10 @@ +libFirm 1.19.1 (2011-05-17) +--------------------------- + +* Fix some set_XXX functions not being exported in the shared library + libFirm 1.19.0 (2011-03-15) --------------------------- diff --git a/include/libfirm/adt/array.h b/include/libfirm/adt/array.h index f7978c1d3..b04b52ea7 100644 --- a/include/libfirm/adt/array.h +++ b/include/libfirm/adt/array.h @@ -32,6 +32,12 @@ #include "../begin.h" +/** + * @ingroup adt + * @defgroup array Arrays + * @{ + */ + /** * Creates a flexible array. * @@ -209,11 +215,15 @@ # define ARR_VRFY(arr) ((void)0) # define ARR_IDX_VRFY(arr, idx) ((void)0) #else +/** Check array for consistency */ # define ARR_VRFY(arr) ir_verify_arr(arr) +/** Check if index is within array bounds */ # define ARR_IDX_VRFY(arr, idx) \ assert((0 <= (idx)) && ((idx) < ARR_LEN((arr)))) #endif +/** @cond PRIVATE */ + /** A type that has most constrained alignment. */ typedef union { long double d; @@ -221,7 +231,6 @@ typedef union { long l; } aligned_type; - /** * The array descriptor header type. */ @@ -257,6 +266,10 @@ static inline void ARR_SHRINKLEN(void *arr, size_t new_len) ARR_DESCR(arr)->nelts = new_len; } +/** @endcond */ + +/** @} */ + #include "../end.h" #endif diff --git a/include/libfirm/adt/bipartite.h b/include/libfirm/adt/bipartite.h index 3d0127663..4d89079f5 100644 --- a/include/libfirm/adt/bipartite.h +++ b/include/libfirm/adt/bipartite.h @@ -28,13 +28,30 @@ #include "../begin.h" +/** + * @ingroup algorithms + * @defgroup bipartite Bipartite Matching + * Solved bipartite matching problem. + * (Variant with only 0/1 costs) + * @{ + */ + +/** internal representation of bipartite matching problem */ typedef struct bipartite_t bipartite_t; +/** Create new bipartite matching problem with @p n_left elements on left side + * and @p n_right elements on right side */ FIRM_API bipartite_t *bipartite_new(int n_left, int n_right); +/** Free memory occupied by bipartite matching problem */ FIRM_API void bipartite_free(bipartite_t *gr); +/** Add edge from @p i (on the left side) to @p j (on the right side) */ FIRM_API void bipartite_add(bipartite_t *gr, int i, int j); +/** Remove edge from @p i (on the left side) to @p j (on the right side) */ FIRM_API void bipartite_remv(bipartite_t *gr, int i, int j); +/** Return 1 if edge from @p i (on the left side) to @p j (on the right side) + * exists, 0 otherwise */ FIRM_API int bipartite_adj(const bipartite_t *gr, int i, int j); +/** Solve bipartite matching problem */ FIRM_API void bipartite_matching(const bipartite_t *gr, int *matching); /** @@ -47,6 +64,8 @@ FIRM_API void bipartite_dump_f(FILE *f, const bipartite_t *gr); */ FIRM_API void bipartite_dump(const char *name, const bipartite_t *gr); +/** @} */ + #include "../end.h" #endif /* _BIPARTITE_H */ diff --git a/include/libfirm/adt/cpset.h b/include/libfirm/adt/cpset.h index 856e32e7e..b13fea0cc 100644 --- a/include/libfirm/adt/cpset.h +++ b/include/libfirm/adt/cpset.h @@ -28,6 +28,13 @@ #include "../begin.h" +/** + * @ingroup adt + * @defgroup Pointer Set (custom Compare) + * A pointer set with user-definable compare function + * @{ + */ + /** * The type of a cpset compare function. * @@ -43,6 +50,8 @@ typedef int (*cpset_cmp_function) (const void *p1, const void *p2); */ typedef unsigned (*cpset_hash_function) (const void *obj); +/** @cond PRIVATE */ + #define HashSet cpset_t #define HashSetIterator cpset_iterator_t #define HashSetEntry cpset_hashset_entry_t @@ -55,7 +64,12 @@ typedef unsigned (*cpset_hash_function) (const void *obj); #undef HashSetIterator #undef HashSet +/** @endcond */ + +/** a pointer set with custom compare function */ typedef struct cpset_t cpset_t; +/** iterator over a pointer set with custom compare function + * @see #cpset_t */ typedef struct cpset_iterator_t cpset_iterator_t; /** @@ -151,6 +165,8 @@ FIRM_API void *cpset_iterator_next(cpset_iterator_t *iterator); */ FIRM_API void cpset_remove_iterator(cpset_t *cpset, const cpset_iterator_t *iterator); +/** @} */ + #include "../end.h" #endif diff --git a/include/libfirm/adt/gaussjordan.h b/include/libfirm/adt/gaussjordan.h index cd87d91a2..4adc14af4 100644 --- a/include/libfirm/adt/gaussjordan.h +++ b/include/libfirm/adt/gaussjordan.h @@ -7,6 +7,13 @@ #include "../begin.h" +/** + * @ingroup algorithms + * @defgroup gassjordan Gauss Jordan Elimination + * Solves a system of linear equations + * @{ + */ + /** * solves a system of linear equations and returns 0 if successful * @@ -16,6 +23,8 @@ */ FIRM_API int firm_gaussjordansolve(double *A, double *b, int nsize); +/** @} */ + #include "../end.h" #endif diff --git a/include/libfirm/adt/hashptr.h b/include/libfirm/adt/hashptr.h index f7d16e7c4..ed6844ff5 100644 --- a/include/libfirm/adt/hashptr.h +++ b/include/libfirm/adt/hashptr.h @@ -19,7 +19,7 @@ /** * @file - * @brief Hash function for pointers + * @brief Hash functions * @author Michael Beck, Sebastian Hack */ #ifndef FIRM_ADT_HASHPTR_H @@ -28,12 +28,25 @@ #include #include "../begin.h" +/** + * @ingroup algorithms + * @defgroup hashptr Hash Functions + * @{ + */ + +/** @cond DISABLED */ + #define _FIRM_FNV_OFFSET_BASIS 2166136261U #define _FIRM_FNV_FNV_PRIME 16777619U /* Computing x * _FIRM_FNV_FNV_PRIME */ #define _FIRM_FNV_TIMES_PRIME(x) ((x) * _FIRM_FNV_FNV_PRIME) +/** @endcond */ + +/** + * Returns a hash value for a block of data. + */ static inline unsigned hash_data(const unsigned char *data, size_t bytes) { size_t i; @@ -50,17 +63,16 @@ static inline unsigned hash_data(const unsigned char *data, size_t bytes) /** * Returns a hash value for a string. * @param str The string (can be const). - * @param len The length of the string. * @return A hash value for the string. */ -static inline unsigned hash_str(const char *data) +static inline unsigned hash_str(const char *str) { unsigned i; unsigned hash = _FIRM_FNV_OFFSET_BASIS; - for(i = 0; data[i] != '\0'; ++i) { + for(i = 0; str[i] != '\0'; ++i) { hash = _FIRM_FNV_TIMES_PRIME(hash); - hash ^= data[i]; + hash ^= str[i]; } return hash; @@ -78,9 +90,9 @@ static inline unsigned hash_ptr(const void *ptr) /** * Combines 2 hash values. - * @param a One hash value. - * @param b Another hash value. - * @return A hash value computed from both. + * @param x One hash value. + * @param y Another hash value. + * @return A hash value computed from both. */ static inline unsigned hash_combine(unsigned x, unsigned y) { @@ -91,6 +103,8 @@ static inline unsigned hash_combine(unsigned x, unsigned y) return hash; } +/** @} */ + #include "../end.h" #endif diff --git a/include/libfirm/adt/hungarian.h b/include/libfirm/adt/hungarian.h index a42fce186..7d1b85ebe 100644 --- a/include/libfirm/adt/hungarian.h +++ b/include/libfirm/adt/hungarian.h @@ -34,17 +34,29 @@ #include "../begin.h" +/** + * @ingroup algorithms + * @defgroup hungarian Hungarian Algorithm + * Solves bipartite matching problems (minimize/maximize cost function) + * @{ + */ + +/** type of matching */ typedef enum match_type_t { HUNGARIAN_MATCH_NORMAL, /**< ever nodes matches another node */ HUNGARIAN_MATCH_PERFECT /**< matchings of nodes having no edge getting removed */ } match_type_t; +/** mode of matching (the optimization goal) */ typedef enum hungarian_mode_t { - HUNGARIAN_MODE_MINIMIZE_COST, - HUNGARIAN_MODE_MAXIMIZE_UTIL + HUNGARIAN_MODE_MINIMIZE_COST, /**< minimize cost */ + HUNGARIAN_MODE_MAXIMIZE_UTIL /**< maximize cost */ } hungarian_mode_t; +/** + * Internal representation of a bipartite matching problem + */ typedef struct hungarian_problem_t hungarian_problem_t; /** @@ -105,6 +117,8 @@ FIRM_API int hungarian_solve(hungarian_problem_t *p, unsigned *assignment, FIRM_API void hungarian_print_cost_matrix(hungarian_problem_t *p, int cost_width); +/** @} */ + #include "../end.h" #endif diff --git a/include/libfirm/adt/list.h b/include/libfirm/adt/list.h index d80d8bce6..2ebc4ea7a 100644 --- a/include/libfirm/adt/list.h +++ b/include/libfirm/adt/list.h @@ -1,5 +1,13 @@ +#ifndef FIRM_ADT_LIST_H +#define FIRM_ADT_LIST_H + +#include + +#include "../begin.h" + /** - * @file + * @ingroup adt + * @defgroup lists Linked Lists * @brief Doubly linked lists. * * Simple doubly linked list implementation. @@ -9,36 +17,41 @@ * sometimes we already know the next/prev entries and we can * generate better code by using them directly rather than * using the generic single-entry routines. - */ -#ifndef FIRM_ADT_LIST_H -#define FIRM_ADT_LIST_H - -#include - -#include "../begin.h" + * @{ + */ +/** + * List Header. + * Put this into all list elements and at the place where you want to keep + * references to the list. */ typedef struct list_head list_head; -struct list_head { - struct list_head *next, *prev; -}; +/** Static initializer for a list header */ #define LIST_HEAD_INIT(name) { &(name), &(name) } +/** Defines a (static) list reference */ #define LIST_HEAD(name) \ struct list_head name = LIST_HEAD_INIT(name) +/** Initializes a list header */ #define INIT_LIST_HEAD(ptr) do { \ (ptr)->next = (ptr); (ptr)->prev = (ptr); \ } while (0) +/** @cond PRIVATE */ +struct list_head { + struct list_head *next, *prev; +}; + #define _list_offsetof(type,member) \ ((char *) &(((type *) 0)->member) - (char *) 0) #define _list_container_of(ptr, type, member) \ ((type *) ((char *) (ptr) - _list_offsetof(type, member))) +/** @endcond */ -/* - * Insert a new entry between two known consecutive entries. +/** + * Inserts a new entry between two known consecutive entries. * * This is only for internal list manipulation where we know * the prev/next entries already! @@ -54,7 +67,7 @@ static inline void __list_add(struct list_head *new_node, } /** - * list_add - add a new entry + * Adds a new entry * @param new_node new entry to be added * @param head list head to add it after * @@ -67,7 +80,7 @@ static inline void list_add(struct list_head *new_node, struct list_head *head) } /** - * list_add_tail - add a new entry + * Adds a new entry * @param new_node new entry to be added * @param head list head to add it before * @@ -79,8 +92,8 @@ static inline void list_add_tail(struct list_head *new_node, struct list_head *h __list_add(new_node, head->prev, head); } -/* - * Delete a list entry by making the prev/next entries +/** + * Deletes a list entry by making the prev/next entries * point to each other. * * This is only for internal list manipulation where we know @@ -93,7 +106,7 @@ static inline void __list_del(struct list_head * prev, struct list_head * next) } /** - * list_del - deletes entry from list. + * Deletes entry from list. * @param entry the element to delete from the list. * * @note @@ -109,7 +122,7 @@ static inline void list_del(struct list_head *entry) /** - * list_del_init - deletes entry from list and reinitialize it. + * Deletes entry from list and reinitialize it. * @param entry the element to delete from the list. */ static inline void list_del_init(struct list_head *entry) @@ -119,7 +132,7 @@ static inline void list_del_init(struct list_head *entry) } /** - * list_move - delete from one list and add as another's head + * Deletes from one list and add as another's head * @param list the entry to move * @param head the head that will precede our entry */ @@ -130,7 +143,7 @@ static inline void list_move(struct list_head *list, struct list_head *head) } /** - * list_move_tail - delete from one list and add as another's tail + * Deletes from one list and add as another's tail * @param list the entry to move * @param head the head that will follow our entry */ @@ -142,7 +155,7 @@ static inline void list_move_tail(struct list_head *list, } /** - * list_empty - tests whether a list is empty + * Tests whether a list is empty * @param head the list to test. */ static inline int list_empty(const struct list_head *head) @@ -150,6 +163,13 @@ static inline int list_empty(const struct list_head *head) return head->next == head; } +/** + * Join two nonempty lists. + * + * @note Use list_splice() if @p list is possibly empty. + * @param list the new list to add. + * @param head the place to add it in the first list. + */ static inline void __list_splice(struct list_head *list, struct list_head *head) { @@ -278,6 +298,8 @@ static inline void list_splice_init(struct list_head *list, &pos->member != (head); \ pos = n, n = list_entry(n->member.next, type, member)) +/** @} */ + #include "../end.h" #endif diff --git a/include/libfirm/adt/obst.h b/include/libfirm/adt/obst.h index f10f515f0..6198b8b95 100644 --- a/include/libfirm/adt/obst.h +++ b/include/libfirm/adt/obst.h @@ -19,7 +19,7 @@ /** * @file - * @brief Provied obstack_chunk_alloc and obstack_chunk_free for obstack.h + * @brief Provides obstack_chunk_alloc and obstack_chunk_free for obstack.h * @author Martin Trapp, Christian Schaefer */ #ifndef FIRM_ADT_OBST_H @@ -28,9 +28,13 @@ #include "obstack.h" #include "xmalloc.h" +/** @cond PRIVATE */ #define obstack_chunk_alloc xmalloc #define obstack_chunk_free free +/** @endcond */ +/** An obstack initializer containing zero values. Can be used to initialize + * obstacks in an initializer. */ #define NULL_OBST { 0, NULL, NULL, NULL, NULL, 0, 0, NULL, NULL, NULL, 0, 0, 0 } #endif diff --git a/include/libfirm/adt/obstack.h b/include/libfirm/adt/obstack.h index 8c81b33d7..40baf8ffa 100644 --- a/include/libfirm/adt/obstack.h +++ b/include/libfirm/adt/obstack.h @@ -18,6 +18,18 @@ Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ +/** @page obstack Obstack Memory Allocation + * + * Obstacks are the prefered way to handle memory allocation in libFirm. + * Compared to classical malloc they are faster but don't allow fine-grained + * freeing of allocated memory. But in a compile this is fine most of the time + * as memory is allocated for a phase or a graph and later the whole phase ends + * or the whole graph gets discarded. + * + * There's very good documentation about Object stacks in the glibc manual: + * http://www.gnu.org/s/libc/manual/html_node/Obstacks.html + */ + /* Summary: All the apparent functions defined here are macros. The idea @@ -108,6 +120,8 @@ Summary: #include "../begin.h" +/** @cond DISABLED */ + /* We need the type of a pointer subtraction. If __PTRDIFF_TYPE__ is defined, as with GNU C, use that; that way we don't pollute the namespace with 's symbols. Otherwise, include @@ -530,6 +544,8 @@ int obstack_printf(struct obstack *obst, const char *fmt, ...) int obstack_vprintf(struct obstack *obst, const char *fmt, va_list ap) FIRM_NOTHROW FIRM_PRINTF(2, 0); +/** @endcond */ + #include "../end.h" #endif diff --git a/include/libfirm/adt/pdeq.h b/include/libfirm/adt/pdeq.h index 3df4cabd2..bfbb45198 100644 --- a/include/libfirm/adt/pdeq.h +++ b/include/libfirm/adt/pdeq.h @@ -29,6 +29,13 @@ #include "../begin.h" +/** + * @ingroup adt + * @defgroup pdeq Double Ended Queue + * Implementation if a double ended queue datastructure for generic pointers + * @{ + */ + /** * The type of the pointer compare function. * @@ -264,6 +271,8 @@ typedef pdeq stack; */ #define stack_empty(st) pdeq_empty(wq) +/** @} */ + #include "../end.h" #endif diff --git a/include/libfirm/adt/plist.h b/include/libfirm/adt/plist.h index a31e3f513..2f0c0dc8c 100644 --- a/include/libfirm/adt/plist.h +++ b/include/libfirm/adt/plist.h @@ -26,9 +26,6 @@ * not very well suited for the interference graph implementation. * This list uses an obstack and a free-list to efficiently manage its * elements. - * @note Until now the code is entirely untested so it probably contains - * plenty of errors. (Matze: Is this still true, the code seems to be - * used at some places....) * @deprecated */ #ifndef FIRM_ADT_PLIST_H @@ -46,27 +43,19 @@ typedef struct plist plist_t; * The plist data type. */ struct plist { - /** - * The obstack used for all allocations. - */ + /** The obstack used for all allocations. */ struct obstack *obst; - /* Set to 1 if plist uses a foreign obstack */ + /** Set to 1 if plist uses a foreign obstack */ unsigned foreign_obstack : 1; - /** - * First element in the list. - */ + /** First element in the list. */ plist_element_t *first_element; - /** - * Last element in the list. - */ + /** Last element in the list. */ plist_element_t *last_element; - /** - * Current number of elements in the list. - */ + /** Current number of elements in the list. */ int element_count; /** @@ -81,9 +70,9 @@ struct plist { * An element in the pointer list. */ struct plist_element { - plist_element_t *next; - plist_element_t *prev; - void *data; + plist_element_t *next; /**< next element in double linked list */ + plist_element_t *prev; /**< previous element in double linked list */ + void *data; /**< element data */ }; /** diff --git a/include/libfirm/adt/pmap.h b/include/libfirm/adt/pmap.h index dc53aade7..6d3a347f3 100644 --- a/include/libfirm/adt/pmap.h +++ b/include/libfirm/adt/pmap.h @@ -19,7 +19,7 @@ /** * @file - * @brief Simplified hashnap for pointer->pointer relations + * @brief Simplified hashmap for pointer->pointer relations * @author Hubert Schmid * @date 09.06.2002 */ @@ -30,6 +30,13 @@ #include "../begin.h" +/** + * @ingroup adt + * @defgroup pmap Pointer Map + * Pointer->Pointer hashmap + * @{ + */ + /** A map which maps addresses to addresses. */ typedef struct pmap pmap; @@ -61,11 +68,12 @@ FIRM_API void pmap_insert(pmap *map, const void * key, void * value); FIRM_API int pmap_contains(pmap *map, const void * key); /** Returns the key, value pair of "key". */ -FIRM_API pmap_entry * pmap_find(pmap *map, const void * key); +FIRM_API pmap_entry *pmap_find(pmap *map, const void * key); /** Returns the value of "key". */ FIRM_API void * pmap_get(pmap *map, const void * key); +/** Return number of elements in the map */ FIRM_API size_t pmap_count(pmap *map); /** @@ -78,6 +86,9 @@ FIRM_API pmap_entry *pmap_first(pmap *map); */ FIRM_API pmap_entry *pmap_next(pmap *); +/** + * Iterate over all elements in the map setting curr to the current element. + */ #define foreach_pmap(pmap, curr) \ for (curr = pmap_first(pmap); curr; curr = pmap_next(pmap)) @@ -86,6 +97,10 @@ FIRM_API pmap_entry *pmap_next(pmap *); */ FIRM_API void pmap_break(pmap *map); +/** + * @} + */ + #include "../end.h" #endif diff --git a/include/libfirm/adt/pqueue.h b/include/libfirm/adt/pqueue.h index 504b73912..35e585ad1 100644 --- a/include/libfirm/adt/pqueue.h +++ b/include/libfirm/adt/pqueue.h @@ -29,6 +29,15 @@ #include "../begin.h" +/** + * @ingroup adt + * @defgroup pqueue Priority Queue + * A priority queue. + * Implementation based on a heap datastructure + * @{ + */ + +/** priority queue */ typedef struct pqueue_t pqueue_t; /** @@ -72,6 +81,8 @@ FIRM_API size_t pqueue_length(const pqueue_t *q); */ FIRM_API int pqueue_empty(const pqueue_t *q); +/** @} */ + #include "../end.h" #endif diff --git a/include/libfirm/adt/pset.h b/include/libfirm/adt/pset.h index 29249b72f..29d8c14c3 100644 --- a/include/libfirm/adt/pset.h +++ b/include/libfirm/adt/pset.h @@ -22,8 +22,6 @@ * @brief optimized version of set for sets containing only pointers * (deprecated) * @author Markus Armbruster - * @note This code has been deprecated. Use pset_new or cpset for new - * code. */ #ifndef FIRM_ADT_PSET_H #define FIRM_ADT_PSET_H @@ -34,6 +32,14 @@ #include "../begin.h" +/** + * @ingroup adt + * @defgroup pset Pointer Set + * (Hash)sets containing pointers. + * @note This code has been deprecated. Use pset_new or cpset for new code. + * @{ + */ + /** * The default comparison function for pointers. * @param x A pointer. @@ -67,8 +73,8 @@ typedef struct pset pset; /** The entry of a pset, representing an element pointer in the set and its meta-information */ typedef struct { - unsigned hash; - void *dptr; + unsigned hash; /**< hash value of element */ + void *dptr; /**< pointer to element data */ } pset_entry; /** @@ -220,6 +226,8 @@ FIRM_API void pset_break(pset *pset); */ FIRM_API void pset_insert_pset_ptr(pset *target, pset *src); +/** @cond PRIVATE */ + #define new_pset(cmp, slots) ((new_pset) ((cmp), (slots))) #define pset_find(pset, key, hash) \ _pset_search ((pset), (key), (hash), _pset_find) @@ -228,12 +236,14 @@ FIRM_API void pset_insert_pset_ptr(pset *target, pset *src); #define pset_hinsert(pset, key, hash) \ ((pset_entry *)_pset_search ((pset), (key), (hash), _pset_hinsert)) -/** @privatesection */ - typedef enum { _pset_find, _pset_insert, _pset_hinsert } _pset_action; FIRM_API void *_pset_search(pset *, const void *, unsigned, _pset_action); +/** @endcond */ + +/** @} */ + #include "../end.h" #endif diff --git a/include/libfirm/adt/pset_new.h b/include/libfirm/adt/pset_new.h index a78ea53a0..a5314abff 100644 --- a/include/libfirm/adt/pset_new.h +++ b/include/libfirm/adt/pset_new.h @@ -33,6 +33,8 @@ #include "../begin.h" +/** @cond PRIVATE */ + #define HashSet pset_new_t #define HashSetIterator pset_new_iterator_t #define ValueType void* @@ -43,7 +45,12 @@ #undef HashSetIterator #undef ValueType +/** @endcond */ + +/** a pointer (hash)set */ typedef struct pset_new_t pset_new_t; +/** iterator over a pointer set. + * @see #pset_new_t */ typedef struct pset_new_iterator_t pset_new_iterator_t; /** diff --git a/include/libfirm/adt/set.h b/include/libfirm/adt/set.h index 6491fa7b0..012befa54 100644 --- a/include/libfirm/adt/set.h +++ b/include/libfirm/adt/set.h @@ -29,6 +29,14 @@ #include "../begin.h" +/** + * @ingroup adt + * @defgroup set Generic Hashset + * Generic Hashset + * @note This code has been deprecated. Use hashset for new code. + * @{ + */ + /** * The abstract type of a set. * @@ -191,6 +199,8 @@ FIRM_API void set_break(set *set); */ #define foreach_set(set, type, entry) for (entry = (type) set_first(set); entry; entry = (type) set_next(set)) +/** @cond PRIVATE */ + /* implementation specific */ #define new_set(cmp, slots) ((new_set) ((cmp), (slots))) #define set_find(set, key, size, hash) \ @@ -202,12 +212,14 @@ FIRM_API void set_break(set *set); #define set_hinsert0(set, key, size, hash) \ ((set_entry *)_set_search ((set), (key), (size), (hash), _set_hinsert0)) -/* Private */ - typedef enum { _set_find, _set_insert, _set_hinsert, _set_hinsert0 } _set_action; FIRM_API void *_set_search(set *, const void *, size_t, unsigned, _set_action); +/** @endcond */ + +/** @} */ + #include "../end.h" #endif diff --git a/include/libfirm/adt/unionfind.h b/include/libfirm/adt/unionfind.h index 80591bc0a..b71d01651 100644 --- a/include/libfirm/adt/unionfind.h +++ b/include/libfirm/adt/unionfind.h @@ -21,11 +21,6 @@ * @file * @brief Union-Find datastructure * @author Matthias Braun - * @brief - * Union-Find datastructure - * - * This implementation uses weighted sets and path compression which results - * in (nearly) O(n) complexity for n find and union operations */ #ifndef FIRM_ADT_UNIONFIND_H #define FIRM_ADT_UNIONFIND_H @@ -34,6 +29,16 @@ #include "../begin.h" +/** + * @ingroup adt + * @defgroup unionfind Union-Find + * Union-Find datastructure + * + * This implementation uses weighted sets and path compression which results + * in (nearly) O(n) complexity for n find and union operations + * @{ + */ + /** * Call this to initialize an array of @p count elements to be used by the * union find functions. @@ -112,6 +117,8 @@ static inline int uf_find(int* data, int e) return repr; } +/** @} */ + #include "../end.h" #endif diff --git a/include/libfirm/adt/xmalloc.h b/include/libfirm/adt/xmalloc.h index 5a8c3b626..b07d0b7a2 100644 --- a/include/libfirm/adt/xmalloc.h +++ b/include/libfirm/adt/xmalloc.h @@ -38,12 +38,34 @@ #include "../begin.h" -/* xmalloc() & friends. */ +/** + * @ingroup adt + * @defgroup xmalloc Memory Allocation + * @{ + */ +/** + * Allocate @p size bytes on the heap. + * This is a wrapper for malloc which calls panic() in case of errors, so no + * error handling is required for code using it. + */ FIRM_API void *xmalloc(size_t size); +/** + * Chane size of a previously allocated memory block to @p size bytes. + * This is a wrapper for realloc which calls panic() in case of errors, so no + * error handling is required for code using it. + */ FIRM_API void *xrealloc(void *ptr, size_t size); +/** + * Allocates memory and copies string @p str into it. + * This is a wrapper for strdup which calls panic() in case of errors, so no + * error handling is required for code using it. + */ FIRM_API char *xstrdup(const char *str); - +/** + * Another name for the free function + * @deprecated + */ #define xfree(ptr) free(ptr) /** @@ -124,6 +146,7 @@ FIRM_API char *xstrdup(const char *str); */ #define OALLOCFZ(obst, type, member, n) ((type*)memset(OALLOCF((obst), type, member, (n)), 0, offsetof(type, member) + sizeof(*((type*)0)->member) * (n))) +/** @} */ #include "../end.h" diff --git a/include/libfirm/be.h b/include/libfirm/be.h index a97ec1b38..41d5454eb 100644 --- a/include/libfirm/be.h +++ b/include/libfirm/be.h @@ -38,18 +38,33 @@ * @{ */ -typedef enum { - ASM_CONSTRAINT_FLAG_NONE = 0, +/** + * flags categorizing assembler constraint specifications + */ +typedef enum asm_constraint_flags_t { + ASM_CONSTRAINT_FLAG_NONE = 0, /**< no constraints */ + /** input/output can be in a register */ ASM_CONSTRAINT_FLAG_SUPPORTS_REGISTER = 1u << 0, + /** input/output can be read/written to/from a memory address */ ASM_CONSTRAINT_FLAG_SUPPORTS_MEMOP = 1u << 1, + /** input can be encoded as an immediate number */ ASM_CONSTRAINT_FLAG_SUPPORTS_IMMEDIATE = 1u << 2, + /** the constraint is not supported yet by libFirm */ ASM_CONSTRAINT_FLAG_NO_SUPPORT = 1u << 3, + /** The input is also written to */ ASM_CONSTRAINT_FLAG_MODIFIER_WRITE = 1u << 4, + /** the input is not written to */ ASM_CONSTRAINT_FLAG_MODIFIER_NO_WRITE = 1u << 5, + /** the input is read */ ASM_CONSTRAINT_FLAG_MODIFIER_READ = 1u << 6, + /** the input is not read */ ASM_CONSTRAINT_FLAG_MODIFIER_NO_READ = 1u << 7, + /** the value is modified before all inputs to the asm block + * are handled. */ ASM_CONSTRAINT_FLAG_MODIFIER_EARLYCLOBBER = 1u << 8, + /** This operand and the following operand are commutative */ ASM_CONSTRAINT_FLAG_MODIFIER_COMMUTATIVE = 1u << 9, + /** invalid constraint (due to parse error) */ ASM_CONSTRAINT_FLAG_INVALID = 1u << 10 } asm_constraint_flags_t; ENUM_BITSET(asm_constraint_flags_t) @@ -138,7 +153,7 @@ typedef struct backend_params { FIRM_API int be_parse_arg(const char *arg); /** - * Return the backend configuration parameter. + * Returns the backend configuration parameter. * * @return libFirm configuration parameters for the selected * backend diff --git a/include/libfirm/cdep.h b/include/libfirm/cdep.h index 1939fcb65..b37e17f52 100644 --- a/include/libfirm/cdep.h +++ b/include/libfirm/cdep.h @@ -33,30 +33,30 @@ * @{ */ -/** Compute the control dependence graph for a graph. */ +/** Computes the control dependence graph for a graph. */ FIRM_API void compute_cdep(ir_graph *irg); -/** Free the control dependence info. */ +/** Frees the control dependence info. */ FIRM_API void free_cdep(ir_graph *irg); -/** Return control dependent block */ +/** Returns control dependent block */ FIRM_API ir_node *get_cdep_node(const ir_cdep *cdep); -/** Get next entry in a list of cdeps */ +/** Returns next entry in a list of cdeps */ FIRM_API ir_cdep *get_cdep_next(const ir_cdep *cdep); /** - * Return a list of all control dependences of a block. + * Returns a list of all control dependences of a block. */ FIRM_API ir_cdep *find_cdep(const ir_node *block); /** - * Replace the control dependence info of old by the info of nw. + * Replaces the control dependence info of old by the info of nw. */ FIRM_API void exchange_cdep(ir_node *old, const ir_node *nw); /** - * Check whether dependee is (directly) control dependent on candidate. + * Checks whether dependee is (directly) control dependent on candidate. * * @param dependee the (possible) dependent block * @param candidate the (possible) block on which dependee is dependent @@ -64,7 +64,7 @@ FIRM_API void exchange_cdep(ir_node *old, const ir_node *nw); FIRM_API int is_cdep_on(const ir_node *dependee, const ir_node *candidate); /** - * If block is control dependent on exactly one node, return this node, + * If block is control dependent on exactly one node, returns this node, * else NULL. * * @param block the block to check @@ -72,7 +72,7 @@ FIRM_API int is_cdep_on(const ir_node *dependee, const ir_node *candidate); FIRM_API ir_node *get_unique_cdep(const ir_node *block); /** - * Check if the given block is control dependent of more than one node. + * Checks if the given block is control dependent of more than one node. * * @param block the block to check */ diff --git a/include/libfirm/cgana.h b/include/libfirm/cgana.h index 101dce7c0..98479ef5d 100644 --- a/include/libfirm/cgana.h +++ b/include/libfirm/cgana.h @@ -67,17 +67,18 @@ FIRM_API size_t cgana(ir_entity ***free_methods); /** - * Free callee information. + * Frees callee information. * * Sets callee_info_state of the graph passed to none. Sets callee field * in all call nodes to NULL. Else it happens that the field contains * pointers to other than firm arrays. */ FIRM_API void free_callee_info(ir_graph *irg); +/** Frees callee information for all graphs in the current program. */ FIRM_API void free_irp_callee_info(void); /** - * Optimize the address expressions passed to call nodes. + * Optimizes the address expressions passed to call nodes. * Performs only the optimizations done by cgana. */ FIRM_API void opt_call_addrs(void); diff --git a/include/libfirm/compound_path.h b/include/libfirm/compound_path.h index ad415fe0b..1661f5237 100644 --- a/include/libfirm/compound_path.h +++ b/include/libfirm/compound_path.h @@ -30,7 +30,11 @@ #include "firm_types.h" #include "begin.h" -typedef struct compound_graph_path compound_graph_path, *ir_compound_graph_path_ptr; +/** + * path into compound types + * @deprecated + */ +typedef struct compound_graph_path compound_graph_path; /** * @deprecated @@ -58,32 +62,32 @@ FIRM_API size_t get_compound_graph_path_length(const compound_graph_path *gr); /** * @deprecated - * Get the entity node of an compound graph path at position pos. + * Returns the entity node of an compound graph path at position pos. */ ir_entity *get_compound_graph_path_node(const compound_graph_path *gr, size_t pos); /** * @deprecated - * Set the entity node of an compound graph path at position pos. + * Sets the entity node of an compound graph path at position pos. */ FIRM_API void set_compound_graph_path_node(compound_graph_path *gr, size_t pos, ir_entity *node); /** * @deprecated - * Get the index of an compound graph path at position pos. + * Returns the index of an compound graph path at position pos. */ FIRM_API long get_compound_graph_path_array_index(const compound_graph_path *gr, size_t pos); /** * @deprecated - * Set the index of an compound graph path at position pos. + * Sets the index of an compound graph path at position pos. */ FIRM_API void set_compound_graph_path_array_index(compound_graph_path *gr, size_t pos, long index); /** * @deprecated - * Get the type of an compound graph path. + * Returns the type of an compound graph path. */ FIRM_API ir_type *get_compound_graph_path_type(const compound_graph_path *gr); @@ -100,6 +104,10 @@ FIRM_API int is_proper_compound_graph_path(compound_graph_path *gr, size_t pos); * corresponding access path to the member of the compound. */ FIRM_API void add_compound_ent_value_w_path(ir_entity *ent, ir_node *val, compound_graph_path *path); +/** + * @deprecated + * Sets initializer value for a compound ent path + */ FIRM_API void set_compound_ent_value_w_path(ir_entity *ent, ir_node *val, compound_graph_path *path, size_t pos); /** @@ -159,7 +167,7 @@ FIRM_API void set_array_entity_values(ir_entity *ent, ir_tarval **values, size_t /** * @deprecated - * Return the offset in bits from the last byte address. + * Returns the offset in bits from the last byte address. * * This requires that the layout of all concerned types is fixed. * @@ -170,7 +178,7 @@ FIRM_API unsigned get_compound_ent_value_offset_bit_remainder(const ir_entity *e /** * @deprecated - * Return the overall offset of value at position pos in bytes. + * Returns the overall offset of value at position pos in bytes. * * This requires that the layout of all concerned types is fixed. * Asserts if bit offset is not byte aligned. diff --git a/include/libfirm/dbginfo.h b/include/libfirm/dbginfo.h index 6f60c6be5..785fb6e9c 100644 --- a/include/libfirm/dbginfo.h +++ b/include/libfirm/dbginfo.h @@ -168,7 +168,7 @@ typedef void (*retrieve_type_dbg_func)(char *buffer, size_t buffer_size, const type_dbg_info *tdbgi); /** - * Set global print_type_dbg_info function in firm + * Sets global print_type_dbg_info function in firm */ FIRM_API void ir_set_type_debug_retrieve(retrieve_type_dbg_func func); diff --git a/include/libfirm/execfreq.h b/include/libfirm/execfreq.h index 1c27c787e..a301e9169 100644 --- a/include/libfirm/execfreq.h +++ b/include/libfirm/execfreq.h @@ -35,26 +35,26 @@ * @{ */ -/** - * Create execfreq structure (to be used with set_execfreq) - */ +/** Creates execfreq structure (to be used with set_execfreq) */ FIRM_API ir_exec_freq *create_execfreq(ir_graph *irg); /** - * Set execution frequency of a basic block + * Sets execution frequency of a basic block */ FIRM_API void set_execfreq(ir_exec_freq *ef, const ir_node *block, double freq); -/** - * Create execfreq structure and initialize with estimated frequencies - */ +/** Creates execfreq structure and initialize with estimated frequencies. */ FIRM_API ir_exec_freq *compute_execfreq(ir_graph *irg, double loop_weight); +/** Frees memory occupied by execution frequency structure @p ef. */ FIRM_API void free_execfreq(ir_exec_freq *ef); +/** Returns execution frequency of block @p block. */ FIRM_API double get_block_execfreq(const ir_exec_freq *ef, const ir_node *block); +/** Returns execution frequency of block @p block, scaled into the range + * of an unsigned long type. */ FIRM_API unsigned long get_block_execfreq_ulong(const ir_exec_freq *ef, const ir_node *block); diff --git a/include/libfirm/firm.h b/include/libfirm/firm.h index 8455c13df..bc15cb05d 100644 --- a/include/libfirm/firm.h +++ b/include/libfirm/firm.h @@ -21,7 +21,8 @@ * @file * @brief Central firm header. * @author Martin Trapp, Christian Schaefer, Goetz Lindenmaier - * @brief Central FIRM header. + * This header includes all other firm headers and can be included conveniently + * by users of the library. */ /** @mainpage @@ -30,9 +31,6 @@ * with a novel concept to model side effects. It allows fast, aggressive * optimizations. * - * This header is the central header of the library implementation of this - * IR. - * * The internal representation of a program in firm is separated into five * different modules: * - Firm Graphs representing the code of a program. (Subdirectory ir.) @@ -57,6 +55,18 @@ * generic functionality to support implementations using firm. * (Code generation, further optimizations). */ + +/** @defgroup irana Analyses */ + +/** @defgroup adt Abstract Data Structures + * This module contains abstract datatypes. The firm API is fully functional + * without these abstract datatypes. They're provided as a convenience. + */ + +/** @defgroup algorithms Algorithms + * This module contains generic algorithms. The firm API is fully functional + * without them. They're provided as a convenience. + */ #ifndef FIRM_COMMON_FIRM_H #define FIRM_COMMON_FIRM_H diff --git a/include/libfirm/firm_types.h b/include/libfirm/firm_types.h index 930411482..7f7f0962f 100644 --- a/include/libfirm/firm_types.h +++ b/include/libfirm/firm_types.h @@ -27,57 +27,105 @@ #include "begin.h" +/** + * @page visited_counters Visited Counters + * A visited counter is an alternative to a visited flag for elements of a + * graph datastructure. + * A visited counter is an integer number added to the elements of a graph. + * There is also a global reference number for the whole datastructure. It is + * now possible to mark nodes by setting their visited counter to the global + * reference counter. Testing is done by comparing with the global reference + * counter. + * The advantage to simple boolean flag variables is that you can clear all + * element marks by increasing the global reference counter and don't need to + * visit the whole structure. + * This makes it more efficient when you only visit/mark a small amount of + * nodes in the graph. + */ + +/** Type for visited counters + * @see visited_counters */ typedef unsigned long ir_visited_t; +/** A label in the code (usually attached to a @ref Block) */ typedef unsigned long ir_label_t; -/** @ingroup dbg_info */ +/** @ingroup dbg_info + * Source Reference */ typedef struct dbg_info dbg_info; -/** @ingroup dbg_info */ +/** @ingroup dbg_info + * Source Type Reference */ typedef struct type_dbg_info type_dbg_info; -/** @ingroup ir_ident */ +/** @ingroup ir_ident + * Identifier */ typedef struct ident ident; -/** @ingroup ir_node */ +/** @ingroup ir_node + * Procedure Graph Node */ typedef struct ir_node ir_node; -/** @ingroup ir_op */ +/** @ingroup ir_op + * Node Opcode */ typedef struct ir_op ir_op; -/** @ingroup ir_mode */ +/** @ingroup ir_mode + * SSA Value mode */ typedef struct ir_mode ir_mode; -/** @ingroup iredges */ +/** @ingroup iredges + * Dynamic Reverse Edge */ typedef struct ir_edge_t ir_edge_t; -/** @ingroup ir_heights */ +/** @ingroup ir_heights + * Computed graph Heights */ typedef struct ir_heights_t ir_heights_t; -/** @ingroup ir_tarval */ +/** @ingroup ir_tarval + * Target Machine Value */ typedef struct ir_tarval ir_tarval; +/** @ingroup enumeration_type + * Enumeration constant */ typedef struct ir_enum_const ir_enum_const; -/** @ingroup ir_type */ +/** @ingroup ir_type + * Type */ typedef struct ir_type ir_type; -/** @ingroup ir_graph */ +/** @ingroup ir_graph + * Procedure Grpah */ typedef struct ir_graph ir_graph; -/** @ingroup ir_prog */ +/** @ingroup ir_prog + * Program */ typedef struct ir_prog ir_prog; -/** @ingroup ir_loop */ +/** @ingroup ir_loop + * Loop */ typedef struct ir_loop ir_loop; -/** @ingroup ir_entity */ +/** @ingroup ir_entity + * Entity */ typedef struct ir_entity ir_entity; +/** Extended Basic Block */ typedef struct ir_extblk ir_extblk; -/** @ingroup execfreq */ +/** @ingroup execfreq + * Execution Frequency Analysis Results */ typedef struct ir_exec_freq ir_exec_freq; -/** @ingroup ir_cdep */ +/** @ingroup ir_cdep + * Control Dependence Analysis Results */ typedef struct ir_cdep ir_cdep; -/** @ingroup ir_op */ +/** @ingroup be + * Target Architecture specific node operations */ typedef struct arch_irn_ops_t arch_irn_ops_t; +/** A graph transformation pass */ typedef struct ir_graph_pass_t ir_graph_pass_t; +/** A whole program transformation pass */ typedef struct ir_prog_pass_t ir_prog_pass_t; +/** A graph pass manager */ typedef struct ir_graph_pass_manager_t ir_graph_pass_manager_t; +/** A program pass manager */ typedef struct ir_prog_pass_manager_t ir_prog_pass_manager_t; -/** @ingroup ir_initializer */ +/** @ingroup ir_initializer + * Initializer (for entities) */ typedef union ir_initializer_t ir_initializer_t; +/** + * @ingroup irgwalk + * type for graph-walk callbacks */ typedef void irg_walk_func(ir_node *, void *); /** + * @ingroup Switch * A switch table mapping integer numbers to proj-numbers of a Switch-node. * Entries map a continuous range of integer numbers to a proj-number. * There must never be two different entries matching the same integer number. @@ -85,6 +133,7 @@ typedef void irg_walk_func(ir_node *, void *); typedef struct ir_switch_table ir_switch_table; /** + * @ingroup ir_cons * This function is called, whenever a local variable is used before definition * * @param irg the IR graph on which this happens @@ -113,6 +162,10 @@ typedef ir_node *uninitialized_local_variable_func_t(ir_graph *irg, ir_mode *mod static inline type operator |= (type& a, type b) { return a = (type)((int)a | (int)b); } \ } #else +/** Marks an enum type as bitset enum. That is the enumeration values will + * probably be combined to form a (bit)set of flags. + * When compiling for C++ this macro will define the ~, &, &=, ^, ^=, | and |= + * operators for the enum values. */ # define ENUM_BITSET(type) #endif @@ -123,10 +176,15 @@ typedef ir_node *uninitialized_local_variable_func_t(ir_graph *irg, ir_mode *mod static inline type operator --(type& a) { return a = (type)((int)a - 1); } \ } #else +/** Marks an enum type as countable enum. The enumeration values will be a + * linear sequence of numbers which can be iterated through by incrementing + * by 1. + * When compiling for C++ this macro will define the ++ and -- operators. */ # define ENUM_COUNTABLE(type) #endif /** + * @ingroup ir_node * Relations for comparing numbers */ typedef enum ir_relation { @@ -150,6 +208,7 @@ typedef enum ir_relation { ENUM_BITSET(ir_relation) /** + * @ingroup ir_node * constrained flags for memory operations. */ typedef enum ir_cons_flags { @@ -163,7 +222,10 @@ typedef enum ir_cons_flags { } ir_cons_flags; ENUM_BITSET(ir_cons_flags) -/** op_pin_state_pinned states. */ +/** + * @ingroup ir_node + * pinned states. + */ typedef enum op_pin_state { op_pin_state_floats = 0, /**< Nodes of this opcode can be placed in any basic block. */ op_pin_state_pinned = 1, /**< Nodes must remain in this basic block. */ @@ -174,6 +236,7 @@ typedef enum op_pin_state { } op_pin_state; /** + * @ingroup Cond * A type to express conditional jump predictions. */ typedef enum cond_jmp_predicate { @@ -183,6 +246,7 @@ typedef enum cond_jmp_predicate { } cond_jmp_predicate; /** + * @ingroup method_type * Additional method type properties: * Tell about special properties of a method type. Some * of these may be discovered by analyses. @@ -225,9 +289,12 @@ typedef enum mtp_additional_properties { } mtp_additional_properties; ENUM_BITSET(mtp_additional_properties) -/** This enum names the different kinds of symbolic Constants represented by +/** + * @ingroup SymConst + * This enum names the different kinds of symbolic Constants represented by * SymConst. The content of the attribute symconst_symbol depends on this tag. - * Use the proper access routine after testing this flag. */ + * Use the proper access routine after testing this flag. + */ typedef enum symconst_kind { symconst_type_size, /**< The SymConst is the size of the given type. symconst_symbol is type *. */ @@ -242,7 +309,9 @@ typedef enum symconst_kind { enumeration type. */ } symconst_kind; -/** SymConst attribute. +/** + * @ingroup SymConst + * SymConst attribute. * * This union contains the symbolic information represented by the node. * @ingroup SymConst @@ -253,8 +322,9 @@ typedef union symconst_symbol { ir_enum_const *enum_p; /**< The enumeration constant of a SymConst. */ } symconst_symbol; -/** The allocation place. +/** * @ingroup Alloc + * The allocation place. */ typedef enum ir_where_alloc { stack_alloc, /**< Alloc allocates the object on the stack. */ diff --git a/include/libfirm/heights.h b/include/libfirm/heights.h index 944f235f2..a101fc48c 100644 --- a/include/libfirm/heights.h +++ b/include/libfirm/heights.h @@ -41,7 +41,7 @@ */ /** - * Get the height of a node inside a basic block. + * Returns the height of a node inside a basic block. * The height of the node is the maximal number of edges between a sink node in * that block and the node itself (plus 1). * @param h The heights object. @@ -51,7 +51,7 @@ FIRM_API unsigned get_irn_height(const ir_heights_t *h, const ir_node *irn); /** - * Check, if a certain node is reachable according to data dependence edges + * Checks if a certain node is reachable according to data dependence edges * from another node. Both nodes must be in the same block. * @param h The heights object. * @param n The first node. @@ -62,7 +62,7 @@ FIRM_API int heights_reachable_in_block(ir_heights_t *h, const ir_node *n, const ir_node *m); /** - * Recompute the height information for a certain block. + * Recomputes the height information for a certain block. * This can be used to recompute the height information of a block. * @param h The heights object. * @param block The block @@ -71,14 +71,14 @@ FIRM_API int heights_reachable_in_block(ir_heights_t *h, const ir_node *n, FIRM_API unsigned heights_recompute_block(ir_heights_t *h, ir_node *block); /** - * Make a new heights object. - * This also computes the heights for each block in the graph. + * Creates a new heights object. This also computes the heights for each block + * in the graph. * @param irg The graph. */ FIRM_API ir_heights_t *heights_new(ir_graph *irg); /** - * Free a heights object. + * Frees a heights object. * @param h The heights object. */ FIRM_API void heights_free(ir_heights_t *h); diff --git a/include/libfirm/ident.h b/include/libfirm/ident.h index 5b97bf6b7..83ad465d5 100644 --- a/include/libfirm/ident.h +++ b/include/libfirm/ident.h @@ -44,7 +44,6 @@ * * @param str the string which shall be stored * @return id a handle for the generated ident - * @see get_id_str(), get_id_strlen() */ FIRM_API ident *new_id_from_str(const char *str); @@ -56,7 +55,6 @@ FIRM_API ident *new_id_from_str(const char *str); * @param str the string (or whatever) which shall be stored * @param len the length of the data in bytes * @return id a handle for the generated ident - * @see new_id_from_str(), get_id_strlen() */ FIRM_API ident *new_id_from_chars(const char *str, size_t len); @@ -68,7 +66,6 @@ FIRM_API ident *new_id_from_chars(const char *str, size_t len); * * @param id the ident * @return cp a string - * @see new_id_from_str(), new_id_from_chars(), get_id_strlen() */ FIRM_API const char *get_id_str(ident *id); @@ -77,34 +74,33 @@ FIRM_API const char *get_id_str(ident *id); * * @param id the ident * @return len the length of the string - * @see new_id_from_str(), new_id_from_chars(), get_id_str() */ FIRM_API size_t get_id_strlen(ident *id); /** - * Returns true if prefix is a prefix of an ident. + * Test if @p prefix is a prefix of ident @p id. * * @param prefix the prefix * @param id the ident - * @see new_id_from_str(), new_id_from_chars(), get_id_str(), id_is_prefix() + * @returns 1 if @p prefix is prefix of @p id, 0 otherwise */ FIRM_API int id_is_prefix(ident *prefix, ident *id); /** - * Returns true if suffix is a suffix of an ident. + * Test if @p suffix is a suffix of ident @p id. * * @param suffix the suffix * @param id the ident - * @see new_id_from_str(), new_id_from_chars(), get_id_str(), id_is_prefix() + * @returns 1 if @p suffix is suffix of @p id, 0 otherwise */ FIRM_API int id_is_suffix(ident *suffix, ident *id); /** - * Return true if an ident contains a given character. + * Test if identifier contains a given character. * * @param id the ident * @param c the character - * @see new_id_from_str(), new_id_from_chars(), get_id_str() + * @returns 1 if character is contained, 0 otherwise */ FIRM_API int id_contains_char(ident *id, char c); diff --git a/include/libfirm/irarch.h b/include/libfirm/irarch.h index a94495bcf..c84710617 100644 --- a/include/libfirm/irarch.h +++ b/include/libfirm/irarch.h @@ -91,13 +91,13 @@ typedef enum { ENUM_BITSET(arch_dep_opts_t) /** - * Set the optimizations that shall be applied. + * Sets the optimizations that shall be applied. * @param opts An optimization bit mask. */ FIRM_API void arch_dep_set_opts(arch_dep_opts_t opts); /** - * Replace Muls with Lea/Shifts/Add/Subs if these + * Replaces Muls with Lea/Shifts/Add/Subs if these * have smaller costs than the original multiplication. * * @param irn The Firm node to inspect. @@ -106,7 +106,7 @@ FIRM_API void arch_dep_set_opts(arch_dep_opts_t opts); FIRM_API ir_node *arch_dep_replace_mul_with_shifts(ir_node *irn); /** - * Replace Divs with Shifts and Add/Subs and Mulh. + * Replaces Divs with Shifts and Add/Subs and Mulh. * This function is driven by the 3 parameters: * - allow_mulhu * - allow_mulhs @@ -123,7 +123,7 @@ FIRM_API ir_node *arch_dep_replace_mul_with_shifts(ir_node *irn); FIRM_API ir_node *arch_dep_replace_div_by_const(ir_node *irn); /** - * Replace Mods with Shifts and Add/Subs and Mulh. + * Replaces Mods with Shifts and Add/Subs and Mulh. * This function is driven by the 3 parameters: * - allow_mulhu * - allow_mulhs diff --git a/include/libfirm/ircgopt.h b/include/libfirm/ircgopt.h index 32cb7b127..b9ce654b1 100644 --- a/include/libfirm/ircgopt.h +++ b/include/libfirm/ircgopt.h @@ -34,20 +34,17 @@ #include "firm_types.h" #include "begin.h" -/* Entfernt alle Methoden, die von den Methoden aus "keep_arr" - * (bezgl. der Abschaetzung get_Call_callee) nicht erreichbar sind. Die - * Abschaetzung der Aufrufrelation muss entsprechend an den - * Call-Operationen gespeichert sein. Die "entity->link"s werden dabei - * ueberschrieben. +/** + * Removes all methods which are not reachable from "keep_arr". * - * Frees all interprocedural loop information. */ + * Frees all interprocedural loop information. + */ FIRM_API void gc_irgs(size_t n_keep, ir_entity *keep_arr[]); /** * Creates an ir_prog pass for gc_irgs(). * * @param name the name of this pass or NULL - * * @return the newly created ir_graph pass */ FIRM_API ir_prog_pass_t *gc_irgs_pass(const char *name); diff --git a/include/libfirm/ircons.h b/include/libfirm/ircons.h index cf836dc53..b378702d5 100644 --- a/include/libfirm/ircons.h +++ b/include/libfirm/ircons.h @@ -810,15 +810,19 @@ FIRM_API ir_node *new_ASM(int arity, ir_node *in[], ir_asm_constraint *inputs, * @{ */ -/** Global variable holding the current ir graph. - * - * This global variable is used by the ir construction - * interface in ircons and by the optimizations. - * Further it is set by all walker functions. +/** + * Global variable holding the graph which is currently constructed. */ FIRM_API ir_graph *current_ir_graph; +/** + * Returns graph which is currently constructed + */ FIRM_API ir_graph *get_current_ir_graph(void); + +/** + * Sets graph which is currently constructed + */ FIRM_API void set_current_ir_graph(ir_graph *graph); /** Create an immature Block. @@ -827,13 +831,37 @@ FIRM_API void set_current_ir_graph(ir_graph *graph); * can be added with add_immBlock_pred(). Once all predecessors are * added the block must be matured. * - * Adds the block to the graph in current_ir_graph. Can be used with automatic - * Phi node construction. + * Adds the block to the graph in current_ir_graph. * This constructor can only be used if the graph is in state_building. */ FIRM_API ir_node *new_d_immBlock(dbg_info *db); +/** Create an immature Block. + * + * An immature Block has an unknown number of predecessors. Predecessors + * can be added with add_immBlock_pred(). Once all predecessors are + * added the block must be matured. + * + * Adds the block to the graph in current_ir_graph. + * This constructor can only be used if the graph is in state_building. + */ FIRM_API ir_node *new_immBlock(void); +/** Create an immature Block. + * + * An immature Block has an unknown number of predecessors. Predecessors + * can be added with add_immBlock_pred(). Once all predecessors are + * added the block must be matured. + * + * This constructor can only be used if the graph is in state_building. + */ FIRM_API ir_node *new_r_immBlock(ir_graph *irg); +/** Create an immature Block. + * + * An immature Block has an unknown number of predecessors. Predecessors + * can be added with add_immBlock_pred(). Once all predecessors are + * added the block must be matured. + * + * This constructor can only be used if the graph is in state_building. + */ FIRM_API ir_node *new_rd_immBlock(dbg_info *db, ir_graph *irg); /** Add a control flow edge to an immature block. */ @@ -842,19 +870,25 @@ FIRM_API void add_immBlock_pred(ir_node *immblock, ir_node *jmp); /** Finalize a Block node, when all control flows are known. */ FIRM_API void mature_immBlock(ir_node *block); -/** Sets the current block in which the following constructors place the - * nodes they construct. +/** + * Sets the current block in which the following constructors place the + * nodes they construct. * - * @param target The new current block. + * @param target The new current block. */ FIRM_API void set_cur_block(ir_node *target); +/** + * Sets current block of a given graph. + * @see set_cur_block() + */ FIRM_API void set_r_cur_block(ir_graph *irg, ir_node *target); /** Returns the current block of the current graph. */ FIRM_API ir_node *get_cur_block(void); +/** Returns current block of a given graph */ FIRM_API ir_node *get_r_cur_block(ir_graph *irg); -/** Get the current value of a local variable. +/** Returns the current value of a local variable. * * Use this function to obtain the last definition of the local variable * associated with pos. Pos may not exceed the value passed as n_loc @@ -864,6 +898,8 @@ FIRM_API ir_node *get_r_cur_block(ir_graph *irg); * @param *mode The mode of the value to get. */ FIRM_API ir_node *get_value(int pos, ir_mode *mode); +/** Returns the current value of a local variable in given graph + * @see get_value() */ FIRM_API ir_node *get_r_value(ir_graph *irg, int pos, ir_mode *mode); /** @@ -875,6 +911,9 @@ FIRM_API ir_node *get_r_value(ir_graph *irg, int pos, ir_mode *mode); * @param pos The position/id of the local variable. */ FIRM_API ir_mode *ir_guess_mode(int pos); +/** + * Try to guess the mode of a local variable in a given graph. + */ FIRM_API ir_mode *ir_r_guess_mode(ir_graph *irg, int pos); /** Remark a new definition of a variable. @@ -888,6 +927,7 @@ FIRM_API ir_mode *ir_r_guess_mode(ir_graph *irg, int pos); * @param *value The new value written to the local variable. */ FIRM_API void set_value(int pos, ir_node *value); +/** Sets current value of a variable in a given graph */ FIRM_API void set_r_value(ir_graph *irg, int pos, ir_node *value); /** @@ -899,15 +939,21 @@ FIRM_API void set_r_value(ir_graph *irg, int pos, ir_node *value); * no value number in the current block. */ FIRM_API int find_value(ir_node *value); +/** + * Find value number for a node in the current block of a given graph + * @see find_value() + */ FIRM_API int r_find_value(ir_graph *irg, ir_node *value); -/** Get the current memory state. +/** Returns the current memory state. * * Use this function to obtain the last definition of the memory * state. This call automatically inserts Phi nodes for the memory * state value. */ FIRM_API ir_node *get_store(void); +/** Returns current memory state for a given graph + * @see get_store() */ FIRM_API ir_node *get_r_store(ir_graph *irg); /** Remark a new definition of the memory state. @@ -918,6 +964,8 @@ FIRM_API ir_node *get_r_store(ir_graph *irg); * @param *store The new memory state. */ FIRM_API void set_store(ir_node *store); +/** Sets current memory state for a given graph + * @see set_store() */ FIRM_API void set_r_store(ir_graph *irg, ir_node *store); /** keep this node alive even if End is not control-reachable from it @@ -926,8 +974,6 @@ FIRM_API void set_r_store(ir_graph *irg, ir_node *store); */ FIRM_API void keep_alive(ir_node *ka); -/* --- initialize and finalize IR construction --- */ - /** Puts the graph into state "phase_high" */ FIRM_API void irg_finalize_cons(ir_graph *irg); @@ -937,6 +983,10 @@ FIRM_API void irg_finalize_cons(ir_graph *irg); * e.g., that no more subtypes will be added. */ FIRM_API void irp_finalize_cons(void); +/** + * Register a new callback for the case that the value of an uninitialized + * variable is requested. + */ FIRM_API void ir_set_uninitialized_local_variable_func( uninitialized_local_variable_func_t *func); diff --git a/include/libfirm/irdom.h b/include/libfirm/irdom.h index 35261d8f9..8626d7be9 100644 --- a/include/libfirm/irdom.h +++ b/include/libfirm/irdom.h @@ -30,8 +30,6 @@ #include "firm_types.h" #include "begin.h" -/** @defgroup irana Analyses */ - /** * @ingroup irana * @defgroup irdom Dominance Information @@ -96,32 +94,32 @@ FIRM_API int block_postdominates(const ir_node *a, const ir_node *b); FIRM_API int block_strictly_postdominates(const ir_node *a, const ir_node *b); /** - * Get the first node in the list of nodes dominated by a given block. + * Returns the first node in the list of nodes dominated by a given block. * * Each node keeps a list of nodes which it immediately dominates. The * nodes are queued using the @c next pointer in the @c dom_info struct. * Each node keeps a head of this list using the pointer @c first in the * same structure. * - * @param bl The block for which to get the first node dominated by @c bl. + * @param block The block for which to get the first node dominated by @c bl. * @return The first node dominated by @p bl. */ FIRM_API ir_node *get_Block_dominated_first(const ir_node *block); /** - * Get the first node in the list of nodes postdominated by a given blcok. + * Returns the first node in the list of nodes postdominated by a given blcok. */ FIRM_API ir_node *get_Block_postdominated_first(const ir_node *bl); /** - * Get the next node in a list of nodes which are dominated by some + * Returns the next node in a list of nodes which are dominated by some * other node. * @see get_Block_dominated_first(). - * @param dom The previous node. + * @param node The previous node. * @return The next node in this list or NULL if it was the last. */ FIRM_API ir_node *get_Block_dominated_next(const ir_node *node); /** - * Get the next node in a list of nodes which are postdominated by another node + * Returns the next node in a list of nodes which are postdominated by another node */ FIRM_API ir_node *get_Block_postdominated_next(const ir_node *node); diff --git a/include/libfirm/irdump.h b/include/libfirm/irdump.h index 933ad3ab9..a4e132b48 100644 --- a/include/libfirm/irdump.h +++ b/include/libfirm/irdump.h @@ -111,7 +111,7 @@ FIRM_API void dump_all_ir_graphs(const char *suffix); FIRM_API void ir_set_dump_path(const char *path); /** - * Set a prefix filter for output functions. + * Sets a prefix filter for output functions. * * All graph dumpers check this name. If the name is != "" and * not a prefix of the graph to be dumped, the dumper does not @@ -368,31 +368,31 @@ typedef int (*dump_edge_vcgattr_func)(FILE *out, const ir_node *node, int to); */ typedef void (*dump_node_edge_func)(FILE *out, const ir_node *node); -/** Set the node_vcgattr hook. */ +/** Sets the node_vcgattr hook. */ FIRM_API void set_dump_node_vcgattr_hook(dump_node_vcgattr_func hook); -/** Set the edge_vcgattr hook. */ +/** Sets the edge_vcgattr hook. */ FIRM_API void set_dump_edge_vcgattr_hook(dump_edge_vcgattr_func hook); /** - * Set the hook to be called to dump additional edges to a node. + * Sets the hook to be called to dump additional edges to a node. * @param func The hook to be called. */ FIRM_API void set_dump_node_edge_hook(dump_node_edge_func func); /** - * Get the additional edge dump hook. + * Returns the additional edge dump hook. * @return The current additional edge dump hook.] */ FIRM_API dump_node_edge_func get_dump_node_edge_hook(void); /** - * Set the hook to be called to dump additional edges to a block. + * Sets the hook to be called to dump additional edges to a block. * @param func The hook to be called. */ FIRM_API void set_dump_block_edge_hook(dump_node_edge_func func); /** - * Get the additional block edge dump hook. + * Returns the additional block edge dump hook. * @return The current additional block edge dump hook. */ FIRM_API dump_node_edge_func get_dump_block_edge_hook(void); diff --git a/include/libfirm/iredges.h b/include/libfirm/iredges.h index 4025e1196..7c522ec21 100644 --- a/include/libfirm/iredges.h +++ b/include/libfirm/iredges.h @@ -37,7 +37,7 @@ */ /** - * Get the first edge pointing to some node. + * Returns the first edge pointing to some node. * @note There is no order on out edges. First in this context only * means, that you get some starting point into the list of edges. * @param irn The node. @@ -48,7 +48,7 @@ FIRM_API const ir_edge_t *get_irn_out_edge_first_kind(const ir_node *irn, ir_edge_kind_t kind); /** - * Get the next edge in the out list of some node. + * Returns the next edge in the out list of some node. * @param irn The node. * @param last The last out edge you have seen. * @return The next out edge in @p irn 's out list after @p last. @@ -94,22 +94,22 @@ FIRM_API const ir_edge_t *get_irn_out_edge_next(const ir_node *irn, */ #define foreach_block_succ(bl, edge) foreach_out_edge_kind(bl, edge, EDGE_KIND_BLOCK) -/* - * Get the source node of an edge. +/** + * Returns the source node of an edge. * @param edge The edge. * @return The source node of that edge. */ FIRM_API ir_node *get_edge_src_irn(const ir_edge_t *edge); /** - * Get the position of an edge. + * Returns the position of an edge. * @param edge The edge. * @return The position in the in array of that edges source. */ FIRM_API int get_edge_src_pos(const ir_edge_t *edge); /** - * Get the edge object of an outgoing edge at a node. + * Returns the edge object of an outgoing edge at a node. * @param irn The node at which the edge originates. * @param pos The position of the edge. * @param kind The kind of the edge. @@ -120,14 +120,14 @@ FIRM_API const ir_edge_t *get_irn_edge_kind(const ir_node *irn, int pos, ir_edge_kind_t kind); /** - * Get the number of registered out edges for a specific kind. + * Returns the number of registered out edges for a specific kind. * @param irn The node. * @param kind The kind. */ FIRM_API int get_irn_n_edges_kind(const ir_node *irn, ir_edge_kind_t kind); /** - * Check, if the out edges are activated. + * Checks if the out edges are activated. * * @param irg The graph. * @param kind The edge kind. @@ -137,7 +137,7 @@ FIRM_API int get_irn_n_edges_kind(const ir_node *irn, ir_edge_kind_t kind); FIRM_API int edges_activated_kind(const ir_graph *irg, ir_edge_kind_t kind); /** - * Activate the edges for an irg. + * Activates the edges for an irg. * * @param irg The graph to activate the edges for. * @param kind The edge kind. @@ -145,7 +145,7 @@ FIRM_API int edges_activated_kind(const ir_graph *irg, ir_edge_kind_t kind); FIRM_API void edges_activate_kind(ir_graph *irg, ir_edge_kind_t kind); /** - * Deactivate the edges for an irg. + * Deactivates the edges for an irg. * * @param irg The graph. * @param kind The edge kind. @@ -153,8 +153,7 @@ FIRM_API void edges_activate_kind(ir_graph *irg, ir_edge_kind_t kind); FIRM_API void edges_deactivate_kind(ir_graph *irg, ir_edge_kind_t kind); /** - * Reroute edges of a specified kind from an old node to - * a new one. + * Reroutes edges of a specified kind from an old node to a new one. * * @param old the old node * @param nw the new node @@ -169,13 +168,13 @@ FIRM_API void edges_reroute_kind(ir_node *old, ir_node *nw, ir_edge_kind_t kind) FIRM_API int edges_verify(ir_graph *irg); /** - * veriy a certrain kind of out edges of graph @p irg. + * Verifies a certrain kind of out edges of graph @p irg. * @returns 1 if a problem was found, 0 otherwise */ FIRM_API int edges_verify_kind(ir_graph *irg, ir_edge_kind_t kind); /** - * Set edge verification flag. + * Sets edge verification flag. */ FIRM_API void edges_init_dbg(int do_dbg); @@ -190,22 +189,28 @@ FIRM_API void edges_init_dbg(int do_dbg); FIRM_API ir_graph_pass_t *irg_verify_edges_pass(const char *name, unsigned assert_on_problem); +/** Convenience version of edges_reroute_kind() with #EDGE_KIND_NORMAL */ #define edges_reroute(old, nw) edges_reroute_kind(old, nw, EDGE_KIND_NORMAL) +/** Conventience version of edges_activated_kind() for #EDGE_KIND_NORMAL and #EDGE_KIND_BLOCK */ #define edges_activated(irg) (edges_activated_kind(irg, EDGE_KIND_NORMAL) && edges_activated_kind(irg, EDGE_KIND_BLOCK)) #ifndef get_irn_n_edges +/** Conventience version of get_irn_n_edges_kind() with #EDGE_KIND_NORMAL. */ #define get_irn_n_edges(irn) get_irn_n_edges_kind(irn, EDGE_KIND_NORMAL) #endif #ifndef get_irn_out_edge_first +/** Convenience version of get_irn_out_edge_first_kind() with #EDGE_KIND_NORMAL */ #define get_irn_out_edge_first(irn) get_irn_out_edge_first_kind(irn, EDGE_KIND_NORMAL) #endif #ifndef get_block_succ_first +/** Convenience version of get_irn_out_edge_first_kind() with #EDGE_KIND_BLOCK */ #define get_block_succ_first(irn) get_irn_out_edge_first_kind(irn, EDGE_KIND_BLOCK) #endif #ifndef get_block_succ_next +/** Convenience version of get_irn_out_edge_next() with #EDGE_KIND_BLOCK */ #define get_block_succ_next(irn, last) get_irn_out_edge_next(irn, last) #endif @@ -219,7 +224,7 @@ FIRM_API ir_graph_pass_t *irg_verify_edges_pass(const char *name, FIRM_API void edges_activate(ir_graph *irg); /** - * Deactivate data and block edges for an irg. + * Deactivates data and block edges for an irg. * If the irg phase is phase_backend, Dependence edges are * additionally deactivated. * @param irg The graph. @@ -227,7 +232,7 @@ FIRM_API void edges_activate(ir_graph *irg); FIRM_API void edges_deactivate(ir_graph *irg); /** - * Ensure that edges are activated. + * Ensures that edges are activated. * * @param irg the IR graph * @@ -236,7 +241,7 @@ FIRM_API void edges_deactivate(ir_graph *irg); FIRM_API int edges_assure(ir_graph *irg); /** - * Ensure that edges of a given kind are activated. + * Ensures that edges of a given kind are activated. * * @param irg the IR graph * @param kind the edge kind @@ -257,6 +262,7 @@ FIRM_API int edges_assure_kind(ir_graph *irg, ir_edge_kind_t kind); FIRM_API void irg_block_edges_walk(ir_node *block, irg_walk_func *pre, irg_walk_func *post, void *env); +/** Graph walker following #EDGE_KIND_NORMAL edges. */ FIRM_API void irg_walk_edges(ir_node *start, irg_walk_func *pre, irg_walk_func *post, void *env); diff --git a/include/libfirm/irextbb.h b/include/libfirm/irextbb.h index 101a68a26..e3466177a 100644 --- a/include/libfirm/irextbb.h +++ b/include/libfirm/irextbb.h @@ -64,14 +64,14 @@ FIRM_API void compute_extbb_execfreqs(ir_graph *irg, ir_exec_freq *execfreqs); FIRM_API void free_extbb(ir_graph *irg); /** - * Return the extended block of a node. + * Returns the extended block of a node. * * @param node the node */ FIRM_API ir_extblk *get_nodes_extbb(const ir_node *node); /** - * Gets the visited counter of an extended block. + * Returns the visited counter of an extended block. * * @param blk the extended basic block */ @@ -125,14 +125,14 @@ FIRM_API void *get_extbb_link(const ir_extblk *blk); FIRM_API void set_extbb_link(ir_extblk *blk, void *link); /** - * Return the number of basic blocks of an extended block. + * Returns the number of basic blocks of an extended block. * * @param blk the extended basic block */ FIRM_API int get_extbb_n_blocks(const ir_extblk *blk); /** - * Return the i'th basic block of an extended block. + * Returns the i'th basic block of an extended block. * * @param blk the extended basic block * @param pos the position @@ -140,14 +140,14 @@ FIRM_API int get_extbb_n_blocks(const ir_extblk *blk); FIRM_API ir_node *get_extbb_block(const ir_extblk *blk, int pos); /** - * Return the leader basic block of an extended block. + * Returns the leader basic block of an extended block. * * @param blk the extended basic block */ FIRM_API ir_node *get_extbb_leader(const ir_extblk *blk); /** - * Return the node number of an extended block. + * Returns the node number of an extended block. * Its the block number of the leader block * * @param blk the extended basic block diff --git a/include/libfirm/irflag.h b/include/libfirm/irflag.h index 32161c40a..45fe2d52e 100644 --- a/include/libfirm/irflag.h +++ b/include/libfirm/irflag.h @@ -34,16 +34,16 @@ * Flags to customize the behavior of libfirm. * * There are the following groups of flags: - * 1. Optimization flags. - * a) There is a flag, 'optimize' to turn on/off all optimizations. - * b) There are flags for each individual optimization. Some flags turns + * -# Optimization flags. + * -# There is a flag, 'optimize' to turn on/off all optimizations. + * -# There are flags for each individual optimization. Some flags turns * transformations in several algorithms on/off. - * 2. Normalization flags. + * -# Normalization flags. * These flags steer transformations of the ir that improve it, as removing * dump Phi nodes (one predecessor, all predecessors are equal ...), Ids, Tuples ... - * 3. Verbosity flags. - * a) Flags to steer the level of the information. - * b) Flags to steer in which phase information should be dumped. + * -# Verbosity flags. + * -# Flags to steer the level of the information. + * -# Flags to steer in which phase information should be dumped. *@{ */ @@ -59,6 +59,8 @@ typedef unsigned optimization_state_t; * Default: optimize == 1. */ FIRM_API void set_optimize(int value); +/** Returns global optimizations flag. + * @see set_optimize() */ FIRM_API int get_optimize(void); /** Enables/Disables constant folding optimization. @@ -106,6 +108,8 @@ FIRM_API void set_opt_global_cse(int value); * 0 == not suppressed. */ FIRM_API void set_opt_suppress_downcast_optimization(int value); +/** Returns suppred_downcast flag. + * @see set_opt_suppress_downcast_optimization() */ FIRM_API int get_opt_suppress_downcast_optimization(void); /** diff --git a/include/libfirm/irgraph.h b/include/libfirm/irgraph.h index 3e956ce13..ce7ab894f 100644 --- a/include/libfirm/irgraph.h +++ b/include/libfirm/irgraph.h @@ -221,6 +221,7 @@ FIRM_API void set_irg_args(ir_graph *irg, ir_node *node); /** Returns the NoMem node of the given IR graph. */ FIRM_API ir_node *get_irg_no_mem(const ir_graph *irg); +/** Sets the NoMem node of graph @p irg. */ FIRM_API void set_irg_no_mem(ir_graph *irg, ir_node *node); /** Returns the number of value numbers of an IR graph. */ @@ -237,12 +238,13 @@ FIRM_API long get_irg_graph_nr(const ir_graph *irg); FIRM_API size_t get_irg_idx(const ir_graph *irg); /** - * Get the node for an index. + * Returns the node for an index. * @param irg The graph. * @param idx The index you want the node for. * @return The node with that index or NULL, if there is no node with that * index. * @note The node you got might be dead. + * @see get_irn_idx() */ FIRM_API ir_node *get_idx_irn(const ir_graph *irg, unsigned idx); @@ -343,23 +345,36 @@ FIRM_API void add_irg_additional_properties(ir_graph *irg, /** A void * field to link arbitrary information to the node. */ FIRM_API void set_irg_link(ir_graph *irg, void *thing); +/** Return void* field previously set by set_irg_link() */ FIRM_API void *get_irg_link(const ir_graph *irg); -/** Increments visited flag by one. - * @see also: get_irn_visited() get_irg_block_visited(). */ +/** Increments node visited counter by one. + * @see @ref visited_counters, irn_visited(), mark_irn_visited() */ FIRM_API void inc_irg_visited(ir_graph *irg); +/** Returns node visited counter. + * @see @ref visited_counters */ FIRM_API ir_visited_t get_irg_visited(const ir_graph *irg); +/** Sets node visited counter. + * @see @ref visited_counters */ FIRM_API void set_irg_visited(ir_graph *irg, ir_visited_t i); -/** An interprocedural flag valid for all irgs. - * @see also: get_irn_visited() get_irg_block_visited(). */ +/** Returns interprocedural node visited counter. + * @see @ref visited_counters */ FIRM_API ir_visited_t get_max_irg_visited(void); +/** Sets interprocedural node visited counter. + * @see @ref visited_counters */ FIRM_API void set_max_irg_visited(int val); +/** Increment interprocedural node visited counter by one. + * @see @ref visited_counters */ FIRM_API ir_visited_t inc_max_irg_visited(void); -/** Increments block_visited by one. - * @see also: get_irn_visited() get_irg_block_visited(). */ +/** Increments block visited counter by one. + * @see @ref visited_counters, Block_block_visited(), mark_Block_block_visited() */ FIRM_API void inc_irg_block_visited(ir_graph *irg); +/** Returns block visited counter. + * @see @ref visited_counters */ FIRM_API ir_visited_t get_irg_block_visited(const ir_graph *irg); +/** Sets block visited counter. + * @see @ref visited_counters */ FIRM_API void set_irg_block_visited(ir_graph *irg, ir_visited_t i); /** @@ -368,7 +383,7 @@ FIRM_API void set_irg_block_visited(ir_graph *irg, ir_visited_t i); * if 2 parties try to use the flags. */ typedef enum ir_resources_t { - IR_RESOURCE_NONE = 0, + IR_RESOURCE_NONE = 0, /**< no resource */ IR_RESOURCE_BLOCK_VISITED = 1 << 0, /**< Block visited flags are used. */ IR_RESOURCE_BLOCK_MARK = 1 << 1, /**< Block mark bits are used. */ IR_RESOURCE_IRN_VISITED = 1 << 2, /**< IR-node visited flags are used. */ @@ -379,8 +394,17 @@ typedef enum ir_resources_t { ENUM_BITSET(ir_resources_t) #ifndef NDEBUG +/** + * Reserves resources of a graph. + * + * This is a debug tool: All code should properly allocate the resources it uses + * so if two interlocked algorithms use the same resources that bug will get + * detected. + */ FIRM_API void ir_reserve_resources(ir_graph *irg, ir_resources_t resources); +/** Frees previously reserved resources. */ FIRM_API void ir_free_resources(ir_graph *irg, ir_resources_t resources); +/** Returns currently reserved resources. */ FIRM_API ir_resources_t ir_resources_reserved(const ir_graph *irg); #else #define ir_reserve_resources(irg,resources) (void)0 @@ -411,14 +435,14 @@ typedef enum { */ IR_GRAPH_STATE_NORMALISATION2 = 1U << 2, /** - * Define the semantic of Load(Sel(x)), if x has a bit offset (Bitfields!). + * Defines the semantic of Load(Sel(x)), if x has a bit offset (Bitfields!). * Normally, the frontend is responsible for bitfield masking operations. - * Set IMPLICIT_BITFIELD_MASKING, if the lowering phase must insert masking + * Sets IMPLICIT_BITFIELD_MASKING, if the lowering phase must insert masking * operations. */ IR_GRAPH_STATE_IMPLICIT_BITFIELD_MASKING = 1U << 3, /** - * Allow localopts to remove edges to unreachable code. + * Allows localopts to remove edges to unreachable code. * Warning: It is only safe to enable this when you are sure that you * apply all localopts to the fixpunkt. (=in optimize_graph_df) */ @@ -457,17 +481,17 @@ typedef enum { } ir_graph_state_t; ENUM_BITSET(ir_graph_state_t) -/** set some state flags on the graph (this does not clear the other flags) */ +/** Sets some state flags on the graph (this does not clear the other flags) */ FIRM_API void set_irg_state(ir_graph *irg, ir_graph_state_t state); -/** clear some state flags of the graph */ +/** Clears some state flags of the graph */ FIRM_API void clear_irg_state(ir_graph *irg, ir_graph_state_t state); -/** query whether a set of graph state flags are activated */ +/** Queries whether a set of graph state flags are activated */ FIRM_API int is_irg_state(const ir_graph *irg, ir_graph_state_t state); -/** Set a description for local value n. */ +/** Sets a description for local value n. */ FIRM_API void set_irg_loc_description(ir_graph *irg, int n, void *description); -/** Get the description for local value n. */ +/** Returns the description for local value n. */ FIRM_API void *get_irg_loc_description(ir_graph *irg, int n); /** Returns a estimated node count of the irg. This count is updated @@ -485,7 +509,7 @@ FIRM_API unsigned get_irg_fp_model(const ir_graph *irg); FIRM_API void set_irg_fp_model(ir_graph *irg, unsigned model); /** - * Access custom graph data. + * Accesses custom graph data. * The data must have been registered with * register_additional_graph_data() before. * @param graph The graph to get the data from. @@ -497,7 +521,7 @@ FIRM_API void set_irg_fp_model(ir_graph *irg, unsigned model); (assert(off > 0 && "Invalid graph data offset"), (type *) ((char *) (graph) - (off))) /** - * Get the pointer to the node some custom data belongs to. + * Returns the pointer to the node some custom data belongs to. * @param data The pointer to the custom data. * @param off The number as returned by register_additional_graph_data(). * @return A pointer to the ir node the custom data belongs to. @@ -506,7 +530,7 @@ FIRM_API void set_irg_fp_model(ir_graph *irg, unsigned model); (assert(off > 0 && "Invalid graph data offset"), (ir_graph *) ((char *) (data) + (off))) /** - * Request additional data to be allocated with an ir graph. + * Requests additional data to be allocated with an ir graph. * @param size The size of the additional data required. * @return A positive number, if the operation was successful, which * must be passed to the access macro get_irg_data(), 0 if the diff --git a/include/libfirm/irhooks.h b/include/libfirm/irhooks.h index ef318d490..10a4847e8 100644 --- a/include/libfirm/irhooks.h +++ b/include/libfirm/irhooks.h @@ -65,6 +65,7 @@ typedef enum { HOOK_OPT_LAST } hook_opt_kind; +/** Result of an if-conversion attempt */ typedef enum if_result_t { IF_RESULT_SUCCESS = 0, /**< if conversion could be done */ IF_RESULT_SIDE_EFFECT = 1, /**< if conversion failed because of side effect */ @@ -172,7 +173,7 @@ typedef struct hook_entry { /** This hook is called at the end of the node info dumper to dump additional node info. */ void (*_hook_node_info)(void *context, FILE *f, const ir_node *n); - } hook; + } hook; /**< hook */ /** the context for every hook */ void *context; @@ -185,35 +186,37 @@ typedef struct hook_entry { * possible hooks */ typedef enum { - hook_new_ir_op, - hook_free_ir_op, - hook_new_node, - hook_set_irn_n, - hook_replace, - hook_turn_into_id, - hook_normalize, - hook_new_graph, - hook_free_graph, - hook_irg_walk, - hook_irg_walk_blkwise, - hook_irg_block_walk, - hook_merge_nodes, - hook_reassociate, - hook_lower, - hook_inline, - hook_tail_rec, - hook_strength_red, - hook_dead_node_elim, - hook_dead_node_elim_subst, - hook_if_conversion, - hook_func_call, + hook_new_ir_op, /**< type for hook_new_ir_op() hook */ + hook_free_ir_op, /**< type for hook_free_ir_op() hook */ + hook_new_node, /**< type for hook_new_node() hook */ + hook_set_irn_n, /**< type for hook_set_irn_n() hook */ + hook_replace, /**< type for hook_replace() hook */ + hook_turn_into_id, /**< type for hook_turn_into_id() hook */ + hook_normalize, /**< type for hook_normalize() hook */ + hook_new_graph, /**< type for hook_new_graph() hook */ + hook_free_graph, /**< type for hook_free_graph() hook */ + hook_irg_walk, /**< type for hook_irg_walk() hook */ + hook_irg_walk_blkwise, /**< type for hook_irg_walk_blkwise() hook */ + hook_irg_block_walk, /**< type for hook_irg_block_walk() hook */ + hook_merge_nodes, /**< type for hook_merge_nodes() hook */ + hook_reassociate, /**< type for hook_reassociate() hook */ + hook_lower, /**< type for hook_lower() hook */ + hook_inline, /**< type for hook_inline() hook */ + hook_tail_rec, /**< type for hook_tail_rec() hook */ + hook_strength_red, /**< type for hook_strength_red() hook */ + hook_dead_node_elim, /**< type for hook_dead_node_elim() hook */ + hook_dead_node_elim_subst, /**< type for hook_dead_node_elim_subst() hook */ + hook_if_conversion, /**< type for hook_if_conversion() hook */ + hook_func_call, /**< type for hook_func_call() hook */ + /** type for hook_arch_dep_replace_mul_with_shifts() hook */ hook_arch_dep_replace_mul_with_shifts, + /** type for hook_arch_dep_replace_division_by_const() hook */ hook_arch_dep_replace_division_by_const, - hook_new_mode, - hook_new_entity, - hook_new_type, - hook_node_info, - hook_last + hook_new_mode, /**< type for hook_new_mode() hook */ + hook_new_entity, /**< type for hook_new_entity() hook */ + hook_new_type, /**< type for hook_new_type() hook */ + hook_node_info, /**< type for hook_node_info() hook */ + hook_last /**< last hook type */ } hook_type_t; /** @@ -232,10 +235,11 @@ FIRM_API void register_hook(hook_type_t hook, hook_entry_t *entry); */ FIRM_API void unregister_hook(hook_type_t hook, hook_entry_t *entry); +/** Global list of registerd hooks. */ FIRM_API hook_entry_t *hooks[hook_last]; /** - * execute the hook what with the args args + * Executes the hook @p what with the args @p args * Do not use this macro directly. */ #define hook_exec(what, args) do { \ @@ -246,43 +250,71 @@ FIRM_API hook_entry_t *hooks[hook_last]; } \ } while (0) +/** Called when a new node opcode has been created */ #define hook_new_ir_op(op) hook_exec(hook_new_ir_op, (hook_ctx_, op)) +/** Called when a node opcode has been freed */ #define hook_free_ir_op(op) hook_exec(hook_free_ir_op, (hook_ctx_, op)) +/** Called after a new node has been created */ #define hook_new_node(graph, node) hook_exec(hook_new_node, (hook_ctx_, graph, node)) +/** Called when a nodes input is changed */ #define hook_set_irn_n(src, pos, tgt, old_tgt) \ hook_exec(hook_set_irn_n, (hook_ctx_, src, pos, tgt, old_tgt)) +/** Called when a node is replaced */ #define hook_replace(old, nw) hook_exec(hook_replace, (hook_ctx_, old, nw)) +/** Called when a node is turned into an Id node */ #define hook_turn_into_id(node) hook_exec(hook_turn_into_id, (hook_ctx_, node)) +/** Called when a node is normalized */ #define hook_normalize(node) hook_exec(hook_normalize, (hook_ctx_, node)) +/** Called after a new graph has been created */ #define hook_new_graph(irg, ent) hook_exec(hook_new_graph, (hook_ctx_, irg, ent)) +/** Called after a graph has been freed */ #define hook_free_graph(irg) hook_exec(hook_free_graph, (hook_ctx_, irg)) +/** Called before a graph walk is started */ #define hook_irg_walk(irg, pre, post) hook_exec(hook_irg_walk, (hook_ctx_, irg, pre, post)) +/** Called before a blockwise graph walk is started */ #define hook_irg_walk_blkwise(irg, pre, post) \ hook_exec(hook_irg_walk_blkwise, (hook_ctx_, irg, pre, post)) +/** Called before a block walk is started */ #define hook_irg_block_walk(irg, node, pre, post) \ hook_exec(hook_irg_block_walk, (hook_ctx_, irg, node, pre, post)) +/** Called before 2 nodes get merged */ #define hook_merge_nodes(new_node_array, new_num_entries, old_node_array, old_num_entries, opt) \ hook_exec(hook_merge_nodes, (hook_ctx_, new_node_array, new_num_entries, old_node_array, old_num_entries, opt)) +/** Called before node inputs get reassociated */ #define hook_reassociate(start) hook_exec(hook_reassociate, (hook_ctx_, start)) +/** Called before a node gets lowered */ #define hook_lower(node) hook_exec(hook_lower, (hook_ctx_, node)) +/** Called before a graph is inlined */ #define hook_inline(call, irg) hook_exec(hook_inline, (hook_ctx_, call, irg)) +/** Called before tail recursion is performed */ #define hook_tail_rec(irg, n_calls) hook_exec(hook_tail_rec, (hook_ctx_, irg, n_calls)) +/** Called before strength reduction is performed */ #define hook_strength_red(irg, node) \ hook_exec(hook_strength_red, (hook_ctx_, irg, node)) +/** Called before dead node elimination is performed */ #define hook_dead_node_elim(irg, start) hook_exec(hook_dead_node_elim, (hook_ctx_, irg, start)) +/** Called when a node is substituted during dead code elimination */ #define hook_dead_node_elim_subst(irg, old, nw) \ hook_exec(hook_dead_node_elim_subst, (hook_ctx_, irg, old, nw)) +/** Called when if-conversion creates a Mux node */ #define hook_if_conversion(irg, phi, pos, mux, reason) \ hook_exec(hook_if_conversion, (hook_ctx_, irg, phi, pos, mux, reason)) +/** Called when a function call is optimized */ #define hook_func_call(irg, call) \ hook_exec(hook_func_call, (hook_ctx_, irg, call)) +/** Called when a mul is replaced with shifts */ #define hook_arch_dep_replace_mul_with_shifts(irn) \ hook_exec(hook_arch_dep_replace_mul_with_shifts, (hook_ctx_, irn)) +/** Called when a dvision by constant is replaced */ #define hook_arch_dep_replace_division_by_const(irn) \ hook_exec(hook_arch_dep_replace_division_by_const, (hook_ctx_, irn)) +/** Called when a new mode has been created */ #define hook_new_mode(mode) hook_exec(hook_new_mode, (hook_ctx_, mode)) +/** Called when a new entity has been created */ #define hook_new_entity(ent) hook_exec(hook_new_entity, (hook_ctx_, ent)) +/** Called when a new type has been created */ #define hook_new_type(tp) hook_exec(hook_new_type, (hook_ctx_, tp)) +/** Called at the end of the node info dumper to dump additional node info. */ #define hook_node_info(F, node) hook_exec(hook_node_info, (hook_ctx_, F, node)) #include "end.h" diff --git a/include/libfirm/irloop.h b/include/libfirm/irloop.h index 1b4b5ce3a..1cc507abf 100644 --- a/include/libfirm/irloop.h +++ b/include/libfirm/irloop.h @@ -54,15 +54,18 @@ FIRM_API void clear_backedges(ir_node *n); /** Loop elements: loop nodes and ir nodes */ typedef union { - firm_kind *kind; /**< is either k_ir_node or k_ir_loop */ - ir_node *node; /**< Pointer to an ir_node element */ - ir_loop *son; /**< Pointer to an ir_loop element */ - ir_graph *irg; /**< Pointer to an ir_graph element (only callgraph loop trees) */ + firm_kind *kind; /**< is either k_ir_node or k_ir_loop */ + ir_node *node; /**< Pointer to an ir_node element */ + ir_loop *son; /**< Pointer to an ir_loop element */ + ir_graph *irg; /**< Pointer to an ir_graph element (only callgraph loop trees) */ } loop_element; +/** Tests whether a given pointer points to a loop. + * @note only works reliably if @p thing points to something with a #firm_kind + * header */ FIRM_API int is_ir_loop(const void *thing); -/** Set the outermost loop in ir graph as basic access to loop tree. */ +/** Sets the outermost loop in ir graph as basic access to loop tree. */ FIRM_API void set_irg_loop(ir_graph *irg, ir_loop *l); /** Returns the root loop info (if exists) for an irg. */ @@ -79,8 +82,8 @@ FIRM_API unsigned get_loop_depth(const ir_loop *loop); /** Returns the number of elements contained in loop. */ FIRM_API size_t get_loop_n_elements(const ir_loop *loop); -/** Returns a loop element. A loop element can be interpreted as a -kind pointer, an ir_node* or an ir_loop*. */ +/** Returns a loop element. A loop element can be interpreted as a + * kind pointer, an ir_node* or an ir_loop*. */ FIRM_API loop_element get_loop_element(const ir_loop *loop, size_t pos); /** Returns a unique node number for the loop node to make output @@ -90,6 +93,8 @@ FIRM_API long get_loop_loop_nr(const ir_loop *loop); /** A field to connect additional information to a loop. */ FIRM_API void set_loop_link(ir_loop *loop, void *link); +/** Returns field with additional loop information. + * @see set_loop_link() */ FIRM_API void *get_loop_link(const ir_loop *loop); /** Constructs backedge information and loop tree for a graph. @@ -144,9 +149,10 @@ FIRM_API void assure_loopinfo(ir_graph *irg); * Resets all backedges. Works for any construction algorithm. */ FIRM_API void free_loop_information(ir_graph *irg); -FIRM_API void free_all_loop_information (void); +/** Removes loop information from all graphs in the current program. */ +FIRM_API void free_all_loop_information(void); -/** Test whether a value is loop invariant. +/** Tests whether a value is loop invariant. * * @param n The node to be tested. * @param block A block node. diff --git a/include/libfirm/irmemory.h b/include/libfirm/irmemory.h index 7ed3fbf25..43858e600 100644 --- a/include/libfirm/irmemory.h +++ b/include/libfirm/irmemory.h @@ -32,7 +32,7 @@ /** @ingroup irana * @defgroup ir_memory Memory Disambiguator * - * A memory disambiguator checks wether 2 given SSA values representing + * A memory disambiguator checks whether 2 given SSA values representing * addresses alias. * * @{ @@ -83,7 +83,7 @@ typedef enum ir_storage_class_class_t { } ir_storage_class_class_t; ENUM_BITSET(ir_storage_class_class_t) -/** Get the base storage class (ignore modifier) */ +/** Returns the base storage class (ignore modifier) */ FIRM_API ir_storage_class_class_t get_base_sc(ir_storage_class_class_t x); /** @@ -146,7 +146,7 @@ FIRM_API ir_alias_relation get_alias_relation( const ir_node *adr2, const ir_mode *mode2); /** - * Set a source language specific memory disambiguator function. + * Sets a source language specific memory disambiguator function. * * @param func The callback. */ @@ -157,11 +157,10 @@ FIRM_API void set_language_memory_disambiguator(DISAMBIGUATOR_FUNC func); */ FIRM_API void mem_disambig_init(void); -/* +/** * Determine the alias relation between two addresses and * cache the result. * - * @param irg The current graph. * @param adr1 The first address. * @param mode1 The mode of the first memory access. * @param adr2 The second address. @@ -215,14 +214,14 @@ FIRM_API void set_irp_globals_entity_usage_state(ir_entity_usage_computed_state FIRM_API void assure_irp_globals_entity_usage_computed(void); /** - * Get the memory disambiguator options for a graph. + * Returns the memory disambiguator options for a graph. * * @param irg the graph */ FIRM_API unsigned get_irg_memory_disambiguator_options(const ir_graph *irg); /** - * Set the memory disambiguator options for a graph. + * Sets the memory disambiguator options for a graph. * * @param irg the graph * @param options a set of options @@ -231,7 +230,8 @@ FIRM_API void set_irg_memory_disambiguator_options(ir_graph *irg, unsigned options); /** - * Set the global disambiguator options for all graphs not having local options. + * Sets the global disambiguator options for all graphs not having local + * options. * * @param options a set of options */ diff --git a/include/libfirm/irmode.h b/include/libfirm/irmode.h index 49b0e8b29..6d458d26a 100644 --- a/include/libfirm/irmode.h +++ b/include/libfirm/irmode.h @@ -136,7 +136,7 @@ FIRM_API int get_mode_sign(const ir_mode *mode); /** Returns the arithmetic of a mode */ FIRM_API ir_mode_arithmetic get_mode_arithmetic(const ir_mode *mode); -/** Get the modulo shift attribute. +/** Returns the modulo shift attribute. * * Attribute modulo shift specifies for modes of kind irms_int_number * whether shift applies modulo to value of bits to shift. Zero for @@ -249,26 +249,47 @@ FIRM_API ir_mode *mode_T; /**< tuple (none) */ FIRM_API ir_mode *mode_ANY;/**< undefined mode */ FIRM_API ir_mode *mode_BAD;/**< bad mode */ +/** Returns float mode */ FIRM_API ir_mode *get_modeF(void); +/** Returns double mode */ FIRM_API ir_mode *get_modeD(void); +/** Returns quadruple prevision mode */ FIRM_API ir_mode *get_modeQ(void); +/** Returns byte signed mode */ FIRM_API ir_mode *get_modeBs(void); +/** Returns byte unsigned mode */ FIRM_API ir_mode *get_modeBu(void); +/** Returns halfword signed mode */ FIRM_API ir_mode *get_modeHs(void); +/** Returns halfword unsigned mode */ FIRM_API ir_mode *get_modeHu(void); +/** Returns integer signed mode */ FIRM_API ir_mode *get_modeIs(void); +/** Returns integer unsigned mode */ FIRM_API ir_mode *get_modeIu(void); +/** Returns long signed mode */ FIRM_API ir_mode *get_modeLs(void); +/** Returns long unsigned mode */ FIRM_API ir_mode *get_modeLu(void); +/** Returns long long signed mode */ FIRM_API ir_mode *get_modeLLs(void); +/** Returns long long unsigned mode */ FIRM_API ir_mode *get_modeLLu(void); +/** Returns pointer mode */ FIRM_API ir_mode *get_modeP(void); +/** Returns internal boolean mode */ FIRM_API ir_mode *get_modeb(void); +/** Returns control-flow mode */ FIRM_API ir_mode *get_modeX(void); +/** Returns Basic-Block mode */ FIRM_API ir_mode *get_modeBB(void); +/** Returns memory mode */ FIRM_API ir_mode *get_modeM(void); +/** Returns tuple mode */ FIRM_API ir_mode *get_modeT(void); +/** Returns ANY mode */ FIRM_API ir_mode *get_modeANY(void); +/** Returns BAD mode */ FIRM_API ir_mode *get_modeBAD(void); /** Returns the machine specific pointer mode for code addresses. */ @@ -289,44 +310,22 @@ FIRM_API void set_modeP_code(ir_mode *p); */ FIRM_API void set_modeP_data(ir_mode *p); -/*@{ - Functions to check, whether a mode is signed, float, int, character, - reference, num, data, datab or dataM. - - For more exact definitions read the corresponding pages - in the firm documentation or the following enumeration - - The set of "float" is defined as: - float = {irm_F, irm_D, irm_E} - - The set of "int" is defined as: - int = {irm_Bs, irm_Bu, irm_Hs, irm_Hu, irm_Is, irm_Iu, irm_Ls, irm_Lu} - - The set of "reference" is defined as: - reference = {irm_P} - - The set of "num" is defined as: - num = {float || int} - - The set of "data" is defined as: - data = {num || reference} - - The set of "datab" is defined as: - datab = {data || irm_b } - - The set of "dataM" is defined as: - dataM = {data || irm_M} -*/ - +/** Returns 1 if @p mode is signed, 0 otherwise */ FIRM_API int mode_is_signed (const ir_mode *mode); +/** Returns 1 if @p mode is for floatingpoint numbers, 0 otherwise */ FIRM_API int mode_is_float (const ir_mode *mode); +/** Returns 1 if @p mode is for integer numbers, 0 otherwise */ FIRM_API int mode_is_int (const ir_mode *mode); +/** Returns 1 if @p mode is for references/pointers, 0 otherwise */ FIRM_API int mode_is_reference (const ir_mode *mode); +/** Returns 1 if @p mode is for numeric values, 0 otherwise */ FIRM_API int mode_is_num (const ir_mode *mode); +/** Returns 1 if @p mode is for data values, 0 otherwise */ FIRM_API int mode_is_data (const ir_mode *mode); +/** Returns 1 if @p mode is for data values or internal booleans, 0 otherwise */ FIRM_API int mode_is_datab (const ir_mode *mode); +/** Returns 1 if @p mode is for data values or memory, 0 otherwise */ FIRM_API int mode_is_dataM (const ir_mode *mode); -/*@}*/ /** * Returns true if sm can be converted to lm without loss @@ -386,7 +385,7 @@ FIRM_API int mode_overflow_on_unary_Minus(const ir_mode *mode); FIRM_API int mode_wrap_around(const ir_mode *mode); /** - * Return the signed integer equivalent mode for an reference mode. + * Returns the signed integer equivalent mode for an reference mode. */ FIRM_API ir_mode *get_reference_mode_signed_eq(ir_mode *mode); @@ -396,7 +395,7 @@ FIRM_API ir_mode *get_reference_mode_signed_eq(ir_mode *mode); FIRM_API void set_reference_mode_signed_eq(ir_mode *ref_mode, ir_mode *int_mode); /** - * Return the unsigned integer equivalent mode for an reference mode. + * Returns the unsigned integer equivalent mode for an reference mode. */ FIRM_API ir_mode *get_reference_mode_unsigned_eq(ir_mode *mode); @@ -406,12 +405,12 @@ FIRM_API ir_mode *get_reference_mode_unsigned_eq(ir_mode *mode); FIRM_API void set_reference_mode_unsigned_eq(ir_mode *ref_mode, ir_mode *int_mode); /** - * Return size of mantissa in bits (for float modes) + * Returns size of mantissa in bits (for float modes) */ FIRM_API unsigned get_mode_mantissa_size(const ir_mode *mode); /** - * Return size of exponent in bits (for float modes) + * Returns size of exponent in bits (for float modes) */ FIRM_API unsigned get_mode_exponent_size(const ir_mode *mode); diff --git a/include/libfirm/irnode.h b/include/libfirm/irnode.h index 43739b4ea..b96dd3986 100644 --- a/include/libfirm/irnode.h +++ b/include/libfirm/irnode.h @@ -74,7 +74,7 @@ FIRM_API int is_ir_node(const void *thing); FIRM_API int get_irn_arity(const ir_node *node); /** - * Get the n-th predecessor of a node. + * Returns the n-th predecessor of a node. * This function removes Id predecessors. */ FIRM_API ir_node *get_irn_n(const ir_node *node, int n); @@ -110,14 +110,14 @@ FIRM_API int add_irn_dep(ir_node *node, ir_node *dep); FIRM_API void add_irn_deps(ir_node *tgt, ir_node *src); /** - * Get the length of the dependency array. + * Returns the length of the dependency array. * @param node The node. * @return The length of the dependency array or 0 if it has not yet been allocated. */ FIRM_API int get_irn_deps(const ir_node *node); /** - * Get an entry of the dependency array. + * Returns an entry of the dependency array. * @param node The node. * @param pos The position. * @return The node at that position. @@ -125,14 +125,14 @@ FIRM_API int get_irn_deps(const ir_node *node); FIRM_API ir_node *get_irn_dep(const ir_node *node, int pos); /** - * Set an entry of the dependency array. + * Sets an entry of the dependency array. * @param node The node. * @param pos The position. * @param dep The dependency target. */ FIRM_API void set_irn_dep(ir_node *node, int pos, ir_node *dep); -/** Replace the n-th predecessor of a node with a new one. */ +/** Replaces the n-th predecessor of a node with a new one. */ FIRM_API void set_irn_n(ir_node *node, int n, ir_node *in); /** * Appends a new predecessor to a node. This only works for nodes with @@ -140,25 +140,23 @@ FIRM_API void set_irn_n(ir_node *node, int n, ir_node *in); * @returns the number of the new input */ FIRM_API int add_irn_n(ir_node *node, ir_node *in); -/** Remove predecessor i from Sync n */ -FIRM_API void del_Sync_n(ir_node *n, int i); /** Sets the mode struct of node. */ FIRM_API void set_irn_mode(ir_node *node, ir_mode *mode); -/** Gets the mode struct of a node. */ +/** Returns the mode struct of a node. */ FIRM_API ir_mode *get_irn_mode(const ir_node *node); -/** Gets the opcode struct of the node. */ +/** Returns the opcode struct of the node. */ FIRM_API ir_op *get_irn_op(const ir_node *node); /** Sets the opcode struct of the node. */ FIRM_API void set_irn_op(ir_node *node, ir_op *op); -/** Gets the opcode-enum of the node. */ +/** Returns the opcode-enum of the node. */ FIRM_API unsigned get_irn_opcode(const ir_node *node); -/** Get the string representation of the opcode. */ +/** Returns the string representation of the opcode. */ FIRM_API const char *get_irn_opname(const ir_node *node); -/** Get the ident for a string representation of the opcode. */ +/** Returns the ident for a string representation of the opcode. */ FIRM_API ident *get_irn_opident(const ir_node *node); /** If arg is an argument of the node, returns its position, -1 otherwise */ FIRM_API int get_irn_pred_pos(ir_node *node, ir_node *arg); -/** Gets the visited counter of a node. */ +/** Returns the visited counter of a node. */ FIRM_API ir_visited_t get_irn_visited(const ir_node *node); /** Sets the visited counter of a node. */ FIRM_API void set_irn_visited(ir_node *node, ir_visited_t visited); @@ -196,7 +194,7 @@ FIRM_API long get_irn_node_nr(const ir_node *node); */ FIRM_API op_pin_state get_irn_pinned(const ir_node *node); -/** Set pin state for nodes with op pin state op_pin_state_exc_pinned */ +/** Sets pin state for nodes with op pin state op_pin_state_exc_pinned */ FIRM_API void set_irn_pinned(ir_node *node, op_pin_state state); /** Returns whether the node is currently pinned. @@ -231,7 +229,7 @@ FIRM_API ir_node *new_ir_node(dbg_info *db, ir_graph *irg, ir_node *block, */ /** - * Return the block the node belongs to. This is only + * Returns the block the node belongs to. This is only * possible for pinned nodes or if the graph is in pinned state. * Otherwise the block may be incorrect. This condition is * now checked by an assertion. @@ -246,15 +244,15 @@ FIRM_API ir_node *get_nodes_block(const ir_node *node); /** Sets the Block of a node. */ FIRM_API void set_nodes_block(ir_node *node, ir_node *block); -/** Return the number of control flow predecessors of a block. */ +/** Returns the number of control flow predecessors of a block. */ FIRM_API int get_Block_n_cfgpreds(const ir_node *block); -/** Return the control flow predecessor of a block at a given position. */ +/** Returns the control flow predecessor of a block at a given position. */ FIRM_API ir_node *get_Block_cfgpred(const ir_node *block, int pos); -/** Set the control flow predecessor of a block at a given position. */ +/** Sets the control flow predecessor of a block at a given position. */ FIRM_API void set_Block_cfgpred(ir_node *block, int pos, ir_node *pred); /** - * Return the position of the predecessor block pred in the inputs + * Returns the position of the predecessor block pred in the inputs * of the block block. * * @param block the block @@ -268,7 +266,7 @@ FIRM_API void set_Block_cfgpred(ir_node *block, int pos, ir_node *pred); */ FIRM_API int get_Block_cfgpred_pos(const ir_node *block, const ir_node *pred); -/** Get the predecessor block. +/** Returns the predecessor block. * * Returns the block corresponding to the predecessor pos of block. * @@ -281,7 +279,7 @@ FIRM_API int get_Block_cfgpred_pos(const ir_node *block, const ir_node *pred); */ FIRM_API ir_node *get_Block_cfgpred_block(const ir_node *node, int pos); -/** Return the matured flag of a block */ +/** Returns the matured flag of a block */ FIRM_API int get_Block_matured(const ir_node *block); /** set the matured flag of a block. */ FIRM_API void set_Block_matured(ir_node *block, int matured); @@ -292,9 +290,9 @@ FIRM_API ir_visited_t get_Block_block_visited(const ir_node *block); /** set block visited flag */ FIRM_API void set_Block_block_visited(ir_node *block, ir_visited_t visit); -/** mark a block as visited by setting its visited counter */ +/** Marks a block as visited by setting its visited counter */ FIRM_API void mark_Block_block_visited(ir_node *node); -/** returns 1 if a block is marked as visited */ +/** Returns 1 if a block is marked as visited */ FIRM_API int Block_block_visited(const ir_node *node); /** Returns the extended basic block a block belongs to. */ @@ -305,22 +303,22 @@ FIRM_API void set_Block_extbb(ir_node *block, ir_extblk *extblk); FIRM_API ir_graph *get_Block_irg(const ir_node *block); /** Returns the entity for a Block (creating it if necessary) */ FIRM_API ir_entity *create_Block_entity(ir_node *block); -/** Gets the head of the Phi list for this block. */ +/** Returns the head of the Phi list for this block. */ FIRM_API ir_node *get_Block_phis(const ir_node *block); /** Sets the head of the Phi list for this block. */ FIRM_API void set_Block_phis(ir_node *block, ir_node *phi); /** Add a Phi node to the list of Block Phi's. */ FIRM_API void add_Block_phi(ir_node *block, ir_node *phi); -/** Get the Block mark (single bit). */ +/** Returns the Block mark (single bit). */ FIRM_API unsigned get_Block_mark(const ir_node *block); -/** Set the Block mark (single bit). */ +/** Sets the Block mark (single bit). */ FIRM_API void set_Block_mark(ir_node *block, unsigned mark); /** @} */ -/** Test whether arbitrary node is frame pointer. +/** Tests whether arbitrary node is frame pointer. * - * Test whether arbitrary node is frame pointer, i.e. Proj(pn_Start_P_frame_base) + * Tests whether arbitrary node is frame pointer, i.e. Proj(pn_Start_P_frame_base) * from Start. If so returns frame type, else Null. */ FIRM_API ir_type *is_frame_pointer(const ir_node *n); @@ -328,31 +326,32 @@ FIRM_API ir_type *is_frame_pointer(const ir_node *n); * @{ */ -/** Return the number of Keep alive node. */ +/** Returns the number of Keep alive node. */ FIRM_API int get_End_n_keepalives(const ir_node *end); -/** Return the Keep alive node a position pos. */ +/** Returns the Keep alive node a position pos. */ FIRM_API ir_node *get_End_keepalive(const ir_node *end, int pos); /** Keep alive dedicated nodes. These must be either PhiM or Block nodes. */ FIRM_API void add_End_keepalive(ir_node *end, ir_node *ka); -/** Set the Keep alive node at position pos. */ +/** Sets the Keep alive node at position pos. */ FIRM_API void set_End_keepalive(ir_node *end, int pos, ir_node *ka); /** - * Set new keep-alives. + * Sets new keep-alives. * Beware: This might be an expensive operation if dynamic edges are enabled, * so avoid it in the backend. */ FIRM_API void set_End_keepalives(ir_node *end, int n, ir_node *in[]); -/** Remove irn from the keep-alive set. */ +/** Removes irn from the keep-alive set. */ FIRM_API void remove_End_keepalive(ir_node *end, ir_node *irn); -/** Remove Bads, NoMem and doublets from the keep-alive set. */ +/** Removes Bads, NoMem and doublets from the keep-alive set. */ FIRM_API void remove_End_Bads_and_doublets(ir_node *end); /** Some parts of the End node are allocated separately -- their memory - is not recovered by dead_node_elimination if a End node is dead. - free_End() frees these data structures. */ + * is not recovered by dead_node_elimination if a End node is dead. + * free_End() frees these data structures. + */ FIRM_API void free_End(ir_node *end); /** @} */ @@ -361,10 +360,14 @@ FIRM_API void free_End(ir_node *end); * @{ */ +/** Returns return value inputs of Return node @p node as array. */ FIRM_API ir_node **get_Return_res_arr(ir_node *node); -FIRM_API size_t get_Return_n_ress(const ir_node *node); -FIRM_API ir_node *get_Return_res(const ir_node *node, int pos); -FIRM_API void set_Return_res(ir_node *node, int pos, ir_node *res); +/** Returns number of return value inputs of Return node @p node. */ +FIRM_API size_t get_Return_n_ress(const ir_node *node); +/** Returns return value input @p pos of Return node @p node. */ +FIRM_API ir_node *get_Return_res(const ir_node *node, int pos); +/** Sets return value input @p pos of Return node @p node to value @p res. */ +FIRM_API void set_Return_res(ir_node *node, int pos, ir_node *res); /** @} */ @@ -372,13 +375,13 @@ FIRM_API void set_Return_res(ir_node *node, int pos, ir_node *res); * @{ */ -/** Return non-zero if the given Const node represents the 0 constant. */ +/** Returns non-zero if the given Const node represents the 0 constant. */ FIRM_API int is_Const_null(const ir_node *node); -/** Return non-zero if the given Const node represents the 1 constant. */ +/** Returns non-zero if the given Const node represents the 1 constant. */ FIRM_API int is_Const_one(const ir_node *node); -/** Return non-zero if the given Const node represents the constant with all bits set. */ +/** Returns non-zero if the given Const node represents the constant with all bits set. */ FIRM_API int is_Const_all_one(const ir_node *node); /** @} */ @@ -408,26 +411,36 @@ FIRM_API int is_SymConst_addr_ent(const ir_node *node); /** Returns non-zero if s symconst kind has an enum_const attribute */ #define SYMCONST_HAS_ENUM(kind) ((kind) == symconst_enum_const) -/** Get the kind of the SymConst. */ +/** Returns the kind of the SymConst. */ FIRM_API symconst_kind get_SymConst_kind(const ir_node *node); -/** Set the kind of the SymConst. */ -FIRM_API void set_SymConst_kind(ir_node *node, symconst_kind num); +/** Sets the kind of the SymConst. */ +FIRM_API void set_SymConst_kind(ir_node *node, symconst_kind num); -/** Only to access SymConst of kind type_size. Else assertion: */ -FIRM_API ir_type *get_SymConst_type(const ir_node *node); -FIRM_API void set_SymConst_type(ir_node *node, ir_type *tp); +/** Returns the type attribute of SymConst node @p node. + * @note Only to access SymConst of kind type_siz, else assertion. + */ +FIRM_API ir_type *get_SymConst_type(const ir_node *node); +/** Sets the type attribute of SymConst node @p node. */ +FIRM_API void set_SymConst_type(ir_node *node, ir_type *tp); -/** Only to access SymConst of kind addr_ent. Else assertion: */ +/** Returns the entity attribute of SymConst node @p node. + * @note Only to access SymConst of kind addr_ent, else assertion. + */ FIRM_API ir_entity *get_SymConst_entity(const ir_node *node); -FIRM_API void set_SymConst_entity(ir_node *node, ir_entity *ent); +/** Sets the entity attribute of Symconst node @p node. */ +FIRM_API void set_SymConst_entity(ir_node *node, ir_entity *ent); -/** Only to access SymConst of kind symconst_enum_const. Else assertion: */ +/** Returns the enum attribute of SymConst node @p node. + * Only to access SymConst of kind symconst_enum_const, else assertion + */ FIRM_API ir_enum_const *get_SymConst_enum(const ir_node *node); -FIRM_API void set_SymConst_enum(ir_node *node, ir_enum_const *ec); +/** Sets the enum attribute of SymConst node @p node. */ +FIRM_API void set_SymConst_enum(ir_node *node, ir_enum_const *ec); +/** Returns the symbol attribute of SymConst node @p node. */ FIRM_API union symconst_symbol get_SymConst_symbol(const ir_node *node); -FIRM_API void set_SymConst_symbol(ir_node *node, - union symconst_symbol sym); +/** Sets the symbol attribute of SymConst node @p node. */ +FIRM_API void set_SymConst_symbol(ir_node *node, union symconst_symbol sym); /** @} */ @@ -435,10 +448,14 @@ FIRM_API void set_SymConst_symbol(ir_node *node, * @{ */ -FIRM_API ir_node **get_Sel_index_arr(ir_node *node); -FIRM_API int get_Sel_n_indexs(const ir_node *node); -FIRM_API ir_node *get_Sel_index(const ir_node *node, int pos); -FIRM_API void set_Sel_index(ir_node *node, int pos, ir_node *index); +/** Returns index inputs of Sel node @p node as array. */ +FIRM_API ir_node **get_Sel_index_arr(ir_node *node); +/** Returns number of index inputs of Sel node @p node. */ +FIRM_API int get_Sel_n_indexs(const ir_node *node); +/** Returns value of index input @p pos of Sel node @p node. */ +FIRM_API ir_node *get_Sel_index(const ir_node *node, int pos); +/** Sets @p index as index input @p pos of Sel node @p node. */ +FIRM_API void set_Sel_index(ir_node *node, int pos, ir_node *index); /** @} */ @@ -446,15 +463,16 @@ FIRM_API void set_Sel_index(ir_node *node, int pos, ir_node *index); * @{ */ +/** Returns parameter inputs of Call node @p node as array. */ FIRM_API ir_node **get_Call_param_arr(ir_node *node); -/** Gets the number of parameters of a call. */ -FIRM_API size_t get_Call_n_params(const ir_node *node); -/** Gets the call parameter at position pos. */ +/** Returns the number of parameters of a call. */ +FIRM_API size_t get_Call_n_params(const ir_node *node); +/** Returns the call parameter at position pos. */ FIRM_API ir_node *get_Call_param(const ir_node *node, int pos); /** Sets the call parameter at position pos. */ -FIRM_API void set_Call_param(ir_node *node, int pos, ir_node *param); +FIRM_API void set_Call_param(ir_node *node, int pos, ir_node *param); -/** Set, get and remove the callee information for a Call node. +/** Sets, get and remove the callee information for a Call node. * * The callee information lists all method entities that can be called * from this node. If the address expression can not be analyzed fully, @@ -471,14 +489,17 @@ FIRM_API void set_Call_param(ir_node *node, int pos, ir_node *param); * * @param node A Call node. */ -FIRM_API int Call_has_callees(const ir_node *node); -FIRM_API size_t get_Call_n_callees(const ir_node *node); +FIRM_API int Call_has_callees(const ir_node *node); +/** Returns the number of callees of Call node @p node. */ +FIRM_API size_t get_Call_n_callees(const ir_node *node); +/** Returns callee number @p pos of Call node @p node. */ FIRM_API ir_entity *get_Call_callee(const ir_node *node, size_t pos); -/** Set the full callee array. +/** Sets the full callee array. * * The passed array is copied. Assumes current_ir_graph set properly! */ FIRM_API void set_Call_callee_arr(ir_node *node, size_t n, ir_entity **arr); +/** Frees callee array of call node @p node */ FIRM_API void remove_Call_callee_arr(ir_node *node); /** @} */ @@ -487,50 +508,62 @@ FIRM_API void remove_Call_callee_arr(ir_node *node); * @{ */ -FIRM_API ir_node **get_Builtin_param_arr(ir_node *node); -/** Gets the number of parameters of a Builtin. */ -FIRM_API int get_Builtin_n_params(const ir_node *node); -/** Gets the Builtin parameter at position pos. */ -FIRM_API ir_node *get_Builtin_param(const ir_node *node, int pos); +/** Returns the parameter inputs of Builtin node @p node as array. */ +FIRM_API ir_node **get_Builtin_param_arr(ir_node *node); +/** Returns the number of parameters of a Builtin. */ +FIRM_API int get_Builtin_n_params(const ir_node *node); +/** Returns the Builtin parameter at position pos. */ +FIRM_API ir_node *get_Builtin_param(const ir_node *node, int pos); /** Sets the Builtin parameter at position pos. */ -FIRM_API void set_Builtin_param(ir_node *node, int pos, ir_node *param); +FIRM_API void set_Builtin_param(ir_node *node, int pos, ir_node *param); /** @} */ /** Returns a human readable string for the ir_builtin_kind. */ FIRM_API const char *get_builtin_kind_name(ir_builtin_kind kind); -FIRM_API int is_unop(const ir_node *node); +/** Tests whether node is an unary operation (opcode arity is #oparity_unary) + * @returns 1 if @p node is an unary operation, 0 otherwise + */ +FIRM_API int is_unop(const ir_node *node); +/** Returns (arithmetic) operand of unary operation @p node. */ FIRM_API ir_node *get_unop_op(const ir_node *node); -FIRM_API void set_unop_op(ir_node *node, ir_node *op); -FIRM_API int is_binop(const ir_node *node); +/** Sets (arithmetic) operand of unary operation @p node. */ +FIRM_API void set_unop_op(ir_node *node, ir_node *op); + +/** Tests whether node is a binary operation (opcode arity is #oparity_binary) + * @returns 1 if @p node is an binary operation, 0 otherwise + */ +FIRM_API int is_binop(const ir_node *node); +/** Returns left operand of binary operation @p node. */ FIRM_API ir_node *get_binop_left(const ir_node *node); -FIRM_API void set_binop_left(ir_node *node, ir_node *left); +/** Sets left operand of binary operation @p node. */ +FIRM_API void set_binop_left(ir_node *node, ir_node *left); +/** Returns rights operand of binary operation @p node. */ FIRM_API ir_node *get_binop_right(const ir_node *node); -FIRM_API void set_binop_right(ir_node *node, ir_node *right); +/** Sets right operand of binary operation @p node. */ +FIRM_API void set_binop_right(ir_node *node, ir_node *right); /** - * Test wether a node is the X_except Proj of a fragile operation + * Tests whether a node is the X_except Proj of a fragile operation */ -FIRM_API int is_x_except_Proj(const ir_node *node); +FIRM_API int is_x_except_Proj(const ir_node *node); /** - * Test wether a node is the X_regular Proj of a fragile operation + * Tests whether a node is the X_regular Proj of a fragile operation */ -FIRM_API int is_x_regular_Proj(const ir_node *node); +FIRM_API int is_x_regular_Proj(const ir_node *node); /** - * Set throws exception attribute of a fragile node + * Sets throws exception attribute of a fragile node * @p throws_exception must be 0 or 1 */ -FIRM_API void ir_set_throws_exception(ir_node *node, int throws_exception); +FIRM_API void ir_set_throws_exception(ir_node *node, int throws_exception); -/** - * Returns throws_exception attribute of a fragile node - */ -FIRM_API int ir_throws_exception(const ir_node *node); +/** Returns throws_exception attribute of a fragile node */ +FIRM_API int ir_throws_exception(const ir_node *node); -/** returns the name of an ir_relation */ +/** Returns the name of an ir_relation */ FIRM_API const char *get_relation_string(ir_relation relation); /** Calculates the negated (Complement(R)) relation, i.e. "<" --> ">=" */ @@ -569,39 +602,73 @@ FIRM_API int is_Cast_downcast(ir_node *node); * @{ */ -/** Returns true if irg in phase phase_building and the Phi has zero - predecessors. It's a Phi0 then. */ -FIRM_API int is_Phi0(const ir_node *n); +/** + * Returns 1 if irg in phase phase_building and the Phi has zero + * predecessors. It's a "Phi0" then. + */ +FIRM_API int is_Phi0(const ir_node *n); +/** + * Returns all phi predecessors as array + */ FIRM_API ir_node **get_Phi_preds_arr(ir_node *node); -FIRM_API int get_Phi_n_preds(const ir_node *node); -FIRM_API ir_node *get_Phi_pred(const ir_node *node, int pos); -FIRM_API void set_Phi_pred(ir_node *node, int pos, ir_node *pred); +/** + * Returns number of predecessors of phi node @p node + */ +FIRM_API int get_Phi_n_preds(const ir_node *node); +/** + * Returns the predecessor with number @p pos of phi node @p node. + * This is the value selected when control flow comes from predecessor @p pos + * of the containing basic block. + */ +FIRM_API ir_node *get_Phi_pred(const ir_node *node, int pos); +/** + * Sets value @p pred as predecessor number @p pos of phi node @p node. + */ +FIRM_API void set_Phi_pred(ir_node *node, int pos, ir_node *pred); /** * Returns the next element of a block phi list. */ -FIRM_API ir_node *get_Phi_next(const ir_node *phi); +FIRM_API ir_node *get_Phi_next(const ir_node *phi); /** * Sets the next link of a block Phi list. */ -FIRM_API void set_Phi_next(ir_node *phi, ir_node *next); +FIRM_API void set_Phi_next(ir_node *phi, ir_node *next); /** @} */ -/** Return true if @p node is a memory operation. +/** Returns true if @p node is a memory operation. * - * A memory operation is an operation that changes the - * memory. I.e., a Load or a Store operation. - * memops have a memory input and output + * A memory operation is a node with an opcode that has irop_flag_uses_memory + * set. It is guaranteed to have (exactly) one memory input. + */ +FIRM_API int is_memop(const ir_node *node); +/** + * Returns the memory input of a memory operation. */ -FIRM_API int is_memop(const ir_node *node); FIRM_API ir_node *get_memop_mem(const ir_node *node); -FIRM_API void set_memop_mem(ir_node *node, ir_node *mem); +/** + * Sets the memory input of a memory operation. + */ +FIRM_API void set_memop_mem(ir_node *node, ir_node *mem); + +/** @addtogroup Sync + * @{ + */ +/** Returns all predecessors of Sync node @p node as array */ FIRM_API ir_node **get_Sync_preds_arr(ir_node *node); -FIRM_API int get_Sync_n_preds(const ir_node *node); -FIRM_API ir_node *get_Sync_pred(const ir_node *node, int pos); -FIRM_API void set_Sync_pred(ir_node *node, int pos, ir_node *pred); -FIRM_API void add_Sync_pred(ir_node *node, ir_node *pred); +/** Returns number of predecessors of Sync node @p node. */ +FIRM_API int get_Sync_n_preds(const ir_node *node); +/** Returns predecessor number @p pos of Sync node @p node. */ +FIRM_API ir_node *get_Sync_pred(const ir_node *node, int pos); +/** Sets value @p pred as predecessor number @p pos of Sync node @p node. */ +FIRM_API void set_Sync_pred(ir_node *node, int pos, ir_node *pred); +/** Adds @p pred to predecessor list of Sync node @p node. */ +FIRM_API void add_Sync_pred(ir_node *node, ir_node *pred); +/** Removes predecessor i from Sync n */ +FIRM_API void del_Sync_n(ir_node *n, int i); + +/** @} */ /** * Returns non-zero if a node is a routine parameter. @@ -614,10 +681,14 @@ FIRM_API int is_arg_Proj(const ir_node *node); * @{ */ +/** Returns all predecessors of Tuple node @p node as array. */ FIRM_API ir_node **get_Tuple_preds_arr(ir_node *node); -FIRM_API int get_Tuple_n_preds(const ir_node *node); +/** Returns number of predecessors of Tuple node @p node. */ +FIRM_API int get_Tuple_n_preds(const ir_node *node); +/** Returns predecessor number @p pos of Tuple node @p node. */ FIRM_API ir_node *get_Tuple_pred(const ir_node *node, int pos); -FIRM_API void set_Tuple_pred(ir_node *node, int pos, ir_node *pred); +/** Sets value @p pred as predecessor number @p pos of Tuple node @p node. */ +FIRM_API void set_Tuple_pred(ir_node *node, int pos, ir_node *pred); /** @} */ @@ -625,11 +696,11 @@ FIRM_API void set_Tuple_pred(ir_node *node, int pos, ir_node *pred); * @{ */ -/** Return the number of input constraints for an ASM node. */ +/** Returns the number of input constraints for an ASM node. */ FIRM_API size_t get_ASM_n_input_constraints(const ir_node *node); -/** Return the number of output constraints for an ASM node. */ +/** Returns the number of output constraints for an ASM node. */ FIRM_API size_t get_ASM_n_output_constraints(const ir_node *node); -/** Return the number of clobbered registers for an ASM node. */ +/** Returns the number of clobbered registers for an ASM node. */ FIRM_API size_t get_ASM_n_clobbers(const ir_node *node); /** @} */ @@ -644,6 +715,7 @@ FIRM_API ir_node *skip_Id(ir_node *node); FIRM_API ir_node *skip_Tuple(ir_node *node); /** Returns operand of node if node is a Cast. */ FIRM_API ir_node *skip_Cast(ir_node *node); +/** Returns operand of node if node is a Cast. */ FIRM_API const ir_node *skip_Cast_const(const ir_node *node); /** Returns operand of node if node is a Pin. */ FIRM_API ir_node *skip_Pin(ir_node *node); @@ -653,7 +725,7 @@ FIRM_API ir_node *skip_Confirm(ir_node *node); FIRM_API ir_node *skip_HighLevel_ops(ir_node *node); /** Returns true if the operation manipulates control flow */ FIRM_API int is_cfop(const ir_node *node); -/** returns true if the operation jumps to an unknown destination. +/** Returns true if the operation jumps to an unknown destination. * See irop_flag_unknown_jump for a detailed explanation */ FIRM_API int is_unknown_jump(const ir_node *node); @@ -683,11 +755,11 @@ FIRM_API int is_irn_forking(const ir_node *node); */ FIRM_API void copy_node_attr(ir_graph *irg, const ir_node *old_node, ir_node *new_node); -/** Return the type attribute of a node n (SymConst, Call, Alloc, Free, +/** Returns the type attribute of a node n (SymConst, Call, Alloc, Free, * Cast) or NULL.*/ FIRM_API ir_type *get_irn_type_attr(ir_node *n); -/** Return the entity attribute of a node n (SymConst, Sel) or NULL. */ +/** Returns the entity attribute of a node n (SymConst, Sel) or NULL. */ FIRM_API ir_entity *get_irn_entity_attr(ir_node *n); /** Returns non-zero for constant-like nodes. */ @@ -709,7 +781,7 @@ FIRM_API int is_irn_start_block_placed(const ir_node *node); */ FIRM_API int is_irn_cse_neutral(const ir_node *node); -/** Gets the string representation of the jump prediction. */ +/** Returns the string representation of the jump prediction. */ FIRM_API const char *get_cond_jmp_predicate_name(cond_jmp_predicate pred); /** @@ -725,7 +797,7 @@ FIRM_API const char *get_cond_jmp_predicate_name(cond_jmp_predicate pred); (assert(off > 0 && "Invalid node data offset"), (type *) ((char *) (node) - (off))) /** - * Get the pointer to the node some custom data belongs to. + * Returns the pointer to the node some custom data belongs to. * @param data The pointer to the custom data. * @param off The number as returned by register_additional_node_data(). * @return A pointer to the ir node the custom data belongs to. @@ -743,15 +815,20 @@ FIRM_API const char *get_cond_jmp_predicate_name(cond_jmp_predicate pred); FIRM_API unsigned firm_register_additional_node_data(unsigned size); /** - * Return a pointer to the node attributes. - * Needed for user-defined nodes. + * Returns a pointer to the node attributes. + * Used for accessing attributes of user-defined nodes. */ FIRM_API void *get_irn_generic_attr(ir_node *node); +/** + * Returns a pointer to the node attributes. + * Used for accessing attributes of user-defined nodes. + */ FIRM_API const void *get_irn_generic_attr_const(const ir_node *node); /** * Returns the unique node index for the node in its graph. * This index is used to access phase information for this node. + * @see get_idx_irn() */ FIRM_API unsigned get_irn_idx(const ir_node *node); @@ -778,28 +855,53 @@ FIRM_API dbg_info *get_irn_dbg_info(const ir_node *n); FIRM_API unsigned firm_default_hash(const ir_node *node); /** - * returns a descriptive name of a node (containing type+number) + * Returns a descriptive name of a node (containing type+number) */ FIRM_API const char *gdb_node_helper(void *firm_object); +/** + * @addtogroup Switch + * @{ + */ + +/** + * Creates a new switch_table datastructure with @p n_entries entries. + * The datastructure is allocated on the obstack of @p irg. + */ FIRM_API ir_switch_table *ir_new_switch_table(ir_graph *irg, size_t n_entries); +/** + * Returns number of entries available in switch table @p table. + */ FIRM_API size_t ir_switch_table_get_n_entries(const ir_switch_table *table); +/** + * Sets entry number @p entry in the switch table @p table. + * @param table the switch table + * @param entry entry number to set + * @param min The minimum tarval that matches this entry + * @param max The maximum tarval that matches this entry + * @param pn Proj number taken on match + */ FIRM_API void ir_switch_table_set(ir_switch_table *table, size_t entry, ir_tarval *min, ir_tarval *max, long pn); +/** Returns maximum tarval value of switch table entry @p entry */ FIRM_API ir_tarval *ir_switch_table_get_max(const ir_switch_table *table, size_t entry); +/** Returns minimum tarval value of switch table entry @p entry */ FIRM_API ir_tarval *ir_switch_table_get_min(const ir_switch_table *table, size_t entry); +/** Returns proj number taken if switch table entry @p entry matches */ FIRM_API long ir_switch_table_get_pn(const ir_switch_table *table, size_t entry); +/** Duplicates switch table @p table on obstack of @p irg */ FIRM_API ir_switch_table *ir_switch_table_duplicate(ir_graph *irg, const ir_switch_table *table); +/** @} */ -/*@}*/ +/** @} */ #include "end.h" diff --git a/include/libfirm/irop.h b/include/libfirm/irop.h index 249fcbf60..0b0630432 100644 --- a/include/libfirm/irop.h +++ b/include/libfirm/irop.h @@ -98,7 +98,7 @@ FIRM_API unsigned get_op_code(const ir_op *op); /** Returns a human readable name of an op_pin_state. */ FIRM_API const char *get_op_pin_state_name(op_pin_state s); -/** Gets pinned state of an opcode. */ +/** Returns pinned state of an opcode. */ FIRM_API op_pin_state get_op_pinned(const ir_op *op); /** Sets pinned in the opcode. Setting it to floating has no effect @@ -125,12 +125,12 @@ typedef void (*op_func)(void); FIRM_API op_func get_generic_function_ptr(const ir_op *op); /** - * Store a generic function pointer into an IR operation. + * Stores a generic function pointer into an IR operation. */ FIRM_API void set_generic_function_ptr(ir_op *op, op_func func); /** - * Return the irop flags of an IR opcode. + * Returns the irop flags of an IR opcode. */ FIRM_API irop_flags get_op_flags(const ir_op *op); @@ -192,20 +192,20 @@ typedef void (*copy_attr_func)(ir_graph *irg, const ir_node *old_node, ir_node * /** * The get_type_attr operation. Used to traverse all types that can be * accessed from an ir_graph. - * Return the type attribute of the node self. + * Returns the type attribute of the node self. */ typedef ir_type *(*get_type_attr_func)(const ir_node *self); /** * The get_entity_attr operation. Used to traverse all entities that can be * accessed from an ir_graph. - * Return the entity attribute of the node self. + * Returns the entity attribute of the node self. */ typedef ir_entity *(*get_entity_attr_func)(const ir_node *self); /** * The verify_node operation. - * Return non-zero if the node verification is ok, else 0. + * Returns non-zero if the node verification is ok, else 0. * Depending on the node verification settings, may even assert. * * @see do_node_verification() @@ -214,7 +214,7 @@ typedef int (*verify_node_func)(const ir_node *node); /** * The verify_node operation for Proj(X). - * Return non-zero if the node verification is ok, else 0. + * Returns non-zero if the node verification is ok, else 0. * Depending on the node verification settings, may even assert. * * @see do_node_verification() @@ -252,8 +252,8 @@ typedef struct { node_cmp_attr_func node_cmp_attr; /**< Compares two node attributes. */ reassociate_func reassociate; /**< Reassociate a tree. */ copy_attr_func copy_attr; /**< Copy node attributes. */ - get_type_attr_func get_type_attr; /**< Return the type attribute of a node. */ - get_entity_attr_func get_entity_attr; /**< Return the entity attribute of a node. */ + get_type_attr_func get_type_attr; /**< Returns the type attribute of a node. */ + get_entity_attr_func get_entity_attr; /**< Returns the entity attribute of a node. */ verify_node_func verify_node; /**< Verify the node. */ verify_proj_node_func verify_proj_node; /**< Verify the Proj node. */ dump_node_func dump_node; /**< Dump a node. */ @@ -284,12 +284,12 @@ FIRM_API ir_op *new_ir_op(unsigned code, const char *name, op_pin_state p, size_t attr_size, const ir_op_ops *ops); /** - * set memory input of operation using memory + * Sets memory input of operation using memory */ FIRM_API void ir_op_set_memory_index(ir_op *op, int memory_index); /** - * Set proj-number for X_regular and X_except projs of fragile nodes. + * Sets proj-number for X_regular and X_except projs of fragile nodes. * Note: should only be used immediately after new_ir_op */ FIRM_API void ir_op_set_fragile_indices(ir_op *op, int pn_x_regular, diff --git a/include/libfirm/iroptimize.h b/include/libfirm/iroptimize.h index 9a5795859..793f8a42e 100644 --- a/include/libfirm/iroptimize.h +++ b/include/libfirm/iroptimize.h @@ -72,7 +72,7 @@ FIRM_API void opt_jumpthreading(ir_graph* irg); FIRM_API ir_graph_pass_t *opt_jumpthreading_pass(const char *name); /** - * Try to simplify boolean expression in the given ir graph. + * Simplifies boolean expression in the given ir graph. * eg. x < 5 && x < 6 becomes x < 5 * * @param irg the graph @@ -89,7 +89,7 @@ FIRM_API void opt_bool(ir_graph *irg); FIRM_API ir_graph_pass_t *opt_bool_pass(const char *name); /** - * Try to reduce the number of conv nodes in the given ir graph. + * Reduces the number of Conv nodes in the given ir graph. * * @param irg the graph * @@ -113,7 +113,7 @@ FIRM_API ir_graph_pass_t *conv_opt_pass(const char *name); typedef int (*check_alloc_entity_func)(ir_entity *ent); /** - * Do simple and fast escape analysis for one graph. + * Performs simple and fast escape analysis for one graph. * * @param irg the graph * @param callback a callback function to check whether a @@ -123,7 +123,7 @@ FIRM_API void escape_enalysis_irg(ir_graph *irg, check_alloc_entity_func callback); /** - * Do simple and fast escape analysis for all graphs. + * Performs simple and fast escape analysis for all graphs. * * This optimization implements a simple and fast but inexact * escape analysis. Some addresses might be marked as 'escaped' even @@ -248,7 +248,7 @@ FIRM_API void opt_parallelize_mem(ir_graph *irg); */ FIRM_API ir_graph_pass_t *opt_parallelize_mem_pass(const char *name); -/* +/** * Check if we can replace the load by a given const from * the const code irg. * @@ -357,13 +357,11 @@ typedef enum osr_flags { induction variables. */ } osr_flags; -/* FirmJNI cannot handle identical enum values... */ - /** default setting */ #define osr_flag_default osr_flag_lftr_with_ov_check /** - * Do the Operator Scalar Replacement optimization and linear + * Performs the Operator Scalar Replacement optimization and linear * function test replacement for loop control. * Can be switched off using the set_opt_strength_red() flag. * In that case, only remove_phi_cycles() is executed. @@ -458,7 +456,7 @@ FIRM_API ir_graph_pass_t *remove_phi_cycles_pass(const char *name); #define DEFAULT_CLONE_THRESHOLD 20 /** - * Do procedure cloning. Evaluate a heuristic weight for every + * Performs procedure cloning. Evaluate a heuristic weight for every * Call(..., Const, ...). If the weight is bigger than threshold, * clone the entity and fix the calls. * @@ -570,8 +568,8 @@ FIRM_API void normalize_n_returns(ir_graph *irg); FIRM_API ir_graph_pass_t *normalize_n_returns_pass(const char *name); /** - * Do the scalar replacement optimization. - * Replace local compound entities (like structures and arrays) + * Performs the scalar replacement optimization. + * Replaces local compound entities (like structures and arrays) * with atomic values if possible. Does not handle classes yet. * * @param irg the graph which should be optimized @@ -797,6 +795,7 @@ FIRM_API ir_prog_pass_t *inline_leave_functions_pass(const char *name, unsigned maxsize, unsigned leavesize, unsigned size, int ignore_runtime); +/** pointer to an optimization function */ typedef void (*opt_ptr)(ir_graph *irg); /** @@ -1011,7 +1010,7 @@ FIRM_API void place_code(ir_graph *irg); FIRM_API ir_graph_pass_t *place_code_pass(const char *name); /** - * Determine information about the values of nodes and perform simplifications + * Determines information about the values of nodes and perform simplifications * using this information. This optimization performs a data-flow analysis to * find the minimal fixpoint. */ @@ -1031,7 +1030,7 @@ FIRM_API void fixpoint_vrp(ir_graph*); FIRM_API ir_graph_pass_t *fixpoint_vrp_irg_pass(const char *name); /** - * Check, if the value of a node is != 0. + * Checks if the value of a node is != 0. * * This is a often needed case, so we handle here Confirm * nodes too. @@ -1043,7 +1042,7 @@ FIRM_API ir_graph_pass_t *fixpoint_vrp_irg_pass(const char *name); FIRM_API int value_not_zero(const ir_node *n, const ir_node **confirm); /** - * Check, if the value of a node cannot represent a NULL pointer. + * Checks if the value of a node cannot represent a NULL pointer. * * - If option sel_based_null_check_elim is enabled, all * Sel nodes can be skipped. @@ -1058,7 +1057,7 @@ FIRM_API int value_not_zero(const ir_node *n, const ir_node **confirm); FIRM_API int value_not_null(const ir_node *n, const ir_node **confirm); /** - * Check, if the value of a node can be confirmed >= 0 or <= 0, + * Checks if the value of a node can be confirmed >= 0 or <= 0, * If the mode of the value did not honor signed zeros, else * check for >= 0 or < 0. * @@ -1067,8 +1066,7 @@ FIRM_API int value_not_null(const ir_node *n, const ir_node **confirm); FIRM_API ir_value_classify_sign classify_value_sign(ir_node *n); /** - * Return the value of a Cmp if one or both predecessors - * are Confirm nodes. + * Returns the value of a Cmp if one or both predecessors are Confirm nodes. * * @param cmp the compare node that will be evaluated * @param left the left operand of the Cmp @@ -1078,22 +1076,22 @@ FIRM_API ir_value_classify_sign classify_value_sign(ir_node *n); FIRM_API ir_tarval *computed_value_Cmp_Confirm( const ir_node *cmp, ir_node *left, ir_node *right, ir_relation relation); +/** Type of callbacks for createing entities of the compiler library */ typedef ir_entity *(*compilerlib_entity_creator_t)(ident *id, ir_type *mt); + /** - * Set the compilerlib entity creation callback that is used to create + * Sets the compilerlib entity creation callback that is used to create * compilerlib function entities. * * @param cb the new compilerlib entity creation callback */ FIRM_API void set_compilerlib_entity_creator(compilerlib_entity_creator_t cb); -/** - * Get the compilerlib entity creation callback. - */ +/** Returns the compilerlib entity creation callback. */ FIRM_API compilerlib_entity_creator_t get_compilerlib_entity_creator(void); /** - * Construct the entity for a given function using the current compilerlib + * Constructs the entity for a given function using the current compilerlib * entity creation callback. * * @param id the identifier of the compilerlib function diff --git a/include/libfirm/irouts.h b/include/libfirm/irouts.h index 7082292d3..a4c2e4447 100644 --- a/include/libfirm/irouts.h +++ b/include/libfirm/irouts.h @@ -37,20 +37,20 @@ * @{ */ -/** returns the number of successors of the node: */ +/** Returns the number of successors of the node: */ FIRM_API int get_irn_n_outs(const ir_node *node); -/** Get the User of a node from the Def-Use edge at position pos. */ +/** Returns the User of a node from the Def-Use edge at position pos. */ FIRM_API ir_node *get_irn_out(const ir_node *def, int pos); /** - * Get the User and its input position from the Def-Use edge of def + * Returns the User and its input position from the Def-Use edge of def * at position pos. */ FIRM_API ir_node *get_irn_out_ex(const ir_node *def, int pos, int *in_pos); /** - * Set the User at position pos. + * Sets the User at position pos. * * @param def the Def node * @param pos the number of the Def-Use edge tat is modified @@ -59,10 +59,10 @@ FIRM_API ir_node *get_irn_out_ex(const ir_node *def, int pos, int *in_pos); */ FIRM_API void set_irn_out(ir_node *def, int pos, ir_node *use, int in_pos); -/** Return the number of control flow successors, ignore keep-alives. */ +/** Returns the number of control flow successors, ignore keep-alives. */ FIRM_API int get_Block_n_cfg_outs(const ir_node *node); -/** Return the number of control flow successors, honor keep-alives. */ +/** Returns the number of control flow successors, honor keep-alives. */ FIRM_API int get_Block_n_cfg_outs_ka(const ir_node *node); /** Access predecessor n, ignore keep-alives. */ @@ -87,7 +87,7 @@ FIRM_API void irg_out_block_walk(ir_node *node, irg_walk_func *pre, irg_walk_func *post, void *env); /** - * returns 1 if outs have been computed for a node, 0 otherwise. + * Returns 1 if outs have been computed for a node, 0 otherwise. * * this is useful to detect newly created nodes that have no outs set yet */ @@ -100,11 +100,15 @@ FIRM_API int get_irn_outs_computed(const ir_node *node); * "op_pin_state_floats". Optimizes Tuple nodes. */ FIRM_API void compute_irg_outs(ir_graph *irg); +/** Recomputes out edges for each graph where it is necessary */ FIRM_API void compute_irp_outs(void); +/** Recomputes out edges if necessary */ FIRM_API void assure_irg_outs(ir_graph *irg); +/** Frees memory occupied by out edges datastructures */ FIRM_API void free_irg_outs(ir_graph *irg); +/** Frees memory occupied by out edges datastructures in the whole program */ FIRM_API void free_irp_outs(void); /** @} */ diff --git a/include/libfirm/irpass.h b/include/libfirm/irpass.h index ce9cfe302..88a08ffd9 100644 --- a/include/libfirm/irpass.h +++ b/include/libfirm/irpass.h @@ -42,7 +42,7 @@ FIRM_API ir_graph_pass_manager_t *new_graph_pass_mgr(const char *name, int dump_all); /** - * Add an ir_graph pass to a graph pass manager. + * Adds an ir_graph pass to a graph pass manager. * * @param mgr the ir_graph pass manager * @param pass the pass to add @@ -51,7 +51,7 @@ FIRM_API void ir_graph_pass_mgr_add(ir_graph_pass_manager_t *mgr, ir_graph_pass_t *pass); /** - * Run all passes of an ir_graph pass manager. + * Runs all passes of an ir_graph pass manager. * * @param mgr the manager * @@ -60,7 +60,7 @@ FIRM_API void ir_graph_pass_mgr_add(ir_graph_pass_manager_t *mgr, FIRM_API int ir_graph_pass_mgr_run(ir_graph_pass_manager_t *mgr); /** - * Terminate an ir_graph pass manager and all owned passes. + * Terminates an ir_graph pass manager and all owned passes. * * @param mgr the manager */ @@ -80,7 +80,7 @@ FIRM_API ir_prog_pass_manager_t *new_prog_pass_mgr(const char *name, int dump_all); /** - * Add an ir_prog pass to an ir_prog pass manager. + * Adds an ir_prog pass to an ir_prog pass manager. * * @param mgr the ir_prog pass manager * @param pass the pass to add @@ -89,7 +89,7 @@ FIRM_API void ir_prog_pass_mgr_add(ir_prog_pass_manager_t *mgr, ir_prog_pass_t *pass); /** - * Add an ir_graph_pass_manager as a pass to an ir_prog pass manager. + * Adds an ir_graph_pass_manager as a pass to an ir_prog pass manager. * * @param mgr the ir_prog pass manager * @param graph_mgr the ir_graph pass manager to be added @@ -98,7 +98,7 @@ FIRM_API void ir_prog_pass_mgr_add_graph_mgr(ir_prog_pass_manager_t *mgr, ir_graph_pass_manager_t *graph_mgr); /** - * Add an ir_graph_pass as a pass to an ir_prog pass manager. + * Adds an ir_graph_pass as a pass to an ir_prog pass manager. * * @param mgr the ir_prog pass manager * @param pass the ir_graph pass to be added @@ -107,7 +107,7 @@ FIRM_API void ir_prog_pass_mgr_add_graph_pass(ir_prog_pass_manager_t *mgr, ir_graph_pass_t *pass); /** - * Run all passes of an ir_prog pass manager. + * Runs all passes of an ir_prog pass manager. * * @param mgr the manager * @@ -116,14 +116,14 @@ FIRM_API void ir_prog_pass_mgr_add_graph_pass(ir_prog_pass_manager_t *mgr, FIRM_API int ir_prog_pass_mgr_run(ir_prog_pass_manager_t *mgr); /** - * Terminate an ir_prog pass manager and all owned passes. + * Terminates an ir_prog pass manager and all owned passes. * * @param mgr the manager */ FIRM_API void term_prog_pass_mgr(ir_prog_pass_manager_t *mgr); /** - * Set the run index for an irgraph pass manager. + * Sets the run index for an irgraph pass manager. * * @param mgr the manager * @param run_idx the index for the first pass of this manager @@ -173,7 +173,7 @@ FIRM_API ir_graph_pass_t *def_graph_pass_constructor( const char *name, int (*function)(ir_graph *irg, void *context)); /** - * Set the run_parallel property of a graph pass. + * Sets the run_parallel property of a graph pass. * If the flag is set to non-zero, the pass can be executed * parallel on all graphs of a ir_prog. * @@ -211,7 +211,7 @@ FIRM_API ir_prog_pass_t *def_prog_pass_constructor( const char *name, int (*function)(ir_prog *irp, void *context)); /** - * Create a pass that calls some function. + * Creates a pass that calls some function. * This pass calls the given function, but has no dump nor verify. * * @param name the name of this pass @@ -224,7 +224,7 @@ FIRM_API ir_prog_pass_t *call_function_pass( const char *name, void (*function)(void *context), void *context); /** - * Set the run index for an irprog pass manager. + * Sets the run index for an irprog pass manager. * * @param mgr the manager * @param run_idx the index for the first pass of this manager diff --git a/include/libfirm/irprog.h b/include/libfirm/irprog.h index fcbb708b4..144465bc3 100644 --- a/include/libfirm/irprog.h +++ b/include/libfirm/irprog.h @@ -51,6 +51,12 @@ * @{ */ +/** + * Segment + * + * A progrom has a number of special segments at the toplevel which modify + * the behaviour of the entities in them. + */ typedef enum ir_segment_t { IR_SEGMENT_FIRST, /** "normal" global data */ @@ -79,18 +85,35 @@ ENUM_COUNTABLE(ir_segment_t) */ FIRM_API ir_prog *irp; +/** + * Resources usable by algorithms modifying the program + */ typedef enum irp_resources_t { - IRP_RESOURCE_NONE = 0, + IRP_RESOURCE_NONE = 0, /**< no resource */ + /** irg link field @see set_irg_link(), get_irg_link() */ IRP_RESOURCE_IRG_LINK = 1 << 0, + /** entity link field @see set_entity_link(), get_entity_link() */ IRP_RESOURCE_ENTITY_LINK = 1 << 1, + /** type visited field @see type_visited(), mark_type_visited(), + * inc_master_type_visited() */ IRP_RESOURCE_TYPE_VISITED = 1 << 2, + /** type link field @see set_type_link(), get_type_link() */ IRP_RESOURCE_TYPE_LINK = 1 << 3, } irp_resources_t; ENUM_BITSET(irp_resources_t) #ifndef NDEBUG +/** + * Reserve resources available for a whole program. + * + * This is a debug tool: All code should properly allocate the resources it uses + * so if two interlocked algorithms use the same resources that bug will get + * detected. + */ FIRM_API void irp_reserve_resources(ir_prog *irp, irp_resources_t resources); +/** Frees resources availabel for a whole program. */ FIRM_API void irp_free_resources(ir_prog *irp, irp_resources_t resources); +/** Returns currently reserved whole program resources. */ FIRM_API irp_resources_t irp_resources_reserved(const ir_prog *irp); #else #define irp_reserve_resources(irp, resources) (void)0 @@ -106,9 +129,7 @@ FIRM_API irp_resources_t irp_resources_reserved(const ir_prog *irp); */ FIRM_API ir_prog *get_irp(void); -/** - * Set current irp - */ +/** Sets current irp */ FIRM_API void set_irp(ir_prog *irp); /** @@ -119,7 +140,7 @@ FIRM_API void set_irp(ir_prog *irp); */ FIRM_API ir_prog *new_ir_prog(const char *name); -/** frees all memory used by irp. Types in type list and irgs in irg +/** Frees all memory used by irp. Types in type list and irgs in irg * list must be freed by hand before. */ FIRM_API void free_ir_prog(void); @@ -130,13 +151,13 @@ FIRM_API void set_irp_prog_name(ident *name); /** Returns true if the user ever set a program name */ FIRM_API int irp_prog_name_is_set(void); -/** Gets the name of the current irp. */ +/** Returns the name of the current irp. */ FIRM_API ident *get_irp_ident(void); -/** Gets the name of the current irp. */ +/** Returns the name of the current irp. */ FIRM_API const char *get_irp_name(void); -/** Gets the main routine of the compiled program. */ +/** Returns the main routine of the compiled program. */ FIRM_API ir_graph *get_irp_main_irg(void); /** Sets the main routine of the compiled program. */ @@ -231,8 +252,7 @@ FIRM_API ir_op *get_irp_opcode(size_t pos); /** Sets the generic function pointer of all opcodes to NULL */ FIRM_API void clear_irp_opcodes_generic_func(void); - -/** Return the graph for global constants of the current irp. +/** Returns the graph for global constants of the current irp. * * Returns an irgraph that only contains constant expressions for * constant entities. Do not use any access function for this @@ -245,7 +265,6 @@ FIRM_API void clear_irp_opcodes_generic_func(void); */ FIRM_API ir_graph *get_const_code_irg(void); - /** The phase state for the program. * * The phase state of the whole program is @@ -255,7 +274,8 @@ FIRM_API ir_graph *get_const_code_irg(void); * low: all graphs are in state low, all types are in state layout fixed. */ FIRM_API irg_phase_state get_irp_phase_state(void); -FIRM_API void set_irp_phase_state(irg_phase_state s); +/** Sets the phase state of the program */ +FIRM_API void set_irp_phase_state(irg_phase_state s); /** * Creates an ir_prog pass for set_irp_phase_state(). @@ -268,8 +288,12 @@ FIRM_API void set_irp_phase_state(irg_phase_state s); FIRM_API ir_prog_pass_t *set_irp_phase_state_pass(const char *name, irg_phase_state state); +/** Returns callee info state for the whole program. + * @see get_irg_callee_info_state() */ FIRM_API irg_callee_info_state get_irp_callee_info_state(void); -FIRM_API void set_irp_callee_info_state(irg_callee_info_state s); +/** Sets callee info state for the whole program. + * @see set_irg_callee_info_state() */ +FIRM_API void set_irp_callee_info_state(irg_callee_info_state s); /** Returns a new, unique label number. */ FIRM_API ir_label_t get_irp_next_label_nr(void); @@ -277,13 +301,13 @@ FIRM_API ir_label_t get_irp_next_label_nr(void); /** Add a new global asm include. */ FIRM_API void add_irp_asm(ident *asm_string); -/** Return the number of global asm includes. */ +/** Returns the number of global asm includes. */ FIRM_API size_t get_irp_n_asms(void); -/** Return the global asm include at position pos. */ +/** Returns the global asm include at position pos. */ FIRM_API ident *get_irp_asm(size_t pos); -/** Return whether optimization dump vcg graphs */ +/** Returns whether optimization dump vcg graphs */ FIRM_API int get_irp_optimization_dumps(void); /** Enable vcg dumping of optimization */ diff --git a/include/libfirm/irtypeinfo.h b/include/libfirm/irtypeinfo.h index 6fc7f2070..9c559dcd2 100644 --- a/include/libfirm/irtypeinfo.h +++ b/include/libfirm/irtypeinfo.h @@ -57,10 +57,12 @@ FIRM_API ir_type *initial_type; * in the order of MIN(\, \#irnodes). */ FIRM_API void init_irtypeinfo(void); +/** Frees memory used by the type information module */ FIRM_API void free_irtypeinfo(void); /* ------------ Irgraph state handling. ------------------------------- */ +/** typeinfo information state */ typedef enum { ir_typeinfo_none, /**< No typeinfo computed, calls to set/get_irn_typeinfo_type() are invalid. */ @@ -70,7 +72,9 @@ typedef enum { because of other transformations. */ } ir_typeinfo_state; -FIRM_API void set_irg_typeinfo_state(ir_graph *irg, ir_typeinfo_state s); +/** Sets state of typeinfo information in graph @p irg to @p state. */ +FIRM_API void set_irg_typeinfo_state(ir_graph *irg, ir_typeinfo_state state); +/** Returns state of typeinfo information in graph @p irg. */ FIRM_API ir_typeinfo_state get_irg_typeinfo_state(const ir_graph *irg); /** Returns accumulated type information state information. @@ -80,9 +84,10 @@ FIRM_API ir_typeinfo_state get_irg_typeinfo_state(const ir_graph *irg); * or no type information. Returns ir_typeinfo_none if no irg contains type information. */ FIRM_API ir_typeinfo_state get_irp_typeinfo_state(void); -FIRM_API void set_irp_typeinfo_state(ir_typeinfo_state s); -/** If typeinfo is consistent, sets it to inconsistent. */ -FIRM_API void set_irp_typeinfo_inconsistent(void); +/** Sets state of typeinfo information for the current program to @p state */ +FIRM_API void set_irp_typeinfo_state(ir_typeinfo_state state); +/** Sets state of typeinfo information for the current program to #ir_typeinfo_inconsistent */ +FIRM_API void set_irp_typeinfo_inconsistent(void); /* ------------ Irnode type information. ------------------------------ */ @@ -93,7 +98,8 @@ FIRM_API void set_irp_typeinfo_inconsistent(void); * assume current_ir_graph set properly. */ FIRM_API ir_type *get_irn_typeinfo_type(const ir_node *n); -FIRM_API void set_irn_typeinfo_type(ir_node *n, ir_type *tp); +/** Sets type information of procedure graph node @p node to type @p type. */ +FIRM_API void set_irn_typeinfo_type(ir_node *node, ir_type *type); #include "end.h" diff --git a/include/libfirm/lowering.h b/include/libfirm/lowering.h index 12ff0565f..f9e2f2ddb 100644 --- a/include/libfirm/lowering.h +++ b/include/libfirm/lowering.h @@ -79,7 +79,7 @@ FIRM_API void lower_switch(ir_graph *irg, unsigned small_switch, /** * Replaces SymConsts by a real constant if possible. - * Replace Sel nodes by address computation. Also resolves array access. + * Replaces Sel nodes by address computation. Also resolves array access. * Handle bit fields by added And/Or calculations. * * @param irg the graph to lower @@ -100,7 +100,7 @@ FIRM_API ir_graph_pass_t *lower_highlevel_graph_pass(const char *name); /** * Replaces SymConsts by a real constant if possible. - * Replace Sel nodes by address computation. Also resolves array access. + * Replaces Sel nodes by address computation. Also resolves array access. * Handle bit fields by added And/Or calculations. * Lowers all graphs. * @@ -165,6 +165,8 @@ FIRM_API ir_graph_pass_t *lower_mux_pass(const char *name, */ typedef int (*i_mapper_func)(ir_node *node, void *ctx); +/** kind of an instruction record + * @see #i_record */ enum ikind { INTRINSIC_CALL = 0, /**< the record represents an intrinsic call */ INTRINSIC_INSTR /**< the record represents an intrinsic instruction */ @@ -196,8 +198,9 @@ typedef struct i_instr_record { * An intrinsic record. */ typedef union i_record { - i_call_record i_call; - i_instr_record i_instr; + enum ikind kind; /**< kind of record */ + i_call_record i_call; /**< used for call records */ + i_instr_record i_instr; /**< used for isnstruction records */ } i_record; /** @@ -215,7 +218,7 @@ typedef union i_record { * @return number of found intrinsics. */ FIRM_API size_t lower_intrinsics(i_record *list, size_t length, - int part_block_used); + int part_block_used); /** * Creates an irprog pass for lower_intrinsics. diff --git a/include/libfirm/timing.h b/include/libfirm/timing.h index 8f1166828..282e4ece1 100644 --- a/include/libfirm/timing.h +++ b/include/libfirm/timing.h @@ -28,6 +28,12 @@ #include "begin.h" +/** + * A timer + * + * A timer can be started/stopped multiple times and measures the (wallclock) + * time spent between start and stop calls. + */ typedef struct ir_timer_t ir_timer_t; /** @@ -47,7 +53,7 @@ FIRM_API int ir_timer_enter_high_priority(void); FIRM_API int ir_timer_leave_high_priority(void); /** - * Get the amount of bytes allocated on the heap. + * Returns the amount of bytes allocated on the heap. * @return The number of bytes allocated on the heap. */ FIRM_API size_t ir_get_heap_used_bytes(void); @@ -55,6 +61,7 @@ FIRM_API size_t ir_get_heap_used_bytes(void); /** * Create a new timer * @return The timer. + * @see #ir_timer_t */ FIRM_API ir_timer_t *ir_timer_new(void); @@ -106,14 +113,14 @@ FIRM_API int ir_timer_push(ir_timer_t *timer); FIRM_API ir_timer_t *ir_timer_pop(void); /** - * Get the number of milliseconds, the timer has elapsed. + * Returns the number of milliseconds, the timer has elapsed. * @param timer The timer. * @return The number of milliseconds the timer is (was) running. */ FIRM_API unsigned long ir_timer_elapsed_msec(const ir_timer_t *timer); /** - * Get the number of microseconds, the timer has elapsed. + * Returns the number of microseconds, the timer has elapsed. * @param timer The timer. * @return The number of milliseconds the timer is (was) running. */ diff --git a/include/libfirm/trouts.h b/include/libfirm/trouts.h index 2d2fcc2f9..2366ae8a7 100644 --- a/include/libfirm/trouts.h +++ b/include/libfirm/trouts.h @@ -42,39 +42,43 @@ * @{ */ -/** Number of Load/Store nodes that possibly access this entity. */ -FIRM_API size_t get_entity_n_accesses(const ir_entity *ent); -/** Load/Store node that possibly access this entity. */ -FIRM_API ir_node *get_entity_access(const ir_entity *ent, size_t pos); +/** Returns number of Load/Store nodes that possibly access entity @p entity. */ +FIRM_API size_t get_entity_n_accesses(const ir_entity *entity); +/** Returns Load/Store node number @p pos that possibly accesses entity @p entity. */ +FIRM_API ir_node *get_entity_access(const ir_entity *entity, size_t pos); -/** Number of references to an entity, in form of SymConst/Sel. - * Including references from constant entities and the like. */ -FIRM_API size_t get_entity_n_references(const ir_entity *ent); -/** References to an entity, in form of SymConst/Sel - * Including references from constants. */ -FIRM_API ir_node *get_entity_reference(const ir_entity *ent, size_t pos); +/** Returns number of references to entity @p entity, in form of SymConst/Sel, + * including references from constant entities and the like. */ +FIRM_API size_t get_entity_n_references(const ir_entity *entity); +/** Returns reference number @p pos of references to an entity, in form of + * SymConst/Sel, including references from constants. */ +FIRM_API ir_node *get_entity_reference(const ir_entity *entity, size_t pos); -/** Number of Alloc nodes that create an instance of this type. */ -FIRM_API size_t get_type_n_allocs(const ir_type *tp); -/** Alloc node that create an instance of this type. */ -FIRM_API ir_node *get_type_alloc(const ir_type *tp, size_t pos); +/** Returns number of Alloc nodes that create an instance of type @p type. */ +FIRM_API size_t get_type_n_allocs(const ir_type *type); +/** Returns Alloc node number @p pos that create an instance of type @p type. */ +FIRM_API ir_node *get_type_alloc(const ir_type *type, size_t pos); -/** Number of Cast nodes that cast a pointer to this type. */ -FIRM_API size_t get_type_n_casts(const ir_type *tp); +/** Returns number of Cast nodes that cast a pointer to type @p type. */ +FIRM_API size_t get_type_n_casts(const ir_type *type); /** Cast node that cast a pointer to this type. */ -FIRM_API ir_node *get_type_cast(const ir_type *tp, size_t pos); +FIRM_API ir_node *get_type_cast(const ir_type *type, size_t pos); /** Returns number of upcasts. O(\#casts). */ FIRM_API size_t get_class_n_upcasts(const ir_type *clss); -/** Return number of downcasts. O(\#casts). */ +/** Returns number of downcasts. O(\#casts). */ FIRM_API size_t get_class_n_downcasts(const ir_type *clss); -FIRM_API size_t get_type_n_pointertypes_to(const ir_type *tp); -FIRM_API ir_type *get_type_pointertype_to(const ir_type *tp, size_t pos); +/** Returns number of pointertypes that point to type @p type. */ +FIRM_API size_t get_type_n_pointertypes_to(const ir_type *type); +/** Returns pointer type number @p pos that points to type @p type. */ +FIRM_API ir_type *get_type_pointertype_to(const ir_type *type, size_t pos); -FIRM_API size_t get_type_n_arraytypes_of(const ir_type *tp); -FIRM_API ir_type *get_type_arraytype_of(const ir_type *tp, size_t pos); +/** Returns number of array types with element type @p type. */ +FIRM_API size_t get_type_n_arraytypes_of(const ir_type *type); +/** Returns array type number @p pos with element type @p type. */ +FIRM_API ir_type *get_type_arraytype_of(const ir_type *type, size_t pos); -/** Compute the outs of types and entities. +/** Computes the outs of types and entities. * * Collects all reference from irnodes to types or entities in the * corresponding types/entities. Further reverses references between @@ -98,7 +102,7 @@ FIRM_API ir_type *get_type_arraytype_of(const ir_type *tp, size_t pos); */ FIRM_API void compute_trouts(void); -/** Free trout data. */ +/** Frees trout data. */ FIRM_API void free_trouts(void); /** @} */ diff --git a/include/libfirm/tv.h b/include/libfirm/tv.h index 9ddebdd49..b616153ce 100644 --- a/include/libfirm/tv.h +++ b/include/libfirm/tv.h @@ -116,7 +116,7 @@ FIRM_API ir_tarval *new_tarval_from_str(const char *str, size_t len, * A tarval with the given mode. If overflow settings are set to * TV_OVERFLOW_BAD then a tarval_bad is returned if the number can't be * represented in the given mode. - * Return bad if the number couldn't successfully be parsed. + * Returns bad if the number couldn't successfully be parsed. */ FIRM_API ir_tarval *new_integer_tarval_from_str(const char *str, size_t len, char sign, unsigned char base, @@ -151,7 +151,7 @@ FIRM_API ir_tarval *new_integer_tarval_from_str(const char *str, size_t len, */ FIRM_API ir_tarval *new_tarval_from_long(long l, ir_mode *mode); -/** Return value as long if possible. +/** Returns value as long if possible. * * This returns a long int with the value represented value, or * gibberish, depending on the size of long int and the size of the @@ -272,7 +272,7 @@ FIRM_API int tarval_is_minus_one(ir_tarval *tv); FIRM_API int tarval_is_all_one(ir_tarval *tv); /** - * Return non-zero if the tarval is a constant (ie. NOT + * Returns non-zero if the tarval is a constant (ie. NOT * a reserved tarval like bad, undef, reachable etc.) */ FIRM_API int tarval_is_constant(ir_tarval *tv); @@ -338,15 +338,16 @@ FIRM_API ir_tarval *get_tarval_minus_one(ir_mode *mode); * returns tarval_bad for float modes */ FIRM_API ir_tarval *get_tarval_all_one(ir_mode *mode); -/** Return quite nan for float_number modes. */ +/** Returns quite nan for float_number modes. */ FIRM_API ir_tarval *get_tarval_nan(ir_mode *mode); -/** Return +inf for float_number modes. */ +/** Returns +inf for float_number modes. */ FIRM_API ir_tarval *get_tarval_plus_inf(ir_mode *mode); -/** Return -inf for float_number modes. */ +/** Returns -inf for float_number modes. */ FIRM_API ir_tarval *get_tarval_minus_inf(ir_mode *mode); +/** Modes for handling integer overflows. */ typedef enum tarval_int_overflow_mode_t { TV_OVERFLOW_BAD, /**< tarval module will return tarval_bad if a overflow occurs */ TV_OVERFLOW_WRAP, /**< tarval module will overflow will be ignored, wrap around occurs */ @@ -361,7 +362,7 @@ typedef enum tarval_int_overflow_mode_t { FIRM_API void tarval_set_integer_overflow_mode(tarval_int_overflow_mode_t ov_mode); /** - * Get the overflow mode for integer operations. + * Returns the overflow mode for integer operations. */ FIRM_API tarval_int_overflow_mode_t tarval_get_integer_overflow_mode(void); @@ -718,7 +719,7 @@ FIRM_API unsigned char get_tarval_sub_bits(ir_tarval *tv, unsigned byte_ofs); FIRM_API int tarval_is_single_bit(ir_tarval *tv); /** - * Return the number of set bits in a given (integer) tarval. + * Returns the number of set bits in a given (integer) tarval. * * @param tv the tarval * @@ -727,7 +728,7 @@ FIRM_API int tarval_is_single_bit(ir_tarval *tv); FIRM_API int get_tarval_popcount(ir_tarval *tv); /** - * Return the number of the lowest set bit in a given (integer) tarval. + * Returns the number of the lowest set bit in a given (integer) tarval. * * @param tv the tarval * diff --git a/include/libfirm/typerep.h b/include/libfirm/typerep.h index 29116a278..bc13f2408 100644 --- a/include/libfirm/typerep.h +++ b/include/libfirm/typerep.h @@ -162,17 +162,17 @@ typedef enum ir_linkage { ENUM_BITSET(ir_linkage) /** - * Return the visibility class of an entity + * Returns the visibility class of an entity */ FIRM_API ir_visibility get_entity_visibility(const ir_entity *entity); /** - * Set visibility class of an entity + * Sets visibility class of an entity */ FIRM_API void set_entity_visibility(ir_entity *entity, ir_visibility visibility); /** - * Return 1 if the entity is visible outside the current compilation unit + * Returns 1 if the entity is visible outside the current compilation unit * or to unknown callers (like asm statements). * (The entity might still be accessible indirectly through pointers) * This is a convenience function and does the same as @@ -182,7 +182,7 @@ FIRM_API void set_entity_visibility(ir_entity *entity, ir_visibility visibility) FIRM_API int entity_is_externally_visible(const ir_entity *entity); /** - * Return 1 if the entity has a definition (initializer) in the current + * Returns 1 if the entity has a definition (initializer) in the current * compilation unit */ FIRM_API int entity_has_definition(const ir_entity *entity); @@ -306,9 +306,11 @@ FIRM_API void set_entity_type(ir_entity *ent, ir_type *tp); /** Returns the linkage of an entity. */ FIRM_API ir_linkage get_entity_linkage(const ir_entity *entity); -/** Sets the linkage of an entity. */ +/** Sets the linkage flags of entity @p entity to @p linkage. */ FIRM_API void set_entity_linkage(ir_entity *entity, ir_linkage linkage); +/** Adds linkage flags @p linkage to entity @p entity. */ FIRM_API void add_entity_linkage(ir_entity *entity, ir_linkage linkage); +/** Remove linkage flags @p linkage from entity @p entity. */ FIRM_API void remove_entity_linkage(ir_entity *entity, ir_linkage linkage); /** @@ -323,7 +325,7 @@ FIRM_API ir_volatility get_entity_volatility(const ir_entity *ent); */ FIRM_API void set_entity_volatility(ir_entity *ent, ir_volatility vol); -/** Return the name of the volatility. */ +/** Returns the name of the volatility. */ FIRM_API const char *get_volatility_name(ir_volatility var); /** Returns alignment of entity in bytes */ @@ -335,7 +337,6 @@ FIRM_API unsigned get_entity_alignment(const ir_entity *entity); */ FIRM_API void set_entity_alignment(ir_entity *entity, unsigned alignment); - /** * Returns indication whether entity is aligned in memory. * @deprecated @@ -348,16 +349,18 @@ FIRM_API ir_align get_entity_aligned(const ir_entity *ent); */ FIRM_API void set_entity_aligned(ir_entity *ent, ir_align a); -/** Return the name of the alignment. */ +/** Returns the name of the alignment. */ FIRM_API const char *get_align_name(ir_align a); -/** Returns the offset of an entity (in a compound) in bytes. Only set if layout = fixed. */ +/** Returns the offset of an entity (in a compound) in bytes. Only set if + * layout = fixed. */ FIRM_API int get_entity_offset(const ir_entity *ent); /** Sets the offset of an entity (in a compound) in bytes. */ FIRM_API void set_entity_offset(ir_entity *ent, int offset); -/** Returns the offset bit remainder of a bitfield entity (in a compound) in bits. Only set if layout = fixed. */ +/** Returns the offset bit remainder of a bitfield entity (in a compound) in + * bits. Only set if layout = fixed. */ FIRM_API unsigned char get_entity_offset_bits_remainder(const ir_entity *ent); /** Sets the offset bit remainder of a bitfield entity (in a compound) in bits. */ @@ -379,15 +382,15 @@ FIRM_API ir_graph *get_entity_irg(const ir_entity *ent); /** A reserved value for "not yet set". */ #define IR_VTABLE_NUM_NOT_SET ((unsigned)(-1)) -/** Gets the entity vtable number. */ +/** Returns the entity vtable number. */ FIRM_API unsigned get_entity_vtable_number(const ir_entity *ent); /** Sets the entity vtable number. */ FIRM_API void set_entity_vtable_number(ir_entity *ent, unsigned vtable_number); -/** Set label number of an entity with code type */ +/** Sets label number of an entity with code type */ FIRM_API void set_entity_label(ir_entity *ent, ir_label_t label); -/** Return label number of an entity with code type */ +/** Returns label number of an entity with code type */ FIRM_API ir_label_t get_entity_label(const ir_entity *ent); /** Checks if an entity is compiler generated. */ @@ -412,7 +415,7 @@ typedef enum { | ir_usage_reinterpret_cast } ir_entity_usage; -/** Return the entity usage */ +/** Returns the entity usage */ FIRM_API ir_entity_usage get_entity_usage(const ir_entity *ent); /** Sets/resets the state of the address taken flag of an entity. */ @@ -433,6 +436,14 @@ FIRM_API dbg_info *get_entity_dbg_info(const ir_entity *ent); */ FIRM_API void set_entity_dbg_info(ir_entity *ent, dbg_info *db); +/** + * Sepcial parameter number which can be used for parameter entities to + * indicate the first non-declared parameter in a procedure with variable + * arguments. + * We assumes that all additional parameters for variable parameters are on the + * stack. Starting from this address you can walk the stack to find all other + * parameters. + */ #define IR_VA_START_PARAMETER_NUMBER ((size_t)-1) /** @@ -470,7 +481,10 @@ FIRM_API int is_irn_const_expression(ir_node *n); */ FIRM_API ir_node *copy_const_value(dbg_info *dbg, ir_node *n, ir_node *to_block); +/** Returns initial value of entity with atomic type @p ent. */ FIRM_API ir_node *get_atomic_ent_value(ir_entity *ent); +/** Sets initial value of entity with atomic type @p ent to node @p val. + * @note @p val must be a node in the const_code graph */ FIRM_API void set_atomic_ent_value(ir_entity *ent, ir_node *val); /** @defgroup ir_initializer Entity Initializers @@ -489,44 +503,44 @@ typedef enum ir_initializer_kind_t { IR_INITIALIZER_COMPOUND } ir_initializer_kind_t; -/** returns kind of an initializer */ +/** Returns kind of an initializer */ FIRM_API ir_initializer_kind_t get_initializer_kind(const ir_initializer_t *initializer); -/** Return the name of the initializer kind. */ +/** Returns the name of the initializer kind. */ FIRM_API const char *get_initializer_kind_name(ir_initializer_kind_t ini); /** - * returns the null initializer (there's only one instance of it in a program ) + * Returns the null initializer (there's only one instance of it in a program ) */ FIRM_API ir_initializer_t *get_initializer_null(void); /** - * creates an initializer containing a reference to a node on the const-code + * Creates an initializer containing a reference to a node on the const-code * irg. */ FIRM_API ir_initializer_t *create_initializer_const(ir_node *value); -/** creates an initializer containing a single tarval value */ +/** Creates an initializer containing a single tarval value */ FIRM_API ir_initializer_t *create_initializer_tarval(ir_tarval *tv); -/** return value contained in a const initializer */ +/** Returns value contained in a const initializer */ FIRM_API ir_node *get_initializer_const_value(const ir_initializer_t *initializer); -/** return value contained in a tarval initializer */ +/** Returns value contained in a tarval initializer */ FIRM_API ir_tarval *get_initializer_tarval_value(const ir_initializer_t *initialzier); -/** creates a compound initializer which holds @p n_entries entries */ +/** Creates a compound initializer which holds @p n_entries entries */ FIRM_API ir_initializer_t *create_initializer_compound(size_t n_entries); -/** returns the number of entries in a compound initializer */ +/** Returns the number of entries in a compound initializer */ FIRM_API size_t get_initializer_compound_n_entries(const ir_initializer_t *initializer); -/** sets entry with index @p index to the initializer @p value */ +/** Sets entry with index @p index to the initializer @p value */ FIRM_API void set_initializer_compound_value(ir_initializer_t *initializer, size_t index, ir_initializer_t *value); -/** returns the value with index @p index of a compound initializer */ +/** Returns the value with index @p index of a compound initializer */ FIRM_API ir_initializer_t *get_initializer_compound_value( const ir_initializer_t *initializer, size_t index); @@ -538,21 +552,40 @@ FIRM_API void set_entity_initializer(ir_entity *entity, ir_initializer_t *initia /** Returns true, if an entity has new style initializers. */ FIRM_API int has_entity_initializer(const ir_entity *entity); -/** Return the new style initializers of an entity. */ +/** Returns the new style initializers of an entity. */ FIRM_API ir_initializer_t *get_entity_initializer(const ir_entity *entity); +/** Adds entity @p ent to the list of entities that overwrite @p overwritten. */ FIRM_API void add_entity_overwrites(ir_entity *ent, ir_entity *overwritten); +/** Returns the number of entities in the list of entities that overwrite + * entity @p ent. */ FIRM_API size_t get_entity_n_overwrites(const ir_entity *ent); -FIRM_API size_t get_entity_overwrites_index(const ir_entity *ent, ir_entity *overwritten); +/** Returns index of @p overwritten in list of entities overwriting entity + * @p ent. */ +FIRM_API size_t get_entity_overwrites_index(const ir_entity *ent, + ir_entity *overwritten); +/** Returns entry @p pos in list of entities overwriting entity @p ent. */ FIRM_API ir_entity *get_entity_overwrites(const ir_entity *ent, size_t pos); -FIRM_API void set_entity_overwrites(ir_entity *ent, size_t pos, ir_entity *overwritten); +/** Sets entry @p pos in list of entities overwriting entity @p ent. */ +FIRM_API void set_entity_overwrites(ir_entity *ent, size_t pos, + ir_entity *overwritten); +/** Remove @p overwritten from list of entities overwriting entity @p ent. */ FIRM_API void remove_entity_overwrites(ir_entity *ent, ir_entity *overwritten); +/** Returns number of entities overwritten by @p ent. */ FIRM_API size_t get_entity_n_overwrittenby(const ir_entity *ent); -FIRM_API size_t get_entity_overwrittenby_index(const ir_entity *ent, ir_entity *overwrites); +/** Returns index of @p overwrites in list of entities overwritten by entity + * @p ent. */ +FIRM_API size_t get_entity_overwrittenby_index(const ir_entity *ent, + ir_entity *overwrites); +/** Return entry @p pos in list of entities overwritten by entity @p ent. */ FIRM_API ir_entity *get_entity_overwrittenby(const ir_entity *ent, size_t pos); -FIRM_API void set_entity_overwrittenby(ir_entity *ent, size_t pos, ir_entity *overwrites); -FIRM_API void remove_entity_overwrittenby(ir_entity *ent, ir_entity *overwrites); +/** Sets entry @p pos in list of entities overwritten by entity @p ent. */ +FIRM_API void set_entity_overwrittenby(ir_entity *ent, size_t pos, + ir_entity *overwrites); +/** Removes entry @p overwrites in list of entities overwritten by @p ent. */ +FIRM_API void remove_entity_overwrittenby(ir_entity *ent, + ir_entity *overwrites); /** * Checks whether a pointer points to an entity. @@ -582,19 +615,24 @@ FIRM_API int is_method_entity(const ir_entity *ent); */ FIRM_API long get_entity_nr(const ir_entity *ent); -/** Returns the entities visited count. */ +/** Returns the entities visited counter. + * @see @ref visited_counters */ FIRM_API ir_visited_t get_entity_visited(const ir_entity *ent); -/** Sets the entities visited count. */ +/** Sets the entities visited counter. + * @see @ref visited_counters */ FIRM_API void set_entity_visited(ir_entity *ent, ir_visited_t num); -/** Sets visited field in entity to entity_visited. */ +/** Marks entity as visited. + * @see @ref visited_counters */ FIRM_API void mark_entity_visited(ir_entity *ent); -/** Returns true if this entity was visited. */ +/** Returns true if this entity was visited. + * @see @ref visited_counters */ FIRM_API int entity_visited(const ir_entity *ent); -/** Returns true if this entity was not visited. */ +/** Returns true if this entity was not visited. + * @see @ref visited_counters */ FIRM_API int entity_not_visited(const ir_entity *ent); /** @@ -891,11 +929,16 @@ typedef enum { inh_transitive_closure_max /**< Invalid value. */ } inh_transitive_closure_state; +/** Sets the transitive closure of sub/superclass state for the + * whole program. */ FIRM_API void set_irp_inh_transitive_closure_state(inh_transitive_closure_state s); +/** Sets the transitive closure of sub/superclass state for the + * whole program to #inh_transitive_closure_invalid */ FIRM_API void invalidate_irp_inh_transitive_closure_state(void); +/** Returns the transitive closure of sub/superclass state for the + * whole program. */ FIRM_API inh_transitive_closure_state get_irp_inh_transitive_closure_state(void); - /** Compute transitive closure of the subclass/superclass and * overwrites/overwrittenby relation. * @@ -906,21 +949,43 @@ FIRM_API void compute_inh_transitive_closure(void); /** Free memory occupied by the transitive closure information. */ FIRM_API void free_inh_transitive_closure(void); -/** Iterate over all transitive subtypes. */ +/** Start iteration over all transitive subtypes of @p tp */ FIRM_API ir_type *get_class_trans_subtype_first(const ir_type *tp); +/** + * Returns next type in a subtype iteration started by + * get_class_trans_subtype_first() + */ FIRM_API ir_type *get_class_trans_subtype_next(const ir_type *tp); +/** + * Check if @p subtp is a subtype of @p tp. This function checks the full + * transitive closure of the subtype relation and not just direct subtyping. + * @return 1 if it is a subtype, 0 otherwise + */ FIRM_API int is_class_trans_subtype(const ir_type *tp, const ir_type *subtp); -/** Iterate over all transitive supertypes. */ +/** Start iteration over all transitive supertypes of @p tp */ FIRM_API ir_type *get_class_trans_supertype_first(const ir_type *tp); +/** + * Returns next type in a supertype iteration started by + * get_class_trans_supertype_first() + */ FIRM_API ir_type *get_class_trans_supertype_next(const ir_type *tp); -/** Iterate over all entities that transitive overwrite this entities. */ +/** Start iteration over all entities that transitive overwrite entity @p ent.*/ FIRM_API ir_entity *get_entity_trans_overwrittenby_first(const ir_entity *ent); +/** + * Returns next entity in a overwrittenby iteration started by + * get_entity_trans_overwrittenby_first() + */ FIRM_API ir_entity *get_entity_trans_overwrittenby_next(const ir_entity *ent); -/** Iterate over all transitive overwritten entities. */ +/** Start iteration over all transitive overwritten entities, overwritten by + * entity @p ent */ FIRM_API ir_entity *get_entity_trans_overwrites_first(const ir_entity *ent); +/** + * Returns next entity in a overwrites iteration started by + * get_entity_trans_overwrites_first() + */ FIRM_API ir_entity *get_entity_trans_overwrites_next(const ir_entity *ent); @@ -956,10 +1021,14 @@ typedef enum { ir_class_casts_state_max } ir_class_cast_state; -FIRM_API void set_irg_class_cast_state(ir_graph *irg, - ir_class_cast_state s); +/** Sets class cast state for graph @p irg to @p state. */ +FIRM_API void set_irg_class_cast_state(ir_graph *irg, + ir_class_cast_state state); +/** Returns class cast state for graph @p irg. */ FIRM_API ir_class_cast_state get_irg_class_cast_state(const ir_graph *irg); -FIRM_API void set_irp_class_cast_state(ir_class_cast_state s); +/** Sets class cast state for the whole program to @p state. */ +FIRM_API void set_irp_class_cast_state(ir_class_cast_state state); +/** Returns class cast state for the whole program. */ FIRM_API ir_class_cast_state get_irp_class_cast_state(void); /** @@ -1017,9 +1086,13 @@ FIRM_API void free_type_entities(ir_type *tp); */ FIRM_API void free_type(ir_type *tp); +/** Returns type opcode of type @p tp */ FIRM_API const tp_op *get_type_tpop(const ir_type *tp); +/** Returns name identifier of type opcode of type @p tp */ FIRM_API ident *get_type_tpop_nameid(const ir_type *tp); +/** Returns name of type opcode of type @p tp */ FIRM_API const char *get_type_tpop_name(const ir_type *tp); +/** Returns opcode of type opcode of type @p tp */ FIRM_API tp_opcode get_type_tpop_code(const ir_type *tp); /** @@ -1087,7 +1160,7 @@ FIRM_API void set_type_size_bytes(ir_type *tp, unsigned size); /** Returns the alignment of a type in bytes. */ FIRM_API unsigned get_type_alignment_bytes(ir_type *tp); -/** Returns the alignment of a type in bits. +/** Sets the alignment of a type in bytes. * * If the alignment of a type is * not set, it is calculated here according to the following rules: @@ -1099,15 +1172,20 @@ FIRM_API unsigned get_type_alignment_bytes(ir_type *tp); */ FIRM_API void set_type_alignment_bytes(ir_type *tp, unsigned align); -/** Returns the visited count of a type. */ +/** Returns the visited counter of a type. + * @see @ref visited_counters */ FIRM_API ir_visited_t get_type_visited(const ir_type *tp); -/** Sets the visited count of a type to num. */ +/** Sets the visited counter of a type to num. + * @see @ref visited_counters */ FIRM_API void set_type_visited(ir_type *tp, ir_visited_t num); -/** Sets visited field in type to type_visited. */ +/** Sets visited field in type to type_visited. + * @see @ref visited_counters */ FIRM_API void mark_type_visited(ir_type *tp); -/** Returns non-zero if the type is already visited */ +/** Returns non-zero if the type is already visited + * @see @ref visited_counters */ FIRM_API int type_visited(const ir_type *tp); -/** Returns non-zero if the type is not yet visited */ +/** Returns non-zero if the type is not yet visited + * @see @ref visited_counters */ FIRM_API int type_not_visited(const ir_type *tp); /** Returns the associated link field of a type. */ @@ -1115,21 +1193,15 @@ FIRM_API void *get_type_link(const ir_type *tp); /** Sets the associated link field of a type. */ FIRM_API void set_type_link(ir_type *tp, void *l); -/** - * Visited flag to traverse the type information. - * - * Increase this flag by one before traversing the type information - * using inc_master_type_visited(). - * Mark type nodes as visited by mark_type_visited(ir_type). - * Check whether node was already visited by type_visited(ir_type) - * and type_not_visited(ir_type). - * Or use the function to walk all types. - * - * @see typewalk - */ +/** Increments type visited reference counter by one. + * @see @ref visited_counters, mark_type_visited(), type_visited() */ +FIRM_API void inc_master_type_visited(void); +/** Sets type visited reference counter. + * @see @ref visited_counters */ FIRM_API void set_master_type_visited(ir_visited_t val); +/** Returns type visited reference counter. + * @see @ref visited_counters */ FIRM_API ir_visited_t get_master_type_visited(void); -FIRM_API void inc_master_type_visited(void); /** * Sets the debug information of a type. @@ -1291,10 +1363,10 @@ FIRM_API ir_type *new_type_class(ident *name); /** Creates a new class type with debug information. */ FIRM_API ir_type *new_d_type_class(ident *name, type_dbg_info *db); -/** return identifier of the class type */ +/** Returns identifier of the class type */ FIRM_API ident *get_class_ident(const ir_type *clss); -/** return identifier of the class type */ +/** Returns identifier of the class type */ FIRM_API const char *get_class_name(const ir_type *clss); /** Returns the number of members of this class. */ @@ -1303,6 +1375,10 @@ FIRM_API size_t get_class_n_members(const ir_type *clss); /** Returns the member at position pos, 0 <= pos < n_member */ FIRM_API ir_entity *get_class_member(const ir_type *clss, size_t pos); +/** + * Special index returned when get_class_member_index() cannot find a member. + * This index is never used for actual members. + */ #define INVALID_MEMBER_INDEX ((size_t)-1) /** Returns index of mem in clss, INVALID_MEMBER_INDEX if not contained. */ @@ -1321,7 +1397,7 @@ FIRM_API void add_class_subtype(ir_type *clss, ir_type *subtype); /** Returns the number of subtypes */ FIRM_API size_t get_class_n_subtypes(const ir_type *clss); -/** Gets the subtype at position pos, 0 <= pos < n_subtype. */ +/** Returns the subtype at position pos, 0 <= pos < n_subtype. */ FIRM_API ir_type *get_class_subtype(ir_type *clss, size_t pos); /** Returns the index to access subclass as subtype of class. @@ -1354,7 +1430,7 @@ FIRM_API size_t get_class_n_supertypes(const ir_type *clss); */ FIRM_API size_t get_class_supertype_index(ir_type *clss, ir_type *super_clss); -/** Gets the supertype at position pos, 0 <= pos < n_supertype. */ +/** Returns the supertype at position pos, 0 <= pos < n_supertype. */ FIRM_API ir_type *get_class_supertype(ir_type *clss, size_t pos); /** Sets the supertype at position pos, 0 <= pos < n_supertype. @@ -1369,7 +1445,7 @@ FIRM_API void remove_class_supertype(ir_type *clss, ir_type *supertype); /** Returns the type info entity of a class. */ FIRM_API ir_entity *get_class_type_info(const ir_type *clss); -/** Set a type info entity for the class. */ +/** Sets a type info entity for the class. */ FIRM_API void set_class_type_info(ir_type *clss, ir_entity *ent); /** Returns the size of the virtual function table. */ @@ -1384,13 +1460,13 @@ FIRM_API int is_class_final(const ir_type *clss); /** Sets the class final flag. */ FIRM_API void set_class_final(ir_type *clss, int flag); -/** Return non-zero if a class is an interface */ +/** Returns non-zero if a class is an interface */ FIRM_API int is_class_interface(const ir_type *clss); /** Sets the class interface flag. */ FIRM_API void set_class_interface(ir_type *clss, int flag); -/** Return non-zero if a class is an abstract class. */ +/** Returns non-zero if a class is an abstract class. */ FIRM_API int is_class_abstract(const ir_type *clss); /** Sets the class abstract flag. */ @@ -1408,6 +1484,7 @@ FIRM_API int is_Class_type(const ir_type *clss); * of the library. */ FIRM_API const tp_op *type_class; +/** Returns type opcode for class type. @see type_class */ FIRM_API const tp_op *get_tpop_class(void); /** @} */ @@ -1435,10 +1512,10 @@ FIRM_API ir_type *new_type_struct(ident *name); /** Creates a new type struct with debug information. */ FIRM_API ir_type *new_d_type_struct(ident *name, type_dbg_info* db); -/** return struct identifier */ +/** Returns struct identifier */ FIRM_API ident *get_struct_ident(const ir_type *strct); -/** return struct identifier as c-string*/ +/** Returns struct identifier as c-string*/ FIRM_API const char *get_struct_name(const ir_type *strct); /** Returns the number of members of this struct. */ @@ -1463,6 +1540,7 @@ FIRM_API int is_Struct_type(const ir_type *strct); * of the library. */ FIRM_API const tp_op *type_struct; +/** Returns type opcode for struct type. @see type_struct */ FIRM_API const tp_op *get_tpop_struct(void); /** @} */ @@ -1488,10 +1566,10 @@ FIRM_API ir_type *new_type_union(ident *name); FIRM_API ir_type *new_d_type_union(ident *name, type_dbg_info* db); -/** return union identifier */ +/** Returns union identifier */ FIRM_API ident *get_union_ident(const ir_type *uni); -/** return union identifier as c-string */ +/** Returns union identifier as c-string */ FIRM_API const char *get_union_name(const ir_type *uni); /** Returns the number of unioned types of this union */ @@ -1514,6 +1592,7 @@ FIRM_API int is_Union_type(const ir_type *uni); * of the library. */ FIRM_API const tp_op *type_union; +/** Returns type opcode for union type. @see type_union */ FIRM_API const tp_op *get_tpop_union(void); /** @} */ @@ -1668,7 +1747,7 @@ typedef enum { #define SET_CDECL(cc_mask) (((cc_mask) & ~cc_bits) | cc_cdecl_set) /** - * Set. the STDCALL convention bits. + * Sets the STDCALL convention bits. */ #define SET_STDCALL(cc_mask) (((cc_mask) & ~cc_bits) | cc_stdcall_set) @@ -1700,6 +1779,7 @@ FIRM_API int is_Method_type(const ir_type *method); * of the library. */ FIRM_API const tp_op *type_method; +/** Returns type opcode for method type @see type_method */ FIRM_API const tp_op *get_tpop_method(void); /** @} */ @@ -1725,7 +1805,7 @@ FIRM_API const tp_op *get_tpop_method(void); * Sets n_dimension to dimension and all dimension entries to NULL. * 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. + * Sets dimension sizes after call to constructor with set_* routines. */ FIRM_API ir_type *new_type_array(size_t n_dims, ir_type *element_type); @@ -1734,7 +1814,7 @@ FIRM_API ir_type *new_type_array(size_t n_dims, ir_type *element_type); * Sets n_dimension to dimension and all dimension entries to NULL. * 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. + * Sets dimension sizes after call to constructor with set_* routines. * A legal array type must have at least one dimension set. */ FIRM_API ir_type *new_d_type_array(size_t n_dims, ir_type *element_type, @@ -1799,13 +1879,13 @@ FIRM_API size_t find_array_dimension(const ir_type *array, size_t order); /** Sets the array element type. */ FIRM_API void set_array_element_type(ir_type *array, ir_type *tp); -/** Gets the array element type. */ +/** Returns the array element type. */ FIRM_API ir_type *get_array_element_type(const ir_type *array); /** Sets the array element entity. */ FIRM_API void set_array_element_entity(ir_type *array, ir_entity *ent); -/** Get the array element entity. */ +/** Returns the array element entity. */ FIRM_API ir_entity *get_array_element_entity(const ir_type *array); /** Returns true if a type is an array type. */ @@ -1820,6 +1900,7 @@ FIRM_API int is_Array_type(const ir_type *array); * of the library. */ FIRM_API const tp_op *type_array; +/** Returns type opcode for array type. @see type_array */ FIRM_API const tp_op *get_tpop_array(void); /** @} */ @@ -1846,13 +1927,13 @@ FIRM_API ir_type *new_d_type_enumeration(ident *name, size_t n_enums, type_dbg_info *db); -/** return enumeration identifier */ +/** Returns enumeration identifier */ FIRM_API ident *get_enumeration_ident(const ir_type *enumeration); -/** return enumeration identifier as c-string */ +/** Returns enumeration identifier as c-string */ FIRM_API const char *get_enumeration_name(const ir_type *enumeration); -/** Set an enumeration constant to a enumeration type at a given position. */ +/** Sets an enumeration constant to a enumeration type at a given position. */ FIRM_API void set_enumeration_const(ir_type *enumeration, size_t pos, ident *nameid, ir_tarval *con); @@ -1894,6 +1975,7 @@ FIRM_API int is_Enumeration_type(const ir_type *enumeration); * of the library. */ FIRM_API const tp_op *type_enumeration; +/** Returns type opcode for enumeration type. @see type_enumeration */ FIRM_API const tp_op *get_tpop_enumeration(void); /** @} */ @@ -1935,6 +2017,7 @@ FIRM_API ir_type *find_pointer_type_to_type(ir_type *tp); * of the library. */ FIRM_API const tp_op *type_pointer; +/** Returns type opcode for pointer type. @see type_pointer */ FIRM_API const tp_op *get_tpop_pointer(void); /** @} */ @@ -1956,7 +2039,7 @@ FIRM_API ir_type *new_d_type_primitive(ir_mode *mode, type_dbg_info* db); /** Returns true if a type is a primitive type. */ FIRM_API int is_Primitive_type(const ir_type *primitive); -/** Return the base type of a primitive (bitfield) type or NULL if none. */ +/** Returns the base type of a primitive (bitfield) type or NULL if none. */ FIRM_API ir_type *get_primitive_base_type(const ir_type *tp); /** Sets the base type of a primitive (bitfield) type. */ @@ -1971,6 +2054,7 @@ FIRM_API void set_primitive_base_type(ir_type *tp, ir_type *base_tp); * of the library. */ FIRM_API const tp_op *type_primitive; +/** Returns type opcode for primitive type. @see type_primitive */ FIRM_API const tp_op *get_tpop_primitive(void); /** @} */ @@ -2006,6 +2090,7 @@ FIRM_API ir_type *get_none_type(void); * one type with this opcode. */ FIRM_API const tp_op *tpop_none; +/** Returns type opcode for none type. @see tpop_none */ FIRM_API const tp_op *get_tpop_none(void); /** @} */ @@ -2024,6 +2109,7 @@ FIRM_API int is_code_type(const ir_type *tp); * The code type is used to mark pieces of code (basic blocks) */ FIRM_API const tp_op *tpop_code; +/** Returns type opcode for code type. @see tpop_code */ FIRM_API const tp_op *get_tpop_code_type(void); /** @} */ @@ -2058,6 +2144,7 @@ FIRM_API ir_type *get_unknown_type(void); * exactly one type with this opcode. */ FIRM_API const tp_op *tpop_unknown; +/** Returns type opcode for unknown type. @see tpop_unknown */ FIRM_API const tp_op *get_tpop_unknown(void); /** @} */ @@ -2075,15 +2162,15 @@ FIRM_API int is_atomic_type(const ir_type *tp); */ /** - * Gets the identifier of a compound type + * Returns the identifier of a compound type */ FIRM_API ident *get_compound_ident(const ir_type *tp); -/** return compound identifier as c-string */ +/** Returns compound identifier as c-string */ FIRM_API const char *get_compound_name(const ir_type *tp); /** - * Gets the number of elements in a Firm compound type. + * Returns the number of elements in a Firm compound type. * * This is just a comfortability function, because structs and * classes can often be treated be the same code, but they have @@ -2096,7 +2183,7 @@ FIRM_API const char *get_compound_name(const ir_type *tp); FIRM_API size_t get_compound_n_members(const ir_type *tp); /** - * Gets the member of a Firm compound type at position pos. + * Returns the member of a Firm compound type at position pos. * * @param tp The type (must be struct, union or class). * @param pos The number of the member. @@ -2278,7 +2365,7 @@ FIRM_API void types_calc_finalization(void); /** @deprecated */ FIRM_API ir_visibility get_type_visibility(const ir_type *tp); /** @deprecated */ -FIRM_API void set_type_visibility(ir_type *tp, ir_visibility v); +FIRM_API void set_type_visibility(ir_type *tp, ir_visibility v); /** @} */ diff --git a/include/libfirm/vrp.h b/include/libfirm/vrp.h index aa2866da0..ef5234b45 100644 --- a/include/libfirm/vrp.h +++ b/include/libfirm/vrp.h @@ -35,6 +35,7 @@ * @{ */ +/** Type of a value range */ enum range_types { VRP_UNDEFINED, /**< No information could be derived so far */ VRP_RANGE, /**< bottom and top form a range, including both values */ @@ -43,7 +44,7 @@ enum range_types { VRP_VARYING /**< information cannot be derived */ }; -/** VRP information */ +/** VRP information for a single node */ typedef struct { ir_tarval *bits_set; /**< The bits which, by analysis, are definitely set: @@ -52,12 +53,12 @@ typedef struct { not set: 1 for may be set, 0: definitely not set */ enum range_types range_type; /**< The range represented by range_top, range_bottom */ - ir_tarval *range_bottom; - ir_tarval *range_top; + ir_tarval *range_bottom; /**< lower end of the value range */ + ir_tarval *range_top; /**< upper end of the value range */ } vrp_attr; /** - * Set vrp data on the graph irg + * Sets vrp data on the graph irg * @param irg graph on which to set vrp data */ FIRM_API void set_vrp_data(ir_graph *irg); @@ -76,8 +77,8 @@ FIRM_API void free_vrp_data(ir_graph *irg); */ FIRM_API ir_relation vrp_cmp(const ir_node *left, const ir_node *right); -/* - * Return the vrp data for this node +/** + * Returns the vrp data for this node * Note: only allowed for nodes with an integer mode! * * @param n: the node for which to return the vrp information diff --git a/scripts/gen_ir.py b/scripts/gen_ir.py index 6510768a7..c9a478bb0 100755 --- a/scripts/gen_ir.py +++ b/scripts/gen_ir.py @@ -596,15 +596,22 @@ FIRM_API ir_node *new_{{node.name}}( {{node|nodeparameters}} {% endfilter %}); {%- endif %} -/** Return true if the node is a {{node.name}} node. */ +/** + * Test if node is a {{node.name}} + * @returns 1 if the node is a {{node.name}} node, 0 otherwise + */ FIRM_API int is_{{node.name}}(const ir_node *node); {% for input in node.ins -%} +/** Returns {{input[0]}} input of {{node.name|a_an}} node. */ FIRM_API ir_node *get_{{node.name}}_{{input[0]}}(const ir_node *node); +/** Sets {{input[0]}} input of {{node.name|a_an}} node. */ FIRM_API void set_{{node.name}}_{{input[0]}}(ir_node *node, ir_node *{{input[0]|escape_keywords}}); {% endfor -%} {% for attr in node.attrs|hasnot("noprop") -%} +/** Returns {{attr.name}} attribute of {{node.name|a_an}} node. */ FIRM_API {{attr.type}} get_{{node.name}}_{{attr.name}}(const ir_node *node); +/** Sets {{attr.name}} attribute of {{node.name|a_an}} node. */ FIRM_API void set_{{node.name}}_{{attr.name}}(ir_node *node, {{attr.type}} {{attr.name}}); {% endfor -%} /** @} */ @@ -656,12 +663,18 @@ typedef enum ir_opcode { } ir_opcode; {% for node in nodes %} -/** @ingroup {{node.name}} */ +/** + * @ingroup {{node.name}} + * {{node.name}} opcode + */ FIRM_API ir_op *op_{{node.name}}; {%- endfor %} {% for node in nodes %} -/** @ingroup {{node.name}} */ +/** + * @ingroup {{node.name}} + * Returns opcode for {{node.name}} nodes. + */ FIRM_API ir_op *get_op_{{node.name}}(void); {%- endfor %} -- 2.20.1