irdump.h 12.7 KB
Newer Older
Christian Würdig's avatar
Christian Würdig committed
1
2
/*
 * This file is part of libFirm.
3
 * Copyright (C) 2012 University of Karlsruhe.
Christian Würdig's avatar
Christian Würdig committed
4
5
 */

6
/**
Matthias Braun's avatar
Matthias Braun committed
7
8
9
 * @file
 * @brief   Write vcg representation of firm to file.
 * @author  Martin Trapp, Christian Schaefer, Goetz Lindenmaier, Hubert Schmidt
Matthias Braun's avatar
Matthias Braun committed
10
 * @brief   Dump routines for the ir graph and all type information.
Michael Beck's avatar
Michael Beck committed
11
 *
12
 */
Matthias Braun's avatar
Matthias Braun committed
13
14
#ifndef FIRM_IR_IRDUMP_H
#define FIRM_IR_IRDUMP_H
15

16
17
18
#include <stdio.h>

#include "firm_types.h"
19
#include "begin.h"
Christian Schäfer's avatar
Christian Schäfer committed
20

21
22
23
/**
 * @ingroup printing
 * @defgroup ir_dump Visualisation
Matthias Braun's avatar
Matthias Braun committed
24
25
26
27
 *
 * 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
Christoph Mallon's avatar
Christoph Mallon committed
28
 * special versions of xvcg.
Matthias Braun's avatar
Matthias Braun committed
29
30
31
32
33
34
35
36
37
 *
 * We have developed an own advanced viewer called ycomp:
 *   http://www.info.uni-karlsruhe.de/software/ycomp/
 *@{
 */

/** @defgroup convenience Convenience Interface
 * @{
 */
Christian Schäfer's avatar
Christian Schäfer committed
38

39
/**
40
41
42
 * Convenience interface for dumping a graph as vcg file.
 *
 * For details on how the filename is constructed see #dump_ir_graph_ext
43
 */
44
FIRM_API void dump_ir_graph(ir_graph *graph, const char *suffix);
45

46
/**
47
 * type for dumpers that dump information about the whole program
48
 */
49
typedef void (*ir_prog_dump_func)(FILE *out);
50
51

/**
52
 * Convenience interface for dumping the whole compilation-unit/program.
53
 *
54
55
56
57
 * The filename is constructed by combining a counter, the name of the current
 * ir_prog and the given @p suffix. The file-extensions is determined by looking
 * at @p mime_type.
 * The file is stored into the directory specified by #ir_set_dump_path
58
 *
Michael Beck's avatar
Michael Beck committed
59
 * @param func       Dumper. Usually one of #dump_callgraph, #dump_typegraph,
60
61
62
 *                   #dump_class_hierarchy, #dump_types_as_text,
 *                   #dump_globals_as_text
 * @param suffix     Suffix to append to the name
63
 */
64
FIRM_API void dump_ir_prog_ext(ir_prog_dump_func func, const char *suffix);
65
66

/**
67
 * type for graph dumpers
68
 */
69
typedef void (*ir_graph_dump_func)(FILE *out, ir_graph *graph);
70
71

/**
72
73
74
75
76
 * Convenience interface for dumping graphs.
 * The filename is constructed by combining a counter, the name of the graphs
 * entity and the given @p suffix. The file-extensions is determined by looking
 * at @p mime_type.
 * The file is stored into the directory specified by #ir_set_dump_path
Michael Beck's avatar
Michael Beck committed
77
 *
78
 * @param func      Dumper. Usually one of #dump_cfg, #dump_loop_tree,
Matthias Braun's avatar
Matthias Braun committed
79
 *                  #dump_ir_graph_file
80
81
 * @param graph     the graph to dump
 * @param suffix    suffix
82
 */
83
84
FIRM_API void dump_ir_graph_ext(ir_graph_dump_func func, ir_graph *graph,
                                const char *suffix);
85
86

/**
87
 * A walker that calls a dumper for each graph in the program
88
 *
89
 * @param suffix        A suffix for the file name.
90
 */
91
FIRM_API void dump_all_ir_graphs(const char *suffix);
92

93
/**
94
 * Specifies output path for the dump_ir_graph function
95
 */
96
FIRM_API void ir_set_dump_path(const char *path);
97

