Commit fbe9e7db authored by Matthias Braun's avatar Matthias Braun
Browse files

Rework API documentation

- Put things into logical groups
- Add cross references from node overview to API docu
parent bed2f723
......@@ -843,7 +843,7 @@ DOCSET_BUNDLE_ID = org.doxygen.Project
# Microsoft HTML help workshop to generate a compiled HTML help file (.chm)
# of the generated HTML documentation.
GENERATE_HTMLHELP = YES
GENERATE_HTMLHELP = NO
# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can
# be used to specify the file name of the resulting .chm file. You
......@@ -1225,13 +1225,13 @@ ENABLE_PREPROCESSING = YES
# compilation will be performed. Macro expansion can be done in a controlled
# way by setting EXPAND_ONLY_PREDEF to YES.
MACRO_EXPANSION = NO
MACRO_EXPANSION = YES
# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
# then the macro expansion is limited to the macros specified with the
# PREDEFINED and EXPAND_AS_DEFINED tags.
EXPAND_ONLY_PREDEF = NO
EXPAND_ONLY_PREDEF = YES
# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
# in the INCLUDE_PATH (see below) will be search if a #include is found.
......@@ -1259,7 +1259,7 @@ INCLUDE_FILE_PATTERNS =
# undefined via #undef or recursively expanded use the := operator
# instead of the = operator.
PREDEFINED =
PREDEFINED = FIRM_API
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
# this tag can be used to specify a list of macro names that should be expanded.
......@@ -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 = YES
GENERATE_TAGFILE = 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
......
......@@ -31,6 +31,13 @@
#include "iroptimize.h"
#include "begin.h"
/**
* @defgroup be Code Generation
*
* Code Generation (backend) produces machine-code.
* @{
*/
typedef enum {
ASM_CONSTRAINT_FLAG_NONE = 0,
ASM_CONSTRAINT_FLAG_SUPPORTS_REGISTER = 1u << 0,
......@@ -171,6 +178,8 @@ FIRM_API asm_constraint_flags_t be_parse_asm_constraints(const char *constraints
*/
FIRM_API int be_is_valid_clobber(const char *clobber);
/** @} */
#include "end.h"
#endif
......@@ -22,7 +22,18 @@
* @brief Representation and computation of the callgraph.
* @author Goetz Lindenmaier
* @date 21.7.2004
* @brief
* @brief callgraph analysis
*/
#ifndef FIRM_ANA_CALLGRAPH_H
#define FIRM_ANA_CALLGRAPH_H
#include "firm_types.h"
#include "begin.h"
/**
* @ingroup irana
* @defgroup callgraph Callgraph
*
* This file contains the representation of the callgraph.
* The nodes of the call graph are ir_graphs. The edges between
* the nodes are calling relations. I.e., if method a calls method
......@@ -35,12 +46,8 @@
* Finally this file contains an algorithm that computes backedges
* in the callgraph, i.e., the algorithm finds possibly recursive calls.
* The algorithm computes an upper bound of all recursive calls.
* @{
*/
#ifndef FIRM_ANA_CALLGRAPH_H
#define FIRM_ANA_CALLGRAPH_H
#include "firm_types.h"
#include "begin.h"
/** Flag to indicate state of callgraph. */
typedef enum {
......@@ -164,6 +171,8 @@ FIRM_API void set_irp_loop_nesting_depth_state(loop_nesting_depth_state s);
/** Marks the nesting depth state of the program representation as inconsistent. */
FIRM_API void set_irp_loop_nesting_depth_state_inconsistent(void);
/** @} */
#include "end.h"
#endif
......@@ -28,6 +28,11 @@
#include "firm_types.h"
#include "begin.h"
/** @ingroup irana
* @defgroup ir_cdep Control Dependence
* @{
*/
/** Compute the control dependence graph for a graph. */
FIRM_API void compute_cdep(ir_graph *irg);
......@@ -73,6 +78,8 @@ FIRM_API ir_node *get_unique_cdep(const ir_node *block);
*/
FIRM_API int has_multiple_cdep(const ir_node *block);
/** @} */
#include "end.h"
#endif
......@@ -36,6 +36,10 @@
#include "firm_types.h"
#include "begin.h"
/** @addtogroup callgraph
* @{
*/
/** Analyses a rough estimation of the possible call graph.
*
* Determines for each Call node the set of possibly called methods.
......@@ -78,6 +82,8 @@ FIRM_API void free_irp_callee_info(void);
*/
FIRM_API void opt_call_addrs(void);
/** @} */
#include "end.h"
#endif
......@@ -22,14 +22,6 @@
* @brief Implements the Firm interface to debug information.
* @author Goetz Lindenmaier, Michael Beck
* @date 2001
* @brief
* Firm requires a debugging module fulfilling this interface, else no
* debugging information is passed to the backend.
* The interface requires a datatype representing the debugging
* information. Firm supports administrating a reference to the debug
* information in every Firm node. Further Firm optimizations call
* routines to propagate debug information from old nodes to new nodes
* if the optimization replaces the old ones by the new ones.
*/
#ifndef FIRM_DEBUG_DBGINFO_H
#define FIRM_DEBUG_DBGINFO_H
......@@ -40,8 +32,14 @@
#include "begin.h"
/**
* @defgroup debug The Firm interface to debugging support.
*
* @defgroup dbg_info Source References
* Firm requires a debugging module fulfilling this interface, else no
* debugging information is passed to the backend.
* The interface requires a datatype representing the debugging
* information. Firm supports administrating a reference to the debug
* information in every Firm node. Further Firm optimizations call
* routines to propagate debug information from old nodes to new nodes
* if the optimization replaces the old ones by the new ones.
* @{
*/
......@@ -146,8 +144,6 @@ typedef void merge_sets_func(ir_node **new_node_array, int new_num_entries, ir_n
FIRM_API void dbg_init(merge_pair_func *dbg_info_merge_pair,
merge_sets_func *dbg_info_merge_sets);
/** @} */
/**
* The type of the debug info retriever function.
* When given a dbg_info returns the name (usually the filename) of the
......@@ -187,6 +183,8 @@ FIRM_API const char *ir_retrieve_dbg_info(const dbg_info *dbg, unsigned *line);
FIRM_API void ir_retrieve_type_dbg_info(char *buffer, size_t buffer_size,
const type_dbg_info *tdbgi);
/** @} */
#include "end.h"
#endif
......@@ -29,7 +29,11 @@
#include "firm_types.h"
#include "begin.h"
struct ir_exec_freq;
/**
* @ingroup irana
* @defgroup execfreq Basic Block Execution Frequency
* @{
*/
/**
* Create execfreq structure (to be used with set_execfreq)
......@@ -54,6 +58,8 @@ FIRM_API double get_block_execfreq(const ir_exec_freq *ef,
FIRM_API unsigned long get_block_execfreq_ulong(const ir_exec_freq *ef,
const ir_node *block);
/** @} */
#include "end.h"
#endif
......@@ -21,8 +21,10 @@
* @file
* @brief Central firm header.
* @author Martin Trapp, Christian Schaefer, Goetz Lindenmaier
* @brief
* Central FIRM header.
* @brief Central FIRM header.
*/
/** @mainpage
*
* FIRM is a full graph based intermediate representation in SSA Form
* with a novel concept to model side effects. It allows fast, aggressive
......@@ -52,8 +54,8 @@
*
* Further this library supplies functionality to build and optimize FIRM graphs
* and further functionality needed in a compiler. Finally there is more
* generic functionality to support implementations using firm. (Code generation,
* further optimizations).
* generic functionality to support implementations using firm.
* (Code generation, further optimizations).
*/
#ifndef FIRM_COMMON_FIRM_H
#define FIRM_COMMON_FIRM_H
......
......@@ -31,26 +31,43 @@ typedef unsigned long ir_visited_t;
typedef unsigned long ir_exc_region_t;
typedef unsigned long ir_label_t;
/** @ingroup dbg_info */
typedef struct dbg_info dbg_info, *dbg_info_ptr;
/** @ingroup dbg_info */
typedef struct type_dbg_info type_dbg_info, *type_dbg_info_ptr;
/** @ingroup ir_ident */
typedef struct ident ident, *ir_ident_ptr;
/** @ingroup ir_node */
typedef struct ir_node ir_node, *ir_node_ptr;
/** @ingroup ir_op */
typedef struct ir_op ir_op, *ir_op_ptr;
/** @ingroup ir_mode */
typedef struct ir_mode ir_mode, *ir_mode_ptr;
/** @ingroup iredges */
typedef struct ir_edge_t ir_edge_t, *ir_edge_ptr;
/** @ingroup ir_heights */
typedef struct ir_heights_t ir_heights_t;
/** @ingroup ir_tarval */
typedef struct ir_tarval ir_tarval, *ir_tarval_ptr;
typedef struct ir_enum_const ir_enum_const, *ir_enum_const_ptr;
/** @ingroup ir_type */
typedef struct ir_type ir_type, *ir_type_ptr;
/** @ingroup ir_graph */
typedef struct ir_graph ir_graph, *ir_graph_ptr;
/** @ingroup ir_prog */
typedef struct ir_prog ir_prog, *ir_prog_ptr;
/** @ingroup ir_loop */
typedef struct ir_loop ir_loop, *ir_loop_ptr;
typedef struct ir_region ir_region, *ir_region_ptr;
/** @ingroup ir_entity */
typedef struct ir_entity ir_entity, *ir_entity_ptr;
typedef struct ir_extblk ir_extblk, *ir_extblk_ptr;
/** @ingroup execfreq */
typedef struct ir_exec_freq ir_exec_freq, *ir_exec_freq_ptr;
/** @ingroup ir_cdep */
typedef struct ir_cdep ir_cdep, *ir_cdep_ptr;
typedef struct sn_entry *seqno_t;
/** @ingroup ir_op */
typedef struct arch_irn_ops_t arch_irn_ops_t;
typedef struct ir_graph_pass_t ir_graph_pass_t;
typedef struct ir_prog_pass_t ir_prog_pass_t;
......@@ -58,6 +75,7 @@ typedef struct ir_prog_pass_t ir_prog_pass_t;
typedef struct ir_graph_pass_manager_t ir_graph_pass_manager_t;
typedef struct ir_prog_pass_manager_t ir_prog_pass_manager_t;
/** @ingroup ir_initializer */
typedef union ir_initializer_t ir_initializer_t, *ir_initializer_ptr;
typedef void irg_walk_func(ir_node *, void *);
......@@ -236,6 +254,7 @@ typedef enum symconst_kind {
/** SymConst attribute.
*
* This union contains the symbolic information represented by the node.
* @ingroup SymConst
*/
typedef union symconst_symbol {
ir_type *type_p; /**< The type of a SymConst. */
......@@ -243,20 +262,26 @@ typedef union symconst_symbol {
ir_enum_const *enum_p; /**< The enumeration constant of a SymConst. */
} symconst_symbol;
/** The allocation place. */
/** The allocation place.
* @ingroup Alloc
*/
typedef enum ir_where_alloc {
stack_alloc, /**< Alloc allocates the object on the stack. */
heap_alloc /**< Alloc allocates the object on the heap. */
} ir_where_alloc;
/** A input/output constraint attribute. */
/** A input/output constraint attribute.
* @ingroup ASM
*/
typedef struct ir_asm_constraint {
unsigned pos; /**< The inputs/output position for this constraint. */
ident *constraint; /**< The constraint for this input/output. */
ir_mode *mode; /**< The mode of the constraint. */
} ir_asm_constraint;
/** Supported libFirm builtins. */
/** Supported libFirm builtins.
* @ingroup Builtin
*/
typedef enum ir_builtin_kind {
ir_bk_trap, /**< GCC __builtin_trap(): insert trap */
ir_bk_debugbreak, /**< MS __debugbreak(): insert debug break */
......
......@@ -22,10 +22,6 @@
* @brief Compute heights of nodes inside basic blocks
* @author Sebastian Hack
* @date 19.04.2006
*
* The height is a measure for the longest datadependencies path from a node to
* the end of a basic block. This is usefull for scheduling heuristics and can
* also be used to speedup reachability queries.
*/
#ifndef FIRM_ANA_HEIGHTS_H
#define FIRM_ANA_HEIGHTS_H
......@@ -33,6 +29,17 @@
#include "firm_types.h"
#include "begin.h"
/**
* @ingroup irana
* @defgroup ir_heights Node Heights
*
* The height is a measure for the longest datadependencies path from a node to
* the end of a basic block. This is usefull for scheduling heuristics and can
* also be used to speedup reachability queries.
*
* @{
*/
/**
* Get 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
......@@ -76,6 +83,8 @@ FIRM_API ir_heights_t *heights_new(ir_graph *irg);
*/
FIRM_API void heights_free(ir_heights_t *h);
/** @} */
#include "end.h"
#endif
......@@ -21,8 +21,7 @@
* @file
* @brief Data type for unique names.
* @author Goetz Lindenmaier
* @brief
* Declarations for identifiers in the firm library
* @brief Declarations for identifiers in the firm library
*/
#ifndef FIRM_IDENT_H
#define FIRM_IDENT_H
......@@ -31,6 +30,11 @@
#include "firm_types.h"
#include "begin.h"
/**
* @defgroup ir_ident Identifiers
* @{
*/
/**
* Store a string and create an ident.
*
......@@ -131,6 +135,8 @@ FIRM_API ident *id_mangle3(const char *prefix, ident *middle,
/** returns a mangled name for a Win32 function using its calling convention */
FIRM_API ident *id_decorate_win32_c_fkt(const ir_entity *ent, ident *id);
/** @} */
#include "end.h"
#endif
This diff is collapsed.
......@@ -22,8 +22,19 @@
* @brief Construct and access dominator tree.
* @author Goetz Lindenmaier
* @date 2.2002
* @brief
* This file contains routines to construct and access dominator information.
* @brief This file contains routines to construct and access dominator information.
*/
#ifndef FIRM_ANA_IRDOM_H
#define FIRM_ANA_IRDOM_H
#include "firm_types.h"
#include "begin.h"
/** @defgroup irana Analyses */
/**
* @ingroup irana
* @defgroup irdom Dominance Information
*
* The dominator information is stored in three fields of block nodes:
* - idom: a reference to the block that is the immediate dominator of
......@@ -34,12 +45,9 @@
*
* We generally presume (like Tarjan) that endless loops do not exist. The
* implementation assumes a control dependency from End to loop header.
*
* @{
*/
#ifndef FIRM_ANA_IRDOM_H
#define FIRM_ANA_IRDOM_H
#include "firm_types.h"
#include "begin.h"
/** Accessing the dominator data structure.
*
......@@ -292,6 +300,8 @@ FIRM_API void free_dom(ir_graph *irg);
*/
FIRM_API void free_postdom(ir_graph *irg);
/** @} */
#include "end.h"
#endif
......@@ -21,18 +21,8 @@
* @file
* @brief Write vcg representation of firm to file.
* @author Martin Trapp, Christian Schaefer, Goetz Lindenmaier, Hubert Schmidt
* @brief
* Dump routines for the ir graph and all type information.
*
* The dump format of most functions is vcg. This is a text based graph
* representation. Some use the original format,
* but most generate an extended format that is only read by some special
* versions of xvcg or by the comercialized version now calles aiSee.
* A test version of aiSee is available at
* http://www.absint.de/aisee/download/index.htm.
* @brief Dump routines for the ir graph and all type information.
*
* We have developed an own advanced viewer called ycomp:
* http://www.info.uni-karlsruhe.de/software/ycomp/
*/
#ifndef FIRM_IR_IRDUMP_H
#define FIRM_IR_IRDUMP_H
......@@ -42,8 +32,24 @@
#include "firm_types.h"
#include "begin.h"
/** @defgroup convenience_dumper Convenience interface for dumpers */
/*@{*/
/** @defgroup ir_dump Visualisation
*
* Dumps information so it can be visualised. The dump format of most functions
* is vcg. This is a text based graph representation. Some use the original
* format, but most generate an extended format that is only read by some
* special versions of xvcg or by the commercialized version now calles aiSee.
*
* A test version of aiSee is available at
* http://www.absint.de/aisee/download/index.htm.
*
* We have developed an own advanced viewer called ycomp:
* http://www.info.uni-karlsruhe.de/software/ycomp/
*@{
*/
/** @defgroup convenience Convenience Interface
* @{
*/
/**
* Convenience interface for dumping a graph as vcg file.
......@@ -134,15 +140,6 @@ FIRM_API ir_prog_pass_t *dump_all_ir_graph_pass(const char *name,
/*@}*/
/**
* @defgroup dumper Dump information to file
* This is the low-level interface for dumping information as text files
* and xvcg graphs.
* Normally you should use the convenience interface @ref convenience_dumper
* instead of the functions in this group.
*/
/*@{*/
/**
* Dumps all Firm nodes of a single graph for a single procedure in
* standard xvcg format.
......
......@@ -28,7 +28,9 @@
#include "begin.h"
/** Supported Edge kinds. */
/** Supported Edge kinds.
* @ingroup iredges
*/
typedef enum ir_edge_kind_t {
EDGE_KIND_FIRST,
EDGE_KIND_NORMAL = EDGE_KIND_FIRST, /**< Normal data flow edges. */
......
......@@ -30,6 +30,12 @@
#include "iredgekinds.h"
#include "begin.h"
/**
* @ingroup irana
* @defgroup iredges Dynamic Reverse Edges
* @{
*/
/**
* Get the first edge pointing to some node.
* @note There is no order on out edges. First in this context only
......@@ -268,6 +274,8 @@ FIRM_API void irg_walk_edges(ir_node *start, irg_walk_func *pre,
FIRM_API void edges_reset_private_data(ir_graph *irg, int offset,
unsigned size);
/** @} */
#include "end.h"
#endif
......@@ -21,7 +21,16 @@
* @file
* @brief Flags to control optimizations.
* @author Christian Schaefer, Goetz Lindenmaier, Michael Beck
* @brief
*/
#ifndef FIRM_IR_IRFLAG_H
#define FIRM_IR_IRFLAG_H
#include "firm_types.h"
#include "begin.h"
/**
* @ingroup iroptimize
* @defgroup Optimization Flags
* Flags to customize the behavior of libfirm.
*
* There are the following groups of flags:
......@@ -35,14 +44,8 @@
* 3. Verbosity flags.
* a) Flags to steer the level of the information.
* b) Flags to steer in which phase information should be dumped.
* 4. Verification flag
* This one controls the behavior of node and type verifications
*@{
*/
#ifndef FIRM_IR_IRFLAG_H
#define FIRM_IR_IRFLAG_H
#include "firm_types.h"
#include "begin.h"
/**
* A container type to load/restore all optimizations
......@@ -156,6 +159,14 @@ FIRM_API void restore_optimization_state(const optimization_state_t *state);
*/
FIRM_API void all_optimizations_off(void);
/** @} */
/** @ingroup irverify
* @defgroup Flags
* Enable/Disable automatic correctness tests
* @{
*/
/**
* Possible verification modes.
*/
......@@ -175,6 +186,8 @@ typedef enum firm_verification_t {
*/
FIRM_API void do_node_verification(firm_verification_t mode);
/** @} */
#include "end.h"
#endif
......@@ -28,6 +28,12 @@
#include "firm_types.h"
#include "begin.h"
/**
* @ingroup iroptimize
* @defgroup irgopt Graph Transformations
* @{
*/
/** Applies local optimizations (see iropt.h) to all nodes reachable from node
* @p n.
*
......@@ -118,6 +124,8 @@ FIRM_API void remove_critical_cf_edges(ir_graph *irg);
FIRM_API void remove_critical_cf_edges_ex(ir_graph *irg,
int ignore_exception_edges);
/** @} */
#include "end.h"
#endif
......@@ -31,7 +31,7 @@
#include "begin.h"
/**
* @page ir_graph The struct ir_graph
* @defgroup ir_graph Procedure Graph
*
* This struct contains all information about a procedure.
* It's allocated directly to memory.
......@@ -105,6 +105,8 @@
* - visited A int used as flag to traverse the ir_graph.
*
* - block_visited A int used as a flag to traverse block nodes in the graph.
*
* @{
*/
/** Global variable holding the current ir graph.
......@@ -523,6 +525,8 @@ FIRM_API void set_irg_fp_model(ir_graph *irg, unsigned model);
*/
FIRM_API size_t register_additional_graph_data(size_t size);
/** @} */
#include "end.h"