LLVM  16.0.0git
BitcodeReader.h
Go to the documentation of this file.
1 //===- llvm/Bitcode/BitcodeReader.h - Bitcode reader ------------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 //
9 // This header defines interfaces to read LLVM bitcode files/streams.
10 //
11 //===----------------------------------------------------------------------===//
12 
13 #ifndef LLVM_BITCODE_BITCODEREADER_H
14 #define LLVM_BITCODE_BITCODEREADER_H
15 
16 #include "llvm/ADT/ArrayRef.h"
17 #include "llvm/ADT/StringRef.h"
19 #include "llvm/Support/Endian.h"
20 #include "llvm/Support/Error.h"
21 #include "llvm/Support/ErrorOr.h"
23 #include <cstdint>
24 #include <memory>
25 #include <string>
26 #include <system_error>
27 #include <vector>
28 namespace llvm {
29 
30 class LLVMContext;
31 class Module;
32 class MemoryBuffer;
33 class ModuleSummaryIndex;
34 
37 
38  // These functions are for converting Expected/Error values to
39  // ErrorOr/std::error_code for compatibility with legacy clients. FIXME:
40  // Remove these functions once no longer needed by the C and libLTO APIs.
41 
42  std::error_code errorToErrorCodeAndEmitErrors(LLVMContext &Ctx, Error Err);
43 
44  template <typename T>
46  if (!Val)
47  return errorToErrorCodeAndEmitErrors(Ctx, Val.takeError());
48  return std::move(*Val);
49  }
50 
51  struct BitcodeFileContents;
52 
53  /// Basic information extracted from a bitcode module to be used for LTO.
54  struct BitcodeLTOInfo {
55  bool IsThinLTO;
56  bool HasSummary;
58  };
59 
60  /// Represents a module in a bitcode file.
61  class BitcodeModule {
62  // This covers the identification (if present) and module blocks.
63  ArrayRef<uint8_t> Buffer;
64  StringRef ModuleIdentifier;
65 
66  // The string table used to interpret this module.
67  StringRef Strtab;
68 
69  // The bitstream location of the IDENTIFICATION_BLOCK.
70  uint64_t IdentificationBit;
71 
72  // The bitstream location of this module's MODULE_BLOCK.
73  uint64_t ModuleBit;
74 
75  BitcodeModule(ArrayRef<uint8_t> Buffer, StringRef ModuleIdentifier,
76  uint64_t IdentificationBit, uint64_t ModuleBit)
77  : Buffer(Buffer), ModuleIdentifier(ModuleIdentifier),
78  IdentificationBit(IdentificationBit), ModuleBit(ModuleBit) {}
79 
80  // Calls the ctor.
83 
85  getModuleImpl(LLVMContext &Context, bool MaterializeAll,
86  bool ShouldLazyLoadMetadata, bool IsImporting,
87  DataLayoutCallbackTy DataLayoutCallback);
88 
89  public:
90  StringRef getBuffer() const {
91  return StringRef((const char *)Buffer.begin(), Buffer.size());
92  }
93 
94  StringRef getStrtab() const { return Strtab; }
95 
96  StringRef getModuleIdentifier() const { return ModuleIdentifier; }
97 
98  /// Read the bitcode module and prepare for lazy deserialization of function
99  /// bodies. If ShouldLazyLoadMetadata is true, lazily load metadata as well.
100  /// If IsImporting is true, this module is being parsed for ThinLTO
101  /// importing into another module.
103  bool ShouldLazyLoadMetadata,
104  bool IsImporting);
105 
106  /// Read the entire bitcode module and return it.
108  LLVMContext &Context, DataLayoutCallbackTy DataLayoutCallback =
109  [](StringRef) { return None; });
110 
111  /// Returns information about the module to be used for LTO: whether to
112  /// compile with ThinLTO, and whether it has a summary.
113  Expected<BitcodeLTOInfo> getLTOInfo();
114 
115  /// Parse the specified bitcode buffer, returning the module summary index.
116  Expected<std::unique_ptr<ModuleSummaryIndex>> getSummary();
117 
118  /// Parse the specified bitcode buffer and merge its module summary index
119  /// into CombinedIndex.
120  Error readSummary(ModuleSummaryIndex &CombinedIndex, StringRef ModulePath,
121  uint64_t ModuleId);
122  };
123 
125  std::vector<BitcodeModule> Mods;
127  };
128 
129  /// Returns the contents of a bitcode file. This includes the raw contents of
130  /// the symbol table embedded in the bitcode file. Clients which require a
131  /// symbol table should prefer to use irsymtab::read instead of this function
132  /// because it creates a reader for the irsymtab and handles upgrading bitcode
133  /// files without a symbol table or with an old symbol table.
135 
136  /// Returns a list of modules in the specified bitcode buffer.
139 
140  /// Read the header of the specified bitcode buffer and prepare for lazy
141  /// deserialization of function bodies. If ShouldLazyLoadMetadata is true,
142  /// lazily load metadata as well. If IsImporting is true, this module is
143  /// being parsed for ThinLTO importing into another module.
146  bool ShouldLazyLoadMetadata = false,
147  bool IsImporting = false);
148 
149  /// Like getLazyBitcodeModule, except that the module takes ownership of
150  /// the memory buffer if successful. If successful, this moves Buffer. On
151  /// error, this *does not* move Buffer. If IsImporting is true, this module is
152  /// being parsed for ThinLTO importing into another module.
154  std::unique_ptr<MemoryBuffer> &&Buffer, LLVMContext &Context,
155  bool ShouldLazyLoadMetadata = false, bool IsImporting = false);
156 
157  /// Read the header of the specified bitcode buffer and extract just the
158  /// triple information. If successful, this returns a string. On error, this
159  /// returns "".
161 
162  /// Return true if \p Buffer contains a bitcode file with ObjC code (category
163  /// or class) in it.
165 
166  /// Read the header of the specified bitcode buffer and extract just the
167  /// producer string information. If successful, this returns a string. On
168  /// error, this returns "".
170 
171  /// Read the specified bitcode file, returning the module.
174  DataLayoutCallbackTy DataLayoutCallback = [](StringRef) {
175  return None;
176  });
177 
178  /// Returns LTO information for the specified bitcode file.
179  Expected<BitcodeLTOInfo> getBitcodeLTOInfo(MemoryBufferRef Buffer);
180 
181  /// Parse the specified bitcode buffer, returning the module summary index.
182  Expected<std::unique_ptr<ModuleSummaryIndex>>
183  getModuleSummaryIndex(MemoryBufferRef Buffer);
184 
185  /// Parse the specified bitcode buffer and merge the index into CombinedIndex.
186  Error readModuleSummaryIndex(MemoryBufferRef Buffer,
187  ModuleSummaryIndex &CombinedIndex,
188  uint64_t ModuleId);
189 
190  /// Parse the module summary index out of an IR file and return the module
191  /// summary index object if found, or an empty summary if not. If Path refers
192  /// to an empty file and IgnoreEmptyThinLTOIndexFile is true, then
193  /// this function will return nullptr.
194  Expected<std::unique_ptr<ModuleSummaryIndex>>
195  getModuleSummaryIndexForFile(StringRef Path,
196  bool IgnoreEmptyThinLTOIndexFile = false);
197 
198  /// isBitcodeWrapper - Return true if the given bytes are the magic bytes
199  /// for an LLVM IR bitcode wrapper.
200  inline bool isBitcodeWrapper(const unsigned char *BufPtr,
201  const unsigned char *BufEnd) {
202  // See if you can find the hidden message in the magic bytes :-).
203  // (Hint: it's a little-endian encoding.)
204  return BufPtr != BufEnd &&
205  BufPtr[0] == 0xDE &&
206  BufPtr[1] == 0xC0 &&
207  BufPtr[2] == 0x17 &&
208  BufPtr[3] == 0x0B;
209  }
210 
211  /// isRawBitcode - Return true if the given bytes are the magic bytes for
212  /// raw LLVM IR bitcode (without a wrapper).
213  inline bool isRawBitcode(const unsigned char *BufPtr,
214  const unsigned char *BufEnd) {
215  // These bytes sort of have a hidden message, but it's not in
216  // little-endian this time, and it's a little redundant.
217  return BufPtr != BufEnd &&
218  BufPtr[0] == 'B' &&
219  BufPtr[1] == 'C' &&
220  BufPtr[2] == 0xc0 &&
221  BufPtr[3] == 0xde;
222  }
223 
224  /// isBitcode - Return true if the given bytes are the magic bytes for
225  /// LLVM IR bitcode, either with or without a wrapper.
226  inline bool isBitcode(const unsigned char *BufPtr,
227  const unsigned char *BufEnd) {
228  return isBitcodeWrapper(BufPtr, BufEnd) ||
229  isRawBitcode(BufPtr, BufEnd);
230  }
231 
232  /// SkipBitcodeWrapperHeader - Some systems wrap bc files with a special
233  /// header for padding or other reasons. The format of this header is:
234  ///
235  /// struct bc_header {
236  /// uint32_t Magic; // 0x0B17C0DE
237  /// uint32_t Version; // Version, currently always 0.
238  /// uint32_t BitcodeOffset; // Offset to traditional bitcode file.
239  /// uint32_t BitcodeSize; // Size of traditional bitcode file.
240  /// ... potentially other gunk ...
241  /// };
242  ///
243  /// This function is called when we find a file with a matching magic number.
244  /// In this case, skip down to the subsection of the file that is actually a
245  /// BC file.
246  /// If 'VerifyBufferSize' is true, check that the buffer is large enough to
247  /// contain the whole bitcode file.
248  inline bool SkipBitcodeWrapperHeader(const unsigned char *&BufPtr,
249  const unsigned char *&BufEnd,
250  bool VerifyBufferSize) {
251  // Must contain the offset and size field!
252  if (unsigned(BufEnd - BufPtr) < BWH_SizeField + 4)
253  return true;
254 
255  unsigned Offset = support::endian::read32le(&BufPtr[BWH_OffsetField]);
256  unsigned Size = support::endian::read32le(&BufPtr[BWH_SizeField]);
257  uint64_t BitcodeOffsetEnd = (uint64_t)Offset + (uint64_t)Size;
258 
259  // Verify that Offset+Size fits in the file.
260  if (VerifyBufferSize && BitcodeOffsetEnd > uint64_t(BufEnd-BufPtr))
261  return true;
262  BufPtr += Offset;
263  BufEnd = BufPtr+Size;
264  return false;
265  }
266 
267  APInt readWideAPInt(ArrayRef<uint64_t> Vals, unsigned TypeBits);
268 
269  const std::error_category &BitcodeErrorCategory();
270  enum class BitcodeError { CorruptedBitcode = 1 };
271  inline std::error_code make_error_code(BitcodeError E) {
272  return std::error_code(static_cast<int>(E), BitcodeErrorCategory());
273  }
274 
275 } // end namespace llvm
276 
277 namespace std {
278 
279 template <> struct is_error_code_enum<llvm::BitcodeError> : std::true_type {};
280 
281 } // end namespace std
282 
283 #endif // LLVM_BITCODE_BITCODEREADER_H
llvm::getOwningLazyBitcodeModule
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.
Definition: BitcodeReader.cpp:7887
llvm::expectedToErrorOrAndEmitErrors
ErrorOr< T > expectedToErrorOrAndEmitErrors(LLVMContext &Ctx, Expected< T > Val)
Definition: BitcodeReader.h:45
llvm::BitcodeError::CorruptedBitcode
@ CorruptedBitcode
llvm::BitcodeModule::parseModule
Expected< std::unique_ptr< Module > > parseModule(LLVMContext &Context, DataLayoutCallbackTy DataLayoutCallback=[](StringRef) { return None;})
Read the entire bitcode module and return it.
Definition: BitcodeReader.cpp:7898
llvm
This is an optimization pass for GlobalISel generic memory operations.
Definition: AddressRanges.h:18
llvm::BitcodeModule::getBuffer
StringRef getBuffer() const
Definition: BitcodeReader.h:90
llvm::BitcodeModule::readSummary
Error readSummary(ModuleSummaryIndex &CombinedIndex, StringRef ModulePath, uint64_t ModuleId)
Parse the specified bitcode buffer and merge its module summary index into CombinedIndex.
Definition: BitcodeReader.cpp:7741
llvm::lltok::Error
@ Error
Definition: LLToken.h:21
BitCodeEnums.h
StringRef.h
llvm::getBitcodeProducerString
Expected< std::string > getBitcodeProducerString(MemoryBufferRef Buffer)
Read the header of the specified bitcode buffer and extract just the producer string information.
Definition: BitcodeReader.cpp:7931
llvm::SkipBitcodeWrapperHeader
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...
Definition: BitcodeReader.h:248
Error.h
MemoryBufferRef.h
llvm::BitcodeFileContents::Symtab
StringRef Symtab
Definition: BitcodeReader.h:126
llvm::readWideAPInt
APInt readWideAPInt(ArrayRef< uint64_t > Vals, unsigned TypeBits)
Definition: BitcodeReader.cpp:2843
llvm::Expected
Tagged union holding either a T or a Error.
Definition: APFloat.h:41
llvm::getModuleSummaryIndex
Expected< std::unique_ptr< ModuleSummaryIndex > > getModuleSummaryIndex(MemoryBufferRef Buffer)
Parse the specified bitcode buffer, returning the module summary index.
Definition: BitcodeReader.cpp:7950
llvm::MemoryBufferRef
Definition: MemoryBufferRef.h:22
llvm::BitcodeModule::getModuleIdentifier
StringRef getModuleIdentifier() const
Definition: BitcodeReader.h:96
Context
LLVMContext & Context
Definition: NVVMIntrRange.cpp:66
llvm::BitcodeLTOInfo
Basic information extracted from a bitcode module to be used for LTO.
Definition: BitcodeReader.h:54
llvm::readModuleSummaryIndex
Error readModuleSummaryIndex(MemoryBufferRef Buffer, ModuleSummaryIndex &CombinedIndex, uint64_t ModuleId)
Parse the specified bitcode buffer and merge the index into CombinedIndex.
Definition: BitcodeReader.cpp:7939
llvm::getBitcodeFileContents
Expected< BitcodeFileContents > getBitcodeFileContents(MemoryBufferRef Buffer)
Returns the contents of a bitcode file.
Definition: BitcodeReader.cpp:7573
E
static GCRegistry::Add< CoreCLRGC > E("coreclr", "CoreCLR-compatible GC")
llvm::BitcodeModule::getLTOInfo
Expected< BitcodeLTOInfo > getLTOInfo()
Returns information about the module to be used for LTO: whether to compile with ThinLTO,...
Definition: BitcodeReader.cpp:7813
llvm::isRawBitcode
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 ...
Definition: BitcodeReader.h:213
llvm::BWH_OffsetField
@ BWH_OffsetField
Definition: BitCodeEnums.h:29
llvm::isBitcode
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,...
Definition: BitcodeReader.h:226
llvm::None
const NoneType None
Definition: None.h:24
llvm::BitcodeFileContents
Definition: BitcodeReader.h:124
llvm::errorToErrorCodeAndEmitErrors
std::error_code errorToErrorCodeAndEmitErrors(LLVMContext &Ctx, Error Err)
Definition: BitcodeReader.cpp:944
llvm::BWH_SizeField
@ BWH_SizeField
Definition: BitCodeEnums.h:30
llvm::BitcodeError
BitcodeError
Definition: BitcodeReader.h:270
llvm::function_ref
An efficient, type-erasing, non-owning reference to a callable.
Definition: STLFunctionalExtras.h:36
llvm::BitcodeLTOInfo::HasSummary
bool HasSummary
Definition: BitcodeReader.h:56
llvm::BitcodeModule::getBitcodeFileContents
friend Expected< BitcodeFileContents > getBitcodeFileContents(MemoryBufferRef Buffer)
Returns the contents of a bitcode file.
uint64_t
llvm::parseBitcodeFile
Expected< std::unique_ptr< Module > > parseBitcodeFile(MemoryBufferRef Buffer, LLVMContext &Context, DataLayoutCallbackTy DataLayoutCallback=[](StringRef) { return None;})
Read the specified bitcode file, returning the module.
Definition: BitcodeReader.cpp:7906
move
compiles ldr LCPI1_0 ldr ldr mov lsr tst moveq r1 ldr LCPI1_1 and r0 bx lr It would be better to do something like to fold the shift into the conditional move
Definition: README.txt:546
llvm::LLVMContext
This is an important class for using LLVM in a threaded context.
Definition: LLVMContext.h:67
llvm::BitcodeErrorCategory
const std::error_category & BitcodeErrorCategory()
Definition: BitcodeReader.cpp:7517
ErrorOr.h
ArrayRef.h
llvm::getModuleSummaryIndexForFile
Expected< std::unique_ptr< ModuleSummaryIndex > > getModuleSummaryIndexForFile(StringRef Path, bool IgnoreEmptyThinLTOIndexFile=false)
Parse the module summary index out of an IR file and return the module summary index object if found,...
Definition: BitcodeReader.cpp:7967
llvm::BitcodeFileContents::Mods
std::vector< BitcodeModule > Mods
Definition: BitcodeReader.h:125
llvm::BitcodeModule::getSummary
Expected< std::unique_ptr< ModuleSummaryIndex > > getSummary()
Parse the specified bitcode buffer, returning the module summary index.
Definition: BitcodeReader.cpp:7753
llvm::ArrayRef< uint8_t >
llvm::StringRef
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:50
llvm::getBitcodeTargetTriple
Expected< std::string > getBitcodeTargetTriple(MemoryBufferRef Buffer)
Read the header of the specified bitcode buffer and extract just the triple information.
Definition: BitcodeReader.cpp:7915
Module
Machine Check Debug Module
Definition: MachineCheckDebugify.cpp:122
llvm::make_error_code
std::error_code make_error_code(BitcodeError E)
Definition: BitcodeReader.h:271
llvm::BitcodeModule::getLazyModule
Expected< std::unique_ptr< Module > > getLazyModule(LLVMContext &Context, bool ShouldLazyLoadMetadata, bool IsImporting)
Read the bitcode module and prepare for lazy deserialization of function bodies.
Definition: BitcodeReader.cpp:7731
std
Definition: BitVector.h:851
llvm::BitcodeLTOInfo::EnableSplitLTOUnit
bool EnableSplitLTOUnit
Definition: BitcodeReader.h:57
llvm::isBitcodeWrapper
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.
Definition: BitcodeReader.h:200
llvm::BitcodeModule::getStrtab
StringRef getStrtab() const
Definition: BitcodeReader.h:94
llvm::BitcodeFileContents::StrtabForSymtab
StringRef StrtabForSymtab
Definition: BitcodeReader.h:126
llvm::Expected::takeError
Error takeError()
Take ownership of the stored error.
Definition: Error.h:597
llvm::support::endian::read32le
uint32_t read32le(const void *P)
Definition: Endian.h:381
llvm::ErrorOr
Represents either an error or a value T.
Definition: ErrorOr.h:56
llvm::getBitcodeLTOInfo
Expected< BitcodeLTOInfo > getBitcodeLTOInfo(MemoryBufferRef Buffer)
Returns LTO information for the specified bitcode file.
Definition: BitcodeReader.cpp:7958
llvm::getBitcodeModuleList
Expected< std::vector< BitcodeModule > > getBitcodeModuleList(MemoryBufferRef Buffer)
Returns a list of modules in the specified bitcode buffer.
Definition: BitcodeReader.cpp:7565
llvm::BitcodeModule
Represents a module in a bitcode file.
Definition: BitcodeReader.h:61
llvm::getLazyBitcodeModule
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...
Definition: BitcodeReader.cpp:7878
Endian.h
llvm::isBitcodeContainingObjCCategory
Expected< bool > isBitcodeContainingObjCCategory(MemoryBufferRef Buffer)
Return true if Buffer contains a bitcode file with ObjC code (category or class) in it.
Definition: BitcodeReader.cpp:7923
llvm::DataLayoutCallbackTy
llvm::function_ref< Optional< std::string >StringRef)> DataLayoutCallbackTy
Definition: Parser.h:31
llvm::BitcodeLTOInfo::IsThinLTO
bool IsThinLTO
Definition: BitcodeReader.h:55