Michael Beck's avatar
Michael Beck committed
98
/**
99
 * Sets a prefix filter for output functions.
100
 *
101
102
103
 * All graph dumpers check this name.  If the name is != "" and
 * not a prefix of the graph to be dumped, the dumper does not
 * dump the graph.
104
 *
105
 * @param name The prefix of the name of the method entity to be dumped.
106
 */
107
108
109
110
111
112
FIRM_API void ir_set_dump_filter(const char *name);

/** Returns the prefix filter set with #ir_set_dump_filter */
FIRM_API const char *ir_get_dump_filter(void);

/*@}*/
Christian Schäfer's avatar
Christian Schäfer committed
113

Michael Beck's avatar
Michael Beck committed
114
/**
115
116
 * Dumps all Firm nodes of a single graph for a single procedure in
 * standard xvcg format.
117
 *
118
119
 * @param graph  The firm graph to be dumped.
 * @param out    Output stream the graph is written to
120
 */
121
FIRM_API void dump_ir_graph_file(FILE *out, ir_graph *graph);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
122

123
124
/**
 * Dump the control flow graph of a procedure.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
125
 *
126
127
 * @param graph   The firm graph whose CFG shall be dumped.
 * @param out     Output stream the CFG is written to
Michael Beck's avatar
Michael Beck committed
128
 *
129
 * Dumps the control flow graph of a procedure in standard xvcg format.
130
 */
131
FIRM_API void dump_cfg(FILE *out, ir_graph *graph);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
132

Sebastian Felis's avatar
Sebastian Felis committed
133
/**
134
 * Dump the call graph.
135
 *
136
 * @param out    Output stream the callgraph is written to
137
 */
138
FIRM_API void dump_callgraph(FILE *out);
Christian Schäfer's avatar
Christian Schäfer committed
139

Michael Beck's avatar
Michael Beck committed
140
141
/**
 * Dumps all type information.
142
 *
143
 * @param out     Output stream the typegraph is written to
144
 *
Michael Beck's avatar
Michael Beck committed
145
146
 * Dumps all type information that is somehow reachable in standard vcg
 * format.
147
 */
148
FIRM_API void dump_typegraph(FILE *out);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
149

Michael Beck's avatar
Michael Beck committed
150
151
/**
 * Dumps the class hierarchy with or without entities.
152
 *
153
 * @param out         Output stream
154
 *
Michael Beck's avatar
Michael Beck committed
155
156
157
158
159
 * Does not dump the global type.
 * Dumps a node for all classes and the sub/supertype relations.  If
 * entities is set to true also dumps the entities of classes, but without
 * any additional information as the entities type.  The overwrites relation
 * is dumped along with the entities.
160
 */
161
FIRM_API void dump_class_hierarchy(FILE *out);
162
163
164

/**
 * Dump a standalone loop tree, which contains the loop nodes and the firm nodes
165
 * belonging to one loop packed together in one subgraph.
166
 *
167
168
 * @param out     Output stream
 * @param graph   Dump the loop tree for this graph.
169
 */
170
FIRM_API void dump_loop_tree(FILE *out, ir_graph *graph);
171

172
173
/**
 * Dumps the loop tree over the call graph.
174
 *
175
176
177
178
179
180
 * @param out   Output stream
 */
FIRM_API void dump_callgraph_loop_tree(FILE *out);

/**
 * Dump type information as text.
181
 *
182
183
184
185
 * Often type graphs are unhandy in their vcg representation.  The text dumper
 * represents the information for a single type more compact, but the relations
 * between the types only implicitly. Dumps only 'real' types, i.e., those in
 * the type list.  Does not dump the global type nor frame types or the like.
186
 */
187
FIRM_API void dump_types_as_text(FILE *out);
188

189
190
/**
 * Dumps all global variables as text.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
191
 *
192
 * @param out         Output stream
193
 *
194
 * Dumps a text representation of the entities in the global type.
Götz Lindenmaier's avatar
Götz Lindenmaier committed
195
 */
196
FIRM_API void dump_globals_as_text(FILE *out);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
197

198
199
200
201
/**
 * Dumps the firm nodes in the sub-loop-tree of loop to a vcg file.
 *
 * @param out     Output stream
Matthias Braun's avatar
Matthias Braun committed
202
 * @param loop    Dump the loop tree for this loop.
203
204
 */
FIRM_API void dump_loop(FILE *out, ir_loop *loop);
205
206

/** Write the graph and all its attributes to the file passed.
207
 *  Does not write the nodes. */
