include/llvm/Bytecode/BytecodeHandler.h

   1 //===-- BytecodeHandler.h - Handle Bytecode Parsing Events ------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file was developed by Reid Spencer and is distributed under the
   6 // University of Illinois Open Source License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 //  This header file defines the interface to the Bytecode Handler. The handler
  11 //  is called by the Bytecode Reader to obtain out-of-band parsing events for
  12 //  tasks other then LLVM IR construction.
  13 //
  14 //===----------------------------------------------------------------------===//
  15
  16 #ifndef LLVM_BYTECODE_BYTECODEHANDLER_H
  17 #define LLVM_BYTECODE_BYTECODEHANDLER_H
  18
  19 #include "llvm/Module.h"
  20
  21 namespace llvm {
  22
  23 class ArrayType;
  24 class StructType;
  25 class PointerType;
  26 class ConstantArray;
  27 class Module;
  28
  29 /// This class provides the interface for handling bytecode events during
  30 /// reading of bytecode. The methods on this interface are invoked by the
  31 /// BytecodeReader as it discovers the content of a bytecode stream.
  32 /// This class provides a a clear separation of concerns between recognizing
  33 /// the semantic units of a bytecode file (the Reader) and deciding what to do
  34 /// with them (the Handler).
  35 ///
  36 /// The BytecodeReader recognizes the content of the bytecode file and
  37 /// calls the BytecodeHandler methods to let it perform additional tasks. This
  38 /// arrangement allows Bytecode files to be read and handled for a number of
  39 /// purposes simply by creating a subclass of BytecodeHandler. None of the
  40 /// parsing details need to be understood, only the meaning of the calls
  41 /// made on this interface.
  42 ///
  43 /// @see BytecodeHandler
  44 /// @brief Handle Bytecode Parsing Events
  45 class BytecodeHandler {
  46
  47 /// @name Constructors And Operators
  48 /// @{
  49 public:
  50   /// @brief Default constructor (empty)
  51   BytecodeHandler() {}
  52   /// @brief Virtual destructor (empty)
  53   virtual ~BytecodeHandler();
  54
  55 private:
  56   BytecodeHandler(const BytecodeHandler &);  // DO NOT IMPLEMENT
  57   void operator=(const BytecodeHandler &);  // DO NOT IMPLEMENT
  58
  59 /// @}
  60 /// @name Handler Methods
  61 /// @{
  62 public:
  63
  64   /// This method is called whenever the parser detects an error in the
  65   /// bytecode formatting. It gives the handler a chance to do something
  66   /// with the error message before the parser throws an exception to
  67   /// terminate the parsing.
  68   /// @brief Handle parsing errors.
  69   virtual void handleError(const std::string& str ) {}
  70
  71   /// This method is called at the beginning of a parse before anything is
  72   /// read in order to give the handler a chance to initialize.
  73   /// @brief Handle the start of a bytecode parse
  74   virtual void handleStart( Module* Mod, unsigned byteSize ) {}
  75
  76   /// This method is called at the end of a parse after everything has been
  77   /// read in order to give the handler a chance to terminate.
  78   /// @brief Handle the end of a bytecode parse
  79   virtual void handleFinish() {}
  80
  81   /// This method is called at the start of a module to indicate that a
  82   /// module is being parsed.
  83   /// @brief Handle the start of a module.
  84   virtual void handleModuleBegin(const std::string& moduleId) {}
  85
  86   /// This method is called at the end of a module to indicate that the module
  87   /// previously being parsed has concluded.
  88   /// @brief Handle the end of a module.
  89   virtual void handleModuleEnd(
  90     const std::string& moduleId ///< An identifier for the module
  91   ) {}
  92
  93   /// This method is called once the version information has been parsed. It
  94   /// provides the information about the version of the bytecode file being
  95   /// read.
  96   /// @brief Handle the bytecode prolog
  97   virtual void handleVersionInfo(
  98     unsigned char RevisionNum,        ///< Byte code revision number
  99     Module::Endianness Endianness,    ///< Endianness indicator
 100     Module::PointerSize PointerSize   ///< PointerSize indicator
 101   ) {}
 102
 103   /// This method is called at the start of a module globals block which
 104   /// contains the global variables and the function placeholders
 105   virtual void handleModuleGlobalsBegin() {}
 106
 107   /// This method is called when a non-initialized global variable is
 108   /// recognized. Its type, constness, and linkage type are provided.
 109   /// @brief Handle a non-initialized global variable
 110   virtual void handleGlobalVariable(
 111     const Type* ElemType,     ///< The type of the global variable
 112     bool isConstant,          ///< Whether the GV is constant or not
 113     GlobalValue::LinkageTypes,///< The linkage type of the GV
 114     unsigned SlotNum,         ///< Slot number of GV
 115     unsigned initSlot         ///< Slot number of GV's initializer (0 if none)
 116   ) {}
 117
 118   /// This method is called when a new type is recognized. The type is
 119   /// converted from the bytecode and passed to this method.
 120   /// @brief Handle a type
 121   virtual void handleType(
 122     const Type* Ty ///< The type that was just recognized
 123   ) {}
 124
 125   /// This method is called when the function prototype for a function is
 126   /// encountered in the module globals block.
 127   virtual void handleFunctionDeclaration(
 128     Function* Func ///< The function being declared
 129   ) {}
 130
 131   /// This method is called when a global variable is initialized with
 132   /// its constant value. Because of forward referencing, etc. this is
 133   /// done towards the end of the module globals block
 134   virtual void handleGlobalInitializer(GlobalVariable*, Constant* ) {}
 135
 136   /// This method is called at the end of the module globals block.
 137   /// @brief Handle end of module globals block.
 138   virtual void handleModuleGlobalsEnd() {}
 139
 140   /// This method is called at the beginning of a compaction table.
 141   /// @brief Handle start of compaction table.
 142   virtual void handleCompactionTableBegin() {}
 143
 144   /// @brief Handle start of a compaction table plane
 145   virtual void handleCompactionTablePlane(
 146     unsigned Ty,         ///< The type of the plane (slot number)
 147     unsigned NumEntries  ///< The number of entries in the plane
 148   ) {}
 149
 150   /// @brief Handle a type entry in the compaction table
 151   virtual void handleCompactionTableType(
 152     unsigned i,       ///< Index in the plane of this type
 153     unsigned TypSlot, ///< Slot number for this type
 154     const Type*       ///< The type referenced by this slot
 155   ) {}
 156
 157   /// @brief Handle a value entry in the compaction table
 158   virtual void handleCompactionTableValue(
 159     unsigned i,       ///< Index in the compaction table's type plane
 160     unsigned TypSlot, ///< The slot (plane) of the type of this value
 161     unsigned ValSlot  ///< The global value slot of the value
 162   ) {}
 163
 164   /// @brief Handle end of a compaction table
 165   virtual void handleCompactionTableEnd() {}
 166
 167   /// @brief Handle start of a symbol table
 168   virtual void handleSymbolTableBegin(
 169     Function* Func,  ///< The function to which the ST belongs
 170     SymbolTable* ST  ///< The symbol table being filled
 171   ) {}
 172
 173   /// @brief Handle start of a symbol table plane
 174   virtual void handleSymbolTablePlane(
 175     unsigned TySlot,      ///< The slotnum of the type plane
 176     unsigned NumEntries,  ///< Number of entries in the plane
 177     const Type* Typ       ///< The type of this type plane
 178   ) {}
 179
 180   /// @brief Handle a named type in the symbol table
 181   virtual void handleSymbolTableType(
 182     unsigned i,              ///< The index of the type in this plane
 183     unsigned slot,           ///< Slot number of the named type
 184     const std::string& name  ///< Name of the type
 185   ) {}
 186
 187   /// @brief Handle a named value in the symbol table
 188   virtual void handleSymbolTableValue(
 189     unsigned i,              ///< The index of the value in this plane
 190     unsigned slot,           ///< Slot number of the named value
 191     const std::string& name  ///< Name of the value.
 192   ) {}
 193
 194   /// @brief Handle the end of a symbol table
 195   virtual void handleSymbolTableEnd() {}
 196
 197   /// @brief Handle the beginning of a function body
 198   virtual void handleFunctionBegin(
 199     Function* Func, ///< The function being defined
 200     unsigned Size   ///< The size (in bytes) of the function's bytecode
 201   ) {}
 202
 203   /// @brief Handle the end of a function body
 204   virtual void handleFunctionEnd(
 205     Function* Func  ///< The function whose definition has just finished.
 206   ) {}
 207
 208   /// @brief Handle the beginning of a basic block
 209   virtual void handleBasicBlockBegin(
 210     unsigned blocknum ///< The block number of the block
 211   ) {}
 212
 213   /// This method is called for each instruction that is parsed.
 214   /// @returns true if the instruction is a block terminating instruction
 215   /// @brief Handle an instruction
 216   virtual bool handleInstruction(
 217     unsigned Opcode,                 ///< Opcode of the instruction
 218     const Type* iType,               ///< Instruction type
 219     std::vector<unsigned>& Operands, ///< Vector of slot # operands
 220     unsigned Length                  ///< Length of instruction in bc bytes
 221   ) { return false; }
 222
 223   /// @brief Handle the end of a basic block
 224   virtual void handleBasicBlockEnd(
 225     unsigned blocknum  ///< The block number of the block just finished
 226   ) {}
 227
 228   /// @brief Handle start of global constants block.
 229   virtual void handleGlobalConstantsBegin() {}
 230
 231   /// @brief Handle a constant expression
 232   virtual void handleConstantExpression(
 233     unsigned Opcode,  ///< Opcode of primary expression operator
 234     std::vector<Constant*> ArgVec, ///< expression args
 235     Constant* C ///< The constant value
 236   ) {}
 237
 238   /// @brief Handle a constant array
 239   virtual void handleConstantArray(
 240     const ArrayType* AT,                ///< Type of the array
 241     std::vector<Constant*>& ElementSlots,///< Slot nums for array values
 242     unsigned TypeSlot,                  ///< Slot # of type
 243     Constant* Val                       ///< The constant value
 244   ) {}
 245
 246   /// @brief Handle a constant structure
 247   virtual void handleConstantStruct(
 248     const StructType* ST,               ///< Type of the struct
 249     std::vector<Constant*>& ElementSlots,///< Slot nums for struct values
 250     Constant* Val                       ///< The constant value
 251   ) {}
 252
 253   /// @brief Handle a constant pointer
 254   virtual void handleConstantPointer(
 255     const PointerType* PT, ///< Type of the pointer
 256     unsigned Slot,         ///< Slot num of initializer value
 257     GlobalValue* GV        ///< Referenced global value
 258   ) {}
 259
 260   /// @brief Handle a constant strings (array special case)
 261   virtual void handleConstantString(
 262     const ConstantArray* CA ///< Type of the string array
 263   ) {}
 264
 265   /// @brief Handle a primitive constant value
 266   virtual void handleConstantValue(
 267     Constant * c ///< The constant just defined
 268   ) {}
 269
 270   /// @brief Handle the end of the global constants
 271   virtual void handleGlobalConstantsEnd() {}
 272
 273   /// @brief Handle an alignment event
 274   virtual void handleAlignment(
 275     unsigned numBytes ///< The number of bytes added for alignment
 276   ) {}
 277
 278   /// @brief Handle a bytecode block
 279   virtual void handleBlock(
 280     unsigned BType,                ///< The type of block
 281     const unsigned char* StartPtr, ///< The start of the block
 282     unsigned Size                  ///< The size of the block
 283   ) {}
 284
 285   /// @brief Handle a variable bit rate 32 bit unsigned
 286   virtual void handleVBR32(
 287     unsigned Size  ///< Number of bytes the vbr_uint took up
 288   ) {}
 289
 290   /// @brief Handle a variable bit rate 64 bit unsigned
 291   virtual void handleVBR64(
 292     unsigned Size  ///< Number of byte sthe vbr_uint64 took up
 293   ) {}
 294 /// @}
 295
 296 };
 297
 298 }
 299 // vim: sw=2 ai
 300 #endif