1 //===-LTO.h - LLVM Link Time Optimizer ------------------------------------===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
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.
14 //===----------------------------------------------------------------------===//
16 #ifndef LLVM_LTO_LTO_H
17 #define LLVM_LTO_LTO_H
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"
39 class MemoryBufferRef;
42 class raw_pwrite_stream;
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.
48 /// This is done for correctness (if value exported, ensure we always
49 /// emit a copy), and compile-time optimization (allow drop of duplicates).
50 void thinLTOResolveWeakForLinkerInIndex(
51 ModuleSummaryIndex &Index,
52 function_ref<bool(GlobalValue::GUID, const GlobalValueSummary *)>
54 function_ref<void(StringRef, GlobalValue::GUID, GlobalValue::LinkageTypes)>
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.
60 void thinLTOInternalizeAndPromoteInIndex(
61 ModuleSummaryIndex &Index,
62 function_ref<bool(StringRef, GlobalValue::GUID)> isExported);
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.
69 std::string getThinLTOOutputFile(const std::string &Path,
70 const std::string &OldPrefix,
71 const std::string &NewPrefix);
73 /// Setup optimization remarks.
74 Expected<std::unique_ptr<ToolOutputFile>>
75 setupOptimizationRemarks(LLVMContext &Context, StringRef LTORemarksFilename,
76 bool LTOPassRemarksWithHotness,
77 unsigned LTOPassRemarksHotnessThreshold,
81 struct SymbolResolution;
82 class ThinBackendProc;
84 /// An input file. This is a symbol table wrapper that only exposes the
85 /// information that an LTO client should need in order to do symbol resolution.
91 // FIXME: Remove LTO class friendship once we have bitcode symbol tables.
93 InputFile() = default;
95 std::vector<BitcodeModule> Mods;
96 SmallVector<char, 0> Strtab;
97 std::vector<Symbol> Symbols;
99 // [begin, end) for each module
100 std::vector<std::pair<size_t, size_t>> ModuleSymIndices;
102 StringRef TargetTriple, SourceFileName, COFFLinkerOpts;
103 std::vector<StringRef> ComdatTable;
108 /// Create an InputFile.
109 static Expected<std::unique_ptr<InputFile>> create(MemoryBufferRef Object);
111 /// The purpose of this class is to only expose the symbol information that an
112 /// LTO client should need in order to do symbol resolution.
113 class Symbol : irsymtab::Symbol {
117 Symbol(const irsymtab::Symbol &S) : irsymtab::Symbol(S) {}
119 using irsymtab::Symbol::isUndefined;
120 using irsymtab::Symbol::isCommon;
121 using irsymtab::Symbol::isWeak;
122 using irsymtab::Symbol::isIndirect;
123 using irsymtab::Symbol::getName;
124 using irsymtab::Symbol::getVisibility;
125 using irsymtab::Symbol::canBeOmittedFromSymbolTable;
126 using irsymtab::Symbol::isTLS;
127 using irsymtab::Symbol::getComdatIndex;
128 using irsymtab::Symbol::getCommonSize;
129 using irsymtab::Symbol::getCommonAlignment;
130 using irsymtab::Symbol::getCOFFWeakExternalFallback;
131 using irsymtab::Symbol::getSectionName;
132 using irsymtab::Symbol::isExecutable;
135 /// A range over the symbols in this InputFile.
136 ArrayRef<Symbol> symbols() const { return Symbols; }
138 /// Returns linker options specified in the input file.
139 StringRef getCOFFLinkerOpts() const { return COFFLinkerOpts; }
141 /// Returns the path to the InputFile.
142 StringRef getName() const;
144 /// Returns the input file's target triple.
145 StringRef getTargetTriple() const { return TargetTriple; }
147 /// Returns the source file path specified at compile time.
148 StringRef getSourceFileName() const { return SourceFileName; }
150 // Returns a table with all the comdats used by this file.
151 ArrayRef<StringRef> getComdatTable() const { return ComdatTable; }
154 ArrayRef<Symbol> module_symbols(unsigned I) const {
155 const auto &Indices = ModuleSymIndices[I];
156 return {Symbols.data() + Indices.first, Symbols.data() + Indices.second};
160 /// This class wraps an output stream for a native object. Most clients should
161 /// just be able to return an instance of this base class from the stream
162 /// callback, but if a client needs to perform some action after the stream is
163 /// written to, that can be done by deriving from this class and overriding the
165 class NativeObjectStream {
167 NativeObjectStream(std::unique_ptr<raw_pwrite_stream> OS) : OS(std::move(OS)) {}
168 std::unique_ptr<raw_pwrite_stream> OS;
169 virtual ~NativeObjectStream() = default;
172 /// This type defines the callback to add a native object that is generated on
175 /// Stream callbacks must be thread safe.
176 typedef std::function<std::unique_ptr<NativeObjectStream>(unsigned Task)>
179 /// This is the type of a native object cache. To request an item from the
180 /// cache, pass a unique string as the Key. For hits, the cached file will be
181 /// added to the link and this function will return AddStreamFn(). For misses,
182 /// the cache will return a stream callback which must be called at most once to
183 /// produce content for the stream. The native object stream produced by the
184 /// stream callback will add the file to the link after the stream is written
187 /// Clients generally look like this:
189 /// if (AddStreamFn AddStream = Cache(Task, Key))
190 /// ProduceContent(AddStream);
191 typedef std::function<AddStreamFn(unsigned Task, StringRef Key)>
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 typedef std::function<std::unique_ptr<ThinBackendProc>(
198 Config &C, ModuleSummaryIndex &CombinedIndex,
199 StringMap<GVSummaryMapTy> &ModuleToDefinedGVSummaries,
200 AddStreamFn AddStream, NativeObjectCache Cache)>
203 /// This ThinBackend runs the individual backend jobs in-process.
204 ThinBackend createInProcessThinBackend(unsigned ParallelismLevel);
206 /// This ThinBackend writes individual module indexes to files, instead of
207 /// running the individual backend jobs. This backend is for distributed builds
208 /// where separate processes will invoke the real backends.
210 /// To find the path to write the index to, the backend checks if the path has a
211 /// prefix of OldPrefix; if so, it replaces that prefix with NewPrefix. It then
212 /// appends ".thinlto.bc" and writes the index to that path. If
213 /// ShouldEmitImportsFiles is true it also writes a list of imported files to a
214 /// similar path with ".imports" appended instead.
215 /// LinkedObjectsFile is an output stream to write the list of object files for
216 /// the final ThinLTO linking. Can be nullptr.
217 /// OnWrite is callback which receives module identifier and notifies LTO user
218 /// that index file for the module (and optionally imports file) was created.
219 using IndexWriteCallback = std::function<void(const std::string &)>;
220 ThinBackend createWriteIndexesThinBackend(std::string OldPrefix,
221 std::string NewPrefix,
222 bool ShouldEmitImportsFiles,
223 raw_fd_ostream *LinkedObjectsFile,
224 IndexWriteCallback OnWrite);
226 /// This class implements a resolution-based interface to LLVM's LTO
227 /// functionality. It supports regular LTO, parallel LTO code generation and
228 /// ThinLTO. You can use it from a linker in the following way:
229 /// - Set hooks and code generation options (see lto::Config struct defined in
230 /// Config.h), and use the lto::Config object to create an lto::LTO object.
231 /// - Create lto::InputFile objects using lto::InputFile::create(), then use
232 /// the symbols() function to enumerate its symbols and compute a resolution
233 /// for each symbol (see SymbolResolution below).
234 /// - After the linker has visited each input file (and each regular object
235 /// file) and computed a resolution for each symbol, take each lto::InputFile
236 /// and pass it and an array of symbol resolutions to the add() function.
237 /// - Call the getMaxTasks() function to get an upper bound on the number of
238 /// native object files that LTO may add to the link.
239 /// - Call the run() function. This function will use the supplied AddStream
240 /// and Cache functions to add up to getMaxTasks() native object files to
246 /// Create an LTO object. A default constructed LTO object has a reasonable
247 /// production configuration, but you can customize it by passing arguments to
248 /// this constructor.
249 /// FIXME: We do currently require the DiagHandler field to be set in Conf.
250 /// Until that is fixed, a Config argument is required.
251 LTO(Config Conf, ThinBackend Backend = nullptr,
252 unsigned ParallelCodeGenParallelismLevel = 1);
255 /// Add an input file to the LTO link, using the provided symbol resolutions.
256 /// The symbol resolutions must appear in the enumeration order given by
257 /// InputFile::symbols().
258 Error add(std::unique_ptr<InputFile> Obj, ArrayRef<SymbolResolution> Res);
260 /// Returns an upper bound on the number of tasks that the client may expect.
261 /// This may only be called after all IR object files have been added. For a
262 /// full description of tasks see LTOBackend.h.
263 unsigned getMaxTasks() const;
265 /// Runs the LTO pipeline. This function calls the supplied AddStream
266 /// function to add native object files to the link.
268 /// The Cache parameter is optional. If supplied, it will be used to cache
269 /// native object files and add them to the link.
271 /// The client will receive at most one callback (via either AddStream or
272 /// Cache) for each task identifier.
273 Error run(AddStreamFn AddStream, NativeObjectCache Cache = nullptr);
278 struct RegularLTOState {
279 RegularLTOState(unsigned ParallelCodeGenParallelismLevel, Config &Conf);
280 struct CommonResolution {
283 /// Record if at least one instance of the common was marked as prevailing
284 bool Prevailing = false;
286 std::map<std::string, CommonResolution> Commons;
288 unsigned ParallelCodeGenParallelismLevel;
290 std::unique_ptr<Module> CombinedModule;
291 std::unique_ptr<IRMover> Mover;
293 // This stores the information about a regular LTO module that we have added
294 // to the link. It will either be linked immediately (for modules without
295 // summaries) or after summary-based dead stripping (for modules with
298 std::unique_ptr<Module> M;
299 std::vector<GlobalValue *> Keep;
301 std::vector<AddedModule> ModsWithSummaries;
304 struct ThinLTOState {
305 ThinLTOState(ThinBackend Backend);
308 ModuleSummaryIndex CombinedIndex;
309 MapVector<StringRef, BitcodeModule> ModuleMap;
310 DenseMap<GlobalValue::GUID, StringRef> PrevailingModuleForGUID;
313 // The global resolution for a particular (mangled) symbol name. This is in
314 // particular necessary to track whether each symbol can be internalized.
315 // Because any input file may introduce a new cross-partition reference, we
316 // cannot make any final internalization decisions until all input files have
317 // been added and the client has called run(). During run() we apply
318 // internalization decisions either directly to the module (for regular LTO)
319 // or to the combined index (for ThinLTO).
320 struct GlobalResolution {
321 /// The unmangled name of the global.
324 /// Keep track if the symbol is visible outside of a module with a summary
325 /// (i.e. in either a regular object or a regular LTO module without a
327 bool VisibleOutsideSummary = false;
329 bool UnnamedAddr = true;
331 /// True if module contains the prevailing definition.
332 bool Prevailing = false;
334 /// Returns true if module contains the prevailing definition and symbol is
335 /// an IR symbol. For example when module-level inline asm block is used,
336 /// symbol can be prevailing in module but have no IR name.
337 bool isPrevailingIRSymbol() const { return Prevailing && !IRName.empty(); }
339 /// This field keeps track of the partition number of this global. The
340 /// regular LTO object is partition 0, while each ThinLTO object has its own
341 /// partition number from 1 onwards.
343 /// Any global that is defined or used by more than one partition, or that
344 /// is referenced externally, may not be internalized.
346 /// Partitions generally have a one-to-one correspondence with tasks, except
347 /// that we use partition 0 for all parallel LTO code generation partitions.
348 /// Any partitioning of the combined LTO object is done internally by the
350 unsigned Partition = Unknown;
352 /// Special partition numbers.
354 /// A partition number has not yet been assigned to this global.
357 /// This global is either used by more than one partition or has an
358 /// external reference, and therefore cannot be internalized.
361 /// The RegularLTO partition
366 // Global mapping from mangled symbol names to resolutions.
367 StringMap<GlobalResolution> GlobalResolutions;
369 void addModuleToGlobalRes(ArrayRef<InputFile::Symbol> Syms,
370 ArrayRef<SymbolResolution> Res, unsigned Partition,
373 // These functions take a range of symbol resolutions [ResI, ResE) and consume
374 // the resolutions used by a single input module by incrementing ResI. After
375 // these functions return, [ResI, ResE) will refer to the resolution range for
376 // the remaining modules in the InputFile.
377 Error addModule(InputFile &Input, unsigned ModI,
378 const SymbolResolution *&ResI, const SymbolResolution *ResE);
380 Expected<RegularLTOState::AddedModule>
381 addRegularLTO(BitcodeModule BM, ArrayRef<InputFile::Symbol> Syms,
382 const SymbolResolution *&ResI, const SymbolResolution *ResE);
383 Error linkRegularLTO(RegularLTOState::AddedModule Mod,
384 bool LivenessFromIndex);
386 Error addThinLTO(BitcodeModule BM, ArrayRef<InputFile::Symbol> Syms,
387 const SymbolResolution *&ResI, const SymbolResolution *ResE);
389 Error runRegularLTO(AddStreamFn AddStream);
390 Error runThinLTO(AddStreamFn AddStream, NativeObjectCache Cache);
392 mutable bool CalledGetMaxTasks = false;
395 /// The resolution for a symbol. The linker must provide a SymbolResolution for
396 /// each global symbol based on its internal resolution of that symbol.
397 struct SymbolResolution {
399 : Prevailing(0), FinalDefinitionInLinkageUnit(0), VisibleToRegularObj(0),
400 LinkerRedefined(0) {}
402 /// The linker has chosen this definition of the symbol.
403 unsigned Prevailing : 1;
405 /// The definition of this symbol is unpreemptable at runtime and is known to
406 /// be in this linkage unit.
407 unsigned FinalDefinitionInLinkageUnit : 1;
409 /// The definition of this symbol is visible outside of the LTO unit.
410 unsigned VisibleToRegularObj : 1;
412 /// Linker redefined version of the symbol which appeared in -wrap or -defsym
414 unsigned LinkerRedefined : 1;