Line data Source code
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/IR/DiagnosticInfo.h"
23 : #include "llvm/IR/ModuleSummaryIndex.h"
24 : #include "llvm/LTO/Config.h"
25 : #include "llvm/Linker/IRMover.h"
26 : #include "llvm/Object/IRSymtab.h"
27 : #include "llvm/Support/Error.h"
28 : #include "llvm/Support/ToolOutputFile.h"
29 : #include "llvm/Support/thread.h"
30 : #include "llvm/Target/TargetOptions.h"
31 : #include "llvm/Transforms/IPO/FunctionImport.h"
32 :
33 : namespace llvm {
34 :
35 : class BitcodeModule;
36 : class Error;
37 : class LLVMContext;
38 : class MemoryBufferRef;
39 : class Module;
40 : class Target;
41 : class raw_pwrite_stream;
42 :
43 : /// Resolve Weak and LinkOnce values in the \p Index. Linkage changes recorded
44 : /// in the index and the ThinLTO backends must apply the changes to the Module
45 : /// via thinLTOResolveWeakForLinkerModule.
46 : ///
47 : /// This is done for correctness (if value exported, ensure we always
48 : /// emit a copy), and compile-time optimization (allow drop of duplicates).
49 : void thinLTOResolveWeakForLinkerInIndex(
50 : ModuleSummaryIndex &Index,
51 : function_ref<bool(GlobalValue::GUID, const GlobalValueSummary *)>
52 : isPrevailing,
53 : function_ref<void(StringRef, GlobalValue::GUID, GlobalValue::LinkageTypes)>
54 : recordNewLinkage);
55 :
56 : /// Update the linkages in the given \p Index to mark exported values
57 : /// as external and non-exported values as internal. The ThinLTO backends
58 : /// must apply the changes to the Module via thinLTOInternalizeModule.
59 : void thinLTOInternalizeAndPromoteInIndex(
60 : ModuleSummaryIndex &Index,
61 : function_ref<bool(StringRef, GlobalValue::GUID)> isExported);
62 :
63 : namespace lto {
64 :
65 : /// Given the original \p Path to an output file, replace any path
66 : /// prefix matching \p OldPrefix with \p NewPrefix. Also, create the
67 : /// resulting directory if it does not yet exist.
68 : std::string getThinLTOOutputFile(const std::string &Path,
69 : const std::string &OldPrefix,
70 : const std::string &NewPrefix);
71 :
72 : /// Setup optimization remarks.
73 : Expected<std::unique_ptr<ToolOutputFile>>
74 : setupOptimizationRemarks(LLVMContext &Context, StringRef LTORemarksFilename,
75 : bool LTOPassRemarksWithHotness, int Count = -1);
76 :
77 : class LTO;
78 : struct SymbolResolution;
79 : class ThinBackendProc;
80 :
81 : /// An input file. This is a symbol table wrapper that only exposes the
82 : /// information that an LTO client should need in order to do symbol resolution.
83 1830 : class InputFile {
84 : public:
85 : class Symbol;
86 :
87 : private:
88 : // FIXME: Remove LTO class friendship once we have bitcode symbol tables.
89 : friend LTO;
90 : InputFile() = default;
91 :
92 : std::vector<BitcodeModule> Mods;
93 : SmallVector<char, 0> Strtab;
94 : std::vector<Symbol> Symbols;
95 :
96 : // [begin, end) for each module
97 : std::vector<std::pair<size_t, size_t>> ModuleSymIndices;
98 :
99 : StringRef TargetTriple, SourceFileName, COFFLinkerOpts;
100 : std::vector<StringRef> ComdatTable;
101 :
102 : public:
103 : ~InputFile();
104 :
105 : /// Create an InputFile.
106 : static Expected<std::unique_ptr<InputFile>> create(MemoryBufferRef Object);
107 :
108 : /// The purpose of this class is to only expose the symbol information that an
109 : /// LTO client should need in order to do symbol resolution.
110 : class Symbol : irsymtab::Symbol {
111 : friend LTO;
112 :
113 : public:
114 1819 : Symbol(const irsymtab::Symbol &S) : irsymtab::Symbol(S) {}
115 :
116 : using irsymtab::Symbol::isUndefined;
117 : using irsymtab::Symbol::isCommon;
118 : using irsymtab::Symbol::isWeak;
119 : using irsymtab::Symbol::isIndirect;
120 : using irsymtab::Symbol::getName;
121 : using irsymtab::Symbol::getVisibility;
122 : using irsymtab::Symbol::canBeOmittedFromSymbolTable;
123 : using irsymtab::Symbol::isTLS;
124 : using irsymtab::Symbol::getComdatIndex;
125 : using irsymtab::Symbol::getCommonSize;
126 : using irsymtab::Symbol::getCommonAlignment;
127 : using irsymtab::Symbol::getCOFFWeakExternalFallback;
128 : using irsymtab::Symbol::getSectionName;
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 0 : 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 0 : StringRef getTargetTriple() const { return TargetTriple; }
143 :
144 : /// Returns the source file path specified at compile time.
145 0 : 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 :
150 : private:
151 : ArrayRef<Symbol> module_symbols(unsigned I) const {
152 726 : const auto &Indices = ModuleSymIndices[I];
153 726 : 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.
162 : class NativeObjectStream {
163 : public:
164 70 : NativeObjectStream(std::unique_ptr<raw_pwrite_stream> OS) : OS(std::move(OS)) {}
165 : std::unique_ptr<raw_pwrite_stream> OS;
166 1442 : 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.
173 : typedef 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);
188 : typedef 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.
194 : typedef 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.
201 : ThinBackend 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.
212 : /// LinkedObjectsFile is an output stream to write the list of object files for
213 : /// the final ThinLTO linking. Can be nullptr.
214 : /// OnWrite is callback which receives module identifier and notifies LTO user
215 : /// that index file for the module (and optionally imports file) was created.
216 : using IndexWriteCallback = std::function<void(const std::string &)>;
217 : ThinBackend createWriteIndexesThinBackend(std::string OldPrefix,
218 : std::string NewPrefix,
219 : bool ShouldEmitImportsFiles,
220 : raw_fd_ostream *LinkedObjectsFile,
221 : IndexWriteCallback OnWrite);
222 :
223 : /// This class implements a resolution-based interface to LLVM's LTO
224 : /// functionality. It supports regular LTO, parallel LTO code generation and
225 : /// ThinLTO. You can use it from a linker in the following way:
226 : /// - Set hooks and code generation options (see lto::Config struct defined in
227 : /// Config.h), and use the lto::Config object to create an lto::LTO object.
228 : /// - Create lto::InputFile objects using lto::InputFile::create(), then use
229 : /// the symbols() function to enumerate its symbols and compute a resolution
230 : /// for each symbol (see SymbolResolution below).
231 : /// - After the linker has visited each input file (and each regular object
232 : /// file) and computed a resolution for each symbol, take each lto::InputFile
233 : /// and pass it and an array of symbol resolutions to the add() function.
234 : /// - Call the getMaxTasks() function to get an upper bound on the number of
235 : /// native object files that LTO may add to the link.
236 : /// - Call the run() function. This function will use the supplied AddStream
237 : /// and Cache functions to add up to getMaxTasks() native object files to
238 : /// the link.
239 477 : class LTO {
240 : friend InputFile;
241 :
242 : public:
243 : /// Create an LTO object. A default constructed LTO object has a reasonable
244 : /// production configuration, but you can customize it by passing arguments to
245 : /// this constructor.
246 : /// FIXME: We do currently require the DiagHandler field to be set in Conf.
247 : /// Until that is fixed, a Config argument is required.
248 : LTO(Config Conf, ThinBackend Backend = nullptr,
249 : unsigned ParallelCodeGenParallelismLevel = 1);
250 : ~LTO();
251 :
252 : /// Add an input file to the LTO link, using the provided symbol resolutions.
253 : /// The symbol resolutions must appear in the enumeration order given by
254 : /// InputFile::symbols().
255 : Error add(std::unique_ptr<InputFile> Obj, ArrayRef<SymbolResolution> Res);
256 :
257 : /// Returns an upper bound on the number of tasks that the client may expect.
258 : /// This may only be called after all IR object files have been added. For a
259 : /// full description of tasks see LTOBackend.h.
260 : unsigned getMaxTasks() const;
261 :
262 : /// Runs the LTO pipeline. This function calls the supplied AddStream
263 : /// function to add native object files to the link.
264 : ///
265 : /// The Cache parameter is optional. If supplied, it will be used to cache
266 : /// native object files and add them to the link.
267 : ///
268 : /// The client will receive at most one callback (via either AddStream or
269 : /// Cache) for each task identifier.
270 : Error run(AddStreamFn AddStream, NativeObjectCache Cache = nullptr);
271 :
272 : private:
273 : Config Conf;
274 :
275 : struct RegularLTOState {
276 : RegularLTOState(unsigned ParallelCodeGenParallelismLevel, Config &Conf);
277 : struct CommonResolution {
278 : uint64_t Size = 0;
279 : unsigned Align = 0;
280 : /// Record if at least one instance of the common was marked as prevailing
281 : bool Prevailing = false;
282 : };
283 : std::map<std::string, CommonResolution> Commons;
284 :
285 : unsigned ParallelCodeGenParallelismLevel;
286 : LTOLLVMContext Ctx;
287 : std::unique_ptr<Module> CombinedModule;
288 : std::unique_ptr<IRMover> Mover;
289 :
290 : // This stores the information about a regular LTO module that we have added
291 : // to the link. It will either be linked immediately (for modules without
292 : // summaries) or after summary-based dead stripping (for modules with
293 : // summaries).
294 52 : struct AddedModule {
295 : std::unique_ptr<Module> M;
296 : std::vector<GlobalValue *> Keep;
297 : };
298 : std::vector<AddedModule> ModsWithSummaries;
299 : } RegularLTO;
300 :
301 : struct ThinLTOState {
302 : ThinLTOState(ThinBackend Backend);
303 :
304 : ThinBackend Backend;
305 : ModuleSummaryIndex CombinedIndex;
306 : MapVector<StringRef, BitcodeModule> ModuleMap;
307 : DenseMap<GlobalValue::GUID, StringRef> PrevailingModuleForGUID;
308 : } ThinLTO;
309 :
310 : // The global resolution for a particular (mangled) symbol name. This is in
311 : // particular necessary to track whether each symbol can be internalized.
312 : // Because any input file may introduce a new cross-partition reference, we
313 : // cannot make any final internalization decisions until all input files have
314 : // been added and the client has called run(). During run() we apply
315 : // internalization decisions either directly to the module (for regular LTO)
316 : // or to the combined index (for ThinLTO).
317 0 : struct GlobalResolution {
318 : /// The unmangled name of the global.
319 : std::string IRName;
320 :
321 : /// Keep track if the symbol is visible outside of a module with a summary
322 : /// (i.e. in either a regular object or a regular LTO module without a
323 : /// summary).
324 : bool VisibleOutsideSummary = false;
325 :
326 : bool UnnamedAddr = true;
327 :
328 : /// True if module contains the prevailing definition.
329 : bool Prevailing = false;
330 :
331 : /// Returns true if module contains the prevailing definition and symbol is
332 : /// an IR symbol. For example when module-level inline asm block is used,
333 : /// symbol can be prevailing in module but have no IR name.
334 1500 : bool isPrevailingIRSymbol() const { return Prevailing && !IRName.empty(); }
335 :
336 : /// This field keeps track of the partition number of this global. The
337 : /// regular LTO object is partition 0, while each ThinLTO object has its own
338 : /// partition number from 1 onwards.
339 : ///
340 : /// Any global that is defined or used by more than one partition, or that
341 : /// is referenced externally, may not be internalized.
342 : ///
343 : /// Partitions generally have a one-to-one correspondence with tasks, except
344 : /// that we use partition 0 for all parallel LTO code generation partitions.
345 : /// Any partitioning of the combined LTO object is done internally by the
346 : /// LTO backend.
347 : unsigned Partition = Unknown;
348 :
349 : /// Special partition numbers.
350 : enum : unsigned {
351 : /// A partition number has not yet been assigned to this global.
352 : Unknown = -1u,
353 :
354 : /// This global is either used by more than one partition or has an
355 : /// external reference, and therefore cannot be internalized.
356 : External = -2u,
357 :
358 : /// The RegularLTO partition
359 : RegularLTO = 0,
360 : };
361 : };
362 :
363 : // Global mapping from mangled symbol names to resolutions.
364 : StringMap<GlobalResolution> GlobalResolutions;
365 :
366 : void addModuleToGlobalRes(ArrayRef<InputFile::Symbol> Syms,
367 : ArrayRef<SymbolResolution> Res, unsigned Partition,
368 : bool InSummary);
369 :
370 : // These functions take a range of symbol resolutions [ResI, ResE) and consume
371 : // the resolutions used by a single input module by incrementing ResI. After
372 : // these functions return, [ResI, ResE) will refer to the resolution range for
373 : // the remaining modules in the InputFile.
374 : Error addModule(InputFile &Input, unsigned ModI,
375 : const SymbolResolution *&ResI, const SymbolResolution *ResE);
376 :
377 : Expected<RegularLTOState::AddedModule>
378 : addRegularLTO(BitcodeModule BM, ArrayRef<InputFile::Symbol> Syms,
379 : const SymbolResolution *&ResI, const SymbolResolution *ResE);
380 : Error linkRegularLTO(RegularLTOState::AddedModule Mod,
381 : bool LivenessFromIndex);
382 :
383 : Error addThinLTO(BitcodeModule BM, ArrayRef<InputFile::Symbol> Syms,
384 : const SymbolResolution *&ResI, const SymbolResolution *ResE);
385 :
386 : Error runRegularLTO(AddStreamFn AddStream);
387 : Error runThinLTO(AddStreamFn AddStream, NativeObjectCache Cache);
388 :
389 : mutable bool CalledGetMaxTasks = false;
390 : };
391 :
392 : /// The resolution for a symbol. The linker must provide a SymbolResolution for
393 : /// each global symbol based on its internal resolution of that symbol.
394 : struct SymbolResolution {
395 : SymbolResolution()
396 1408 : : Prevailing(0), FinalDefinitionInLinkageUnit(0), VisibleToRegularObj(0),
397 1408 : LinkerRedefined(0) {}
398 :
399 : /// The linker has chosen this definition of the symbol.
400 : unsigned Prevailing : 1;
401 :
402 : /// The definition of this symbol is unpreemptable at runtime and is known to
403 : /// be in this linkage unit.
404 : unsigned FinalDefinitionInLinkageUnit : 1;
405 :
406 : /// The definition of this symbol is visible outside of the LTO unit.
407 : unsigned VisibleToRegularObj : 1;
408 :
409 : /// Linker redefined version of the symbol which appeared in -wrap or -defsym
410 : /// linker option.
411 : unsigned LinkerRedefined : 1;
412 : };
413 :
414 : } // namespace lto
415 : } // namespace llvm
416 :
417 : #endif
|
