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