1 //===-LTO.h - LLVM Link Time Optimizer ------------------------------------===//
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
7 //===----------------------------------------------------------------------===//
9 // This file declares functions and classes used to support LTO. It is intended
10 // to be used both by LTO classes as well as by clients (gold-plugin) that
11 // don't utilize the LTO code generator interfaces.
13 //===----------------------------------------------------------------------===//
15 #ifndef LLVM_LTO_LTO_H
16 #define LLVM_LTO_LTO_H
18 #include "llvm/ADT/MapVector.h"
19 #include "llvm/ADT/StringMap.h"
20 #include "llvm/Bitcode/BitcodeReader.h"
21 #include "llvm/IR/ModuleSummaryIndex.h"
22 #include "llvm/LTO/Config.h"
23 #include "llvm/Object/IRSymtab.h"
24 #include "llvm/Support/Error.h"
25 #include "llvm/Support/thread.h"
26 #include "llvm/Transforms/IPO/FunctionImport.h"
33 class MemoryBufferRef;
35 class raw_pwrite_stream;
39 /// Resolve linkage for prevailing symbols in the \p Index. Linkage changes
40 /// recorded in the index and the ThinLTO backends must apply the changes to
41 /// the module via thinLTOResolvePrevailingInModule.
43 /// This is done for correctness (if value exported, ensure we always
44 /// emit a copy), and compile-time optimization (allow drop of duplicates).
45 void thinLTOResolvePrevailingInIndex(
46 ModuleSummaryIndex &Index,
47 function_ref<bool(GlobalValue::GUID, const GlobalValueSummary *)>
49 function_ref<void(StringRef, GlobalValue::GUID, GlobalValue::LinkageTypes)>
51 const DenseSet<GlobalValue::GUID> &GUIDPreservedSymbols);
53 /// Update the linkages in the given \p Index to mark exported values
54 /// as external and non-exported values as internal. The ThinLTO backends
55 /// must apply the changes to the Module via thinLTOInternalizeModule.
56 void thinLTOInternalizeAndPromoteInIndex(
57 ModuleSummaryIndex &Index,
58 function_ref<bool(StringRef, ValueInfo)> isExported,
59 function_ref<bool(GlobalValue::GUID, const GlobalValueSummary *)>
62 /// Computes a unique hash for the Module considering the current list of
63 /// export/import and other global analysis results.
64 /// The hash is produced in \p Key.
65 void computeLTOCacheKey(
66 SmallString<40> &Key, const lto::Config &Conf,
67 const ModuleSummaryIndex &Index, StringRef ModuleID,
68 const FunctionImporter::ImportMapTy &ImportList,
69 const FunctionImporter::ExportSetTy &ExportList,
70 const std::map<GlobalValue::GUID, GlobalValue::LinkageTypes> &ResolvedODR,
71 const GVSummaryMapTy &DefinedGlobals,
72 const std::set<GlobalValue::GUID> &CfiFunctionDefs = {},
73 const std::set<GlobalValue::GUID> &CfiFunctionDecls = {});
77 /// Given the original \p Path to an output file, replace any path
78 /// prefix matching \p OldPrefix with \p NewPrefix. Also, create the
79 /// resulting directory if it does not yet exist.
80 std::string getThinLTOOutputFile(const std::string &Path,
81 const std::string &OldPrefix,
82 const std::string &NewPrefix);
84 /// Setup optimization remarks.
85 Expected<std::unique_ptr<ToolOutputFile>>
86 setupLLVMOptimizationRemarks(LLVMContext &Context, StringRef RemarksFilename,
87 StringRef RemarksPasses, StringRef RemarksFormat,
88 bool RemarksWithHotness, int Count = -1);
90 /// Setups the output file for saving statistics.
91 Expected<std::unique_ptr<ToolOutputFile>>
92 setupStatsFile(StringRef StatsFilename);
95 struct SymbolResolution;
96 class ThinBackendProc;
98 /// An input file. This is a symbol table wrapper that only exposes the
99 /// information that an LTO client should need in order to do symbol resolution.
105 // FIXME: Remove LTO class friendship once we have bitcode symbol tables.
107 InputFile() = default;
109 std::vector<BitcodeModule> Mods;
110 SmallVector<char, 0> Strtab;
111 std::vector<Symbol> Symbols;
113 // [begin, end) for each module
114 std::vector<std::pair<size_t, size_t>> ModuleSymIndices;
116 StringRef TargetTriple, SourceFileName, COFFLinkerOpts;
117 std::vector<StringRef> DependentLibraries;
118 std::vector<StringRef> ComdatTable;
123 /// Create an InputFile.
124 static Expected<std::unique_ptr<InputFile>> create(MemoryBufferRef Object);
126 /// The purpose of this class is to only expose the symbol information that an
127 /// LTO client should need in order to do symbol resolution.
128 class Symbol : irsymtab::Symbol {
132 Symbol(const irsymtab::Symbol &S) : irsymtab::Symbol(S) {}
134 using irsymtab::Symbol::isUndefined;
135 using irsymtab::Symbol::isCommon;
136 using irsymtab::Symbol::isWeak;
137 using irsymtab::Symbol::isIndirect;
138 using irsymtab::Symbol::getName;
139 using irsymtab::Symbol::getIRName;
140 using irsymtab::Symbol::getVisibility;
141 using irsymtab::Symbol::canBeOmittedFromSymbolTable;
142 using irsymtab::Symbol::isTLS;
143 using irsymtab::Symbol::getComdatIndex;
144 using irsymtab::Symbol::getCommonSize;
145 using irsymtab::Symbol::getCommonAlignment;
146 using irsymtab::Symbol::getCOFFWeakExternalFallback;
147 using irsymtab::Symbol::getSectionName;
148 using irsymtab::Symbol::isExecutable;
149 using irsymtab::Symbol::isUsed;
152 /// A range over the symbols in this InputFile.
153 ArrayRef<Symbol> symbols() const { return Symbols; }
155 /// Returns linker options specified in the input file.
156 StringRef getCOFFLinkerOpts() const { return COFFLinkerOpts; }
158 /// Returns dependent library specifiers from the input file.
159 ArrayRef<StringRef> getDependentLibraries() const { return DependentLibraries; }
161 /// Returns the path to the InputFile.
162 StringRef getName() const;
164 /// Returns the input file's target triple.
165 StringRef getTargetTriple() const { return TargetTriple; }
167 /// Returns the source file path specified at compile time.
168 StringRef getSourceFileName() const { return SourceFileName; }
170 // Returns a table with all the comdats used by this file.
171 ArrayRef<StringRef> getComdatTable() const { return ComdatTable; }
173 // Returns the only BitcodeModule from InputFile.
174 BitcodeModule &getSingleBitcodeModule();
177 ArrayRef<Symbol> module_symbols(unsigned I) const {
178 const auto &Indices = ModuleSymIndices[I];
179 return {Symbols.data() + Indices.first, Symbols.data() + Indices.second};
183 /// This class wraps an output stream for a native object. Most clients should
184 /// just be able to return an instance of this base class from the stream
185 /// callback, but if a client needs to perform some action after the stream is
186 /// written to, that can be done by deriving from this class and overriding the
188 class NativeObjectStream {
190 NativeObjectStream(std::unique_ptr<raw_pwrite_stream> OS) : OS(std::move(OS)) {}
191 std::unique_ptr<raw_pwrite_stream> OS;
192 virtual ~NativeObjectStream() = default;
195 /// This type defines the callback to add a native object that is generated on
198 /// Stream callbacks must be thread safe.
200 std::function<std::unique_ptr<NativeObjectStream>(unsigned Task)>;
202 /// This is the type of a native object cache. To request an item from the
203 /// cache, pass a unique string as the Key. For hits, the cached file will be
204 /// added to the link and this function will return AddStreamFn(). For misses,
205 /// the cache will return a stream callback which must be called at most once to
206 /// produce content for the stream. The native object stream produced by the
207 /// stream callback will add the file to the link after the stream is written
210 /// Clients generally look like this:
212 /// if (AddStreamFn AddStream = Cache(Task, Key))
213 /// ProduceContent(AddStream);
214 using NativeObjectCache =
215 std::function<AddStreamFn(unsigned Task, StringRef Key)>;
217 /// A ThinBackend defines what happens after the thin-link phase during ThinLTO.
218 /// The details of this type definition aren't important; clients can only
219 /// create a ThinBackend using one of the create*ThinBackend() functions below.
220 using ThinBackend = std::function<std::unique_ptr<ThinBackendProc>(
221 const Config &C, ModuleSummaryIndex &CombinedIndex,
222 StringMap<GVSummaryMapTy> &ModuleToDefinedGVSummaries,
223 AddStreamFn AddStream, NativeObjectCache Cache)>;
225 /// This ThinBackend runs the individual backend jobs in-process.
226 /// The default value means to use one job per hardware core (not hyper-thread).
227 ThinBackend createInProcessThinBackend(ThreadPoolStrategy Parallelism);
229 /// This ThinBackend writes individual module indexes to files, instead of
230 /// running the individual backend jobs. This backend is for distributed builds
231 /// where separate processes will invoke the real backends.
233 /// To find the path to write the index to, the backend checks if the path has a
234 /// prefix of OldPrefix; if so, it replaces that prefix with NewPrefix. It then
235 /// appends ".thinlto.bc" and writes the index to that path. If
236 /// ShouldEmitImportsFiles is true it also writes a list of imported files to a
237 /// similar path with ".imports" appended instead.
238 /// LinkedObjectsFile is an output stream to write the list of object files for
239 /// the final ThinLTO linking. Can be nullptr.
240 /// OnWrite is callback which receives module identifier and notifies LTO user
241 /// that index file for the module (and optionally imports file) was created.
242 using IndexWriteCallback = std::function<void(const std::string &)>;
243 ThinBackend createWriteIndexesThinBackend(std::string OldPrefix,
244 std::string NewPrefix,
245 bool ShouldEmitImportsFiles,
246 raw_fd_ostream *LinkedObjectsFile,
247 IndexWriteCallback OnWrite);
249 /// This class implements a resolution-based interface to LLVM's LTO
250 /// functionality. It supports regular LTO, parallel LTO code generation and
251 /// ThinLTO. You can use it from a linker in the following way:
252 /// - Set hooks and code generation options (see lto::Config struct defined in
253 /// Config.h), and use the lto::Config object to create an lto::LTO object.
254 /// - Create lto::InputFile objects using lto::InputFile::create(), then use
255 /// the symbols() function to enumerate its symbols and compute a resolution
256 /// for each symbol (see SymbolResolution below).
257 /// - After the linker has visited each input file (and each regular object
258 /// file) and computed a resolution for each symbol, take each lto::InputFile
259 /// and pass it and an array of symbol resolutions to the add() function.
260 /// - Call the getMaxTasks() function to get an upper bound on the number of
261 /// native object files that LTO may add to the link.
262 /// - Call the run() function. This function will use the supplied AddStream
263 /// and Cache functions to add up to getMaxTasks() native object files to
269 /// Create an LTO object. A default constructed LTO object has a reasonable
270 /// production configuration, but you can customize it by passing arguments to
271 /// this constructor.
272 /// FIXME: We do currently require the DiagHandler field to be set in Conf.
273 /// Until that is fixed, a Config argument is required.
274 LTO(Config Conf, ThinBackend Backend = nullptr,
275 unsigned ParallelCodeGenParallelismLevel = 1);
278 /// Add an input file to the LTO link, using the provided symbol resolutions.
279 /// The symbol resolutions must appear in the enumeration order given by
280 /// InputFile::symbols().
281 Error add(std::unique_ptr<InputFile> Obj, ArrayRef<SymbolResolution> Res);
283 /// Returns an upper bound on the number of tasks that the client may expect.
284 /// This may only be called after all IR object files have been added. For a
285 /// full description of tasks see LTOBackend.h.
286 unsigned getMaxTasks() const;
288 /// Runs the LTO pipeline. This function calls the supplied AddStream
289 /// function to add native object files to the link.
291 /// The Cache parameter is optional. If supplied, it will be used to cache
292 /// native object files and add them to the link.
294 /// The client will receive at most one callback (via either AddStream or
295 /// Cache) for each task identifier.
296 Error run(AddStreamFn AddStream, NativeObjectCache Cache = nullptr);
298 /// Static method that returns a list of libcall symbols that can be generated
299 /// by LTO but might not be visible from bitcode symbol table.
300 static ArrayRef<const char*> getRuntimeLibcallSymbols();
305 struct RegularLTOState {
306 RegularLTOState(unsigned ParallelCodeGenParallelismLevel,
308 struct CommonResolution {
311 /// Record if at least one instance of the common was marked as prevailing
312 bool Prevailing = false;
314 std::map<std::string, CommonResolution> Commons;
316 unsigned ParallelCodeGenParallelismLevel;
318 std::unique_ptr<Module> CombinedModule;
319 std::unique_ptr<IRMover> Mover;
321 // This stores the information about a regular LTO module that we have added
322 // to the link. It will either be linked immediately (for modules without
323 // summaries) or after summary-based dead stripping (for modules with
326 std::unique_ptr<Module> M;
327 std::vector<GlobalValue *> Keep;
329 std::vector<AddedModule> ModsWithSummaries;
330 bool EmptyCombinedModule = true;
333 using ModuleMapType = MapVector<StringRef, BitcodeModule>;
335 struct ThinLTOState {
336 ThinLTOState(ThinBackend Backend);
339 ModuleSummaryIndex CombinedIndex;
340 // The full set of bitcode modules in input order.
341 ModuleMapType ModuleMap;
342 // The bitcode modules to compile, if specified by the LTO Config.
343 Optional<ModuleMapType> ModulesToCompile;
344 DenseMap<GlobalValue::GUID, StringRef> PrevailingModuleForGUID;
347 // The global resolution for a particular (mangled) symbol name. This is in
348 // particular necessary to track whether each symbol can be internalized.
349 // Because any input file may introduce a new cross-partition reference, we
350 // cannot make any final internalization decisions until all input files have
351 // been added and the client has called run(). During run() we apply
352 // internalization decisions either directly to the module (for regular LTO)
353 // or to the combined index (for ThinLTO).
354 struct GlobalResolution {
355 /// The unmangled name of the global.
358 /// Keep track if the symbol is visible outside of a module with a summary
359 /// (i.e. in either a regular object or a regular LTO module without a
361 bool VisibleOutsideSummary = false;
363 bool UnnamedAddr = true;
365 /// True if module contains the prevailing definition.
366 bool Prevailing = false;
368 /// Returns true if module contains the prevailing definition and symbol is
369 /// an IR symbol. For example when module-level inline asm block is used,
370 /// symbol can be prevailing in module but have no IR name.
371 bool isPrevailingIRSymbol() const { return Prevailing && !IRName.empty(); }
373 /// This field keeps track of the partition number of this global. The
374 /// regular LTO object is partition 0, while each ThinLTO object has its own
375 /// partition number from 1 onwards.
377 /// Any global that is defined or used by more than one partition, or that
378 /// is referenced externally, may not be internalized.
380 /// Partitions generally have a one-to-one correspondence with tasks, except
381 /// that we use partition 0 for all parallel LTO code generation partitions.
382 /// Any partitioning of the combined LTO object is done internally by the
384 unsigned Partition = Unknown;
386 /// Special partition numbers.
388 /// A partition number has not yet been assigned to this global.
391 /// This global is either used by more than one partition or has an
392 /// external reference, and therefore cannot be internalized.
395 /// The RegularLTO partition
400 // Global mapping from mangled symbol names to resolutions.
401 StringMap<GlobalResolution> GlobalResolutions;
403 void addModuleToGlobalRes(ArrayRef<InputFile::Symbol> Syms,
404 ArrayRef<SymbolResolution> Res, unsigned Partition,
407 // These functions take a range of symbol resolutions [ResI, ResE) and consume
408 // the resolutions used by a single input module by incrementing ResI. After
409 // these functions return, [ResI, ResE) will refer to the resolution range for
410 // the remaining modules in the InputFile.
411 Error addModule(InputFile &Input, unsigned ModI,
412 const SymbolResolution *&ResI, const SymbolResolution *ResE);
414 Expected<RegularLTOState::AddedModule>
415 addRegularLTO(BitcodeModule BM, ArrayRef<InputFile::Symbol> Syms,
416 const SymbolResolution *&ResI, const SymbolResolution *ResE);
417 Error linkRegularLTO(RegularLTOState::AddedModule Mod,
418 bool LivenessFromIndex);
420 Error addThinLTO(BitcodeModule BM, ArrayRef<InputFile::Symbol> Syms,
421 const SymbolResolution *&ResI, const SymbolResolution *ResE);
423 Error runRegularLTO(AddStreamFn AddStream);
424 Error runThinLTO(AddStreamFn AddStream, NativeObjectCache Cache,
425 const DenseSet<GlobalValue::GUID> &GUIDPreservedSymbols);
427 Error checkPartiallySplit();
429 mutable bool CalledGetMaxTasks = false;
431 // Use Optional to distinguish false from not yet initialized.
432 Optional<bool> EnableSplitLTOUnit;
435 /// The resolution for a symbol. The linker must provide a SymbolResolution for
436 /// each global symbol based on its internal resolution of that symbol.
437 struct SymbolResolution {
439 : Prevailing(0), FinalDefinitionInLinkageUnit(0), VisibleToRegularObj(0),
440 LinkerRedefined(0) {}
442 /// The linker has chosen this definition of the symbol.
443 unsigned Prevailing : 1;
445 /// The definition of this symbol is unpreemptable at runtime and is known to
446 /// be in this linkage unit.
447 unsigned FinalDefinitionInLinkageUnit : 1;
449 /// The definition of this symbol is visible outside of the LTO unit.
450 unsigned VisibleToRegularObj : 1;
452 /// Linker redefined version of the symbol which appeared in -wrap or -defsym
454 unsigned LinkerRedefined : 1;