Convenience Interface

Topics
	Low Level Interface
	This interface exists to enable some custom vcg formatting/slicing used to produce example images for the homepage.

Typedefs
typedef void(*	ir_prog_dump_func) (FILE *out)
	type for dumpers that dump information about the whole program
typedef void(*	ir_graph_dump_func) (FILE *out, ir_graph *graph)
	type for graph dumpers
typedef int(*	dump_node_vcgattr_func) (FILE *out, const ir_node *node, const ir_node *local)
	This hook is called to dump the vcg attributes of a node to a file.
typedef int(*	dump_edge_vcgattr_func) (FILE *out, const ir_node *node, int to)
	This hook is called to dump the vcg attributes of an edge to a file.
typedef void(*	dump_node_edge_func) (FILE *out, const ir_node *node)
	This hook allows dumping of additional edges (it is called outside a node: {} environment)
typedef void	dump_node_info_cb_t(void *data, FILE *out, const ir_node *n)
	A node info dumper callback.

Enumerations
enum	ir_dump_verbosity_t {   dump_verbosity_onlynames = 0x00000001 , dump_verbosity_fields = 0x00000002 , dump_verbosity_methods = 0x00000004 , dump_verbosity_nostatic = 0x00000040 ,   dump_verbosity_typeattrs = 0x00000008 , dump_verbosity_entattrs = 0x00000010 , dump_verbosity_entconsts = 0x00000020 , dump_verbosity_accessStats = 0x00000100 ,   dump_verbosity_max = 0x4FF00FBE }
	Verbosity for text dumpers. More...
enum	ir_dump_flags_t {   ir_dump_flag_blocks_as_subgraphs = 1U << 0 , ir_dump_flag_with_typegraph = 1U << 1 , ir_dump_flag_disable_edge_labels = 1U << 2 , ir_dump_flag_consts_local = 1U << 3 ,   ir_dump_flag_idx_label = 1U << 4 , ir_dump_flag_number_label = 1U << 5 , ir_dump_flag_keepalive_edges = 1U << 6 , ir_dump_flag_out_edges = 1U << 7 ,   ir_dump_flag_dominance = 1U << 8 , ir_dump_flag_loops = 1U << 9 , ir_dump_flag_back_edges = 1U << 10 , ir_dump_flag_iredges = 1U << 11 ,   ir_dump_flag_all_anchors = 1U << 12 , ir_dump_flag_show_marks = 1U << 13 , ir_dump_flag_no_entity_values = 1U << 14 , ir_dump_flag_ld_names = 1U << 15 ,   ir_dump_flag_entities_in_hierarchy = 1U << 16 }
	A bitset indicating various options that affect what information is dumped and how exactly it is dumped. More...

Functions
void	dump_ir_graph (ir_graph *graph, const char *suffix)
	Convenience interface for dumping a graph as vcg file.
void	dump_ir_prog_ext (ir_prog_dump_func func, const char *suffix)
	Convenience interface for dumping the whole compilation-unit/program.
void	dump_ir_graph_ext (ir_graph_dump_func func, ir_graph *graph, const char *suffix)
	Convenience interface for dumping graphs.
void	dump_all_ir_graphs (const char *suffix)
	A walker that calls a dumper for each graph in the program.
void	ir_set_dump_path (const char *path)
	Specifies output path for the dump_ir_graph function.
void	ir_set_dump_filter (const char *name)
	Sets a prefix filter for output functions.
const char *	ir_get_dump_filter (void)
	Returns the substring filter set with ir_set_dump_filter.
void	dump_ir_graph_file (FILE *out, ir_graph *graph)
	Dumps all Firm nodes of a single graph for a single procedure in standard xvcg format.
void	dump_cfg (FILE *out, ir_graph *graph)
	Dump the control flow graph of a procedure.
void	dump_callgraph (FILE *out)
	Dump the call graph.
void	dump_typegraph (FILE *out)
	Dumps all type information.
void	dump_class_hierarchy (FILE *out)
	Dumps the class hierarchy with or without entities.
void	dump_loop_tree (FILE *out, ir_graph *graph)
	Dump a standalone loop tree, which contains the loop nodes and the firm nodes belonging to one loop packed together in one subgraph.
void	dump_callgraph_loop_tree (FILE *out)
	Dumps the loop tree over the call graph.
