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