contrib/llvm/include/llvm/Object/IRSymtab.h

   1 //===- IRSymtab.h - data definitions for IR symbol tables -------*- 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 file contains data definitions and a reader and builder for a symbol
  11 // table for LLVM IR. Its purpose is to allow linkers and other consumers of
  12 // bitcode files to efficiently read the symbol table for symbol resolution
  13 // purposes without needing to construct a module in memory.
  14 //
  15 // As with most object files the symbol table has two parts: the symbol table
  16 // itself and a string table which is referenced by the symbol table.
  17 //
  18 // A symbol table corresponds to a single bitcode file, which may consist of
  19 // multiple modules, so symbol tables may likewise contain symbols for multiple
  20 // modules.
  21 //
  22 //===----------------------------------------------------------------------===//
  23
  24 #ifndef LLVM_OBJECT_IRSYMTAB_H
  25 #define LLVM_OBJECT_IRSYMTAB_H
  26
  27 #include "llvm/ADT/ArrayRef.h"
  28 #include "llvm/ADT/iterator_range.h"
  29 #include "llvm/ADT/StringRef.h"
  30 #include "llvm/IR/GlobalValue.h"
  31 #include "llvm/Object/SymbolicFile.h"
  32 #include "llvm/Support/Endian.h"
  33 #include "llvm/Support/Error.h"
  34 #include <cassert>
  35 #include <cstdint>
  36 #include <vector>
  37
  38 namespace llvm {
  39 namespace irsymtab {
  40
  41 namespace storage {
  42
  43 // The data structures in this namespace define the low-level serialization
  44 // format. Clients that just want to read a symbol table should use the
  45 // irsymtab::Reader class.
  46
  47 using Word = support::ulittle32_t;
  48
  49 /// A reference to a string in the string table.
  50 struct Str {
  51   Word Offset, Size;
  52
  53   StringRef get(StringRef Strtab) const {
  54     return {Strtab.data() + Offset, Size};
  55   }
  56 };
  57
  58 /// A reference to a range of objects in the symbol table.
  59 template <typename T> struct Range {
  60   Word Offset, Size;
  61
  62   ArrayRef<T> get(StringRef Symtab) const {
  63     return {reinterpret_cast<const T *>(Symtab.data() + Offset), Size};
  64   }
  65 };
  66
  67 /// Describes the range of a particular module's symbols within the symbol
  68 /// table.
  69 struct Module {
  70   Word Begin, End;
  71
  72   /// The index of the first Uncommon for this Module.
  73   Word UncBegin;
  74 };
  75
  76 /// This is equivalent to an IR comdat.
  77 struct Comdat {
  78   Str Name;
  79 };
  80
  81 /// Contains the information needed by linkers for symbol resolution, as well as
  82 /// by the LTO implementation itself.
  83 struct Symbol {
  84   /// The mangled symbol name.
  85   Str Name;
  86
  87   /// The unmangled symbol name, or the empty string if this is not an IR
  88   /// symbol.
  89   Str IRName;
  90
  91   /// The index into Header::Comdats, or -1 if not a comdat member.
  92   Word ComdatIndex;
  93
  94   Word Flags;
  95   enum FlagBits {
  96     FB_visibility, // 2 bits
  97     FB_has_uncommon = FB_visibility + 2,
  98     FB_undefined,
  99     FB_weak,
 100     FB_common,
 101     FB_indirect,
 102     FB_used,
 103     FB_tls,
 104     FB_may_omit,
 105     FB_global,
 106     FB_format_specific,
 107     FB_unnamed_addr,
 108     FB_executable,
 109   };
 110 };
 111
 112 /// This data structure contains rarely used symbol fields and is optionally
 113 /// referenced by a Symbol.
 114 struct Uncommon {
 115   Word CommonSize, CommonAlign;
 116
 117   /// COFF-specific: the name of the symbol that a weak external resolves to
 118   /// if not defined.
 119   Str COFFWeakExternFallbackName;
 120 };
 121
 122 struct Header {
 123   Range<Module> Modules;
 124   Range<Comdat> Comdats;
 125   Range<Symbol> Symbols;
 126   Range<Uncommon> Uncommons;
 127
 128   Str TargetTriple, SourceFileName;
 129
 130   /// COFF-specific: linker directives.
 131   Str COFFLinkerOpts;
 132 };
 133
 134 } // end namespace storage
 135
 136 /// Fills in Symtab and Strtab with a valid symbol and string table for Mods.
 137 Error build(ArrayRef<Module *> Mods, SmallVector<char, 0> &Symtab,
 138             SmallVector<char, 0> &Strtab);
 139
 140 /// This represents a symbol that has been read from a storage::Symbol and
 141 /// possibly a storage::Uncommon.
 142 struct Symbol {
 143   // Copied from storage::Symbol.
 144   StringRef Name, IRName;
 145   int ComdatIndex;
 146   uint32_t Flags;
 147
 148   // Copied from storage::Uncommon.
 149   uint32_t CommonSize, CommonAlign;
 150   StringRef COFFWeakExternFallbackName;
 151
 152   /// Returns the mangled symbol name.
 153   StringRef getName() const { return Name; }
 154
 155   /// Returns the unmangled symbol name, or the empty string if this is not an
 156   /// IR symbol.
 157   StringRef getIRName() const { return IRName; }
 158
 159   /// Returns the index into the comdat table (see Reader::getComdatTable()), or
 160   /// -1 if not a comdat member.
 161   int getComdatIndex() const { return ComdatIndex; }
 162
 163   using S = storage::Symbol;
 164
 165   GlobalValue::VisibilityTypes getVisibility() const {
 166     return GlobalValue::VisibilityTypes((Flags >> S::FB_visibility) & 3);
 167   }
 168
 169   bool isUndefined() const { return (Flags >> S::FB_undefined) & 1; }
 170   bool isWeak() const { return (Flags >> S::FB_weak) & 1; }
 171   bool isCommon() const { return (Flags >> S::FB_common) & 1; }
 172   bool isIndirect() const { return (Flags >> S::FB_indirect) & 1; }
 173   bool isUsed() const { return (Flags >> S::FB_used) & 1; }
 174   bool isTLS() const { return (Flags >> S::FB_tls) & 1; }
 175
 176   bool canBeOmittedFromSymbolTable() const {
 177     return (Flags >> S::FB_may_omit) & 1;
 178   }
 179
 180   bool isGlobal() const { return (Flags >> S::FB_global) & 1; }
 181   bool isFormatSpecific() const { return (Flags >> S::FB_format_specific) & 1; }
 182   bool isUnnamedAddr() const { return (Flags >> S::FB_unnamed_addr) & 1; }
 183   bool isExecutable() const { return (Flags >> S::FB_executable) & 1; }
 184
 185   uint64_t getCommonSize() const {
 186     assert(isCommon());
 187     return CommonSize;
 188   }
 189
 190   uint32_t getCommonAlignment() const {
 191     assert(isCommon());
 192     return CommonAlign;
 193   }
 194
 195   /// COFF-specific: for weak externals, returns the name of the symbol that is
 196   /// used as a fallback if the weak external remains undefined.
 197   StringRef getCOFFWeakExternalFallback() const {
 198     assert(isWeak() && isIndirect());
 199     return COFFWeakExternFallbackName;
 200   }
 201 };
 202
 203 /// This class can be used to read a Symtab and Strtab produced by
 204 /// irsymtab::build.
 205 class Reader {
 206   StringRef Symtab, Strtab;
 207
 208   ArrayRef<storage::Module> Modules;
 209   ArrayRef<storage::Comdat> Comdats;
 210   ArrayRef<storage::Symbol> Symbols;
 211   ArrayRef<storage::Uncommon> Uncommons;
 212
 213   StringRef str(storage::Str S) const { return S.get(Strtab); }
 214
 215   template <typename T> ArrayRef<T> range(storage::Range<T> R) const {
 216     return R.get(Symtab);
 217   }
 218
 219   const storage::Header &header() const {
 220     return *reinterpret_cast<const storage::Header *>(Symtab.data());
 221   }
 222
 223 public:
 224   class SymbolRef;
 225
 226   Reader() = default;
 227   Reader(StringRef Symtab, StringRef Strtab) : Symtab(Symtab), Strtab(Strtab) {
 228     Modules = range(header().Modules);
 229     Comdats = range(header().Comdats);
 230     Symbols = range(header().Symbols);
 231     Uncommons = range(header().Uncommons);
 232   }
 233
 234   using symbol_range = iterator_range<object::content_iterator<SymbolRef>>;
 235
 236   /// Returns the symbol table for the entire bitcode file.
 237   /// The symbols enumerated by this method are ephemeral, but they can be
 238   /// copied into an irsymtab::Symbol object.
 239   symbol_range symbols() const;
 240
 241   /// Returns a slice of the symbol table for the I'th module in the file.
 242   /// The symbols enumerated by this method are ephemeral, but they can be
 243   /// copied into an irsymtab::Symbol object.
 244   symbol_range module_symbols(unsigned I) const;
 245
 246   StringRef getTargetTriple() const { return str(header().TargetTriple); }
 247
 248   /// Returns the source file path specified at compile time.
 249   StringRef getSourceFileName() const { return str(header().SourceFileName); }
 250
 251   /// Returns a table with all the comdats used by this file.
 252   std::vector<StringRef> getComdatTable() const {
 253     std::vector<StringRef> ComdatTable;
 254     ComdatTable.reserve(Comdats.size());
 255     for (auto C : Comdats)
 256       ComdatTable.push_back(str(C.Name));
 257     return ComdatTable;
 258   }
 259
 260   /// COFF-specific: returns linker options specified in the input file.
 261   StringRef getCOFFLinkerOpts() const { return str(header().COFFLinkerOpts); }
 262 };
 263
 264 /// Ephemeral symbols produced by Reader::symbols() and
 265 /// Reader::module_symbols().
 266 class Reader::SymbolRef : public Symbol {
 267   const storage::Symbol *SymI, *SymE;
 268   const storage::Uncommon *UncI;
 269   const Reader *R;
 270
 271   void read() {
 272     if (SymI == SymE)
 273       return;
 274
 275     Name = R->str(SymI->Name);
 276     IRName = R->str(SymI->IRName);
 277     ComdatIndex = SymI->ComdatIndex;
 278     Flags = SymI->Flags;
 279
 280     if (Flags & (1 << storage::Symbol::FB_has_uncommon)) {
 281       CommonSize = UncI->CommonSize;
 282       CommonAlign = UncI->CommonAlign;
 283       COFFWeakExternFallbackName = R->str(UncI->COFFWeakExternFallbackName);
 284     }
 285   }
 286
 287 public:
 288   SymbolRef(const storage::Symbol *SymI, const storage::Symbol *SymE,
 289             const storage::Uncommon *UncI, const Reader *R)
 290       : SymI(SymI), SymE(SymE), UncI(UncI), R(R) {
 291     read();
 292   }
 293
 294   void moveNext() {
 295     ++SymI;
 296     if (Flags & (1 << storage::Symbol::FB_has_uncommon))
 297       ++UncI;
 298     read();
 299   }
 300
 301   bool operator==(const SymbolRef &Other) const { return SymI == Other.SymI; }
 302 };
 303
 304 inline Reader::symbol_range Reader::symbols() const {
 305   return {SymbolRef(Symbols.begin(), Symbols.end(), Uncommons.begin(), this),
 306           SymbolRef(Symbols.end(), Symbols.end(), nullptr, this)};
 307 }
 308
 309 inline Reader::symbol_range Reader::module_symbols(unsigned I) const {
 310   const storage::Module &M = Modules[I];
 311   const storage::Symbol *MBegin = Symbols.begin() + M.Begin,
 312                         *MEnd = Symbols.begin() + M.End;
 313   return {SymbolRef(MBegin, MEnd, Uncommons.begin() + M.UncBegin, this),
 314           SymbolRef(MEnd, MEnd, nullptr, this)};
 315 }
 316
 317 } // end namespace irsymtab
 318 } // end namespace llvm
 319
 320 #endif // LLVM_OBJECT_IRSYMTAB_H