void	dump_types_as_text (FILE *out)
	Dump type information as text.
void	dump_globals_as_text (FILE *out)
	Dumps all global variables as text.
void	dump_loop (FILE *out, ir_loop *loop)
	Dumps the firm nodes in the sub-loop-tree of loop to a vcg file.
void	dump_graph_as_text (FILE *out, const ir_graph *graph)
	Write the graph and all its attributes to the file passed.
void	dump_entity_to_file (FILE *out, const ir_entity *entity)
	Write the entity and all its attributes to the passed file.
void	dump_type_to_file (FILE *out, const ir_type *type)
	Write the type and all its attributes to the file passed.
void	ir_set_dump_verbosity (ir_dump_verbosity_t verbosity)
	override currently set text dump flags with new ones
ir_dump_verbosity_t	ir_get_dump_verbosity (void)
	return currently set text dump flags
void	ir_set_dump_flags (ir_dump_flags_t flags)
	override currently set dump flags with new ones
void	ir_add_dump_flags (ir_dump_flags_t flags)
	add flags to the currently set dump flags
void	ir_remove_dump_flags (ir_dump_flags_t flags)
	disable certain dump flags
ir_dump_flags_t	ir_get_dump_flags (void)
	return currently set dump flags
void	set_dump_node_vcgattr_hook (dump_node_vcgattr_func hook)
	Sets the node_vcgattr hook.
void	set_dump_edge_vcgattr_hook (dump_edge_vcgattr_func hook)
	Sets the edge_vcgattr hook.
void	set_dump_node_edge_hook (dump_node_edge_func func)
	Sets the hook to be called to dump additional edges to a node.
dump_node_edge_func	get_dump_node_edge_hook (void)
	Returns the additional edge dump hook.
void	set_dump_block_edge_hook (dump_node_edge_func func)
	Sets the hook to be called to dump additional edges to a block.
dump_node_edge_func	get_dump_block_edge_hook (void)
	Returns the additional block edge dump hook.
hook_entry_t *	dump_add_node_info_callback (dump_node_info_cb_t *cb, void *data)
	Adds a new node info dumper callback.
void	dump_remove_node_info_callback (hook_entry_t *handle)
	Removes a previously added info dumper callback.

Detailed Description

Typedef Documentation

dump_edge_vcgattr_func

typedef int(* dump_edge_vcgattr_func) (FILE *out, const ir_node *node, int to)

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.

Definition at line 310 of file irdump.h.

dump_node_edge_func

typedef void(* dump_node_edge_func) (FILE *out, const ir_node *node)

This hook allows dumping of additional edges (it is called outside a node: {} environment)

Definition at line 316 of file irdump.h.

dump_node_info_cb_t

typedef void dump_node_info_cb_t(void *data, FILE *out, const ir_node *n)

A node info dumper callback.

Definition at line 348 of file irdump.h.

dump_node_vcgattr_func

typedef int(* dump_node_vcgattr_func) (FILE *out, const ir_node *node, const ir_node *local)

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.

Definition at line 303 of file irdump.h.

ir_graph_dump_func

typedef void(* ir_graph_dump_func) (FILE *out, ir_graph *graph)

type for graph dumpers

Definition at line 69 of file irdump.h.

ir_prog_dump_func

typedef void(* ir_prog_dump_func) (FILE *out)

type for dumpers that dump information about the whole program

Definition at line 49 of file irdump.h.

Enumeration Type Documentation

ir_dump_flags_t

enum ir_dump_flags_t

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.

Enumerator
ir_dump_flag_blocks_as_subgraphs	dump basic blocks as subgraphs which contain the nodes in the block
ir_dump_flag_with_typegraph	dump (parts of) typegraph along with nodes
ir_dump_flag_disable_edge_labels	Sets the vcg flag "display_edge_labels" to no. This is necessary as xvcg fails to display graphs with self-edges if these edges have labels.
ir_dump_flag_consts_local	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_idx_label	if set node idx will be added to node labels
ir_dump_flag_number_label	if set node number will be added to node labels
ir_dump_flag_keepalive_edges	show keepalive edges from the end node
ir_dump_flag_out_edges	dump out edges
ir_dump_flag_dominance	if set dumps edges from blocks to their immediate dominator
ir_dump_flag_loops	If set the dumper dumps loop nodes and edges from these nodes to the contained ir nodes.
ir_dump_flag_back_edges	if set (and backedge info is computed) dump backedges
ir_dump_flag_iredges	dump backedges from iredges.h
ir_dump_flag_all_anchors	dump all anchor nodes, even the unused ones
ir_dump_flag_show_marks	dumps marked blocks with an asterisk in the label
ir_dump_flag_no_entity_values	turns of dumping of constant entity values in typegraphs
ir_dump_flag_ld_names	dumps ld_names of entities instead of their names
ir_dump_flag_entities_in_hierarchy	dump entities in class hierarchies

