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"
28 #include "llvm/ADT/iterator_range.h"
29 #include "llvm/IR/Comdat.h"
30 #include "llvm/IR/GlobalValue.h"
31 #include "llvm/Object/SymbolicFile.h"
32 #include "llvm/Support/Allocator.h"
33 #include "llvm/Support/Endian.h"
34 #include "llvm/Support/Error.h"
35 #include <cassert>
36 #include <cstdint>
37 #include <vector>
38 
39 namespace llvm {
40 
41 struct BitcodeFileContents;
42 class StringTableBuilder;
43 
44 namespace irsymtab {
45 
46 namespace storage {
47 
48 // The data structures in this namespace define the low-level serialization
49 // format. Clients that just want to read a symbol table should use the
50 // irsymtab::Reader class.
51 
52 using Word = support::ulittle32_t;
53 
54 /// A reference to a string in the string table.
55 struct Str {
56   Word Offset, Size;
57 
58   StringRef get(StringRef Strtab) const {
59     return {Strtab.data() + Offset, Size};
60   }
61 };
62 
63 /// A reference to a range of objects in the symbol table.
64 template <typename T> struct Range {
65   Word Offset, Size;
66 
67   ArrayRef<T> get(StringRef Symtab) const {
68     return {reinterpret_cast<const T *>(Symtab.data() + Offset), Size};
69   }
70 };
71 
72 /// Describes the range of a particular module's symbols within the symbol
73 /// table.
74 struct Module {
75   Word Begin, End;
76 
77   /// The index of the first Uncommon for this Module.
78   Word UncBegin;
79 };
80 
81 /// This is equivalent to an IR comdat.
82 struct Comdat {
83   Str Name;
84 
85   // llvm::Comdat::SelectionKind
86   Word SelectionKind;
87 };
88 
89 /// Contains the information needed by linkers for symbol resolution, as well as
90 /// by the LTO implementation itself.
91 struct Symbol {
92   /// The mangled symbol name.
93   Str Name;
94 
95   /// The unmangled symbol name, or the empty string if this is not an IR
96   /// symbol.
97   Str IRName;
98 
99   /// The index into Header::Comdats, or -1 if not a comdat member.
100   Word ComdatIndex;
101 
102   Word Flags;
103   enum FlagBits {
104     FB_visibility, // 2 bits
105     FB_has_uncommon = FB_visibility + 2,
106     FB_undefined,
107     FB_weak,
108     FB_common,
109     FB_indirect,
110     FB_used,
111     FB_tls,
112     FB_may_omit,
113     FB_global,
114     FB_format_specific,
115     FB_unnamed_addr,
116     FB_executable,
117   };
118 };
119 
120 /// This data structure contains rarely used symbol fields and is optionally
121 /// referenced by a Symbol.
122 struct Uncommon {
123   Word CommonSize, CommonAlign;
124 
125   /// COFF-specific: the name of the symbol that a weak external resolves to
126   /// if not defined.
127   Str COFFWeakExternFallbackName;
128 
129   /// Specified section name, if any.
130   Str SectionName;
131 };
132 
133 
134 struct Header {
135   /// Version number of the symtab format. This number should be incremented
136   /// when the format changes, but it does not need to be incremented if a
137   /// change to LLVM would cause it to create a different symbol table.
138   Word Version;
139   enum { kCurrentVersion = 3 };
140 
141   /// The producer's version string (LLVM_VERSION_STRING " " LLVM_REVISION).
142   /// Consumers should rebuild the symbol table from IR if the producer's
143   /// version does not match the consumer's version due to potential differences
144   /// in symbol table format, symbol enumeration order and so on.
145   Str Producer;
146 
147   Range<Module> Modules;
148   Range<Comdat> Comdats;
149   Range<Symbol> Symbols;
150   Range<Uncommon> Uncommons;
151 
152   Str TargetTriple, SourceFileName;
153 
154   /// COFF-specific: linker directives.
155   Str COFFLinkerOpts;
156 
157   /// Dependent Library Specifiers
158   Range<Str> DependentLibraries;
159 };
160 
161 } // end namespace storage
162 
163 /// Fills in Symtab and StrtabBuilder with a valid symbol and string table for
164 /// Mods.
165 Error build(ArrayRef<Module *> Mods, SmallVector<char, 0> &Symtab,
166             StringTableBuilder &StrtabBuilder, BumpPtrAllocator &Alloc);
167 
168 /// This represents a symbol that has been read from a storage::Symbol and
169 /// possibly a storage::Uncommon.
170 struct Symbol {
171   // Copied from storage::Symbol.
172   StringRef Name, IRName;
173   int ComdatIndex;
174   uint32_t Flags;
175 
176   // Copied from storage::Uncommon.
177   uint32_t CommonSize, CommonAlign;
178   StringRef COFFWeakExternFallbackName;
179   StringRef SectionName;
180 
181   /// Returns the mangled symbol name.
182   StringRef getName() const { return Name; }
183 
184   /// Returns the unmangled symbol name, or the empty string if this is not an
185   /// IR symbol.
186   StringRef getIRName() const { return IRName; }
187 
188   /// Returns the index into the comdat table (see Reader::getComdatTable()), or
189   /// -1 if not a comdat member.
190   int getComdatIndex() const { return ComdatIndex; }
191 
192   using S = storage::Symbol;
193 
194   GlobalValue::VisibilityTypes getVisibility() const {
195     return GlobalValue::VisibilityTypes((Flags >> S::FB_visibility) & 3);
196   }
197 
198   bool isUndefined() const { return (Flags >> S::FB_undefined) & 1; }
199   bool isWeak() const { return (Flags >> S::FB_weak) & 1; }
200   bool isCommon() const { return (Flags >> S::FB_common) & 1; }
201   bool isIndirect() const { return (Flags >> S::FB_indirect) & 1; }
202   bool isUsed() const { return (Flags >> S::FB_used) & 1; }
203   bool isTLS() const { return (Flags >> S::FB_tls) & 1; }
204 
205   bool canBeOmittedFromSymbolTable() const {
206     return (Flags >> S::FB_may_omit) & 1;
207   }
208 
209   bool isGlobal() const { return (Flags >> S::FB_global) & 1; }
210   bool isFormatSpecific() const { return (Flags >> S::FB_format_specific) & 1; }
211   bool isUnnamedAddr() const { return (Flags >> S::FB_unnamed_addr) & 1; }
212   bool isExecutable() const { return (Flags >> S::FB_executable) & 1; }
213 
214   uint64_t getCommonSize() const {
215     assert(isCommon());
216     return CommonSize;
217   }
218 
219   uint32_t getCommonAlignment() const {
220     assert(isCommon());
221     return CommonAlign;
222   }
223 
224   /// COFF-specific: for weak externals, returns the name of the symbol that is
225   /// used as a fallback if the weak external remains undefined.
226   StringRef getCOFFWeakExternalFallback() const {
227     assert(isWeak() && isIndirect());
228     return COFFWeakExternFallbackName;
229   }
230 
231   StringRef getSectionName() const { return SectionName; }
232 };
233 
234 /// This class can be used to read a Symtab and Strtab produced by
235 /// irsymtab::build.
236 class Reader {
237   StringRef Symtab, Strtab;
238 
239   ArrayRef<storage::Module> Modules;
240   ArrayRef<storage::Comdat> Comdats;
241   ArrayRef<storage::Symbol> Symbols;
242   ArrayRef<storage::Uncommon> Uncommons;
243   ArrayRef<storage::Str> DependentLibraries;
244 
245   StringRef str(storage::Str S) const { return S.get(Strtab); }
246 
247   template <typename T> ArrayRef<T> range(storage::Range<T> R) const {
248     return R.get(Symtab);
249   }
250 
251   const storage::Header &header() const {
252     return *reinterpret_cast<const storage::Header *>(Symtab.data());
253   }
254 
255 public:
256   class SymbolRef;
257 
258   Reader() = default;
259   Reader(StringRef Symtab, StringRef Strtab) : Symtab(Symtab), Strtab(Strtab) {
260     Modules = range(header().Modules);
261     Comdats = range(header().Comdats);
262     Symbols = range(header().Symbols);
263     Uncommons = range(header().Uncommons);
264     DependentLibraries = range(header().DependentLibraries);
265   }
266 
267   using symbol_range = iterator_range<object::content_iterator<SymbolRef>>;
268 
269   /// Returns the symbol table for the entire bitcode file.
270   /// The symbols enumerated by this method are ephemeral, but they can be
271   /// copied into an irsymtab::Symbol object.
272   symbol_range symbols() const;
273 
274   size_t getNumModules() const { return Modules.size(); }
275 
276   /// Returns a slice of the symbol table for the I'th module in the file.
277   /// The symbols enumerated by this method are ephemeral, but they can be
278   /// copied into an irsymtab::Symbol object.
279   symbol_range module_symbols(unsigned I) const;
280 
281   StringRef getTargetTriple() const { return str(header().TargetTriple); }
282 
283   /// Returns the source file path specified at compile time.
284   StringRef getSourceFileName() const { return str(header().SourceFileName); }
285 
286   /// Returns a table with all the comdats used by this file.
287   std::vector<std::pair<StringRef, llvm::Comdat::SelectionKind>>
288   getComdatTable() const {
289     std::vector<std::pair<StringRef, llvm::Comdat::SelectionKind>> ComdatTable;
290     ComdatTable.reserve(Comdats.size());
291     for (auto C : Comdats)
292       ComdatTable.push_back({str(C.Name), llvm::Comdat::SelectionKind(
293                                               uint32_t(C.SelectionKind))});
294     return ComdatTable;
295   }
296 
297   /// COFF-specific: returns linker options specified in the input file.
298   StringRef getCOFFLinkerOpts() const { return str(header().COFFLinkerOpts); }
299 
300   /// Returns dependent library specifiers
301   std::vector<StringRef> getDependentLibraries() const {
302     std::vector<StringRef> Specifiers;
303     Specifiers.reserve(DependentLibraries.size());
304     for (auto S : DependentLibraries) {
305       Specifiers.push_back(str(S));
306     }
307     return Specifiers;
308   }
309 };
310 
311 /// Ephemeral symbols produced by Reader::symbols() and
312 /// Reader::module_symbols().
313 class Reader::SymbolRef : public Symbol {
314   const storage::Symbol *SymI, *SymE;
315   const storage::Uncommon *UncI;
316   const Reader *R;
317 
318   void read() {
319     if (SymI == SymE)
320       return;
321 
322     Name = R->str(SymI->Name);
323     IRName = R->str(SymI->IRName);
324     ComdatIndex = SymI->ComdatIndex;
325     Flags = SymI->Flags;
326 
327     if (Flags & (1 << storage::Symbol::FB_has_uncommon)) {
328       CommonSize = UncI->CommonSize;
329       CommonAlign = UncI->CommonAlign;
330       COFFWeakExternFallbackName = R->str(UncI->COFFWeakExternFallbackName);
331       SectionName = R->str(UncI->SectionName);
332     } else
333       // Reset this field so it can be queried unconditionally for all symbols.
334       SectionName = "";
335   }
336 
337 public:
338   SymbolRef(const storage::Symbol *SymI, const storage::Symbol *SymE,
339             const storage::Uncommon *UncI, const Reader *R)
340       : SymI(SymI), SymE(SymE), UncI(UncI), R(R) {
341     read();
342   }
343 
344   void moveNext() {
345     ++SymI;
346     if (Flags & (1 << storage::Symbol::FB_has_uncommon))
347       ++UncI;
348     read();
349   }
350 
351   bool operator==(const SymbolRef &Other) const { return SymI == Other.SymI; }
352 };
353 
354 inline Reader::symbol_range Reader::symbols() const {
355   return {SymbolRef(Symbols.begin(), Symbols.end(), Uncommons.begin(), this),
356           SymbolRef(Symbols.end(), Symbols.end(), nullptr, this)};
357 }
358 
359 inline Reader::symbol_range Reader::module_symbols(unsigned I) const {
360   const storage::Module &M = Modules[I];
361   const storage::Symbol *MBegin = Symbols.begin() + M.Begin,
362                         *MEnd = Symbols.begin() + M.End;
363   return {SymbolRef(MBegin, MEnd, Uncommons.begin() + M.UncBegin, this),
364           SymbolRef(MEnd, MEnd, nullptr, this)};
365 }
366 
367 /// The contents of the irsymtab in a bitcode file. Any underlying data for the
368 /// irsymtab are owned by Symtab and Strtab.
369 struct FileContents {
370   SmallVector<char, 0> Symtab, Strtab;
371   Reader TheReader;
372 };
373 
374 /// Reads the contents of a bitcode file, creating its irsymtab if necessary.
375 Expected<FileContents> readBitcode(const BitcodeFileContents &BFC);
376 
377 } // end namespace irsymtab
378 } // end namespace llvm
379 
380 #endif // LLVM_OBJECT_IRSYMTAB_H
381