1 //===-- llvm/Bytecode/Reader.h - Reader for VM bytecode files ---*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file was developed by the LLVM research group and is distributed under
6 // the University of Illinois Open Source License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 // This functionality is implemented by the lib/Bytecode/Reader library.
11 // This library is used to read VM bytecode files from an iostream.
13 // Note that performance of this library is _crucial_ for performance of the
14 // JIT type applications, so we have designed the bytecode format to support
17 //===----------------------------------------------------------------------===//
19 #ifndef LLVM_BYTECODE_READER_H
20 #define LLVM_BYTECODE_READER_H
22 #include "llvm/System/Path.h"
23 #include "llvm/ModuleProvider.h"
24 #include "llvm/Module.h"
29 // Forward declare the handler class
30 class BytecodeHandler;
32 /// This function returns a ModuleProvider that can be used to do lazy
33 /// function-at-a-time loading from a bytecode file.
34 /// @returns NULL on error
35 /// @returns ModuleProvider* if successful
36 /// @brief Get a ModuleProvide for a bytecode file.
37 ModuleProvider *getBytecodeModuleProvider(
38 const std::string &Filename, ///< Name of file to be read
39 std::string* ErrMsg = 0, ///< Optional error message holder
40 BytecodeHandler* H = 0 ///< Optional handler for reader events
43 /// This function returns a ModuleProvider that can be used to do lazy
44 /// function function-at-a-time loading from a bytecode buffer.
45 /// @returns NULL on error
46 /// @returns ModuleProvider* if successful
47 /// @brief Get a ModuleProvider for a bytecode buffer.
48 ModuleProvider *getBytecodeBufferModuleProvider(
49 const unsigned char *Buffer, ///< Start of buffer to parse
50 unsigned BufferSize, ///< Size of the buffer
51 const std::string &ModuleID, ///< Name to give the module
52 std::string* ErrMsg = 0, ///< Optional place to return an error message
53 BytecodeHandler* H = 0 ///< Optional handler for reader events
56 /// This is the main interface to bytecode parsing. It opens the file specified
57 /// by \p Filename and parses the entire file, returing the corresponding Module
58 /// object if successful.
59 /// @returns NULL on error
60 /// @returns the module corresponding to the bytecode file, if successful
61 /// @brief Parse the given bytecode file
62 Module* ParseBytecodeFile(
63 const std::string &Filename, ///< Name of file to parse
64 std::string *ErrMsg = 0 ///< Optional place to return an error message
67 /// Parses a bytecode buffer specified by \p Buffer and \p BufferSize.
68 /// @returns NULL on error
69 /// @returns the module corresponding to the bytecode buffer, if successful
70 /// @brief Parse a given bytecode buffer
71 Module* ParseBytecodeBuffer(
72 const unsigned char *Buffer, ///< Start of buffer to parse
73 unsigned BufferSize, ///< Size of the buffer
74 const std::string &ModuleID="", ///< Name to give the module
75 std::string *ErrMsg = 0 ///< Optional place to return an error message
78 /// This function will read only the necessary parts of a bytecode file in order
79 /// to determine the list of dependent libraries encoded within it. The \p
80 /// deplibs parameter will contain a vector of strings of the bytecode module's
81 /// dependent libraries.
82 /// @returns true on error, false otherwise
83 /// @brief Get the list of dependent libraries from a bytecode file.
84 bool GetBytecodeDependentLibraries(
85 const std::string &fileName, ///< File name to read bytecode from
86 Module::LibraryListType& deplibs, ///< List of dependent libraries extracted
87 std::string* ErrMsg = 0 ///< Optional error message holder
90 /// This function will read only the necessary parts of a bytecode file in order
91 /// to obtain a list of externally visible global symbols that the bytecode
92 /// module defines. This is used for archiving and linking when only the list
93 /// of symbols the module defines is needed.
94 /// @returns true on error, false otherwise
95 /// @brief Get a bytecode file's externally visibile defined global symbols.
96 bool GetBytecodeSymbols(
97 const sys::Path& fileName, ///< Filename to read bytecode from
98 std::vector<std::string>& syms, ///< Vector to return symbols in
99 std::string* ErrMsg = 0 ///< Optional error message holder
102 /// This function will read only the necessary parts of a bytecode buffer in
103 /// order to obtain a list of externally visible global symbols that the
104 /// bytecode module defines. This is used for archiving and linking when only
105 /// the list of symbols the module defines is needed and the bytecode is
106 /// already in memory.
107 /// @returns the ModuleProvider on success, 0 if the bytecode can't be parsed
108 /// @brief Get a bytecode file's externally visibile defined global symbols.
109 ModuleProvider* GetBytecodeSymbols(
110 const unsigned char*Buffer, ///< The buffer to be parsed
111 unsigned Length, ///< The length of \p Buffer
112 const std::string& ModuleID, ///< An identifier for the module
113 std::vector<std::string>& symbols, ///< The symbols defined in the module
114 std::string* ErrMsg = 0 ///< Optional error message holder
117 } // End llvm namespace