1//===-LTO.h - LLVM Link Time Optimizer ------------------------------------===// 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 declares functions and classes used to support LTO. It is intended 11// to be used both by LTO classes as well as by clients (gold-plugin) that 12// don't utilize the LTO code generator interfaces. 13// 14//===----------------------------------------------------------------------===// 15 16#ifndef LLVM_LTO_LTO_H 17#define LLVM_LTO_LTO_H 18 19#include "llvm/ADT/MapVector.h" 20#include "llvm/ADT/StringMap.h" 21#include "llvm/ADT/StringSet.h" 22#include "llvm/Analysis/ObjectUtils.h" 23#include "llvm/IR/DiagnosticInfo.h" 24#include "llvm/IR/ModuleSummaryIndex.h" 25#include "llvm/LTO/Config.h" 26#include "llvm/Linker/IRMover.h" 27#include "llvm/Object/IRSymtab.h" 28#include "llvm/Support/Error.h" 29#include "llvm/Support/ToolOutputFile.h" 30#include "llvm/Support/thread.h" 31#include "llvm/Target/TargetOptions.h" 32#include "llvm/Transforms/IPO/FunctionImport.h" 33 34namespace llvm { 35 36class BitcodeModule; 37class Error; 38class LLVMContext; 39class MemoryBufferRef; 40class Module; 41class Target; 42class raw_pwrite_stream; 43 44/// Resolve Weak and LinkOnce values in the \p Index. Linkage changes recorded 45/// in the index and the ThinLTO backends must apply the changes to the Module 46/// via thinLTOResolveWeakForLinkerModule. 47/// 48/// This is done for correctness (if value exported, ensure we always 49/// emit a copy), and compile-time optimization (allow drop of duplicates). 50void thinLTOResolveWeakForLinkerInIndex( 51 ModuleSummaryIndex &Index, 52 function_ref<bool(GlobalValue::GUID, const GlobalValueSummary *)> 53 isPrevailing, 54 function_ref<void(StringRef, GlobalValue::GUID, GlobalValue::LinkageTypes)> 55 recordNewLinkage); 56 57/// Update the linkages in the given \p Index to mark exported values 58/// as external and non-exported values as internal. The ThinLTO backends 59/// must apply the changes to the Module via thinLTOInternalizeModule. 60void thinLTOInternalizeAndPromoteInIndex( 61 ModuleSummaryIndex &Index, 62 function_ref<bool(StringRef, GlobalValue::GUID)> isExported); 63 64namespace lto { 65 66/// Given the original \p Path to an output file, replace any path 67/// prefix matching \p OldPrefix with \p NewPrefix. Also, create the 68/// resulting directory if it does not yet exist. 69std::string getThinLTOOutputFile(const std::string &Path, 70 const std::string &OldPrefix, 71 const std::string &NewPrefix); 72 73/// Setup optimization remarks. 74Expected<std::unique_ptr<tool_output_file>> 75setupOptimizationRemarks(LLVMContext &Context, StringRef LTORemarksFilename, 76 bool LTOPassRemarksWithHotness, int Count = -1); 77 78class LTO; 79struct SymbolResolution; 80class ThinBackendProc; 81 82/// An input file. This is a symbol table wrapper that only exposes the 83/// information that an LTO client should need in order to do symbol resolution. 84class InputFile { 85public: 86 class Symbol; 87 88private: 89 // FIXME: Remove LTO class friendship once we have bitcode symbol tables. 90 friend LTO; 91 InputFile() = default; 92 93 std::vector<BitcodeModule> Mods; 94 SmallVector<char, 0> Strtab; 95 std::vector<Symbol> Symbols; 96 97 // [begin, end) for each module 98 std::vector<std::pair<size_t, size_t>> ModuleSymIndices; 99 100 StringRef TargetTriple, SourceFileName, COFFLinkerOpts; 101 std::vector<StringRef> ComdatTable; 102 103public: 104 ~InputFile(); 105 106 /// Create an InputFile. 107 static Expected<std::unique_ptr<InputFile>> create(MemoryBufferRef Object); 108 109 /// The purpose of this class is to only expose the symbol information that an 110 /// LTO client should need in order to do symbol resolution. 111 class Symbol : irsymtab::Symbol { 112 friend LTO; 113 114 public: 115 Symbol(const irsymtab::Symbol &S) : irsymtab::Symbol(S) {} 116 117 using irsymtab::Symbol::isUndefined; 118 using irsymtab::Symbol::isCommon; 119 using irsymtab::Symbol::isWeak; 120 using irsymtab::Symbol::isIndirect; 121 using irsymtab::Symbol::getName; 122 using irsymtab::Symbol::getVisibility; 123 using irsymtab::Symbol::canBeOmittedFromSymbolTable; 124 using irsymtab::Symbol::isTLS; 125 using irsymtab::Symbol::getComdatIndex; 126 using irsymtab::Symbol::getCommonSize; 127 using irsymtab::Symbol::getCommonAlignment; 128 using irsymtab::Symbol::getCOFFWeakExternalFallback; 129 using irsymtab::Symbol::isExecutable; 130 }; 131 132 /// A range over the symbols in this InputFile. 133 ArrayRef<Symbol> symbols() const { return Symbols; } 134 135 /// Returns linker options specified in the input file. 136 StringRef getCOFFLinkerOpts() const { return COFFLinkerOpts; } 137 138 /// Returns the path to the InputFile. 139 StringRef getName() const; 140 141 /// Returns the input file's target triple. 142 StringRef getTargetTriple() const { return TargetTriple; } 143 144 /// Returns the source file path specified at compile time. 145 StringRef getSourceFileName() const { return SourceFileName; } 146 147 // Returns a table with all the comdats used by this file. 148 ArrayRef<StringRef> getComdatTable() const { return ComdatTable; } 149 150private: 151 ArrayRef<Symbol> module_symbols(unsigned I) const { 152 const auto &Indices = ModuleSymIndices[I]; 153 return {Symbols.data() + Indices.first, Symbols.data() + Indices.second}; 154 } 155}; 156 157/// This class wraps an output stream for a native object. Most clients should 158/// just be able to return an instance of this base class from the stream 159/// callback, but if a client needs to perform some action after the stream is 160/// written to, that can be done by deriving from this class and overriding the 161/// destructor. 162class NativeObjectStream { 163public: 164 NativeObjectStream(std::unique_ptr<raw_pwrite_stream> OS) : OS(std::move(OS)) {} 165 std::unique_ptr<raw_pwrite_stream> OS; 166 virtual ~NativeObjectStream() = default; 167}; 168 169/// This type defines the callback to add a native object that is generated on 170/// the fly. 171/// 172/// Stream callbacks must be thread safe. 173typedef std::function<std::unique_ptr<NativeObjectStream>(unsigned Task)> 174 AddStreamFn; 175 176/// This is the type of a native object cache. To request an item from the 177/// cache, pass a unique string as the Key. For hits, the cached file will be 178/// added to the link and this function will return AddStreamFn(). For misses, 179/// the cache will return a stream callback which must be called at most once to 180/// produce content for the stream. The native object stream produced by the 181/// stream callback will add the file to the link after the stream is written 182/// to. 183/// 184/// Clients generally look like this: 185/// 186/// if (AddStreamFn AddStream = Cache(Task, Key)) 187/// ProduceContent(AddStream); 188typedef std::function<AddStreamFn(unsigned Task, StringRef Key)> 189 NativeObjectCache; 190 191/// A ThinBackend defines what happens after the thin-link phase during ThinLTO. 192/// The details of this type definition aren't important; clients can only 193/// create a ThinBackend using one of the create*ThinBackend() functions below. 194typedef std::function<std::unique_ptr<ThinBackendProc>( 195 Config &C, ModuleSummaryIndex &CombinedIndex, 196 StringMap<GVSummaryMapTy> &ModuleToDefinedGVSummaries, 197 AddStreamFn AddStream, NativeObjectCache Cache)> 198 ThinBackend; 199 200/// This ThinBackend runs the individual backend jobs in-process. 201ThinBackend createInProcessThinBackend(unsigned ParallelismLevel); 202 203/// This ThinBackend writes individual module indexes to files, instead of 204/// running the individual backend jobs. This backend is for distributed builds 205/// where separate processes will invoke the real backends. 206/// 207/// To find the path to write the index to, the backend checks if the path has a 208/// prefix of OldPrefix; if so, it replaces that prefix with NewPrefix. It then 209/// appends ".thinlto.bc" and writes the index to that path. If 210/// ShouldEmitImportsFiles is true it also writes a list of imported files to a 211/// similar path with ".imports" appended instead. 212ThinBackend createWriteIndexesThinBackend(std::string OldPrefix, 213 std::string NewPrefix, 214 bool ShouldEmitImportsFiles, 215 std::string LinkedObjectsFile); 216 217/// This class implements a resolution-based interface to LLVM's LTO 218/// functionality. It supports regular LTO, parallel LTO code generation and 219/// ThinLTO. You can use it from a linker in the following way: 220/// - Set hooks and code generation options (see lto::Config struct defined in 221/// Config.h), and use the lto::Config object to create an lto::LTO object. 222/// - Create lto::InputFile objects using lto::InputFile::create(), then use 223/// the symbols() function to enumerate its symbols and compute a resolution 224/// for each symbol (see SymbolResolution below). 225/// - After the linker has visited each input file (and each regular object 226/// file) and computed a resolution for each symbol, take each lto::InputFile 227/// and pass it and an array of symbol resolutions to the add() function. 228/// - Call the getMaxTasks() function to get an upper bound on the number of 229/// native object files that LTO may add to the link. 230/// - Call the run() function. This function will use the supplied AddStream 231/// and Cache functions to add up to getMaxTasks() native object files to 232/// the link. 233class LTO { 234 friend InputFile; 235 236public: 237 /// Create an LTO object. A default constructed LTO object has a reasonable 238 /// production configuration, but you can customize it by passing arguments to 239 /// this constructor. 240 /// FIXME: We do currently require the DiagHandler field to be set in Conf. 241 /// Until that is fixed, a Config argument is required. 242 LTO(Config Conf, ThinBackend Backend = nullptr, 243 unsigned ParallelCodeGenParallelismLevel = 1); 244 ~LTO(); 245 246 /// Add an input file to the LTO link, using the provided symbol resolutions. 247 /// The symbol resolutions must appear in the enumeration order given by 248 /// InputFile::symbols(). 249 Error add(std::unique_ptr<InputFile> Obj, ArrayRef<SymbolResolution> Res); 250 251 /// Returns an upper bound on the number of tasks that the client may expect. 252 /// This may only be called after all IR object files have been added. For a 253 /// full description of tasks see LTOBackend.h. 254 unsigned getMaxTasks() const; 255 256 /// Runs the LTO pipeline. This function calls the supplied AddStream 257 /// function to add native object files to the link. 258 /// 259 /// The Cache parameter is optional. If supplied, it will be used to cache 260 /// native object files and add them to the link. 261 /// 262 /// The client will receive at most one callback (via either AddStream or 263 /// Cache) for each task identifier. 264 Error run(AddStreamFn AddStream, NativeObjectCache Cache = nullptr); 265 266private: 267 Config Conf; 268 269 struct RegularLTOState { 270 RegularLTOState(unsigned ParallelCodeGenParallelismLevel, Config &Conf); 271 struct CommonResolution { 272 uint64_t Size = 0; 273 unsigned Align = 0; 274 /// Record if at least one instance of the common was marked as prevailing 275 bool Prevailing = false; 276 }; 277 std::map<std::string, CommonResolution> Commons; 278 279 unsigned ParallelCodeGenParallelismLevel; 280 LTOLLVMContext Ctx; 281 bool HasModule = false; 282 std::unique_ptr<Module> CombinedModule; 283 std::unique_ptr<IRMover> Mover; 284 285 // This stores the information about a regular LTO module that we have added 286 // to the link. It will either be linked immediately (for modules without 287 // summaries) or after summary-based dead stripping (for modules with 288 // summaries). 289 struct AddedModule { 290 std::unique_ptr<Module> M; 291 std::vector<GlobalValue *> Keep; 292 }; 293 std::vector<AddedModule> ModsWithSummaries; 294 } RegularLTO; 295 296 struct ThinLTOState { 297 ThinLTOState(ThinBackend Backend); 298 299 ThinBackend Backend; 300 ModuleSummaryIndex CombinedIndex; 301 MapVector<StringRef, BitcodeModule> ModuleMap; 302 DenseMap<GlobalValue::GUID, StringRef> PrevailingModuleForGUID; 303 } ThinLTO; 304 305 // The global resolution for a particular (mangled) symbol name. This is in 306 // particular necessary to track whether each symbol can be internalized. 307 // Because any input file may introduce a new cross-partition reference, we 308 // cannot make any final internalization decisions until all input files have 309 // been added and the client has called run(). During run() we apply 310 // internalization decisions either directly to the module (for regular LTO) 311 // or to the combined index (for ThinLTO). 312 struct GlobalResolution { 313 /// The unmangled name of the global. 314 std::string IRName; 315 316 /// Keep track if the symbol is visible outside of a module with a summary 317 /// (i.e. in either a regular object or a regular LTO module without a 318 /// summary). 319 bool VisibleOutsideSummary = false; 320 321 bool UnnamedAddr = true; 322 323 /// This field keeps track of the partition number of this global. The 324 /// regular LTO object is partition 0, while each ThinLTO object has its own 325 /// partition number from 1 onwards. 326 /// 327 /// Any global that is defined or used by more than one partition, or that 328 /// is referenced externally, may not be internalized. 329 /// 330 /// Partitions generally have a one-to-one correspondence with tasks, except 331 /// that we use partition 0 for all parallel LTO code generation partitions. 332 /// Any partitioning of the combined LTO object is done internally by the 333 /// LTO backend. 334 unsigned Partition = Unknown; 335 336 /// Special partition numbers. 337 enum : unsigned { 338 /// A partition number has not yet been assigned to this global. 339 Unknown = -1u, 340 341 /// This global is either used by more than one partition or has an 342 /// external reference, and therefore cannot be internalized. 343 External = -2u, 344 345 /// The RegularLTO partition 346 RegularLTO = 0, 347 }; 348 }; 349 350 // Global mapping from mangled symbol names to resolutions. 351 StringMap<GlobalResolution> GlobalResolutions; 352 353 void addModuleToGlobalRes(ArrayRef<InputFile::Symbol> Syms, 354 ArrayRef<SymbolResolution> Res, unsigned Partition, 355 bool InSummary); 356 357 // These functions take a range of symbol resolutions [ResI, ResE) and consume 358 // the resolutions used by a single input module by incrementing ResI. After 359 // these functions return, [ResI, ResE) will refer to the resolution range for 360 // the remaining modules in the InputFile. 361 Error addModule(InputFile &Input, unsigned ModI, 362 const SymbolResolution *&ResI, const SymbolResolution *ResE); 363 364 Expected<RegularLTOState::AddedModule> 365 addRegularLTO(BitcodeModule BM, ArrayRef<InputFile::Symbol> Syms, 366 const SymbolResolution *&ResI, const SymbolResolution *ResE); 367 Error linkRegularLTO(RegularLTOState::AddedModule Mod, 368 bool LivenessFromIndex); 369 370 Error addThinLTO(BitcodeModule BM, ArrayRef<InputFile::Symbol> Syms, 371 const SymbolResolution *&ResI, const SymbolResolution *ResE); 372 373 Error runRegularLTO(AddStreamFn AddStream); 374 Error runThinLTO(AddStreamFn AddStream, NativeObjectCache Cache, 375 bool HasRegularLTO); 376 377 mutable bool CalledGetMaxTasks = false; 378}; 379 380/// The resolution for a symbol. The linker must provide a SymbolResolution for 381/// each global symbol based on its internal resolution of that symbol. 382struct SymbolResolution { 383 SymbolResolution() 384 : Prevailing(0), FinalDefinitionInLinkageUnit(0), VisibleToRegularObj(0), 385 LinkerRedefined(0) {} 386 387 /// The linker has chosen this definition of the symbol. 388 unsigned Prevailing : 1; 389 390 /// The definition of this symbol is unpreemptable at runtime and is known to 391 /// be in this linkage unit. 392 unsigned FinalDefinitionInLinkageUnit : 1; 393 394 /// The definition of this symbol is visible outside of the LTO unit. 395 unsigned VisibleToRegularObj : 1; 396 397 /// Linker redefined version of the symbol which appeared in -wrap or -defsym 398 /// linker option. 399 unsigned LinkerRedefined : 1; 400}; 401 402} // namespace lto 403} // namespace llvm 404 405#endif 406