Definition at line 245 of file irdump.h.

ir_dump_verbosity_t

enum ir_dump_verbosity_t

Verbosity for text dumpers.

Enumerator
dump_verbosity_onlynames	Only dump names. Turns off all other flags up to 0x00010000.
dump_verbosity_fields	Dump types and fields (like a type declaration).
dump_verbosity_methods	Dump types and methods (like a type declaration).
dump_verbosity_nostatic	Dump types and dynamic allocated fields (like a type declaration). This excludes methods and static, polymorphic fields.
dump_verbosity_typeattrs	Dump all type attributes.
dump_verbosity_entattrs	Dump all entity attributes.
dump_verbosity_entconsts	Dump entity constants.
dump_verbosity_accessStats	Dump entity access statistics.
dump_verbosity_max	Turn everything on.

Definition at line 217 of file irdump.h.

Function Documentation

dump_add_node_info_callback()

hook_entry_t * dump_add_node_info_callback	(	dump_node_info_cb_t *	cb,
		void *	data )

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.

Parameters

cb	the callback function to be called
data	a context parameter

Returns

A callback handle.

Note

This functionality is only available, if Firm hooks are enabled.

dump_all_ir_graphs()

void dump_all_ir_graphs

(

const char *

suffix

)

A walker that calls a dumper for each graph in the program.

Parameters

suffix

A suffix for the file name.

dump_callgraph()

void dump_callgraph

(

FILE *

out

)

Dump the call graph.

Parameters

out	Output stream the callgraph is written to

dump_callgraph_loop_tree()

void dump_callgraph_loop_tree

(

FILE *

out

)

Dumps the loop tree over the call graph.

Parameters

out	Output stream

dump_cfg()

void dump_cfg	(	FILE *	out,
		ir_graph *	graph )

Dump the control flow graph of a procedure.

Parameters

graph	The firm graph whose CFG shall be dumped.
out	Output stream the CFG is written to

Dumps the control flow graph of a procedure in standard xvcg format.

dump_class_hierarchy()

void dump_class_hierarchy

(

FILE *

out

)

Dumps the class hierarchy with or without entities.

Parameters

out	Output stream

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.

dump_entity_to_file()

void dump_entity_to_file	(	FILE *	out,
		const ir_entity *	entity )

Write the entity and all its attributes to the passed file.

dump_globals_as_text()

void dump_globals_as_text

(

FILE *

out

)

Dumps all global variables as text.

Parameters

out	Output stream

Dumps a text representation of the entities in the global type.

dump_graph_as_text()

void dump_graph_as_text	(	FILE *	out,
		const ir_graph *	graph )

Write the graph and all its attributes to the file passed.

Does not write the nodes.

dump_ir_graph()

void dump_ir_graph	(	ir_graph *	graph,
		const char *	suffix )

Convenience interface for dumping a graph as vcg file.

For details on how the filename is constructed see dump_ir_graph_ext

dump_ir_graph_ext()

void dump_ir_graph_ext	(	ir_graph_dump_func	func,
		ir_graph *	graph,
		const char *	suffix )

Convenience interface for dumping graphs.

The filename is constructed by combining a counter, the name of the graphs entity and the given suffix. The file-extensions is determined by looking at mime_type. The file is stored into the directory specified by ir_set_dump_path

Parameters

func	Dumper. Usually one of dump_cfg, dump_loop_tree, dump_ir_graph_file
graph	the graph to dump
suffix	suffix

dump_ir_graph_file()

void dump_ir_graph_file	(	FILE *	out,
		ir_graph *	graph )

Dumps all Firm nodes of a single graph for a single procedure in standard xvcg format.

Parameters

graph	The firm graph to be dumped.
out	Output stream the graph is written to

