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