LLVM  4.0.0
BitcodeReader.h
Go to the documentation of this file.
1 //===-- llvm/Bitcode/BitcodeReader.h - Bitcode reader ----*- C++ -*-===//
2 //
3 // The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 //
10 // This header defines interfaces to read LLVM bitcode files/streams.
11 //
12 //===----------------------------------------------------------------------===//
13 
14 #ifndef LLVM_BITCODE_BITCODEREADER_H
15 #define LLVM_BITCODE_BITCODEREADER_H
16 
17 #include "llvm/Bitcode/BitCodes.h"
18 #include "llvm/IR/DiagnosticInfo.h"
20 #include "llvm/Support/Endian.h"
21 #include "llvm/Support/Error.h"
22 #include "llvm/Support/ErrorOr.h"
24 #include <memory>
25 
26 namespace llvm {
27  class LLVMContext;
28  class Module;
29 
30  // These functions are for converting Expected/Error values to
31  // ErrorOr/std::error_code for compatibility with legacy clients. FIXME:
32  // Remove these functions once no longer needed by the C and libLTO APIs.
33 
34  std::error_code errorToErrorCodeAndEmitErrors(LLVMContext &Ctx, Error Err);
35 
36  template <typename T>
38  if (!Val)
39  return errorToErrorCodeAndEmitErrors(Ctx, Val.takeError());
40  return std::move(*Val);
41  }
42 
43  /// Represents a module in a bitcode file.
44  class BitcodeModule {
45  // This covers the identification (if present) and module blocks.
46  ArrayRef<uint8_t> Buffer;
47  StringRef ModuleIdentifier;
48 
49  // The bitstream location of the IDENTIFICATION_BLOCK.
50  uint64_t IdentificationBit;
51 
52  // The bitstream location of this module's MODULE_BLOCK.
53  uint64_t ModuleBit;
54 
55  BitcodeModule(ArrayRef<uint8_t> Buffer, StringRef ModuleIdentifier,
56  uint64_t IdentificationBit, uint64_t ModuleBit)
57  : Buffer(Buffer), ModuleIdentifier(ModuleIdentifier),
58  IdentificationBit(IdentificationBit), ModuleBit(ModuleBit) {}
59 
60  // Calls the ctor.
63 
65  bool MaterializeAll,
66  bool ShouldLazyLoadMetadata,
67  bool IsImporting);
68 
69  public:
70  StringRef getBuffer() const {
71  return StringRef((const char *)Buffer.begin(), Buffer.size());
72  }
73 
74  StringRef getModuleIdentifier() const { return ModuleIdentifier; }
75 
76  /// Read the bitcode module and prepare for lazy deserialization of function
77  /// bodies. If ShouldLazyLoadMetadata is true, lazily load metadata as well.
78  /// If IsImporting is true, this module is being parsed for ThinLTO
79  /// importing into another module.
81  bool ShouldLazyLoadMetadata,
82  bool IsImporting);
83 
84  /// Read the entire bitcode module and return it.
86 
87  /// Check if the given bitcode buffer contains a summary block.
89 
90  /// Parse the specified bitcode buffer, returning the module summary index.
92  };
93 
94  /// Returns a list of modules in the specified bitcode buffer.
95  Expected<std::vector<BitcodeModule>>
96  getBitcodeModuleList(MemoryBufferRef Buffer);
97 
98  /// Read the header of the specified bitcode buffer and prepare for lazy
99  /// deserialization of function bodies. If ShouldLazyLoadMetadata is true,
100  /// lazily load metadata as well. If IsImporting is true, this module is
101  /// being parsed for ThinLTO importing into another module.
102  Expected<std::unique_ptr<Module>>
103  getLazyBitcodeModule(MemoryBufferRef Buffer, LLVMContext &Context,
104  bool ShouldLazyLoadMetadata = false,
105  bool IsImporting = false);
106 
107  /// Like getLazyBitcodeModule, except that the module takes ownership of
108  /// the memory buffer if successful. If successful, this moves Buffer. On
109  /// error, this *does not* move Buffer. If IsImporting is true, this module is
110  /// being parsed for ThinLTO importing into another module.
111  Expected<std::unique_ptr<Module>> getOwningLazyBitcodeModule(
112  std::unique_ptr<MemoryBuffer> &&Buffer, LLVMContext &Context,
113  bool ShouldLazyLoadMetadata = false, bool IsImporting = false);
114 
115  /// Read the header of the specified bitcode buffer and extract just the
116  /// triple information. If successful, this returns a string. On error, this
117  /// returns "".
118  Expected<std::string> getBitcodeTargetTriple(MemoryBufferRef Buffer);
119 
120  /// Return true if \p Buffer contains a bitcode file with ObjC code (category
121  /// or class) in it.
122  Expected<bool> isBitcodeContainingObjCCategory(MemoryBufferRef Buffer);
123 
124  /// Read the header of the specified bitcode buffer and extract just the
125  /// producer string information. If successful, this returns a string. On
126  /// error, this returns "".
127  Expected<std::string> getBitcodeProducerString(MemoryBufferRef Buffer);
128 
129  /// Read the specified bitcode file, returning the module.
130  Expected<std::unique_ptr<Module>> parseBitcodeFile(MemoryBufferRef Buffer,
131  LLVMContext &Context);
132 
133  /// Check if the given bitcode buffer contains a summary block.
134  Expected<bool> hasGlobalValueSummary(MemoryBufferRef Buffer);
135 
136  /// Parse the specified bitcode buffer, returning the module summary index.
137  Expected<std::unique_ptr<ModuleSummaryIndex>>
138  getModuleSummaryIndex(MemoryBufferRef Buffer);
139 
140  /// isBitcodeWrapper - Return true if the given bytes are the magic bytes
141  /// for an LLVM IR bitcode wrapper.
142  ///
143  inline bool isBitcodeWrapper(const unsigned char *BufPtr,
144  const unsigned char *BufEnd) {
145  // See if you can find the hidden message in the magic bytes :-).
146  // (Hint: it's a little-endian encoding.)
147  return BufPtr != BufEnd &&
148  BufPtr[0] == 0xDE &&
149  BufPtr[1] == 0xC0 &&
150  BufPtr[2] == 0x17 &&
151  BufPtr[3] == 0x0B;
152  }
153 
154  /// isRawBitcode - Return true if the given bytes are the magic bytes for
155  /// raw LLVM IR bitcode (without a wrapper).
156  ///
157  inline bool isRawBitcode(const unsigned char *BufPtr,
158  const unsigned char *BufEnd) {
159  // These bytes sort of have a hidden message, but it's not in
160  // little-endian this time, and it's a little redundant.
161  return BufPtr != BufEnd &&
162  BufPtr[0] == 'B' &&
163  BufPtr[1] == 'C' &&
164  BufPtr[2] == 0xc0 &&
165  BufPtr[3] == 0xde;
166  }
167 
168  /// isBitcode - Return true if the given bytes are the magic bytes for
169  /// LLVM IR bitcode, either with or without a wrapper.
170  ///
171  inline bool isBitcode(const unsigned char *BufPtr,
172  const unsigned char *BufEnd) {
173  return isBitcodeWrapper(BufPtr, BufEnd) ||
174  isRawBitcode(BufPtr, BufEnd);
175  }
176 
177  /// SkipBitcodeWrapperHeader - Some systems wrap bc files with a special
178  /// header for padding or other reasons. The format of this header is:
179  ///
180  /// struct bc_header {
181  /// uint32_t Magic; // 0x0B17C0DE
182  /// uint32_t Version; // Version, currently always 0.
183  /// uint32_t BitcodeOffset; // Offset to traditional bitcode file.
184  /// uint32_t BitcodeSize; // Size of traditional bitcode file.
185  /// ... potentially other gunk ...
186  /// };
187  ///
188  /// This function is called when we find a file with a matching magic number.
189  /// In this case, skip down to the subsection of the file that is actually a
190  /// BC file.
191  /// If 'VerifyBufferSize' is true, check that the buffer is large enough to
192  /// contain the whole bitcode file.
193  inline bool SkipBitcodeWrapperHeader(const unsigned char *&BufPtr,
194  const unsigned char *&BufEnd,
195  bool VerifyBufferSize) {
196  // Must contain the offset and size field!
197  if (unsigned(BufEnd - BufPtr) < BWH_SizeField + 4)
198  return true;
199 
200  unsigned Offset = support::endian::read32le(&BufPtr[BWH_OffsetField]);
201  unsigned Size = support::endian::read32le(&BufPtr[BWH_SizeField]);
202  uint64_t BitcodeOffsetEnd = (uint64_t)Offset + (uint64_t)Size;
203 
204  // Verify that Offset+Size fits in the file.
205  if (VerifyBufferSize && BitcodeOffsetEnd > uint64_t(BufEnd-BufPtr))
206  return true;
207  BufPtr += Offset;
208  BufEnd = BufPtr+Size;
209  return false;
210  }
211 
213  enum class BitcodeError { CorruptedBitcode = 1 };
214  inline std::error_code make_error_code(BitcodeError E) {
215  return std::error_code(static_cast<int>(E), BitcodeErrorCategory());
216  }
217 
218 } // End llvm namespace
219 
220 namespace std {
221 template <> struct is_error_code_enum<llvm::BitcodeError> : std::true_type {};
222 }
223 
224 #endif
Represents either an error or a value T.
Definition: ErrorOr.h:68
LLVMContext & Context
Expected< std::unique_ptr< Module > > getLazyBitcodeModule(MemoryBufferRef Buffer, LLVMContext &Context, bool ShouldLazyLoadMetadata=false, bool IsImporting=false)
Read the header of the specified bitcode buffer and prepare for lazy deserialization of function bodi...
Expected< bool > hasSummary()
Check if the given bitcode buffer contains a summary block.
Expected< std::unique_ptr< ModuleSummaryIndex > > getSummary()
Parse the specified bitcode buffer, returning the module summary index.
bool isBitcodeWrapper(const unsigned char *BufPtr, const unsigned char *BufEnd)
isBitcodeWrapper - Return true if the given bytes are the magic bytes for an LLVM IR bitcode wrapper...
Error takeError()
Take ownership of the stored error.
Expected< std::vector< BitcodeModule > > getBitcodeModuleList(MemoryBufferRef Buffer)
Returns a list of modules in the specified bitcode buffer.
Represents a module in a bitcode file.
Definition: BitcodeReader.h:44
std::error_code make_error_code(BitcodeError E)
Tagged union holding either a T or a Error.
static const unsigned BWH_OffsetField
Definition: BitCodes.h:30
static const unsigned BWH_SizeField
Definition: BitCodes.h:31
const std::error_category & BitcodeErrorCategory()
static GCRegistry::Add< CoreCLRGC > E("coreclr","CoreCLR-compatible GC")
Expected< std::string > getBitcodeProducerString(MemoryBufferRef Buffer)
Read the header of the specified bitcode buffer and extract just the producer string information...
This is an important class for using LLVM in a threaded context.
Definition: LLVMContext.h:48
static ManagedStatic< _object_error_category > error_category
uint32_t Offset
Expected< std::string > getBitcodeTargetTriple(MemoryBufferRef Buffer)
Read the header of the specified bitcode buffer and extract just the triple information.
StringRef getBuffer() const
Definition: BitcodeReader.h:70
Expected< bool > isBitcodeContainingObjCCategory(MemoryBufferRef Buffer)
Return true if Buffer contains a bitcode file with ObjC code (category or class) in it...
bool isBitcode(const unsigned char *BufPtr, const unsigned char *BufEnd)
isBitcode - Return true if the given bytes are the magic bytes for LLVM IR bitcode, either with or without a wrapper.
bool isRawBitcode(const unsigned char *BufPtr, const unsigned char *BufEnd)
isRawBitcode - Return true if the given bytes are the magic bytes for raw LLVM IR bitcode (without a ...
StringRef getModuleIdentifier() const
Definition: BitcodeReader.h:74
Expected< std::unique_ptr< Module > > parseBitcodeFile(MemoryBufferRef Buffer, LLVMContext &Context)
Read the specified bitcode file, returning the module.
ErrorOr< T > expectedToErrorOrAndEmitErrors(LLVMContext &Ctx, Expected< T > Val)
Definition: BitcodeReader.h:37
bool SkipBitcodeWrapperHeader(const unsigned char *&BufPtr, const unsigned char *&BufEnd, bool VerifyBufferSize)
SkipBitcodeWrapperHeader - Some systems wrap bc files with a special header for padding or other reas...
uint32_t read32le(const void *P)
Definition: Endian.h:318
Provides ErrorOr<T> smart pointer.
Expected< std::unique_ptr< Module > > getOwningLazyBitcodeModule(std::unique_ptr< MemoryBuffer > &&Buffer, LLVMContext &Context, bool ShouldLazyLoadMetadata=false, bool IsImporting=false)
Like getLazyBitcodeModule, except that the module takes ownership of the memory buffer if successful...
ModuleSummaryIndex.h This file contains the declarations the classes that hold the module index and s...
std::error_code errorToErrorCodeAndEmitErrors(LLVMContext &Ctx, Error Err)
Expected< std::unique_ptr< ModuleSummaryIndex > > getModuleSummaryIndex(MemoryBufferRef Buffer)
Parse the specified bitcode buffer, returning the module summary index.
Expected< std::unique_ptr< Module > > getLazyModule(LLVMContext &Context, bool ShouldLazyLoadMetadata, bool IsImporting)
Read the bitcode module and prepare for lazy deserialization of function bodies.
Expected< std::unique_ptr< Module > > parseModule(LLVMContext &Context)
Read the entire bitcode module and return it.
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:47
Expected< bool > hasGlobalValueSummary(MemoryBufferRef Buffer)
Check if the given bitcode buffer contains a summary block.
friend Expected< std::vector< BitcodeModule > > getBitcodeModuleList(MemoryBufferRef Buffer)
Returns a list of modules in the specified bitcode buffer.