dump_ir_prog_ext()

void dump_ir_prog_ext	(	ir_prog_dump_func	func,
		const char *	suffix )

Convenience interface for dumping the whole compilation-unit/program.

The filename is constructed by combining a counter, the name of the current ir_prog and the given suffix. The file-extensions is determined by looking at mime_type. The file is stored into the directory specified by ir_set_dump_path

Parameters

func	Dumper. Usually one of dump_callgraph, dump_typegraph, dump_class_hierarchy, dump_types_as_text, dump_globals_as_text
suffix	Suffix to append to the name

dump_loop()

void dump_loop	(	FILE *	out,
		ir_loop *	loop )

Dumps the firm nodes in the sub-loop-tree of loop to a vcg file.

Parameters

out	Output stream
loop	Dump the loop tree for this loop.

dump_loop_tree()

void dump_loop_tree	(	FILE *	out,
		ir_graph *	graph )

Dump a standalone loop tree, which contains the loop nodes and the firm nodes belonging to one loop packed together in one subgraph.

Parameters

out	Output stream
graph	Dump the loop tree for this graph.

dump_remove_node_info_callback()

void dump_remove_node_info_callback

(

hook_entry_t *

handle

)

Removes a previously added info dumper callback.

Parameters

handle

the callback handle returned from dump_add_node_info_callback()

dump_type_to_file()

void dump_type_to_file	(	FILE *	out,
		const ir_type *	type )

Write the type and all its attributes to the file passed.

dump_typegraph()

void dump_typegraph

(

FILE *

out

)

Dumps all type information.

Parameters

out	Output stream the typegraph is written to

Dumps all type information that is somehow reachable in standard vcg format.

dump_types_as_text()

void dump_types_as_text

(

FILE *

out

)

Dump type information as text.

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.

get_dump_block_edge_hook()

dump_node_edge_func get_dump_block_edge_hook

(

void

)

Returns the additional block edge dump hook.

Returns

The current additional block edge dump hook.

get_dump_node_edge_hook()

dump_node_edge_func get_dump_node_edge_hook

(

void

)

Returns the additional edge dump hook.

Returns

The current additional edge dump hook.]

ir_add_dump_flags()

void ir_add_dump_flags

(

ir_dump_flags_t

flags

)

add flags to the currently set dump flags

ir_get_dump_filter()

const char * ir_get_dump_filter

(

void

)

Returns the substring filter set with ir_set_dump_filter.

ir_get_dump_flags()

ir_dump_flags_t ir_get_dump_flags

(

void

)

return currently set dump flags

ir_get_dump_verbosity()

ir_dump_verbosity_t ir_get_dump_verbosity

(

void

)

return currently set text dump flags

ir_remove_dump_flags()

void ir_remove_dump_flags

(

ir_dump_flags_t

flags

)

disable certain dump flags

ir_set_dump_filter()

void ir_set_dump_filter

(

const char *

name

)

Sets a prefix filter for output functions.

All graph dumpers check this name. If the name is != "" and not a substring of the graph to be dumped, the dumper does not dump the graph.

Parameters

name	The prefix of the name of the method entity to be dumped.

ir_set_dump_flags()

void ir_set_dump_flags

(

ir_dump_flags_t

flags

)

override currently set dump flags with new ones

ir_set_dump_path()

void ir_set_dump_path

(

const char *

path

)

Specifies output path for the dump_ir_graph function.

ir_set_dump_verbosity()

void ir_set_dump_verbosity

(

ir_dump_verbosity_t

verbosity

)

override currently set text dump flags with new ones

set_dump_block_edge_hook()

void set_dump_block_edge_hook

(

dump_node_edge_func

func

)

Sets the hook to be called to dump additional edges to a block.

Parameters

func	The hook to be called.

set_dump_edge_vcgattr_hook()

void set_dump_edge_vcgattr_hook

(

dump_edge_vcgattr_func

hook

)

Sets the edge_vcgattr hook.

set_dump_node_edge_hook()

void set_dump_node_edge_hook

(

dump_node_edge_func

func

)

Sets the hook to be called to dump additional edges to a node.

Parameters

func	The hook to be called.

set_dump_node_vcgattr_hook()

void set_dump_node_vcgattr_hook

(

dump_node_vcgattr_func

hook

)

Sets the node_vcgattr hook.