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