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 | |
30 | namespace llvm { |
31 | |
32 | class Error; |
33 | class IRMover; |
34 | class LLVMContext; |
35 | class MemoryBufferRef; |
36 | class Module; |
37 | class raw_pwrite_stream; |
38 | class 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). |
46 | void 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. |
57 | void 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. |
66 | void 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 | |
76 | namespace 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. |
81 | std::string getThinLTOOutputFile(StringRef Path, StringRef OldPrefix, |
82 | StringRef NewPrefix); |
83 | |
84 | /// Setup optimization remarks. |
85 | Expected<std::unique_ptr<ToolOutputFile>> ( |
86 | LLVMContext &Context, StringRef , StringRef , |
87 | StringRef , bool , |
88 | std::optional<uint64_t> = 0, int Count = -1); |
89 | |
90 | /// Setups the output file for saving statistics. |
91 | Expected<std::unique_ptr<ToolOutputFile>> |
92 | setupStatsFile(StringRef StatsFilename); |
93 | |
94 | /// Produces a container ordering for optimal multi-threaded processing. Returns |
95 | /// ordered indices to elements in the input array. |
96 | std::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. |
101 | void updateMemProfAttributes(Module &Mod, const ModuleSummaryIndex &Index); |
102 | |
103 | class LTO; |
104 | struct SymbolResolution; |
105 | class 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. |
109 | class InputFile { |
110 | public: |
111 | class Symbol; |
112 | |
113 | private: |
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 | |
129 | public: |
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 | |
187 | private: |
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. |
197 | using 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. |
210 | using IndexWriteCallback = std::function<void(const std::string &)>; |
211 | ThinBackend 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. |
231 | ThinBackend 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. |
254 | class LTO { |
255 | friend InputFile; |
256 | |
257 | public: |
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 | |
304 | private: |
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. |
455 | struct 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 | |