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

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