LLVM  9.0.0svn
IRSymtab.h
Go to the documentation of this file.
1 //===- IRSymtab.h - data definitions for IR symbol tables -------*- 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 file contains data definitions and a reader and builder for a symbol
10 // table for LLVM IR. Its purpose is to allow linkers and other consumers of
11 // bitcode files to efficiently read the symbol table for symbol resolution
12 // purposes without needing to construct a module in memory.
13 //
14 // As with most object files the symbol table has two parts: the symbol table
15 // itself and a string table which is referenced by the symbol table.
16 //
17 // A symbol table corresponds to a single bitcode file, which may consist of
18 // multiple modules, so symbol tables may likewise contain symbols for multiple
19 // modules.
20 //
21 //===----------------------------------------------------------------------===//
22 
23 #ifndef LLVM_OBJECT_IRSYMTAB_H
24 #define LLVM_OBJECT_IRSYMTAB_H
25 
26 #include "llvm/ADT/ArrayRef.h"
27 #include "llvm/ADT/StringRef.h"
29 #include "llvm/IR/GlobalValue.h"
31 #include "llvm/Support/Endian.h"
32 #include "llvm/Support/Error.h"
33 #include <cassert>
34 #include <cstdint>
35 #include <vector>
36 
37 namespace llvm {
38 
39 struct BitcodeFileContents;
40 class StringTableBuilder;
41 
42 namespace irsymtab {
43 
44 namespace storage {
45 
46 // The data structures in this namespace define the low-level serialization
47 // format. Clients that just want to read a symbol table should use the
48 // irsymtab::Reader class.
49 
51 
52 /// A reference to a string in the string table.
53 struct Str {
55 
56  StringRef get(StringRef Strtab) const {
57  return {Strtab.data() + Offset, Size};
58  }
59 };
60 
61 /// A reference to a range of objects in the symbol table.
62 template <typename T> struct Range {
64 
65  ArrayRef<T> get(StringRef Symtab) const {
66  return {reinterpret_cast<const T *>(Symtab.data() + Offset), Size};
67  }
68 };
69 
70 /// Describes the range of a particular module's symbols within the symbol
71 /// table.
72 struct Module {
73  Word Begin, End;
74 
75  /// The index of the first Uncommon for this Module.
77 };
78 
79 /// This is equivalent to an IR comdat.
80 struct Comdat {
82 };
83 
84 /// Contains the information needed by linkers for symbol resolution, as well as
85 /// by the LTO implementation itself.
86 struct Symbol {
87  /// The mangled symbol name.
89 
90  /// The unmangled symbol name, or the empty string if this is not an IR
91  /// symbol.
93 
94  /// The index into Header::Comdats, or -1 if not a comdat member.
96 
98  enum FlagBits {
99  FB_visibility, // 2 bits
100  FB_has_uncommon = FB_visibility + 2,
112  };
113 };
114 
115 /// This data structure contains rarely used symbol fields and is optionally
116 /// referenced by a Symbol.
117 struct Uncommon {
118  Word CommonSize, CommonAlign;
119 
120  /// COFF-specific: the name of the symbol that a weak external resolves to
121  /// if not defined.
123 
124  /// Specified section name, if any.
126 };
127 
128 struct Header {
129  /// Version number of the symtab format. This number should be incremented
130  /// when the format changes, but it does not need to be incremented if a
131  /// change to LLVM would cause it to create a different symbol table.
133  enum { kCurrentVersion = 1 };
134 
135  /// The producer's version string (LLVM_VERSION_STRING " " LLVM_REVISION).
136  /// Consumers should rebuild the symbol table from IR if the producer's
137  /// version does not match the consumer's version due to potential differences
138  /// in symbol table format, symbol enumeration order and so on.
140 
145 
146  Str TargetTriple, SourceFileName;
147 
148  /// COFF-specific: linker directives.
150 };
151 
152 } // end namespace storage
153 
154 /// Fills in Symtab and StrtabBuilder with a valid symbol and string table for
155 /// Mods.
157  StringTableBuilder &StrtabBuilder, BumpPtrAllocator &Alloc);
158 
159 /// This represents a symbol that has been read from a storage::Symbol and
160 /// possibly a storage::Uncommon.
161 struct Symbol {
162  // Copied from storage::Symbol.
163  StringRef Name, IRName;
166 
167  // Copied from storage::Uncommon.
168  uint32_t CommonSize, CommonAlign;
171 
172  /// Returns the mangled symbol name.
173  StringRef getName() const { return Name; }
174 
175  /// Returns the unmangled symbol name, or the empty string if this is not an
176  /// IR symbol.
177  StringRef getIRName() const { return IRName; }
178 
179  /// Returns the index into the comdat table (see Reader::getComdatTable()), or
180  /// -1 if not a comdat member.
181  int getComdatIndex() const { return ComdatIndex; }
182 
184 
186  return GlobalValue::VisibilityTypes((Flags >> S::FB_visibility) & 3);
187  }
188 
189  bool isUndefined() const { return (Flags >> S::FB_undefined) & 1; }
190  bool isWeak() const { return (Flags >> S::FB_weak) & 1; }
191  bool isCommon() const { return (Flags >> S::FB_common) & 1; }
192  bool isIndirect() const { return (Flags >> S::FB_indirect) & 1; }
193  bool isUsed() const { return (Flags >> S::FB_used) & 1; }
194  bool isTLS() const { return (Flags >> S::FB_tls) & 1; }
195 
197  return (Flags >> S::FB_may_omit) & 1;
198  }
199 
200  bool isGlobal() const { return (Flags >> S::FB_global) & 1; }
201  bool isFormatSpecific() const { return (Flags >> S::FB_format_specific) & 1; }
202  bool isUnnamedAddr() const { return (Flags >> S::FB_unnamed_addr) & 1; }
203  bool isExecutable() const { return (Flags >> S::FB_executable) & 1; }
204 
205  uint64_t getCommonSize() const {
206  assert(isCommon());
207  return CommonSize;
208  }
209 
211  assert(isCommon());
212  return CommonAlign;
213  }
214 
215  /// COFF-specific: for weak externals, returns the name of the symbol that is
216  /// used as a fallback if the weak external remains undefined.
218  assert(isWeak() && isIndirect());
219  return COFFWeakExternFallbackName;
220  }
221 
223 };
224 
225 /// This class can be used to read a Symtab and Strtab produced by
226 /// irsymtab::build.
227 class Reader {
228  StringRef Symtab, Strtab;
229 
233  ArrayRef<storage::Uncommon> Uncommons;
234 
235  StringRef str(storage::Str S) const { return S.get(Strtab); }
236 
237  template <typename T> ArrayRef<T> range(storage::Range<T> R) const {
238  return R.get(Symtab);
239  }
240 
241  const storage::Header &header() const {
242  return *reinterpret_cast<const storage::Header *>(Symtab.data());
243  }
244 
245 public:
246  class SymbolRef;
247 
248  Reader() = default;
249  Reader(StringRef Symtab, StringRef Strtab) : Symtab(Symtab), Strtab(Strtab) {
250  Modules = range(header().Modules);
251  Comdats = range(header().Comdats);
252  Symbols = range(header().Symbols);
253  Uncommons = range(header().Uncommons);
254  }
255 
257 
258  /// Returns the symbol table for the entire bitcode file.
259  /// The symbols enumerated by this method are ephemeral, but they can be
260  /// copied into an irsymtab::Symbol object.
261  symbol_range symbols() const;
262 
263  size_t getNumModules() const { return Modules.size(); }
264 
265  /// Returns a slice of the symbol table for the I'th module in the file.
266  /// The symbols enumerated by this method are ephemeral, but they can be
267  /// copied into an irsymtab::Symbol object.
268  symbol_range module_symbols(unsigned I) const;
269 
270  StringRef getTargetTriple() const { return str(header().TargetTriple); }
271 
272  /// Returns the source file path specified at compile time.
273  StringRef getSourceFileName() const { return str(header().SourceFileName); }
274 
275  /// Returns a table with all the comdats used by this file.
276  std::vector<StringRef> getComdatTable() const {
277  std::vector<StringRef> ComdatTable;
278  ComdatTable.reserve(Comdats.size());
279  for (auto C : Comdats)
280  ComdatTable.push_back(str(C.Name));
281  return ComdatTable;
282  }
283 
284  /// COFF-specific: returns linker options specified in the input file.
285  StringRef getCOFFLinkerOpts() const { return str(header().COFFLinkerOpts); }
286 };
287 
288 /// Ephemeral symbols produced by Reader::symbols() and
289 /// Reader::module_symbols().
290 class Reader::SymbolRef : public Symbol {
291  const storage::Symbol *SymI, *SymE;
292  const storage::Uncommon *UncI;
293  const Reader *R;
294 
295  void read() {
296  if (SymI == SymE)
297  return;
298 
299  Name = R->str(SymI->Name);
300  IRName = R->str(SymI->IRName);
301  ComdatIndex = SymI->ComdatIndex;
302  Flags = SymI->Flags;
303 
304  if (Flags & (1 << storage::Symbol::FB_has_uncommon)) {
305  CommonSize = UncI->CommonSize;
306  CommonAlign = UncI->CommonAlign;
307  COFFWeakExternFallbackName = R->str(UncI->COFFWeakExternFallbackName);
308  SectionName = R->str(UncI->SectionName);
309  } else
310  // Reset this field so it can be queried unconditionally for all symbols.
311  SectionName = "";
312  }
313 
314 public:
315  SymbolRef(const storage::Symbol *SymI, const storage::Symbol *SymE,
316  const storage::Uncommon *UncI, const Reader *R)
317  : SymI(SymI), SymE(SymE), UncI(UncI), R(R) {
318  read();
319  }
320 
321  void moveNext() {
322  ++SymI;
323  if (Flags & (1 << storage::Symbol::FB_has_uncommon))
324  ++UncI;
325  read();
326  }
327 
328  bool operator==(const SymbolRef &Other) const { return SymI == Other.SymI; }
329 };
330 
332  return {SymbolRef(Symbols.begin(), Symbols.end(), Uncommons.begin(), this),
333  SymbolRef(Symbols.end(), Symbols.end(), nullptr, this)};
334 }
335 
337  const storage::Module &M = Modules[I];
338  const storage::Symbol *MBegin = Symbols.begin() + M.Begin,
339  *MEnd = Symbols.begin() + M.End;
340  return {SymbolRef(MBegin, MEnd, Uncommons.begin() + M.UncBegin, this),
341  SymbolRef(MEnd, MEnd, nullptr, this)};
342 }
343 
344 /// The contents of the irsymtab in a bitcode file. Any underlying data for the
345 /// irsymtab are owned by Symtab and Strtab.
346 struct FileContents {
349 };
350 
351 /// Reads the contents of a bitcode file, creating its irsymtab if necessary.
353 
354 } // end namespace irsymtab
355 } // end namespace llvm
356 
357 #endif // LLVM_OBJECT_IRSYMTAB_H
uint64_t CallInst * C
StringRef getIRName() const
Returns the unmangled symbol name, or the empty string if this is not an IR symbol.
Definition: IRSymtab.h:177
GlobalValue::VisibilityTypes getVisibility() const
Definition: IRSymtab.h:185
StringRef getCOFFWeakExternalFallback() const
COFF-specific: for weak externals, returns the name of the symbol that is used as a fallback if the w...
Definition: IRSymtab.h:217
bool isTLS() const
Definition: IRSymtab.h:194
This class represents lattice values for constants.
Definition: AllocatorList.h:23
Contains the information needed by linkers for symbol resolution, as well as by the LTO implementatio...
Definition: IRSymtab.h:86
amdgpu Simplify well known AMD library false FunctionCallee Value const Twine & Name
This provides a very simple, boring adaptor for a begin and end iterator into a range type...
Reader(StringRef Symtab, StringRef Strtab)
Definition: IRSymtab.h:249
symbol_range module_symbols(unsigned I) const
Returns a slice of the symbol table for the I&#39;th module in the file.
Definition: IRSymtab.h:336
Word ComdatIndex
The index into Header::Comdats, or -1 if not a comdat member.
Definition: IRSymtab.h:95
bool isExecutable() const
Definition: IRSymtab.h:203
Str SectionName
Specified section name, if any.
Definition: IRSymtab.h:125
bool canBeOmittedFromSymbolTable() const
Definition: IRSymtab.h:196
Str IRName
The unmangled symbol name, or the empty string if this is not an IR symbol.
Definition: IRSymtab.h:92
A reference to a range of objects in the symbol table.
Definition: IRSymtab.h:62
bool isFormatSpecific() const
Definition: IRSymtab.h:201
size_t getNumModules() const
Definition: IRSymtab.h:263
The contents of the irsymtab in a bitcode file.
Definition: IRSymtab.h:346
Tagged union holding either a T or a Error.
Definition: CachePruning.h:22
bool isCommon() const
Definition: IRSymtab.h:191
Utility for building string tables with deduplicated suffixes.
SmallVector< char, 0 > Symtab
Definition: IRSymtab.h:347
VisibilityTypes
An enumeration for the kinds of visibility of global values.
Definition: GlobalValue.h:62
bool isUndefined() const
Definition: IRSymtab.h:189
ArrayRef - Represent a constant reference to an array (0 or more elements consecutively in memory)...
Definition: APInt.h:32
StringRef SectionName
Definition: IRSymtab.h:170
StringRef getName() const
Returns the mangled symbol name.
Definition: IRSymtab.h:173
A reference to a string in the string table.
Definition: IRSymtab.h:53
Ephemeral symbols produced by Reader::symbols() and Reader::module_symbols().
Definition: IRSymtab.h:290
Error build(ArrayRef< Module *> Mods, SmallVector< char, 0 > &Symtab, StringTableBuilder &StrtabBuilder, BumpPtrAllocator &Alloc)
Fills in Symtab and StrtabBuilder with a valid symbol and string table for Mods.
Definition: IRSymtab.cpp:322
Describes the range of a particular module&#39;s symbols within the symbol table.
Definition: IRSymtab.h:72
Word Version
Version number of the symtab format.
Definition: IRSymtab.h:132
uint32_t getCommonAlignment() const
Definition: IRSymtab.h:210
detail::packed_endian_specific_integral< uint32_t, little, unaligned > ulittle32_t
Definition: Endian.h:274
Allocate memory in an ever growing pool, as if by bump-pointer.
Definition: Allocator.h:140
size_t size() const
size - Get the array size.
Definition: ArrayRef.h:148
bool isIndirect() const
Definition: IRSymtab.h:192
Str COFFLinkerOpts
COFF-specific: linker directives.
Definition: IRSymtab.h:149
Str Name
The mangled symbol name.
Definition: IRSymtab.h:88
symbol_range symbols() const
Returns the symbol table for the entire bitcode file.
Definition: IRSymtab.h:331
bool isUsed() const
Definition: IRSymtab.h:193
This data structure contains rarely used symbol fields and is optionally referenced by a Symbol...
Definition: IRSymtab.h:117
ArrayRef< T > get(StringRef Symtab) const
Definition: IRSymtab.h:65
This represents a symbol that has been read from a storage::Symbol and possibly a storage::Uncommon...
Definition: IRSymtab.h:161
StringRef getSectionName() const
Definition: IRSymtab.h:222
Range< Uncommon > Uncommons
Definition: IRSymtab.h:144
int getComdatIndex() const
Returns the index into the comdat table (see Reader::getComdatTable()), or -1 if not a comdat member...
Definition: IRSymtab.h:181
bool operator==(const SymbolRef &Other) const
Definition: IRSymtab.h:328
StringRef getSourceFileName() const
Returns the source file path specified at compile time.
Definition: IRSymtab.h:273
StringRef getCOFFLinkerOpts() const
COFF-specific: returns linker options specified in the input file.
Definition: IRSymtab.h:285
std::vector< StringRef > getComdatTable() const
Returns a table with all the comdats used by this file.
Definition: IRSymtab.h:276
Expected< FileContents > readBitcode(const BitcodeFileContents &BFC)
Reads the contents of a bitcode file, creating its irsymtab if necessary.
Definition: IRSymtab.cpp:361
A range adaptor for a pair of iterators.
static bool isWeak(const MCSymbolELF &Sym)
bool isGlobal() const
Definition: IRSymtab.h:200
StringRef getTargetTriple() const
Definition: IRSymtab.h:270
Str Producer
The producer&#39;s version string (LLVM_VERSION_STRING " " LLVM_REVISION).
Definition: IRSymtab.h:139
bool isWeak() const
Definition: IRSymtab.h:190
value_type read(const void *memory, endianness endian)
Read a value of a particular endianness from memory.
Definition: Endian.h:65
SymbolRef(const storage::Symbol *SymI, const storage::Symbol *SymE, const storage::Uncommon *UncI, const Reader *R)
Definition: IRSymtab.h:315
#define I(x, y, z)
Definition: MD5.cpp:58
LLVM_NODISCARD const char * data() const
data - Get a pointer to the start of the string (which may not be null terminated).
Definition: StringRef.h:122
assert(ImpDefSCC.getReg()==AMDGPU::SCC &&ImpDefSCC.isDef())
bool isUnnamedAddr() const
Definition: IRSymtab.h:202
This is equivalent to an IR comdat.
Definition: IRSymtab.h:80
Lightweight error class with error context and mandatory checking.
Definition: Error.h:157
uint64_t getCommonSize() const
Definition: IRSymtab.h:205
const char SectionName[]
Definition: AMDGPUPTNote.h:23
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:48
StringRef COFFWeakExternFallbackName
Definition: IRSymtab.h:169
StringRef get(StringRef Strtab) const
Definition: IRSymtab.h:56
Word UncBegin
The index of the first Uncommon for this Module.
Definition: IRSymtab.h:76
This class can be used to read a Symtab and Strtab produced by irsymtab::build.
Definition: IRSymtab.h:227
Str COFFWeakExternFallbackName
COFF-specific: the name of the symbol that a weak external resolves to if not defined.
Definition: IRSymtab.h:122