Matthias Braun's avatar
Matthias Braun committed
208
FIRM_API void dump_graph_as_text(FILE *out, const ir_graph *graph);
209

210
/** Write the entity and all its attributes to the passed file. */
Matthias Braun's avatar
Matthias Braun committed
211
FIRM_API void dump_entity_to_file(FILE *out, const ir_entity *entity);
212

213
/** Write the type and all its attributes to the file passed. */
Matthias Braun's avatar
Matthias Braun committed
214
FIRM_API void dump_type_to_file(FILE *out, const ir_type *type);
215

Götz Lindenmaier's avatar
Götz Lindenmaier committed
216
217
/** Verbosity for text dumpers */
typedef enum {
218
219
220
221
222
223
224
225
226
227
228
229
230
	dump_verbosity_onlynames         = 0x00000001,   /**< Only dump names. Turns off all other
	                                                      flags up to 0x00010000. */
	dump_verbosity_fields            = 0x00000002,   /**< Dump types and fields (like a type declaration). */
	dump_verbosity_methods           = 0x00000004,   /**< Dump types and methods (like a type declaration). */
	dump_verbosity_nostatic          = 0x00000040,   /**< Dump types and dynamic allocated fields (like a
	                                                      type declaration). This excludes methods and
	                                                      static, polymorphic fields. */
	dump_verbosity_typeattrs         = 0x00000008,   /**< Dump all type attributes. */
	dump_verbosity_entattrs          = 0x00000010,   /**< Dump all entity attributes. */
	dump_verbosity_entconsts         = 0x00000020,   /**< Dump entity constants. */

	dump_verbosity_accessStats       = 0x00000100,   /**< Dump entity access statistics. */

231
232
	dump_verbosity_max                = 0x4FF00FBE   /**< Turn everything on */
} ir_dump_verbosity_t;
233
ENUM_BITSET(ir_dump_verbosity_t)
Götz Lindenmaier's avatar
Götz Lindenmaier committed
234

235
236
237
238
/** override currently set text dump flags with new ones */
FIRM_API void ir_set_dump_verbosity(ir_dump_verbosity_t verbosity);
/** return currently set text dump flags */
FIRM_API ir_dump_verbosity_t ir_get_dump_verbosity(void);
239

Sebastian Felis's avatar
Sebastian Felis committed
240
/**
241
242
243
 * A bitset indicating various options that affect what information is dumped
 * and how exactly it is dumped. This affects the dumpers that produce vcg
 * graphs.
244
 */
245
246
247
248
249
250
typedef enum {
	/** dump basic blocks as subgraphs which contain the nodes in the block */
	ir_dump_flag_blocks_as_subgraphs   = 1U << 0,
	/** dump (parts of) typegraph along with nodes */
	ir_dump_flag_with_typegraph        = 1U << 2,
	/** Sets the vcg flag "display_edge_labels" to no.
Christoph Mallon's avatar
Christoph Mallon committed
251
	 * This is necessary as xvcg fails to display graphs
252
253
254
255
256
257
	 * with self-edges if these edges have labels. */
	ir_dump_flag_disable_edge_labels   = 1U << 3,
	/** If set constants will be replicated for every use. In non blocked view
	 * edges from constant to block are skipped.  Vcg then layouts the graphs
	 * more compact, this makes them better readable. */
	ir_dump_flag_consts_local          = 1U << 4,
258
	/** if set node idx will be added to node labels */
259
260
261
262
263
264
265
266
267
268
	ir_dump_flag_idx_label             = 1U << 5,
	/** if set node number will be added to node labels */
	ir_dump_flag_number_label          = 1U << 6,
	/** show keepalive edges from the end node */
	ir_dump_flag_keepalive_edges       = 1U << 7,
	/** dump out edges */
	ir_dump_flag_out_edges             = 1U << 8,
	/** if set dumps edges from blocks to their immediate dominator */
	ir_dump_flag_dominance             = 1U << 9,
	/** If set the dumper dumps loop nodes and edges from these nodes to the
269
	 * contained ir nodes. */
270
271
272
273
274
275
276
277
278
279
	ir_dump_flag_loops                 = 1U << 10,
	/** if set (and backedge info is computed) dump backedges */
	ir_dump_flag_back_edges            = 1U << 11,
	/** dump backedges from iredges.h */
	ir_dump_flag_iredges               = 1U << 13,
	/** write node addresses into the vcg info */
	ir_dump_flag_node_addresses        = 1U << 14,
	/** dump all anchor nodes, even the unused ones */
	ir_dump_flag_all_anchors           = 1U << 15,
	/** dumps marked blocks with an asterisk in the label */
Matthias Braun's avatar
Matthias Braun committed
280
	ir_dump_flag_show_marks            = 1U << 16,
281
282
283
284
285
286
287
288

	/** turns of dumping of constant entity values in typegraphs */
	ir_dump_flag_no_entity_values      = 1U << 20,
	/** dumps ld_names of entities instead of their names */
	ir_dump_flag_ld_names              = 1U << 21,
	/** dump entities in class hierarchies */
	ir_dump_flag_entities_in_hierarchy = 1U << 22,
} ir_dump_flags_t;
289
ENUM_BITSET(ir_dump_flags_t)
290
291
292
293
294
295
296
297
298

