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 "firm_types.h"
  36
  37 #ifdef __cplusplus
  38 extern "C" {
  39 #endif
  40
  41
  42 /** Returns the link of a firm node.
  43  *  Possible firm structures are: entity, type, ir_graph, ir_node and
  44  *  ir_mode. Otherwise this function has no effect
  45  *
  46  *  Derived walker or dumper have to call this function to store data
  47  *  to a firm structure. The real link field of firm structure is used
  48  *  by this firm walker to collect walking data.
  49  *
  50  *  @param thing Pointer to a firm structure
  51  *  @return Link pointer
  52  *
  53  *  @note After calling firm_walk_finalize() the stored link
  54  *        information may be invalid. */
  55 void *get_firm_walk_link(void *thing);
  56
  57 /** Set the link field of a firm structure.
  58  *  Possible firm structures are: entity, type, ir_graph, ir_node and
  59  *  ir_mode. Otherwise this function has no effect
  60  *
  61  *  Derived walker or dumper have to call this function to store data
  62  *  to a firm structure. The real link field of firm structure is used
  63  *  by this firm walker to collect walking data.
  64  *
  65  *  @param thing firm structure
  66  *  @param link Pointer to link field
  67  *
  68  *  @note After calling firm_walk_finalize() the stored link
  69  *        information may be invalid. */
  70 void set_firm_walk_link(void *thing, void *link);
  71
  72 /** Initialisation function for firm walker callbacks */
  73 typedef void firm_walk_init_func(void *env);
  74 /** Finalisation function for firm walker callbacks */
  75 typedef void firm_walk_finalize_func(void *env);
  76
  77 /** Mode callback function definition */
  78 typedef void firm_walk_mode_func(ir_mode *mode, void *env);
  79 /** Type callback function definition */
  80 typedef void firm_walk_type_func(ir_type *tp, void *env);
  81 /** Entity callback function definition */
  82 typedef void firm_walk_entity_func(entity *ent, void *env);
  83 /** Graph callback function definition */
  84 typedef void firm_walk_graph_func(ir_graph *irg, void *env);
  85 /* @{ */
  86 /** Block callback function definition */
  87 typedef void firm_walk_block_init_func(ir_graph *irg, void *env);
  88 typedef void firm_walk_block_func(ir_node *block, void *env);
  89 typedef void firm_walk_block_finalize_func(ir_graph *irg, void *env);
  90 /* @} */
  91 /** Node callback function definition */
  92 typedef void firm_walk_node_func (ir_node *irn, void *env);
  93
  94 /** @enum firm_walk_flags
  95  *
  96  *  Flags for the firm walker to modify some dumping behavior
  97  */
  98 typedef enum
  99 {
 100   FW_WITH_ALL_TYPES     = 1<<0, /**< Collect and dump all types, especially
 101                                       unused types.
 102                                       @note This flag could be set in
 103                                       firm_dumper_init() and is unused in
 104                                       firm_dump() */
 105   FW_WITH_DOMINATOR     = 1<<1, /**< nyi */
 106   FW_WITH_OUTEDGES      = 1<<2, /**< nyi */
 107   FW_WITH_LOOPS         = 1<<3, /**< nyi */
 108   FW_DUMP_BLOCK_AS_IRN  = 1<<4, /**< Dump all block nodes as irn nodes
 109                                       additionally */
 110   FW_DUMP_IRN_IN_PREFIX = 1<<5  /**< Dumps all ir nodes in prefix order
 111                                       according to the internal firm graph
 112                                       structure */
 113 } firm_walk_flags;
 114
 115 /** Interface of the firm walker */
 116 typedef struct
 117 {
 118   /* @{ */
 119   /** Interface function to dump all used and internal modes.
 120       Internal modes are: BB, X, M and T */
 121   firm_walk_init_func *do_mode_init;
 122   firm_walk_mode_func *do_mode;
 123   firm_walk_finalize_func *do_mode_finalize;
 124   /* @} */
 125
 126   /* @{ */
 127   /** Interface to dump all collected types.
 128    *
 129    *  @note To dump all (not only used types by default) a special walk
 130    *        flag must be set for the walker initializer */
 131   firm_walk_init_func *do_type_init;
 132   firm_walk_type_func *do_type;
 133   firm_walk_finalize_func *do_type_finalize;
 134   /* @} */
 135
 136   /* @{ */
 137   /** Dumping interface for entities */
 138   firm_walk_init_func *do_entity_init;
 139   firm_walk_entity_func *do_entity;
 140   firm_walk_finalize_func *do_entity_finalize;
 141   /* @} */
 142
 143   /** Dumps all graphs and subnodes.
 144    *
 145    *  The firm walker dump a graph with its blocks and nodes nested.
 146    *  Fist do_graph_init will be called (if defined). For each graph
 147    *  do_graph will be call in a loop.
 148    *  After all blocks in a graph are dumped, do_graph_post() is called.
 149    *  After dumped all graphs, do_graph_finalize will be called.
 150    *
 151    *  Within do_graph each block will be dumped. First do_block_init,
 152    *  for each block do_block and after all dumped blocks
 153    *  do_block_finalize.
 154    *
 155    *  The ir nodes are dumped nested in their blocks as well. Within
 156    *  do_block, for each ir node do_node is called in postfix order
 157    *  according to the internal firm representation. By changing the
 158    *  walking flag, a prefix order is also possible. */
 159   firm_walk_init_func *do_graph_init;
 160   firm_walk_graph_func *do_graph;
 161   firm_walk_graph_func *do_graph_post;
 162   firm_walk_finalize_func *do_graph_finalize;
 163
 164   /* @{ */
 165   /** Dumping interface for blocks. If blocks should be handled like
 166    *  like a normal ir node, a special walker flag could be set.
 167    *  @see do_graph */
 168   firm_walk_block_init_func *do_block_init;
 169   firm_walk_block_func *do_block;
 170   firm_walk_block_func *do_block_post;
 171   firm_walk_block_finalize_func *do_block_finalize;
 172   /* @} */
 173
 174   /** Dumping interface for ir nodes
 175    *  @see do_graph */
 176   firm_walk_node_func *do_node;
 177   /* dominator */
 178   /* procedures */
 179   /* loop */
 180   firm_walk_flags flags;
 181   /* pointer to environment of interface */
 182   void *env;
 183 } firm_walk_interface;
 184
 185
 186 /** Initialize the dumper und collect all data from the firm intermediate
 187  *  representation
 188  *
 189  *  @param flags flags */
 190 void firm_walk_init(firm_walk_flags flags);
 191
 192 /** Walker of the firm intermediate representation.
 193  *
 194  *  The callback functions of the interface will be called nested, e.g. for
 195  *  each block: init function of block, do_block, nested function of nodes,
 196  *  finalize function of block.
 197  *
 198  *  - modes
 199  *  - types
 200  *  - entities
 201  *  - ir graphs
 202  *    - procedures
 203  *    - blocks
 204  *    - nodes. Options: dominator, outedges
 205  *
 206  *  @param wif Stucture of walker interface. In this struct the used callback
 207  *             functions are defined.
 208  */
 209 void firm_walk(firm_walk_interface *wif);
 210
 211 /** Finalize the walker and frees all stored data for dumping */
 212 void firm_walk_finalize(void);
 213
 214 #ifdef __cplusplus
 215 }
 216 #endif
 217
 218
 219 #endif /* _FIRM_WALK_H_ */