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