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/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" 33 34 namespace llvm { 35 36 class BitcodeModule; 37 class Error; 38 class LLVMContext; 39 class MemoryBufferRef; 40 class Module; 41 class Target; 42 class raw_pwrite_stream; 43 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. 47 /// 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 *)> 53 isPrevailing, 54 function_ref<void(StringRef, GlobalValue::GUID, GlobalValue::LinkageTypes)> 55 recordNewLinkage); 56 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); 63 64 namespace lto { 65 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); 72 73 /// Setup optimization remarks. 74 Expected<std::unique_ptr<tool_output_file>> 75 setupOptimizationRemarks(LLVMContext &Context, StringRef LTORemarksFilename, 76 bool LTOPassRemarksWithHotness, int Count = -1); 77 78 class LTO; 79 struct SymbolResolution; 80 class ThinBackendProc; 81 82 /// An input file. This is a symbol table wrapper that only exposes the 83 /// information that an LTO client should need in order to do symbol resolution. 84 class InputFile { 85 public: 86 class Symbol; 87 88 private: 89 // FIXME: Remove LTO class friendship once we have bitcode symbol tables. 90 friend LTO; 91 InputFile() = default; 92 93 std::vector<BitcodeModule> Mods; 94 SmallVector<char, 0> Strtab; 95 std::vector<Symbol> Symbols; 96 97 // [begin, end) for each module 98 std::vector<std::pair<size_t, size_t>> ModuleSymIndices; 99 100 StringRef SourceFileName, COFFLinkerOpts; 101 std::vector<StringRef> ComdatTable; 102 103 public: 104 ~InputFile(); 105 106 /// Create an InputFile. 107 static Expected<std::unique_ptr<InputFile>> create(MemoryBufferRef Object); 108 109 /// The purpose of this class is to only expose the symbol information that an 110 /// LTO client should need in order to do symbol resolution. 111 class Symbol : irsymtab::Symbol { 112 friend LTO; 113 114 public: 115 Symbol(const irsymtab::Symbol &S) : irsymtab::Symbol(S) {} 116 117 using irsymtab::Symbol::isUndefined; 118 using irsymtab::Symbol::isCommon; 119 using irsymtab::Symbol::isWeak; 120 using irsymtab::Symbol::isIndirect; 121 using irsymtab::Symbol::getName; 122 using irsymtab::Symbol::getVisibility; 123 using irsymtab::Symbol::canBeOmittedFromSymbolTable; 124 using irsymtab::Symbol::isTLS; 125 using irsymtab::Symbol::getComdatIndex; 126 using irsymtab::Symbol::getCommonSize; 127 using irsymtab::Symbol::getCommonAlignment; 128 using irsymtab::Symbol::getCOFFWeakExternalFallback; 129 }; 130 131 /// A range over the symbols in this InputFile. 132 ArrayRef<Symbol> symbols() const { return Symbols; } 133 134 /// Returns linker options specified in the input file. 135 StringRef getCOFFLinkerOpts() const { return COFFLinkerOpts; } 136 137 /// Returns the path to the InputFile. 138 StringRef getName() const; 139 140 /// Returns the source file path specified at compile time. 141 StringRef getSourceFileName() const { return SourceFileName; } 142 143 // Returns a table with all the comdats used by this file. 144 ArrayRef<StringRef> getComdatTable() const { return ComdatTable; } 145 146 private: 147 ArrayRef<Symbol> module_symbols(unsigned I) const { 148 const auto &Indices = ModuleSymIndices[I]; 149 return {Symbols.data() + Indices.first, Symbols.data() + Indices.second}; 150 } 151 }; 152 153 /// This class wraps an output stream for a native object. Most clients should 154 /// just be able to return an instance of this base class from the stream 155 /// callback, but if a client needs to perform some action after the stream is 156 /// written to, that can be done by deriving from this class and overriding the 157 /// destructor. 158 class NativeObjectStream { 159 public: 160 NativeObjectStream(std::unique_ptr<raw_pwrite_stream> OS) : OS(std::move(OS)) {} 161 std::unique_ptr<raw_pwrite_stream> OS; 162 virtual ~NativeObjectStream() = default; 163 }; 164 165 /// This type defines the callback to add a native object that is generated on 166 /// the fly. 167 /// 168 /// Stream callbacks must be thread safe. 169 typedef std::function<std::unique_ptr<NativeObjectStream>(unsigned Task)> 170 AddStreamFn; 171 172 /// This is the type of a native object cache. To request an item from the 173 /// cache, pass a unique string as the Key. For hits, the cached file will be 174 /// added to the link and this function will return AddStreamFn(). For misses, 175 /// the cache will return a stream callback which must be called at most once to 176 /// produce content for the stream. The native object stream produced by the 177 /// stream callback will add the file to the link after the stream is written 178 /// to. 179 /// 180 /// Clients generally look like this: 181 /// 182 /// if (AddStreamFn AddStream = Cache(Task, Key)) 183 /// ProduceContent(AddStream); 184 typedef std::function<AddStreamFn(unsigned Task, StringRef Key)> 185 NativeObjectCache; 186 187 /// A ThinBackend defines what happens after the thin-link phase during ThinLTO. 188 /// The details of this type definition aren't important; clients can only 189 /// create a ThinBackend using one of the create*ThinBackend() functions below. 190 typedef std::function<std::unique_ptr<ThinBackendProc>( 191 Config &C, ModuleSummaryIndex &CombinedIndex, 192 StringMap<GVSummaryMapTy> &ModuleToDefinedGVSummaries, 193 AddStreamFn AddStream, NativeObjectCache Cache)> 194 ThinBackend; 195 196 /// This ThinBackend runs the individual backend jobs in-process. 197 ThinBackend createInProcessThinBackend(unsigned ParallelismLevel); 198 199 /// This ThinBackend writes individual module indexes to files, instead of 200 /// running the individual backend jobs. This backend is for distributed builds 201 /// where separate processes will invoke the real backends. 202 /// 203 /// To find the path to write the index to, the backend checks if the path has a 204 /// prefix of OldPrefix; if so, it replaces that prefix with NewPrefix. It then 205 /// appends ".thinlto.bc" and writes the index to that path. If 206 /// ShouldEmitImportsFiles is true it also writes a list of imported files to a 207 /// similar path with ".imports" appended instead. 208 ThinBackend createWriteIndexesThinBackend(std::string OldPrefix, 209 std::string NewPrefix, 210 bool ShouldEmitImportsFiles, 211 std::string LinkedObjectsFile); 212 213 /// This class implements a resolution-based interface to LLVM's LTO 214 /// functionality. It supports regular LTO, parallel LTO code generation and 215 /// ThinLTO. You can use it from a linker in the following way: 216 /// - Set hooks and code generation options (see lto::Config struct defined in 217 /// Config.h), and use the lto::Config object to create an lto::LTO object. 218 /// - Create lto::InputFile objects using lto::InputFile::create(), then use 219 /// the symbols() function to enumerate its symbols and compute a resolution 220 /// for each symbol (see SymbolResolution below). 221 /// - After the linker has visited each input file (and each regular object 222 /// file) and computed a resolution for each symbol, take each lto::InputFile 223 /// and pass it and an array of symbol resolutions to the add() function. 224 /// - Call the getMaxTasks() function to get an upper bound on the number of 225 /// native object files that LTO may add to the link. 226 /// - Call the run() function. This function will use the supplied AddStream 227 /// and Cache functions to add up to getMaxTasks() native object files to 228 /// the link. 229 class LTO { 230 friend InputFile; 231 232 public: 233 /// Create an LTO object. A default constructed LTO object has a reasonable 234 /// production configuration, but you can customize it by passing arguments to 235 /// this constructor. 236 /// FIXME: We do currently require the DiagHandler field to be set in Conf. 237 /// Until that is fixed, a Config argument is required. 238 LTO(Config Conf, ThinBackend Backend = nullptr, 239 unsigned ParallelCodeGenParallelismLevel = 1); 240 ~LTO(); 241 242 /// Add an input file to the LTO link, using the provided symbol resolutions. 243 /// The symbol resolutions must appear in the enumeration order given by 244 /// InputFile::symbols(). 245 Error add(std::unique_ptr<InputFile> Obj, ArrayRef<SymbolResolution> Res); 246 247 /// Returns an upper bound on the number of tasks that the client may expect. 248 /// This may only be called after all IR object files have been added. For a 249 /// full description of tasks see LTOBackend.h. 250 unsigned getMaxTasks() const; 251 252 /// Runs the LTO pipeline. This function calls the supplied AddStream 253 /// function to add native object files to the link. 254 /// 255 /// The Cache parameter is optional. If supplied, it will be used to cache 256 /// native object files and add them to the link. 257 /// 258 /// The client will receive at most one callback (via either AddStream or 259 /// Cache) for each task identifier. 260 Error run(AddStreamFn AddStream, NativeObjectCache Cache = nullptr); 261 262 private: 263 Config Conf; 264 265 struct RegularLTOState { 266 RegularLTOState(unsigned ParallelCodeGenParallelismLevel, Config &Conf); 267 struct CommonResolution { 268 uint64_t Size = 0; 269 unsigned Align = 0; 270 /// Record if at least one instance of the common was marked as prevailing 271 bool Prevailing = false; 272 }; 273 std::map<std::string, CommonResolution> Commons; 274 275 unsigned ParallelCodeGenParallelismLevel; 276 LTOLLVMContext Ctx; 277 bool HasModule = false; 278 std::unique_ptr<Module> CombinedModule; 279 std::unique_ptr<IRMover> Mover; 280 } RegularLTO; 281 282 struct ThinLTOState { 283 ThinLTOState(ThinBackend Backend); 284 285 ThinBackend Backend; 286 ModuleSummaryIndex CombinedIndex; 287 MapVector<StringRef, BitcodeModule> ModuleMap; 288 DenseMap<GlobalValue::GUID, StringRef> PrevailingModuleForGUID; 289 } ThinLTO; 290 291 // The global resolution for a particular (mangled) symbol name. This is in 292 // particular necessary to track whether each symbol can be internalized. 293 // Because any input file may introduce a new cross-partition reference, we 294 // cannot make any final internalization decisions until all input files have 295 // been added and the client has called run(). During run() we apply 296 // internalization decisions either directly to the module (for regular LTO) 297 // or to the combined index (for ThinLTO). 298 struct GlobalResolution { 299 /// The unmangled name of the global. 300 std::string IRName; 301 302 /// Keep track if the symbol is visible outside of ThinLTO (i.e. in 303 /// either a regular object or the regular LTO partition). 304 bool VisibleOutsideThinLTO = false; 305 306 bool UnnamedAddr = true; 307 308 /// This field keeps track of the partition number of this global. The 309 /// regular LTO object is partition 0, while each ThinLTO object has its own 310 /// partition number from 1 onwards. 311 /// 312 /// Any global that is defined or used by more than one partition, or that 313 /// is referenced externally, may not be internalized. 314 /// 315 /// Partitions generally have a one-to-one correspondence with tasks, except 316 /// that we use partition 0 for all parallel LTO code generation partitions. 317 /// Any partitioning of the combined LTO object is done internally by the 318 /// LTO backend. 319 unsigned Partition = Unknown; 320 321 /// Special partition numbers. 322 enum : unsigned { 323 /// A partition number has not yet been assigned to this global. 324 Unknown = -1u, 325 326 /// This global is either used by more than one partition or has an 327 /// external reference, and therefore cannot be internalized. 328 External = -2u, 329 330 /// The RegularLTO partition 331 RegularLTO = 0, 332 }; 333 }; 334 335 // Global mapping from mangled symbol names to resolutions. 336 StringMap<GlobalResolution> GlobalResolutions; 337 338 void addSymbolToGlobalRes(const InputFile::Symbol &Sym, SymbolResolution Res, 339 unsigned Partition); 340 341 // These functions take a range of symbol resolutions [ResI, ResE) and consume 342 // the resolutions used by a single input module by incrementing ResI. After 343 // these functions return, [ResI, ResE) will refer to the resolution range for 344 // the remaining modules in the InputFile. 345 Error addModule(InputFile &Input, unsigned ModI, 346 const SymbolResolution *&ResI, const SymbolResolution *ResE); 347 Error addRegularLTO(BitcodeModule BM, 348 ArrayRef<InputFile::Symbol> Syms, 349 const SymbolResolution *&ResI, 350 const SymbolResolution *ResE); 351 Error addThinLTO(BitcodeModule BM, ArrayRef<InputFile::Symbol> Syms, 352 const SymbolResolution *&ResI, const SymbolResolution *ResE); 353 354 Error runRegularLTO(AddStreamFn AddStream); 355 Error runThinLTO(AddStreamFn AddStream, NativeObjectCache Cache, 356 bool HasRegularLTO); 357 358 mutable bool CalledGetMaxTasks = false; 359 }; 360 361 /// The resolution for a symbol. The linker must provide a SymbolResolution for 362 /// each global symbol based on its internal resolution of that symbol. 363 struct SymbolResolution { 364 SymbolResolution() 365 : Prevailing(0), FinalDefinitionInLinkageUnit(0), VisibleToRegularObj(0) { 366 } 367 /// The linker has chosen this definition of the symbol. 368 unsigned Prevailing : 1; 369 370 /// The definition of this symbol is unpreemptable at runtime and is known to 371 /// be in this linkage unit. 372 unsigned FinalDefinitionInLinkageUnit : 1; 373 374 /// The definition of this symbol is visible outside of the LTO unit. 375 unsigned VisibleToRegularObj : 1; 376 }; 377 378 } // namespace lto 379 } // namespace llvm 380 381 #endif 382