nsz Git - libfirm/blob - include/libfirm/irdump.h

   1 /*
   2  * Copyright (C) 1995-2008 University of Karlsruhe.  All right reserved.
   3  *
   4  * This file is part of libFirm.
   5  *
   6  * This file may be distributed and/or modified under the terms of the
   7  * GNU General Public License version 2 as published by the Free Software
   8  * Foundation and appearing in the file LICENSE.GPL included in the
   9  * packaging of this file.
  10  *
  11  * Licensees holding valid libFirm Professional Edition licenses may use
  12  * this file in accordance with the libFirm Commercial License.
  13  * Agreement provided with the Software.
  14  *
  15  * This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
  16  * WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  17  * PURPOSE.
  18  */
  19
  20 /**
  21  * @file
  22  * @brief   Write vcg representation of firm to file.
  23  * @author  Martin Trapp, Christian Schaefer, Goetz Lindenmaier, Hubert Schmidt
  24  * @version $Id$
  25  * @brief
  26  *  Dump routines for the ir graph and all type information.
  27  *
  28  *  The dump format of most functions is vcg.  This is a text based graph
  29  *  representation. Some use the original format,
  30  *  but most generate an extended format that is only read by some special
  31  *  versions of xvcg or by the comercialized version now calles aiSee.
  32  *  A test version of aiSee is available at
  33  *   http://www.absint.de/aisee/download/index.htm.
  34  *
  35  *  We have developed an own advanced viewer called ycomp:
  36  *    http://www.info.uni-karlsruhe.de/software/ycomp/
  37  */
  38 #ifndef FIRM_IR_IRDUMP_H
  39 #define FIRM_IR_IRDUMP_H
  40
  41 #include <stdio.h>
  42
  43 #include "firm_types.h"
  44 #include "begin.h"
  45
  46 /** @defgroup convenience_dumper   Convenience interface for dumpers */
  47 /*@{*/
  48
  49 /**
  50  * Convenience interface for dumping a graph as vcg file.
  51  *
  52  * For details on how the filename is constructed see #dump_ir_graph_ext
  53  */
  54 FIRM_API void dump_ir_graph(ir_graph *graph, const char *suffix);
  55
  56 /**
  57  * type for dumpers that dump information about the whole program
  58  */
  59 typedef void (*ir_prog_dump_func)(FILE *out);
  60
  61 /**
  62  * Convenience interface for dumping the whole compilation-unit/program.
  63  *
  64  * The filename is constructed by combining a counter, the name of the current
  65  * ir_prog and the given @p suffix. The file-extensions is determined by looking
  66  * at @p mime_type.
  67  * The file is stored into the directory specified by #ir_set_dump_path
  68  *
  69  * @param func       Dumper. Usualle one of #dump_callgraph, #dump_type_graph,
  70  *                   #dump_class_hierarchy, #dump_types_as_text,
  71  *                   #dump_globals_as_text
  72  * @param suffix     Suffix to append to the name
  73  */
  74 FIRM_API void dump_ir_prog_ext(ir_prog_dump_func func, const char *suffix);
  75
  76 /**
  77  * type for graph dumpers
  78  */
  79 typedef void (*ir_graph_dump_func)(FILE *out, ir_graph *graph);
  80
  81 /**
  82  * Convenience interface for dumping graphs.
  83  * The filename is constructed by combining a counter, the name of the graphs
  84  * entity and the given @p suffix. The file-extensions is determined by looking
  85  * at @p mime_type.
  86  * The file is stored into the directory specified by #ir_set_dump_path
  87  *
  88  * @param func      Dumper. Usually one of #dump_cfg, #dump_loop_tree,
  89  *                  #dump_graph_to_file
  90  * @param graph     the graph to dump
  91  * @param suffix    suffix
  92  */
  93 FIRM_API void dump_ir_graph_ext(ir_graph_dump_func func, ir_graph *graph,
  94                                 const char *suffix);
  95
  96 /**
  97  * A walker that calls a dumper for each graph in the program
  98  *
  99  * @param suffix        A suffix for the file name.
 100  */
 101 FIRM_API void dump_all_ir_graphs(const char *suffix);
 102
 103 /**
 104  * Specifies output path for the dump_ir_graph function
 105  */
 106 FIRM_API void ir_set_dump_path(const char *path);
 107
 108 /**
 109  * Set a prefix filter for output functions.
 110  *
 111  * All graph dumpers check this name.  If the name is != "" and
 112  * not a prefix of the graph to be dumped, the dumper does not
 113  * dump the graph.
 114  *
 115  * @param name The prefix of the name of the method entity to be dumped.
 116  */
 117 FIRM_API void ir_set_dump_filter(const char *name);
 118
 119 /** Returns the prefix filter set with #ir_set_dump_filter */
 120 FIRM_API const char *ir_get_dump_filter(void);
 121
 122 /** Returns true if dump file filter is not set, or if it is a prefix of name */
 123 FIRM_API int ir_should_dump(const char *name);
 124
 125 /**
 126  * Creates an ir_prog pass for dump_all_ir_graphs().
 127  *
 128  * @param name          the name of this pass or NULL
 129  * @param dump_graph    The dumper to be used for dumping.
 130  * @param suffix        A suffix for the file name.
 131  *
 132  * @return  the newly created ir_prog pass
 133  */
 134 FIRM_API ir_prog_pass_t *dump_all_ir_graph_pass(const char *name,
 135                                                 const char *suffix);
 136
 137 /*@}*/
 138
 139 /**
 140  * @defgroup dumper     Dump information to file
 141  * This is the low-level interface for dumping information as text files
 142  * and xvcg graphs.
 143  * Normally you should use the convenience interface @ref convenience_dumper
 144  * instead of the functions in this group.
 145  */
 146 /*@{*/
 147
 148 /**
 149  * Dumps all Firm nodes of a single graph for a single procedure in
 150  * standard xvcg format.
 151  *
 152  * @param graph  The firm graph to be dumped.
 153  * @param out    Output stream the graph is written to
 154  */
 155 FIRM_API void dump_ir_graph_file(FILE *out, ir_graph *graph);
 156
 157 /**
 158  * Dump the control flow graph of a procedure.
 159  *
 160  * @param graph   The firm graph whose CFG shall be dumped.
 161  * @param out     Output stream the CFG is written to
 162  *
 163  * Dumps the control flow graph of a procedure in standard xvcg format.
 164  */
 165 FIRM_API void dump_cfg(FILE *out, ir_graph *graph);
 166
 167 /**
 168  * Dump the call graph.
 169  *
 170  * @param out    Output stream the callgraph is written to
 171  */
 172 FIRM_API void dump_callgraph(FILE *out);
 173
 174 /**
 175  * Dumps all type information.
 176  *
 177  * @param out     Output stream the typegraph is written to
 178  *
 179  * Dumps all type information that is somehow reachable in standard vcg
 180  * format.
 181  */
 182 FIRM_API void dump_typegraph(FILE *out);
 183
 184 /**
 185  * Dumps the class hierarchy with or without entities.
 186  *
 187  * @param out         Output stream
 188  * @param entities    Flag whether to dump the entities.
 189  *
 190  * Does not dump the global type.
 191  * Dumps a node for all classes and the sub/supertype relations.  If
 192  * entities is set to true also dumps the entities of classes, but without
 193  * any additional information as the entities type.  The overwrites relation
 194  * is dumped along with the entities.
 195  */
 196 FIRM_API void dump_class_hierarchy(FILE *out);
 197
 198 /**
 199  * Dump a standalone loop tree, which contains the loop nodes and the firm nodes
 200  * belonging to one loop packed together in one subgraph.
 201  *
 202  * @param out     Output stream
 203  * @param graph   Dump the loop tree for this graph.
 204  */
 205 FIRM_API void dump_loop_tree(FILE *out, ir_graph *graph);
 206
 207 /**
 208  * Dumps the loop tree over the call graph.
 209  *
 210  * @param out   Output stream
 211  */
 212 FIRM_API void dump_callgraph_loop_tree(FILE *out);
 213
 214 /**
 215  * Dump type information as text.
 216  *
 217  * Often type graphs are unhandy in their vcg representation.  The text dumper
 218  * represents the information for a single type more compact, but the relations
 219  * between the types only implicitly. Dumps only 'real' types, i.e., those in
 220  * the type list.  Does not dump the global type nor frame types or the like.
 221  */
 222 FIRM_API void dump_types_as_text(FILE *out);
 223
 224 /**
 225  * Dumps all global variables as text.
 226  *
 227  * @param out         Output stream
 228  * @param verbosity   verbosity flag
 229  *
 230  * Dumps a text representation of the entities in the global type.
 231  */
 232 FIRM_API void dump_globals_as_text(FILE *out);
 233
 234 /**
 235  * Dumps the firm nodes in the sub-loop-tree of loop to a vcg file.
 236  *
 237  * @param out     Output stream
 238  * @param l       Dump the loop tree for this loop.
 239  */
 240 FIRM_API void dump_loop(FILE *out, ir_loop *loop);
 241
 242 /** Write the irnode and all its attributes to the file passed. */
 243 FIRM_API void dump_irnode_to_file(FILE *out, ir_node *node);
 244
 245 /** Write the graph and all its attributes to the file passed.
 246  *  Does not write the nodes. */
 247 FIRM_API void dump_graph_as_text(FILE *out, ir_graph *graph);
 248
 249 /** Write the entity and all its attributes to the passed file. */
 250 FIRM_API void dump_entity_to_file(FILE *out, ir_entity *entity);
 251
 252 /** Write the type and all its attributes to the file passed. */
 253 FIRM_API void dump_type_to_file(FILE *out, ir_type *type);
 254
 255 /** Verbosity for text dumpers */
 256 typedef enum {
 257         dump_verbosity_onlynames         = 0x00000001,   /**< Only dump names. Turns off all other
 258                                                               flags up to 0x00010000. */
 259         dump_verbosity_fields            = 0x00000002,   /**< Dump types and fields (like a type declaration). */
 260         dump_verbosity_methods           = 0x00000004,   /**< Dump types and methods (like a type declaration). */
 261         dump_verbosity_nostatic          = 0x00000040,   /**< Dump types and dynamic allocated fields (like a
 262                                                               type declaration). This excludes methods and
 263                                                               static, polymorphic fields. */
 264         dump_verbosity_typeattrs         = 0x00000008,   /**< Dump all type attributes. */
 265         dump_verbosity_entattrs          = 0x00000010,   /**< Dump all entity attributes. */
 266         dump_verbosity_entconsts         = 0x00000020,   /**< Dump entity constants. */
 267
 268         dump_verbosity_accessStats       = 0x00000100,   /**< Dump entity access statistics. */
 269
 270         dump_verbosity_noClassTypes      = 0x00001000,   /**< Dump no class       types. */
 271         dump_verbosity_noStructTypes     = 0x00002000,   /**< Dump no struct      types. */
 272         dump_verbosity_noUnionTypes      = 0x00004000,   /**< Dump no union       types. */
 273         dump_verbosity_noArrayTypes      = 0x00008000,   /**< Dump no array       types. */
 274         dump_verbosity_noPointerTypes    = 0x00010000,   /**< Dump no pointer     types. */
 275         dump_verbosity_noMethodTypes     = 0x00020000,   /**< Dump no method      types. */
 276         dump_verbosity_noPrimitiveTypes  = 0x00040000,   /**< Dump no primitive   types .*/
 277         dump_verbosity_noEnumerationTypes= 0x00080000,   /**< Dump no enumeration types. */
 278
 279         dump_verbosity_onlyClassTypes     = 0x000FE000,  /**< Dump only class     types. */
 280         dump_verbosity_onlyStructTypes    = 0x000FD000,  /**< Dump only struct    types. */
 281         dump_verbosity_onlyUnionTypes     = 0x000FB000,  /**< Dump only union     types. */
 282         dump_verbosity_onlyArrayTypes     = 0x000F7000,  /**< Dump only array     types. */
 283         dump_verbosity_onlyPointerTypes   = 0x000EF000,  /**< Dump only pointer   types. */
 284         dump_verbosity_onlyMethodTypes    = 0x000DF000,  /**< Dump only method    types. */
 285         dump_verbosity_onlyPrimitiveTypes = 0x000BF000,  /**< Dump only primitive types. */
 286         dump_verbosity_onlyEnumerationTypes=0x0007F000,  /**< Dump only enumeration types. */
 287
 288         dump_verbosity_max                = 0x4FF00FBE   /**< Turn everything on */
 289 } ir_dump_verbosity_t;
 290
 291 /** override currently set text dump flags with new ones */
 292 FIRM_API void ir_set_dump_verbosity(ir_dump_verbosity_t verbosity);
 293 /** return currently set text dump flags */
 294 FIRM_API ir_dump_verbosity_t ir_get_dump_verbosity(void);
 295
 296 /**
 297  * A bitset indicating various options that affect what information is dumped
 298  * and how exactly it is dumped. This affects the dumpers that produce vcg
 299  * graphs.
 300  */
 301 typedef enum {
 302         /** dump basic blocks as subgraphs which contain the nodes in the block */
 303         ir_dump_flag_blocks_as_subgraphs   = 1U << 0,
 304         /** display blocks in extended basic grouped inside a subgraph */
 305         ir_dump_flag_group_extbb           = 1U << 1,
 306         /** dump (parts of) typegraph along with nodes */
 307         ir_dump_flag_with_typegraph        = 1U << 2,
 308         /** Sets the vcg flag "display_edge_labels" to no.
 309          * This is necessary as xvcg and aisee both fail to display graphs
 310          * with self-edges if these edges have labels. */
 311         ir_dump_flag_disable_edge_labels   = 1U << 3,
 312         /** If set constants will be replicated for every use. In non blocked view
 313          * edges from constant to block are skipped.  Vcg then layouts the graphs
 314          * more compact, this makes them better readable. */
 315         ir_dump_flag_consts_local          = 1U << 4,
 316         /** if set node idx will be added to node labels */
 317         ir_dump_flag_idx_label             = 1U << 5,
 318         /** if set node number will be added to node labels */
 319         ir_dump_flag_number_label          = 1U << 6,
 320         /** show keepalive edges from the end node */
 321         ir_dump_flag_keepalive_edges       = 1U << 7,
 322         /** dump out edges */
 323         ir_dump_flag_out_edges             = 1U << 8,
 324         /** if set dumps edges from blocks to their immediate dominator */
 325         ir_dump_flag_dominance             = 1U << 9,
 326         /** If set the dumper dumps loop nodes and edges from these nodes to the
 327          * contained ir nodes. */
 328         ir_dump_flag_loops                 = 1U << 10,
 329         /** if set (and backedge info is computed) dump backedges */
 330         ir_dump_flag_back_edges            = 1U << 11,
 331         /** dump type info from ana/irtypeinfo.h in the node labels */
 332         ir_dump_flag_analysed_types        = 1U << 12,
 333         /** dump backedges from iredges.h */
 334         ir_dump_flag_iredges               = 1U << 13,
 335         /** write node addresses into the vcg info */
 336         ir_dump_flag_node_addresses        = 1U << 14,
 337         /** dump all anchor nodes, even the unused ones */
 338         ir_dump_flag_all_anchors           = 1U << 15,
 339         /** dumps macroblock edges from every block to its macroblock */
 340         ir_dump_flag_macroblock_edges      = 1U << 16,
 341         /** dumps marked blocks with an asterisk in the label */
 342         ir_dump_flag_show_marks            = 1U << 17,
 343
 344         /** turns of dumping of constant entity values in typegraphs */
 345         ir_dump_flag_no_entity_values      = 1U << 20,
 346         /** dumps ld_names of entities instead of their names */
 347         ir_dump_flag_ld_names              = 1U << 21,
 348         /** dump entities in class hierarchies */
 349         ir_dump_flag_entities_in_hierarchy = 1U << 22,
 350 } ir_dump_flags_t;
 351
 352 /** override currently set dump flags with new ones */
 353 FIRM_API void ir_set_dump_flags(ir_dump_flags_t flags);
 354 /** add flags to the currently set dump flags */
 355 FIRM_API void ir_add_dump_flags(ir_dump_flags_t flags);
 356 /** disable certain dump flags */
 357 FIRM_API void ir_remove_dump_flags(ir_dump_flags_t flags);
 358 /** return currently set dump flags */
 359 FIRM_API ir_dump_flags_t ir_get_dump_flags(void);
 360
 361 /**
 362  * This hook is called to dump the vcg attributes of a node to a file.
 363  * If this function returns zero, the default attributes are added, else
 364  * removed.
 365  */
 366 typedef int (*dump_node_vcgattr_func)(FILE *out, ir_node *node, ir_node *local);
 367
 368 /**
 369  * This hook is called to dump the vcg attributes of an edge to a file.
 370  * If this function returns zero, the default attributes are added, else
 371  * removed.
 372  */
 373 typedef int (*dump_edge_vcgattr_func)(FILE *out, ir_node *node, int to);
 374
 375 typedef void (*dump_node_edge_func)(FILE *out, ir_node *node);
 376
 377 /** Set the node_vcgattr hook. */
 378 FIRM_API void set_dump_node_vcgattr_hook(dump_node_vcgattr_func hook);
 379 /** Set the edge_vcgattr hook. */
 380 FIRM_API void set_dump_edge_vcgattr_hook(dump_edge_vcgattr_func hook);
 381
 382 /**
 383  * Set the hook to be called to dump additional edges to a node.
 384  * @param func The hook to be called.
 385  */
 386 FIRM_API void set_dump_node_edge_hook(dump_node_edge_func func);
 387
 388 /**
 389  * Get the additional edge dump hook.
 390  * @return The current additional edge dump hook.]
 391  */
 392 FIRM_API dump_node_edge_func get_dump_node_edge_hook(void);
 393
 394 /**
 395  * Set the hook to be called to dump additional edges to a block.
 396  * @param func The hook to be called.
 397  */
 398 FIRM_API void set_dump_block_edge_hook(dump_node_edge_func func);
 399
 400 /**
 401  * Get the additional block edge dump hook.
 402  * @return The current additional block edge dump hook.
 403  */
 404 FIRM_API dump_node_edge_func get_dump_block_edge_hook(void);
 405
 406 /** A node info dumper callback. */
 407 typedef void (dump_node_info_cb_t)(void *data, FILE *out, const ir_node *n);
 408
 409 /**
 410  * Adds a new node info dumper callback. It is possible to add an unlimited
 411  * number of callbacks. The callbacks are called at the end of the default
 412  * info dumper.
 413  *
 414  * @param cb    the callback function to be called
 415  * @param data  a context parameter
 416  *
 417  * @return A callback handle.
 418  *
 419  * @note This functionality is only available, if Firm hooks are enabled.
 420  */
 421 FIRM_API void *dump_add_node_info_callback(dump_node_info_cb_t *cb, void *data);
 422
 423 /**
 424  * Remove a previously added info dumper callback.
 425  *
 426  * @param handle  the callback handle returned from
 427  *                dump_add_node_info_callback()
 428  */
 429 FIRM_API void dump_remove_node_info_callback(void *handle);
 430
 431 /*@}*/
 432
 433 #include "end.h"
 434
 435 #endif