1//===-LTO.h - LLVM Link Time Optimizer ------------------------------------===//
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 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.
12//
13//===----------------------------------------------------------------------===//
14
15#ifndef LLVM_LTO_LTO_H
16#define LLVM_LTO_LTO_H
17
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/Caching.h"
25#include "llvm/Support/Error.h"
26#include "llvm/Support/thread.h"
27#include "llvm/Transforms/IPO/FunctionAttrs.h"
28#include "llvm/Transforms/IPO/FunctionImport.h"
29
30namespace llvm {
31
32class Error;
33class IRMover;
34class LLVMContext;
35class MemoryBufferRef;
36class Module;
37class raw_pwrite_stream;
38class ToolOutputFile;
39
40/// Resolve linkage for prevailing symbols in the \p Index. Linkage changes
41/// recorded in the index and the ThinLTO backends must apply the changes to
42/// the module via thinLTOFinalizeInModule.
43///
44/// This is done for correctness (if value exported, ensure we always
45/// emit a copy), and compile-time optimization (allow drop of duplicates).
46void thinLTOResolvePrevailingInIndex(
47 const lto::Config &C, ModuleSummaryIndex &Index,
48 function_ref<bool(GlobalValue::GUID, const GlobalValueSummary *)>
49 isPrevailing,
50 function_ref<void(StringRef, GlobalValue::GUID, GlobalValue::LinkageTypes)>
51 recordNewLinkage,
52 const DenseSet<GlobalValue::GUID> &GUIDPreservedSymbols);
53
54/// Update the linkages in the given \p Index to mark exported values
55/// as external and non-exported values as internal. The ThinLTO backends
56/// must apply the changes to the Module via thinLTOInternalizeModule.
57void thinLTOInternalizeAndPromoteInIndex(
58 ModuleSummaryIndex &Index,
59 function_ref<bool(StringRef, ValueInfo)> isExported,
60 function_ref<bool(GlobalValue::GUID, const GlobalValueSummary *)>
61 isPrevailing);
62
63/// Computes a unique hash for the Module considering the current list of
64/// export/import and other global analysis results.
65/// The hash is produced in \p Key.
66void computeLTOCacheKey(
67 SmallString<40> &Key, const lto::Config &Conf,
68 const ModuleSummaryIndex &Index, StringRef ModuleID,
69 const FunctionImporter::ImportMapTy &ImportList,
70 const FunctionImporter::ExportSetTy &ExportList,
71 const std::map<GlobalValue::GUID, GlobalValue::LinkageTypes> &ResolvedODR,
72 const GVSummaryMapTy &DefinedGlobals,
73 const std::set<GlobalValue::GUID> &CfiFunctionDefs = {},
74 const std::set<GlobalValue::GUID> &CfiFunctionDecls = {});
75
76namespace lto {
77
78/// Given the original \p Path to an output file, replace any path
79/// prefix matching \p OldPrefix with \p NewPrefix. Also, create the
80/// resulting directory if it does not yet exist.
81std::string getThinLTOOutputFile(StringRef Path, StringRef OldPrefix,
82 StringRef NewPrefix);
83
84/// Setup optimization remarks.
85Expected<std::unique_ptr<ToolOutputFile>> setupLLVMOptimizationRemarks(
86 LLVMContext &Context, StringRef RemarksFilename, StringRef RemarksPasses,
87 StringRef RemarksFormat, bool RemarksWithHotness,
88 std::optional<uint64_t> RemarksHotnessThreshold = 0, int Count = -1);
89
90/// Setups the output file for saving statistics.
91Expected<std::unique_ptr<ToolOutputFile>>
92setupStatsFile(StringRef StatsFilename);
93
94/// Produces a container ordering for optimal multi-threaded processing. Returns
95/// ordered indices to elements in the input array.
96std::vector<int> generateModulesOrdering(ArrayRef<BitcodeModule *> R);
97
98/// Updates MemProf attributes (and metadata) based on whether the index
99/// has recorded that we are linking with allocation libraries containing
100/// the necessary APIs for downstream transformations.
101void updateMemProfAttributes(Module &Mod, const ModuleSummaryIndex &Index);
102
103class LTO;
104struct SymbolResolution;
105class ThinBackendProc;
106
107/// An input file. This is a symbol table wrapper that only exposes the
108/// information that an LTO client should need in order to do symbol resolution.
109class InputFile {
110public:
111 class Symbol;
112
113private:
114 // FIXME: Remove LTO class friendship once we have bitcode symbol tables.
115 friend LTO;
116 InputFile() = default;
117
118 std::vector<BitcodeModule> Mods;
119 SmallVector<char, 0> Strtab;
120 std::vector<Symbol> Symbols;
121
122 // [begin, end) for each module
123 std::vector<std::pair<size_t, size_t>> ModuleSymIndices;
124
125 StringRef TargetTriple, SourceFileName, COFFLinkerOpts;
126 std::vector<StringRef> DependentLibraries;
127 std::vector<std::pair<StringRef, Comdat::SelectionKind>> ComdatTable;
128
129public:
130 ~InputFile();
131
132 /// Create an InputFile.
133 static Expected<std::unique_ptr<InputFile>> create(MemoryBufferRef Object);
134
135 /// The purpose of this class is to only expose the symbol information that an
136 /// LTO client should need in order to do symbol resolution.
137 class Symbol : irsymtab::Symbol {
138 friend LTO;
139
140 public:
141 Symbol(const irsymtab::Symbol &S) : irsymtab::Symbol(S) {}
142
143 using irsymtab::Symbol::isUndefined;
144 using irsymtab::Symbol::isCommon;
145 using irsymtab::Symbol::isWeak;
146 using irsymtab::Symbol::isIndirect;
147 using irsymtab::Symbol::getName;
148 using irsymtab::Symbol::getIRName;
149 using irsymtab::Symbol::getVisibility;
150 using irsymtab::Symbol::canBeOmittedFromSymbolTable;
151 using irsymtab::Symbol::isTLS;
152 using irsymtab::Symbol::getComdatIndex;
153 using irsymtab::Symbol::getCommonSize;
154 using irsymtab::Symbol::getCommonAlignment;
155 using irsymtab::Symbol::getCOFFWeakExternalFallback;
156 using irsymtab::Symbol::getSectionName;
157 using irsymtab::Symbol::isExecutable;
158 using irsymtab::Symbol::isUsed;
159 };
160
161 /// A range over the symbols in this InputFile.
162 ArrayRef<Symbol> symbols() const { return Symbols; }
163
164 /// Returns linker options specified in the input file.
165 StringRef getCOFFLinkerOpts() const { return COFFLinkerOpts; }
166
167 /// Returns dependent library specifiers from the input file.
168 ArrayRef<StringRef> getDependentLibraries() const { return DependentLibraries; }
169
170 /// Returns the path to the InputFile.
171 StringRef getName() const;
172
173 /// Returns the input file's target triple.
174 StringRef getTargetTriple() const { return TargetTriple; }
175
176 /// Returns the source file path specified at compile time.
177 StringRef getSourceFileName() const { return SourceFileName; }
178
179 // Returns a table with all the comdats used by this file.
180 ArrayRef<std::pair<StringRef, Comdat::SelectionKind>> getComdatTable() const {
181 return ComdatTable;
182 }
183
184 // Returns the only BitcodeModule from InputFile.
185 BitcodeModule &getSingleBitcodeModule();
186
187private:
188 ArrayRef<Symbol> module_symbols(unsigned I) const {
189 const auto &Indices = ModuleSymIndices[I];
190 return {Symbols.data() + Indices.first, Symbols.data() + Indices.second};
191 }
192};
193
194/// A ThinBackend defines what happens after the thin-link phase during ThinLTO.
195/// The details of this type definition aren't important; clients can only
196/// create a ThinBackend using one of the create*ThinBackend() functions below.
197using ThinBackend = std::function<std::unique_ptr<ThinBackendProc>(
198 const Config &C, ModuleSummaryIndex &CombinedIndex,
199 DenseMap<StringRef, GVSummaryMapTy> &ModuleToDefinedGVSummaries,
200 AddStreamFn AddStream, FileCache Cache)>;
201
202/// This ThinBackend runs the individual backend jobs in-process.
203/// The default value means to use one job per hardware core (not hyper-thread).
204/// OnWrite is callback which receives module identifier and notifies LTO user
205/// that index file for the module (and optionally imports file) was created.
206/// ShouldEmitIndexFiles being true will write sharded ThinLTO index files
207/// to the same path as the input module, with suffix ".thinlto.bc"
208/// ShouldEmitImportsFiles is true it also writes a list of imported files to a
209/// similar path with ".imports" appended instead.
210using IndexWriteCallback = std::function<void(const std::string &)>;
211ThinBackend createInProcessThinBackend(ThreadPoolStrategy Parallelism,
212 IndexWriteCallback OnWrite = nullptr,
213 bool ShouldEmitIndexFiles = false,
214 bool ShouldEmitImportsFiles = false);
215
216/// This ThinBackend writes individual module indexes to files, instead of
217/// running the individual backend jobs. This backend is for distributed builds
218/// where separate processes will invoke the real backends.
219///
220/// To find the path to write the index to, the backend checks if the path has a
221/// prefix of OldPrefix; if so, it replaces that prefix with NewPrefix. It then
222/// appends ".thinlto.bc" and writes the index to that path. If
223/// ShouldEmitImportsFiles is true it also writes a list of imported files to a
224/// similar path with ".imports" appended instead.
225/// LinkedObjectsFile is an output stream to write the list of object files for
226/// the final ThinLTO linking. Can be nullptr. If LinkedObjectsFile is not
227/// nullptr and NativeObjectPrefix is not empty then it replaces the prefix of
228/// the objects with NativeObjectPrefix instead of NewPrefix. OnWrite is
229/// callback which receives module identifier and notifies LTO user that index
230/// file for the module (and optionally imports file) was created.
231ThinBackend createWriteIndexesThinBackend(std::string OldPrefix,
232 std::string NewPrefix,
233 std::string NativeObjectPrefix,
234 bool ShouldEmitImportsFiles,
235 raw_fd_ostream *LinkedObjectsFile,
236 IndexWriteCallback OnWrite);
237
238/// This class implements a resolution-based interface to LLVM's LTO
239/// functionality. It supports regular LTO, parallel LTO code generation and
240/// ThinLTO. You can use it from a linker in the following way:
241/// - Set hooks and code generation options (see lto::Config struct defined in
242/// Config.h), and use the lto::Config object to create an lto::LTO object.
243/// - Create lto::InputFile objects using lto::InputFile::create(), then use
244/// the symbols() function to enumerate its symbols and compute a resolution
245/// for each symbol (see SymbolResolution below).
246/// - After the linker has visited each input file (and each regular object
247/// file) and computed a resolution for each symbol, take each lto::InputFile
248/// and pass it and an array of symbol resolutions to the add() function.
249/// - Call the getMaxTasks() function to get an upper bound on the number of
250/// native object files that LTO may add to the link.
251/// - Call the run() function. This function will use the supplied AddStream
252/// and Cache functions to add up to getMaxTasks() native object files to
253/// the link.
254class LTO {
255 friend InputFile;
256
257public:
258 /// Unified LTO modes
259 enum LTOKind {
260 /// Any LTO mode without Unified LTO. The default mode.
261 LTOK_Default,
262
263 /// Regular LTO, with Unified LTO enabled.
264 LTOK_UnifiedRegular,
265
266 /// ThinLTO, with Unified LTO enabled.
267 LTOK_UnifiedThin,
268 };
269
270 /// Create an LTO object. A default constructed LTO object has a reasonable
271 /// production configuration, but you can customize it by passing arguments to
272 /// this constructor.
273 /// FIXME: We do currently require the DiagHandler field to be set in Conf.
274 /// Until that is fixed, a Config argument is required.
275 LTO(Config Conf, ThinBackend Backend = nullptr,
276 unsigned ParallelCodeGenParallelismLevel = 1,
277 LTOKind LTOMode = LTOK_Default);
278 ~LTO();
279
280 /// Add an input file to the LTO link, using the provided symbol resolutions.
281 /// The symbol resolutions must appear in the enumeration order given by
282 /// InputFile::symbols().
283 Error add(std::unique_ptr<InputFile> Obj, ArrayRef<SymbolResolution> Res);
284
285 /// Returns an upper bound on the number of tasks that the client may expect.
286 /// This may only be called after all IR object files have been added. For a
287 /// full description of tasks see LTOBackend.h.
288 unsigned getMaxTasks() const;
289
290 /// Runs the LTO pipeline. This function calls the supplied AddStream
291 /// function to add native object files to the link.
292 ///
293 /// The Cache parameter is optional. If supplied, it will be used to cache
294 /// native object files and add them to the link.
295 ///
296 /// The client will receive at most one callback (via either AddStream or
297 /// Cache) for each task identifier.
298 Error run(AddStreamFn AddStream, FileCache Cache = nullptr);
299
300 /// Static method that returns a list of libcall symbols that can be generated
301 /// by LTO but might not be visible from bitcode symbol table.
302 static ArrayRef<const char*> getRuntimeLibcallSymbols();
303
304private:
305 Config Conf;
306
307 struct RegularLTOState {
308 RegularLTOState(unsigned ParallelCodeGenParallelismLevel,
309 const Config &Conf);
310 struct CommonResolution {
311 uint64_t Size = 0;
312 Align Alignment;
313 /// Record if at least one instance of the common was marked as prevailing
314 bool Prevailing = false;
315 };
316 std::map<std::string, CommonResolution> Commons;
317
318 unsigned ParallelCodeGenParallelismLevel;
319 LTOLLVMContext Ctx;
320 std::unique_ptr<Module> CombinedModule;
321 std::unique_ptr<IRMover> Mover;
322
323 // This stores the information about a regular LTO module that we have added
324 // to the link. It will either be linked immediately (for modules without
325 // summaries) or after summary-based dead stripping (for modules with
326 // summaries).
327 struct AddedModule {
328 std::unique_ptr<Module> M;
329 std::vector<GlobalValue *> Keep;
330 };
331 std::vector<AddedModule> ModsWithSummaries;
332 bool EmptyCombinedModule = true;
333 } RegularLTO;
334
335 using ModuleMapType = MapVector<StringRef, BitcodeModule>;
336
337 struct ThinLTOState {
338 ThinLTOState(ThinBackend Backend);
339
340 ThinBackend Backend;
341 ModuleSummaryIndex CombinedIndex;
342 // The full set of bitcode modules in input order.
343 ModuleMapType ModuleMap;
344 // The bitcode modules to compile, if specified by the LTO Config.
345 std::optional<ModuleMapType> ModulesToCompile;
346 DenseMap<GlobalValue::GUID, StringRef> PrevailingModuleForGUID;
347 } ThinLTO;
348
349 // The global resolution for a particular (mangled) symbol name. This is in
350 // particular necessary to track whether each symbol can be internalized.
351 // Because any input file may introduce a new cross-partition reference, we
352 // cannot make any final internalization decisions until all input files have
353 // been added and the client has called run(). During run() we apply
354 // internalization decisions either directly to the module (for regular LTO)
355 // or to the combined index (for ThinLTO).
356 struct GlobalResolution {
357 /// The unmangled name of the global.
358 std::string IRName;
359
360 /// Keep track if the symbol is visible outside of a module with a summary
361 /// (i.e. in either a regular object or a regular LTO module without a
362 /// summary).
363 bool VisibleOutsideSummary = false;
364
365 /// The symbol was exported dynamically, and therefore could be referenced
366 /// by a shared library not visible to the linker.
367 bool ExportDynamic = false;
368
369 bool UnnamedAddr = true;
370
371 /// True if module contains the prevailing definition.
372 bool Prevailing = false;
373
374 /// Returns true if module contains the prevailing definition and symbol is
375 /// an IR symbol. For example when module-level inline asm block is used,
376 /// symbol can be prevailing in module but have no IR name.
377 bool isPrevailingIRSymbol() const { return Prevailing && !IRName.empty(); }
378
379 /// This field keeps track of the partition number of this global. The
380 /// regular LTO object is partition 0, while each ThinLTO object has its own
381 /// partition number from 1 onwards.
382 ///
383 /// Any global that is defined or used by more than one partition, or that
384 /// is referenced externally, may not be internalized.
385 ///
386 /// Partitions generally have a one-to-one correspondence with tasks, except
387 /// that we use partition 0 for all parallel LTO code generation partitions.
388 /// Any partitioning of the combined LTO object is done internally by the
389 /// LTO backend.
390 unsigned Partition = Unknown;
391
392 /// Special partition numbers.
393 enum : unsigned {
394 /// A partition number has not yet been assigned to this global.
395 Unknown = -1u,
396
397 /// This global is either used by more than one partition or has an
398 /// external reference, and therefore cannot be internalized.
399 External = -2u,
400
401 /// The RegularLTO partition
402 RegularLTO = 0,
403 };
404 };
405
406 // Global mapping from mangled symbol names to resolutions.
407 // Make this an optional to guard against accessing after it has been reset
408 // (to reduce memory after we're done with it).
409 std::optional<StringMap<GlobalResolution>> GlobalResolutions;
410
411 void addModuleToGlobalRes(ArrayRef<InputFile::Symbol> Syms,
412 ArrayRef<SymbolResolution> Res, unsigned Partition,
413 bool InSummary);
414
415 // These functions take a range of symbol resolutions [ResI, ResE) and consume
416 // the resolutions used by a single input module by incrementing ResI. After
417 // these functions return, [ResI, ResE) will refer to the resolution range for
418 // the remaining modules in the InputFile.
419 Error addModule(InputFile &Input, unsigned ModI,
420 const SymbolResolution *&ResI, const SymbolResolution *ResE);
421
422 Expected<RegularLTOState::AddedModule>
423 addRegularLTO(BitcodeModule BM, ArrayRef<InputFile::Symbol> Syms,
424 const SymbolResolution *&ResI, const SymbolResolution *ResE);
425 Error linkRegularLTO(RegularLTOState::AddedModule Mod,
426 bool LivenessFromIndex);
427
428 Error addThinLTO(BitcodeModule BM, ArrayRef<InputFile::Symbol> Syms,
429 const SymbolResolution *&ResI, const SymbolResolution *ResE);
430
431 Error runRegularLTO(AddStreamFn AddStream);
432 Error runThinLTO(AddStreamFn AddStream, FileCache Cache,
433 const DenseSet<GlobalValue::GUID> &GUIDPreservedSymbols);
434
435 Error checkPartiallySplit();
436
437 mutable bool CalledGetMaxTasks = false;
438
439 // LTO mode when using Unified LTO.
440 LTOKind LTOMode;
441
442 // Use Optional to distinguish false from not yet initialized.
443 std::optional<bool> EnableSplitLTOUnit;
444
445 // Identify symbols exported dynamically, and that therefore could be
446 // referenced by a shared library not visible to the linker.
447 DenseSet<GlobalValue::GUID> DynamicExportSymbols;
448
449 // Diagnostic optimization remarks file
450 std::unique_ptr<ToolOutputFile> DiagnosticOutputFile;
451};
452
453/// The resolution for a symbol. The linker must provide a SymbolResolution for
454/// each global symbol based on its internal resolution of that symbol.
455struct SymbolResolution {
456 SymbolResolution()
457 : Prevailing(0), FinalDefinitionInLinkageUnit(0), VisibleToRegularObj(0),
458 ExportDynamic(0), LinkerRedefined(0) {}
459
460 /// The linker has chosen this definition of the symbol.
461 unsigned Prevailing : 1;
462
463 /// The definition of this symbol is unpreemptable at runtime and is known to
464 /// be in this linkage unit.
465 unsigned FinalDefinitionInLinkageUnit : 1;
466
467 /// The definition of this symbol is visible outside of the LTO unit.
468 unsigned VisibleToRegularObj : 1;
469
470 /// The symbol was exported dynamically, and therefore could be referenced
471 /// by a shared library not visible to the linker.
472 unsigned ExportDynamic : 1;
473
474 /// Linker redefined version of the symbol which appeared in -wrap or -defsym
475 /// linker option.
476 unsigned LinkerRedefined : 1;
477};
478
479} // namespace lto
480} // namespace llvm
481
482#endif
483

source code of llvm/include/llvm/LTO/LTO.h