LLVM API Documentation

Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages

BytecodeHandler.h

Go to the documentation of this file.
00001 //===-- BytecodeHandler.h - Handle Bytecode Parsing Events ------*- C++ -*-===//
00002 // 
00003 //                     The LLVM Compiler Infrastructure
00004 //
00005 // This file was developed by Reid Spencer and is distributed under the 
00006 // University of Illinois Open Source License. See LICENSE.TXT for details.
00007 // 
00008 //===----------------------------------------------------------------------===//
00009 //
00010 //  This header file defines the interface to the Bytecode Handler. The handler
00011 //  is called by the Bytecode Reader to obtain out-of-band parsing events for
00012 //  tasks other then LLVM IR construction.
00013 //
00014 //===----------------------------------------------------------------------===//
00015 
00016 #ifndef LLVM_BYTECODE_BYTECODEHANDLER_H
00017 #define LLVM_BYTECODE_BYTECODEHANDLER_H
00018 
00019 #include "llvm/Module.h"
00020 
00021 namespace llvm {
00022 
00023 class ArrayType;
00024 class StructType;
00025 class PointerType;
00026 class PackedType;
00027 class ConstantArray;
00028 class Module;
00029 
00030 /// This class provides the interface for handling bytecode events during
00031 /// reading of bytecode. The methods on this interface are invoked by the 
00032 /// BytecodeReader as it discovers the content of a bytecode stream. 
00033 /// This class provides a a clear separation of concerns between recognizing 
00034 /// the semantic units of a bytecode file (the Reader) and deciding what to do 
00035 /// with them (the Handler). 
00036 ///
00037 /// The BytecodeReader recognizes the content of the bytecode file and
00038 /// calls the BytecodeHandler methods to let it perform additional tasks. This
00039 /// arrangement allows Bytecode files to be read and handled for a number of
00040 /// purposes simply by creating a subclass of BytecodeHandler. None of the
00041 /// parsing details need to be understood, only the meaning of the calls
00042 /// made on this interface.
00043 /// 
00044 /// @see BytecodeHandler
00045 /// @brief Handle Bytecode Parsing Events
00046 class BytecodeHandler {
00047 
00048 /// @name Constructors And Operators
00049 /// @{
00050 public:
00051   /// @brief Default constructor (empty)
00052   BytecodeHandler() {}
00053   /// @brief Virtual destructor (empty)
00054   virtual ~BytecodeHandler();
00055 
00056 private:
00057   BytecodeHandler(const BytecodeHandler &);  // DO NOT IMPLEMENT
00058   void operator=(const BytecodeHandler &);  // DO NOT IMPLEMENT
00059 
00060 /// @}
00061 /// @name Handler Methods
00062 /// @{
00063 public:
00064 
00065   /// This method is called whenever the parser detects an error in the
00066   /// bytecode formatting. It gives the handler a chance to do something
00067   /// with the error message before the parser throws an exception to 
00068   /// terminate the parsing. 
00069   /// @brief Handle parsing errors.
00070   virtual void handleError(const std::string& str ) {}
00071 
00072   /// This method is called at the beginning of a parse before anything is
00073   /// read in order to give the handler a chance to initialize.
00074   /// @brief Handle the start of a bytecode parse
00075   virtual void handleStart( Module* Mod, unsigned byteSize ) {}
00076 
00077   /// This method is called at the end of a parse after everything has been
00078   /// read in order to give the handler a chance to terminate.
00079   /// @brief Handle the end of a bytecode parse
00080   virtual void handleFinish() {}
00081 
00082   /// This method is called at the start of a module to indicate that a
00083   /// module is being parsed.
00084   /// @brief Handle the start of a module.
00085   virtual void handleModuleBegin(const std::string& moduleId) {}
00086 
00087   /// This method is called at the end of a module to indicate that the module
00088   /// previously being parsed has concluded.
00089   /// @brief Handle the end of a module.
00090   virtual void handleModuleEnd(
00091     const std::string& moduleId ///< An identifier for the module
00092   ) {}
00093 
00094   /// This method is called once the version information has been parsed. It 
00095   /// provides the information about the version of the bytecode file being 
00096   /// read.
00097   /// @brief Handle the bytecode prolog
00098   virtual void handleVersionInfo(
00099     unsigned char RevisionNum,        ///< Byte code revision number
00100     Module::Endianness Endianness,    ///< Endianness indicator
00101     Module::PointerSize PointerSize   ///< PointerSize indicator
00102   ) {}
00103 
00104   /// This method is called at the start of a module globals block which
00105   /// contains the global variables and the function placeholders
00106   virtual void handleModuleGlobalsBegin() {}
00107 
00108   /// This method is called when a non-initialized global variable is 
00109   /// recognized. Its type, constness, and linkage type are provided.
00110   /// @brief Handle a non-initialized global variable
00111   virtual void handleGlobalVariable( 
00112     const Type* ElemType,     ///< The type of the global variable
00113     bool isConstant,          ///< Whether the GV is constant or not
00114     GlobalValue::LinkageTypes,///< The linkage type of the GV
00115     unsigned SlotNum,         ///< Slot number of GV
00116     unsigned initSlot         ///< Slot number of GV's initializer (0 if none)
00117   ) {}
00118 
00119   /// This method is called when a type list is recognized. It simply
00120   /// provides the number of types that the list contains. The handler
00121   /// should expect that number of calls to handleType.
00122   /// @brief Handle a type
00123   virtual void handleTypeList( 
00124     unsigned numEntries ///< The number of entries in the type list
00125   ) {}
00126 
00127   /// This method is called when a new type is recognized. The type is 
00128   /// converted from the bytecode and passed to this method.
00129   /// @brief Handle a type
00130   virtual void handleType( 
00131     const Type* Ty ///< The type that was just recognized
00132   ) {}
00133 
00134   /// This method is called when the function prototype for a function is
00135   /// encountered in the module globals block.
00136   virtual void handleFunctionDeclaration( 
00137     Function* Func ///< The function being declared
00138   ) {}
00139 
00140   /// This method is called when a global variable is initialized with
00141   /// its constant value. Because of forward referencing, etc. this is
00142   /// done towards the end of the module globals block
00143   virtual void handleGlobalInitializer(GlobalVariable*, Constant* ) {}
00144 
00145   /// This method is called for each dependent library name found
00146   /// in the module globals block.
00147   virtual void handleDependentLibrary(const std::string& libName) {}
00148 
00149   /// This method is called if the module globals has a non-empty target 
00150   /// triple
00151   virtual void handleTargetTriple(const std::string& triple) {}
00152 
00153   /// This method is called at the end of the module globals block.
00154   /// @brief Handle end of module globals block.
00155   virtual void handleModuleGlobalsEnd() {}
00156 
00157   /// This method is called at the beginning of a compaction table.
00158   /// @brief Handle start of compaction table.
00159   virtual void handleCompactionTableBegin() {}
00160 
00161   /// @brief Handle start of a compaction table plane
00162   virtual void handleCompactionTablePlane( 
00163     unsigned Ty,         ///< The type of the plane (slot number)
00164     unsigned NumEntries  ///< The number of entries in the plane
00165   ) {}
00166 
00167   /// @brief Handle a type entry in the compaction table
00168   virtual void handleCompactionTableType( 
00169     unsigned i,       ///< Index in the plane of this type
00170     unsigned TypSlot, ///< Slot number for this type
00171     const Type*       ///< The type referenced by this slot
00172   ) {}
00173 
00174   /// @brief Handle a value entry in the compaction table
00175   virtual void handleCompactionTableValue(
00176     unsigned i,       ///< Index in the compaction table's type plane
00177     unsigned TypSlot, ///< The slot (plane) of the type of this value
00178     unsigned ValSlot  ///< The global value slot of the value
00179   ) {}
00180 
00181   /// @brief Handle end of a compaction table
00182   virtual void handleCompactionTableEnd() {}
00183 
00184   /// @brief Handle start of a symbol table
00185   virtual void handleSymbolTableBegin( 
00186     Function* Func,  ///< The function to which the ST belongs
00187     SymbolTable* ST  ///< The symbol table being filled
00188   ) {}
00189 
00190   /// @brief Handle start of a symbol table plane
00191   virtual void handleSymbolTablePlane( 
00192     unsigned TySlot,      ///< The slotnum of the type plane
00193     unsigned NumEntries,  ///< Number of entries in the plane
00194     const Type* Typ       ///< The type of this type plane
00195   ) {}
00196 
00197   /// @brief Handle a named type in the symbol table
00198   virtual void handleSymbolTableType( 
00199     unsigned i,              ///< The index of the type in this plane
00200     unsigned slot,           ///< Slot number of the named type
00201     const std::string& name  ///< Name of the type
00202   ) {}
00203 
00204   /// @brief Handle a named value in the symbol table
00205   virtual void handleSymbolTableValue( 
00206     unsigned i,              ///< The index of the value in this plane
00207     unsigned slot,           ///< Slot number of the named value
00208     const std::string& name  ///< Name of the value.
00209   ) {}
00210 
00211   /// @brief Handle the end of a symbol table
00212   virtual void handleSymbolTableEnd() {}
00213 
00214   /// @brief Handle the beginning of a function body
00215   virtual void handleFunctionBegin(
00216     Function* Func, ///< The function being defined
00217     unsigned Size   ///< The size (in bytes) of the function's bytecode
00218   ) {}
00219 
00220   /// @brief Handle the end of a function body
00221   virtual void handleFunctionEnd(
00222     Function* Func  ///< The function whose definition has just finished.
00223   ) {}
00224 
00225   /// @brief Handle the beginning of a basic block
00226   virtual void handleBasicBlockBegin(
00227     unsigned blocknum ///< The block number of the block
00228   ) {}
00229 
00230   /// This method is called for each instruction that is parsed. 
00231   /// @returns true if the instruction is a block terminating instruction
00232   /// @brief Handle an instruction
00233   virtual bool handleInstruction(
00234     unsigned Opcode,                 ///< Opcode of the instruction
00235     const Type* iType,               ///< Instruction type
00236     std::vector<unsigned>& Operands, ///< Vector of slot # operands
00237     unsigned Length                  ///< Length of instruction in bc bytes
00238   ) { return false; }
00239 
00240   /// @brief Handle the end of a basic block
00241   virtual void handleBasicBlockEnd(
00242     unsigned blocknum  ///< The block number of the block just finished
00243   ) {}
00244 
00245   /// @brief Handle start of global constants block.
00246   virtual void handleGlobalConstantsBegin() {}
00247 
00248   /// @brief Handle a constant expression
00249   virtual void handleConstantExpression( 
00250     unsigned Opcode,  ///< Opcode of primary expression operator
00251     std::vector<Constant*> ArgVec, ///< expression args
00252     Constant* C ///< The constant value
00253   ) {}
00254 
00255   /// @brief Handle a constant array
00256   virtual void handleConstantArray( 
00257     const ArrayType* AT,                ///< Type of the array
00258     std::vector<Constant*>& ElementSlots,///< Slot nums for array values
00259     unsigned TypeSlot,                  ///< Slot # of type
00260     Constant* Val                       ///< The constant value
00261   ) {}
00262 
00263   /// @brief Handle a constant structure 
00264   virtual void handleConstantStruct( 
00265     const StructType* ST,               ///< Type of the struct
00266     std::vector<Constant*>& ElementSlots,///< Slot nums for struct values
00267     Constant* Val                       ///< The constant value
00268   ) {}
00269 
00270   /// @brief Handle a constant packed
00271   virtual void handleConstantPacked( 
00272     const PackedType* PT,                ///< Type of the array
00273     std::vector<Constant*>& ElementSlots,///< Slot nums for packed values
00274     unsigned TypeSlot,                  ///< Slot # of type
00275     Constant* Val                       ///< The constant value
00276   ) {}
00277 
00278   /// @brief Handle a constant pointer
00279   virtual void handleConstantPointer( 
00280     const PointerType* PT, ///< Type of the pointer
00281     unsigned Slot,         ///< Slot num of initializer value
00282     GlobalValue* GV        ///< Referenced global value
00283   ) {}
00284 
00285   /// @brief Handle a constant strings (array special case)
00286   virtual void handleConstantString(
00287     const ConstantArray* CA ///< Type of the string array
00288   ) {}
00289 
00290   /// @brief Handle a primitive constant value
00291   virtual void handleConstantValue( 
00292     Constant * c ///< The constant just defined
00293   ) {}
00294 
00295   /// @brief Handle the end of the global constants
00296   virtual void handleGlobalConstantsEnd() {}
00297 
00298   /// @brief Handle an alignment event
00299   virtual void handleAlignment(
00300     unsigned numBytes ///< The number of bytes added for alignment
00301   ) {}
00302 
00303   /// @brief Handle a bytecode block
00304   virtual void handleBlock(
00305     unsigned BType,                ///< The type of block
00306     const unsigned char* StartPtr, ///< The start of the block
00307     unsigned Size                  ///< The size of the block
00308   ) {}
00309 
00310   /// @brief Handle a variable bit rate 32 bit unsigned
00311   virtual void handleVBR32(
00312     unsigned Size  ///< Number of bytes the vbr_uint took up
00313   ) {}
00314 
00315   /// @brief Handle a variable bit rate 64 bit unsigned
00316   virtual void handleVBR64(
00317     unsigned Size  ///< Number of byte sthe vbr_uint64 took up
00318   ) {}
00319 /// @}
00320 
00321 };
00322 
00323 }
00324 // vim: sw=2 ai
00325 #endif