2 * Copyright (C) 1995-2008 University of Karlsruhe. All right reserved.
4 * This file is part of libFirm.
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.
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.
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
22 * @brief Write vcg representation of firm to file.
23 * @author Martin Trapp, Christian Schaefer, Goetz Lindenmaier, Hubert Schmidt
26 * Dump routines for the ir graph and all type information.
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.
35 * We have developed an own advanced viewer called ycomp:
36 * http://www.info.uni-karlsruhe.de/software/ycomp/
38 #ifndef FIRM_IR_IRDUMP_H
39 #define FIRM_IR_IRDUMP_H
43 #include "firm_types.h"
46 /** @defgroup convenience_dumper Convenience interface for dumpers */
50 * Convenience interface for dumping a graph as vcg file.
52 * For details on how the filename is constructed see #dump_ir_graph_ext
54 FIRM_API void dump_ir_graph(ir_graph *graph, const char *suffix);
57 * type for dumpers that dump information about the whole program
59 typedef void (*ir_prog_dump_func)(FILE *out);
62 * Convenience interface for dumping the whole compilation-unit/program.
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
67 * The file is stored into the directory specified by #ir_set_dump_path
69 * @param func Dumper. Usually one of #dump_callgraph, #dump_typegraph,
70 * #dump_class_hierarchy, #dump_types_as_text,
71 * #dump_globals_as_text
72 * @param suffix Suffix to append to the name
74 FIRM_API void dump_ir_prog_ext(ir_prog_dump_func func, const char *suffix);
77 * type for graph dumpers
79 typedef void (*ir_graph_dump_func)(FILE *out, ir_graph *graph);
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
86 * The file is stored into the directory specified by #ir_set_dump_path
88 * @param func Dumper. Usually one of #dump_cfg, #dump_loop_tree,
90 * @param graph the graph to dump
91 * @param suffix suffix
93 FIRM_API void dump_ir_graph_ext(ir_graph_dump_func func, ir_graph *graph,
97 * A walker that calls a dumper for each graph in the program
99 * @param suffix A suffix for the file name.
101 FIRM_API void dump_all_ir_graphs(const char *suffix);
104 * Specifies output path for the dump_ir_graph function
106 FIRM_API void ir_set_dump_path(const char *path);
109 * Set a prefix filter for output functions.
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
115 * @param name The prefix of the name of the method entity to be dumped.
117 FIRM_API void ir_set_dump_filter(const char *name);
119 /** Returns the prefix filter set with #ir_set_dump_filter */
120 FIRM_API const char *ir_get_dump_filter(void);
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);
126 * Creates an ir_prog pass for dump_all_ir_graphs().
128 * @param name the name of this pass or NULL
129 * @param suffix A suffix for the file name.
131 * @return the newly created ir_prog pass
133 FIRM_API ir_prog_pass_t *dump_all_ir_graph_pass(const char *name,
139 * @defgroup dumper Dump information to file
140 * This is the low-level interface for dumping information as text files
142 * Normally you should use the convenience interface @ref convenience_dumper
143 * instead of the functions in this group.
148 * Dumps all Firm nodes of a single graph for a single procedure in
149 * standard xvcg format.
151 * @param graph The firm graph to be dumped.
152 * @param out Output stream the graph is written to
154 FIRM_API void dump_ir_graph_file(FILE *out, ir_graph *graph);
157 * Dump the control flow graph of a procedure.
159 * @param graph The firm graph whose CFG shall be dumped.
160 * @param out Output stream the CFG is written to
162 * Dumps the control flow graph of a procedure in standard xvcg format.
164 FIRM_API void dump_cfg(FILE *out, ir_graph *graph);
167 * Dump the call graph.
169 * @param out Output stream the callgraph is written to
171 FIRM_API void dump_callgraph(FILE *out);
174 * Dumps all type information.
176 * @param out Output stream the typegraph is written to
178 * Dumps all type information that is somehow reachable in standard vcg
181 FIRM_API void dump_typegraph(FILE *out);
184 * Dumps the class hierarchy with or without entities.
186 * @param out Output stream
188 * Does not dump the global type.
189 * Dumps a node for all classes and the sub/supertype relations. If
190 * entities is set to true also dumps the entities of classes, but without
191 * any additional information as the entities type. The overwrites relation
192 * is dumped along with the entities.
194 FIRM_API void dump_class_hierarchy(FILE *out);
197 * Dump a standalone loop tree, which contains the loop nodes and the firm nodes
198 * belonging to one loop packed together in one subgraph.
200 * @param out Output stream
201 * @param graph Dump the loop tree for this graph.
203 FIRM_API void dump_loop_tree(FILE *out, ir_graph *graph);
206 * Dumps the loop tree over the call graph.
208 * @param out Output stream
210 FIRM_API void dump_callgraph_loop_tree(FILE *out);
213 * Dump type information as text.
215 * Often type graphs are unhandy in their vcg representation. The text dumper
216 * represents the information for a single type more compact, but the relations
217 * between the types only implicitly. Dumps only 'real' types, i.e., those in
218 * the type list. Does not dump the global type nor frame types or the like.
220 FIRM_API void dump_types_as_text(FILE *out);
223 * Dumps all global variables as text.
225 * @param out Output stream
227 * Dumps a text representation of the entities in the global type.
229 FIRM_API void dump_globals_as_text(FILE *out);
232 * Dumps the firm nodes in the sub-loop-tree of loop to a vcg file.
234 * @param out Output stream
235 * @param loop Dump the loop tree for this loop.
237 FIRM_API void dump_loop(FILE *out, ir_loop *loop);
239 /** Write the irnode and all its attributes to the file passed. */
240 FIRM_API void dump_irnode_to_file(FILE *out, ir_node *node);
242 /** Write the graph and all its attributes to the file passed.
243 * Does not write the nodes. */
244 FIRM_API void dump_graph_as_text(FILE *out, ir_graph *graph);
246 /** Write the entity and all its attributes to the passed file. */
247 FIRM_API void dump_entity_to_file(FILE *out, ir_entity *entity);
249 /** Write the type and all its attributes to the file passed. */
250 FIRM_API void dump_type_to_file(FILE *out, ir_type *type);
252 /** Verbosity for text dumpers */
254 dump_verbosity_onlynames = 0x00000001, /**< Only dump names. Turns off all other
255 flags up to 0x00010000. */
256 dump_verbosity_fields = 0x00000002, /**< Dump types and fields (like a type declaration). */
257 dump_verbosity_methods = 0x00000004, /**< Dump types and methods (like a type declaration). */
258 dump_verbosity_nostatic = 0x00000040, /**< Dump types and dynamic allocated fields (like a
259 type declaration). This excludes methods and
260 static, polymorphic fields. */
261 dump_verbosity_typeattrs = 0x00000008, /**< Dump all type attributes. */
262 dump_verbosity_entattrs = 0x00000010, /**< Dump all entity attributes. */
263 dump_verbosity_entconsts = 0x00000020, /**< Dump entity constants. */
265 dump_verbosity_accessStats = 0x00000100, /**< Dump entity access statistics. */
267 dump_verbosity_noClassTypes = 0x00001000, /**< Dump no class types. */
268 dump_verbosity_noStructTypes = 0x00002000, /**< Dump no struct types. */
269 dump_verbosity_noUnionTypes = 0x00004000, /**< Dump no union types. */
270 dump_verbosity_noArrayTypes = 0x00008000, /**< Dump no array types. */
271 dump_verbosity_noPointerTypes = 0x00010000, /**< Dump no pointer types. */
272 dump_verbosity_noMethodTypes = 0x00020000, /**< Dump no method types. */
273 dump_verbosity_noPrimitiveTypes = 0x00040000, /**< Dump no primitive types .*/
274 dump_verbosity_noEnumerationTypes= 0x00080000, /**< Dump no enumeration types. */
276 dump_verbosity_onlyClassTypes = 0x000FE000, /**< Dump only class types. */
277 dump_verbosity_onlyStructTypes = 0x000FD000, /**< Dump only struct types. */
278 dump_verbosity_onlyUnionTypes = 0x000FB000, /**< Dump only union types. */
279 dump_verbosity_onlyArrayTypes = 0x000F7000, /**< Dump only array types. */
280 dump_verbosity_onlyPointerTypes = 0x000EF000, /**< Dump only pointer types. */
281 dump_verbosity_onlyMethodTypes = 0x000DF000, /**< Dump only method types. */
282 dump_verbosity_onlyPrimitiveTypes = 0x000BF000, /**< Dump only primitive types. */
283 dump_verbosity_onlyEnumerationTypes=0x0007F000, /**< Dump only enumeration types. */
285 dump_verbosity_max = 0x4FF00FBE /**< Turn everything on */
286 } ir_dump_verbosity_t;
287 ENUM_BITSET(ir_dump_verbosity_t)
289 /** override currently set text dump flags with new ones */
290 FIRM_API void ir_set_dump_verbosity(ir_dump_verbosity_t verbosity);
291 /** return currently set text dump flags */
292 FIRM_API ir_dump_verbosity_t ir_get_dump_verbosity(void);
295 * A bitset indicating various options that affect what information is dumped
296 * and how exactly it is dumped. This affects the dumpers that produce vcg
300 /** dump basic blocks as subgraphs which contain the nodes in the block */
301 ir_dump_flag_blocks_as_subgraphs = 1U << 0,
302 /** display blocks in extended basic grouped inside a subgraph */
303 ir_dump_flag_group_extbb = 1U << 1,
304 /** dump (parts of) typegraph along with nodes */
305 ir_dump_flag_with_typegraph = 1U << 2,
306 /** Sets the vcg flag "display_edge_labels" to no.
307 * This is necessary as xvcg and aisee both fail to display graphs
308 * with self-edges if these edges have labels. */
309 ir_dump_flag_disable_edge_labels = 1U << 3,
310 /** If set constants will be replicated for every use. In non blocked view
311 * edges from constant to block are skipped. Vcg then layouts the graphs
312 * more compact, this makes them better readable. */
313 ir_dump_flag_consts_local = 1U << 4,
314 /** if set node idx will be added to node labels */
315 ir_dump_flag_idx_label = 1U << 5,
316 /** if set node number will be added to node labels */
317 ir_dump_flag_number_label = 1U << 6,
318 /** show keepalive edges from the end node */
319 ir_dump_flag_keepalive_edges = 1U << 7,
320 /** dump out edges */
321 ir_dump_flag_out_edges = 1U << 8,
322 /** if set dumps edges from blocks to their immediate dominator */
323 ir_dump_flag_dominance = 1U << 9,
324 /** If set the dumper dumps loop nodes and edges from these nodes to the
325 * contained ir nodes. */
326 ir_dump_flag_loops = 1U << 10,
327 /** if set (and backedge info is computed) dump backedges */
328 ir_dump_flag_back_edges = 1U << 11,
329 /** dump type info from ana/irtypeinfo.h in the node labels */
330 ir_dump_flag_analysed_types = 1U << 12,
331 /** dump backedges from iredges.h */
332 ir_dump_flag_iredges = 1U << 13,
333 /** write node addresses into the vcg info */
334 ir_dump_flag_node_addresses = 1U << 14,
335 /** dump all anchor nodes, even the unused ones */
336 ir_dump_flag_all_anchors = 1U << 15,
337 /** dumps marked blocks with an asterisk in the label */
338 ir_dump_flag_show_marks = 1U << 16,
340 /** turns of dumping of constant entity values in typegraphs */
341 ir_dump_flag_no_entity_values = 1U << 20,
342 /** dumps ld_names of entities instead of their names */
343 ir_dump_flag_ld_names = 1U << 21,
344 /** dump entities in class hierarchies */
345 ir_dump_flag_entities_in_hierarchy = 1U << 22,
347 ENUM_BITSET(ir_dump_flags_t)
349 /** override currently set dump flags with new ones */
350 FIRM_API void ir_set_dump_flags(ir_dump_flags_t flags);
351 /** add flags to the currently set dump flags */
352 FIRM_API void ir_add_dump_flags(ir_dump_flags_t flags);
353 /** disable certain dump flags */
354 FIRM_API void ir_remove_dump_flags(ir_dump_flags_t flags);
355 /** return currently set dump flags */
356 FIRM_API ir_dump_flags_t ir_get_dump_flags(void);
359 * This hook is called to dump the vcg attributes of a node to a file.
360 * If this function returns zero, the default attributes are added, else
363 typedef int (*dump_node_vcgattr_func)(FILE *out, ir_node *node, ir_node *local);
366 * This hook is called to dump the vcg attributes of an edge to a file.
367 * If this function returns zero, the default attributes are added, else
370 typedef int (*dump_edge_vcgattr_func)(FILE *out, ir_node *node, int to);
372 typedef void (*dump_node_edge_func)(FILE *out, ir_node *node);
374 /** Set the node_vcgattr hook. */
375 FIRM_API void set_dump_node_vcgattr_hook(dump_node_vcgattr_func hook);
376 /** Set the edge_vcgattr hook. */
377 FIRM_API void set_dump_edge_vcgattr_hook(dump_edge_vcgattr_func hook);
380 * Set the hook to be called to dump additional edges to a node.
381 * @param func The hook to be called.
383 FIRM_API void set_dump_node_edge_hook(dump_node_edge_func func);
386 * Get the additional edge dump hook.
387 * @return The current additional edge dump hook.]
389 FIRM_API dump_node_edge_func get_dump_node_edge_hook(void);
392 * Set the hook to be called to dump additional edges to a block.
393 * @param func The hook to be called.
395 FIRM_API void set_dump_block_edge_hook(dump_node_edge_func func);
398 * Get the additional block edge dump hook.
399 * @return The current additional block edge dump hook.
401 FIRM_API dump_node_edge_func get_dump_block_edge_hook(void);
403 /** A node info dumper callback. */
404 typedef void (dump_node_info_cb_t)(void *data, FILE *out, const ir_node *n);
407 * Adds a new node info dumper callback. It is possible to add an unlimited
408 * number of callbacks. The callbacks are called at the end of the default
411 * @param cb the callback function to be called
412 * @param data a context parameter
414 * @return A callback handle.
416 * @note This functionality is only available, if Firm hooks are enabled.
418 FIRM_API void *dump_add_node_info_callback(dump_node_info_cb_t *cb, void *data);
421 * Remove a previously added info dumper callback.
423 * @param handle the callback handle returned from
424 * dump_add_node_info_callback()
426 FIRM_API void dump_remove_node_info_callback(void *handle);