/** override currently set dump flags with new ones */
FIRM_API void ir_set_dump_flags(ir_dump_flags_t flags);
/** add flags to the currently set dump flags */
FIRM_API void ir_add_dump_flags(ir_dump_flags_t flags);
/** disable certain dump flags */
FIRM_API void ir_remove_dump_flags(ir_dump_flags_t flags);
/** return currently set dump flags */
FIRM_API ir_dump_flags_t ir_get_dump_flags(void);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
299

300
/**
301
302
303
 * This hook is called to dump the vcg attributes of a node to a file.
 * If this function returns zero, the default attributes are added, else
 * removed.
304
 */
305
typedef int (*dump_node_vcgattr_func)(FILE *out, const ir_node *node, const ir_node *local);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
306

307
308
309
310
/**
 * This hook is called to dump the vcg attributes of an edge to a file.
 * If this function returns zero, the default attributes are added, else
 * removed.
311
 */
312
typedef int (*dump_edge_vcgattr_func)(FILE *out, const ir_node *node, int to);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
313

314
315
316
317
318
/**
 * This hook allows dumping of additional edges (it is called outside a node: {}
 * environment)
 */
typedef void (*dump_node_edge_func)(FILE *out, const ir_node *node);
Götz Lindenmaier's avatar
Götz Lindenmaier committed
319

320
/** Sets the node_vcgattr hook. */
321
FIRM_API void set_dump_node_vcgattr_hook(dump_node_vcgattr_func hook);
322
/** Sets the edge_vcgattr hook. */
323
FIRM_API void set_dump_edge_vcgattr_hook(dump_edge_vcgattr_func hook);
324

325
/**
326
 * Sets the hook to be called to dump additional edges to a node.
327
 * @param func The hook to be called.
328
 */
329
FIRM_API void set_dump_node_edge_hook(dump_node_edge_func func);
330

331
/**
332
 * Returns the additional edge dump hook.
333
 * @return The current additional edge dump hook.]
334
 */
335
FIRM_API dump_node_edge_func get_dump_node_edge_hook(void);
336

337
/**
338
 * Sets the hook to be called to dump additional edges to a block.
339
 * @param func The hook to be called.
340
 */
341
FIRM_API void set_dump_block_edge_hook(dump_node_edge_func func);
342

343
/**
344
 * Returns the additional block edge dump hook.
345
 * @return The current additional block edge dump hook.
346
 */
347
FIRM_API dump_node_edge_func get_dump_block_edge_hook(void);
348

349
/** A node info dumper callback. */
350
typedef void (dump_node_info_cb_t)(void *data, FILE *out, const ir_node *n);
351
352
353
354
355
356
357
358
359
360
361

/**
 * Adds a new node info dumper callback. It is possible to add an unlimited
 * number of callbacks. The callbacks are called at the end of the default
 * info dumper.
 *
 * @param cb    the callback function to be called
 * @param data  a context parameter
 *
 * @return A callback handle.
 *
362
 * @note This functionality is only available, if Firm hooks are enabled.
363
 */
364
FIRM_API hook_entry_t *dump_add_node_info_callback(dump_node_info_cb_t *cb, void *data);
365
366
367
368

/**
 * Remove a previously added info dumper callback.
 *
369
370
 * @param handle  the callback handle returned from
 *                dump_add_node_info_callback()
371
 */
372
FIRM_API void dump_remove_node_info_callback(hook_entry_t *handle);
373
374

/*@}*/
375
376

#include "end.h"
377

Matthias Braun's avatar
Matthias Braun committed
378
#endif