nsz Git - libfirm/blob - ir/common/firmwalk.h

   1 /*
   2  * Project:     libFIRM
   3  * File name:   ir/common/firmwalk.h
   4  * Purpose:     Walker that touches all Firm data structures
   5  * Author:      Sebastian Felis
   6  * Modified by:
   7  * Created:     7.2003
   8  * CVS-ID:      $Id$
   9  * Copyright:   (c) 2003 Universität Karlsruhe
  10  * Licence:     This file protected by GPL -  GNU GENERAL PUBLIC LICENSE.
  11  */
  12
  13 /**
  14  *  @file firmwalk.h
  15  *
  16  *  Firm walker over intermediate representation.
  17  *
  18  *  To initialize the walker, call firm_walk_init(). This function
  19  *  collects all specific data from the firm represenation. After
  20  *  building the walker information firm_walk() could be called
  21  *  serveral times with different flags (options) from specific walker
  22  *  or dumper. At least firm_walk_finalizer() should be called to free
  23  *  the stored data.
  24  *
  25  *  This walker could be used for a dumper e.g. a vcg or xml dumper.
  26  *
  27  *  @note If a specific walker or dumper which uses the link field
  28  *        of any firm node, the the wrapper functions set_firm_walk_link()
  29  *        and get_firm_walk_link() should be used, because the firm walker
  30  *        make use of the link field to store its own data.
  31  */
  32 #ifndef _FIRM_WALK_H_
  33 #define _FIRM_WALK_H_
  34
  35 #include "type.h"
  36 #include "irgraph.h"
  37 #include "typewalk.h"
  38
  39 /** Returns the link of a firm node.
  40  *  Possible firm structures are: entity, type, ir_graph, ir_node and
  41  *  ir_mode. Otherwise this function has no effect
  42  *
  43  *  Derived walker or dumper have to call this function to store data
  44  *  to a firm structure. The real link field of firm structure is used
  45  *  by this firm walker to collect walking data.
  46  *
  47  *  @param thing Pointer to a firm structure
  48  *  @retrun Link pointer
  49  *
  50  *  @note After calling firm_walk_finalize() the stored link
  51  *        information may be invalid. */
  52 void *get_firm_walk_link(void *thing);
  53
  54 /** Set the link field of a firm structure.
  55  *  Possible firm structures are: entity, type, ir_graph, ir_node and
  56  *  ir_mode. Otherwise this function has no effect
  57  *
  58  *  Derived walker or dumper have to call this function to store data
  59  *  to a firm structure. The real link field of firm structure is used
  60  *  by this firm walker to collect walking data.
  61  *
  62  *  @param thing firm structur
  63  *  @param link Pointer to link field
  64  *
  65  *  @note After calling firm_walk_finalize() the stored link
  66  *        information may be invalid. */
  67 void set_firm_walk_link(void *thing, void *link);
  68
  69 /** Initialisation function for firm walker callbacks */
  70 typedef void firm_walk_init_func(void *env);
  71 /** Finalisation function for firm walker callbacks */
  72 typedef void firm_walk_finalize_func(void *env);
  73
  74 /** Mode callback function definition */
  75 typedef void firm_walk_mode_func(ir_mode *mode, void *env);
  76 /** Type callback function definition */
  77 typedef void firm_walk_type_func(type *tp, void *env);
  78 /** Entity callback function definition */
  79 typedef void firm_walk_entity_func(entity *ent, void *env);
  80 /** Graph callback function definition */
  81 typedef void firm_walk_graph_func(ir_graph *irg, void *env);
  82 //@{
  83 /** Block callback function definition */
  84 typedef void firm_walk_block_init_func(ir_graph *irg, void *env);
  85 typedef void firm_walk_block_func(ir_node *block, void *env);
  86 typedef void firm_walk_block_finalize_func(ir_graph *irg, void *env);
  87 //@}
  88 /** Node callback function definition */
  89 typedef void firm_walk_node_func (ir_node *irn, void *env);
  90
  91 /** @enum firm_walk_flags
  92  *
  93  *  Flags for the firm walker to modify some dumping behavior
  94  */
  95 typedef enum
  96 {
  97   FW_WITH_ALL_TYPES     = 1<<0, /**< Collect and dump all types, especially
  98                                       unused types.
  99                                       @note This flag could be set in
 100                                       firm_dumper_init() and is unused in
 101                                       firm_dump() */
 102   FW_WITH_DOMINATOR     = 1<<1, /**< nyi */
 103   FW_WITH_OUTEDGES      = 1<<2, /**< nyi */
 104   FW_WITH_LOOPS         = 1<<3, /**< nyi */
 105   FW_DUMP_BLOCK_AS_IRN  = 1<<4, /**< Dump all block nodes as irn nodes
 106                                       additionally */
 107   FW_DUMP_IRN_IN_PREFIX = 1<<5, /**< Dumps all ir nodes in prefix order
 108                                       according to the internal firm graph
 109                                       structure */
 110 } firm_walk_flags;
 111
 112 /** Interface of the firm walker */
 113 typedef struct
 114 {
 115   //@{
 116   /** Interface function to dump all used and internal modes.
 117       Internal modes are: BB, X, M and T */
 118   firm_walk_init_func *do_mode_init;
 119   firm_walk_mode_func *do_mode;
 120   firm_walk_finalize_func *do_mode_finalize;
 121   //@}
 122
 123   //@{
 124   /** Interface to dump all collected types.
 125    *
 126    *  @node To dump all (not only used types by default) a special walk
 127    *        flag must be set for the walker initializer */
 128   firm_walk_init_func *do_type_init;
 129   firm_walk_type_func *do_type;
 130   firm_walk_finalize_func *do_type_finalize;
 131   //@}
 132
 133   //@{
 134   /** Dumping interface for entities */
 135   firm_walk_init_func *do_entity_init;
 136   firm_walk_entity_func *do_entity;
 137   firm_walk_finalize_func *do_entity_finalize;
 138   //@}
 139
 140   /** Dumps all graphs and subnodes.
 141    *
 142    *  The firm walker dump a graph with its blocks and nodes nested.
 143    *  Fist do_graph_init will be called (if defined). For each graph
 144    *  do_graph will be call in a loop. After dumped all graphs,
 145    *  do_graph_finalize will be called.
 146    *
 147    *  Within do_graph each block will be dumped. First do_block_init,
 148    *  for each block do_block and after all dumped blocks
 149    *  do_block_finalize.
 150    *
 151    *  The ir nodes are dumped nested in their blocks as well. Within
 152    *  do_block, for each ir node do_node is called in postfix order
 153    *  according to the internal firm representation. By changing the
 154    *  walking flag, a prefix order is also possible. */
 155   firm_walk_init_func *do_graph_init;
 156   firm_walk_graph_func *do_graph;
 157   firm_walk_finalize_func *do_graph_finalize;
 158
 159   //@{
 160   /** Dumping interface for blocks. If blocks should be handled like
 161    *  like a normal ir node, a special walker flag could be set.
 162    *  @see do_graph */
 163   firm_walk_block_init_func *do_block_init;
 164   firm_walk_block_func *do_block;
 165   firm_walk_block_finalize_func *do_block_finalize;
 166   //@}
 167
 168   /** Dumping interface for ir nodes
 169    *  @see do_graph */
 170   firm_walk_node_func *do_node;
 171   /* dominator */
 172   /* procedures */
 173   /* loop */
 174   firm_walk_flags flags;
 175   /* pointer to environment of interface */
 176   void *env;
 177 } firm_walk_interface;
 178
 179
 180 /** Initialize the dumper und collect all data from the firm intermediate
 181  *  representation
 182  *
 183  *  @param flags flags */
 184 void firm_walk_init(firm_walk_flags flags);
 185
 186 /** Walker of the firm intermediate representation.
 187  *
 188  *  The callback functions of the interface will be called nested, e.g. for
 189  *  each block: init function of block, do_block, nested function of nodes,
 190  *  finalize function of block.
 191  *
 192  *  - modes
 193  *  - types
 194  *  - entities
 195  *  - ir graphs
 196  *    - procedures
 197  *    - blocks
 198  *    - nodes. Options: dominator, outedges
 199  *
 200  *  @param wif Stucture of walker interface. In this struct the used callback
 201  *             functions are defined.
 202  */
 203 void firm_walk(firm_walk_interface *wif);
 204
 205 /** Finalize the walker and frees all stored data for dumping */
 206 void firm_walk_finalize(void);
 207
 208 #endif /* _FIRM_WALK_H_ */