include/llvm/LTO/LTO.h

   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<ToolOutputFile>>
  75 setupOptimizationRemarks(LLVMContext &Context, StringRef LTORemarksFilename,
  76                          bool LTOPassRemarksWithHotness,
  77                          unsigned LTOPassRemarksHotnessThreshold,
  78                          int Count = -1);
  79
  80 class LTO;
  81 struct SymbolResolution;
  82 class ThinBackendProc;
  83
  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.
  86 class InputFile {
  87 public:
  88   class Symbol;
  89
  90 private:
  91   // FIXME: Remove LTO class friendship once we have bitcode symbol tables.
  92   friend LTO;
  93   InputFile() = default;
  94
  95   std::vector<BitcodeModule> Mods;
  96   SmallVector<char, 0> Strtab;
  97   std::vector<Symbol> Symbols;
  98
  99   // [begin, end) for each module
 100   std::vector<std::pair<size_t, size_t>> ModuleSymIndices;
 101
 102   StringRef TargetTriple, SourceFileName, COFFLinkerOpts;
 103   std::vector<StringRef> ComdatTable;
 104
 105 public:
 106   ~InputFile();
 107
 108   /// Create an InputFile.
 109   static Expected<std::unique_ptr<InputFile>> create(MemoryBufferRef Object);
 110
 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 {
 114     friend LTO;
 115
 116   public:
 117     Symbol(const irsymtab::Symbol &S) : irsymtab::Symbol(S) {}
 118
 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;
 133   };
 134
 135   /// A range over the symbols in this InputFile.
 136   ArrayRef<Symbol> symbols() const { return Symbols; }
 137
 138   /// Returns linker options specified in the input file.
 139   StringRef getCOFFLinkerOpts() const { return COFFLinkerOpts; }
 140
 141   /// Returns the path to the InputFile.
 142   StringRef getName() const;
 143
 144   /// Returns the input file's target triple.
 145   StringRef getTargetTriple() const { return TargetTriple; }
 146
 147   /// Returns the source file path specified at compile time.
 148   StringRef getSourceFileName() const { return SourceFileName; }
 149
 150   // Returns a table with all the comdats used by this file.
 151   ArrayRef<StringRef> getComdatTable() const { return ComdatTable; }
 152
 153 private:
 154   ArrayRef<Symbol> module_symbols(unsigned I) const {
 155     const auto &Indices = ModuleSymIndices[I];
 156     return {Symbols.data() + Indices.first, Symbols.data() + Indices.second};
 157   }
 158 };
 159
 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
 164 /// destructor.
 165 class NativeObjectStream {
 166 public:
 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;
 170 };
 171
 172 /// This type defines the callback to add a native object that is generated on
 173 /// the fly.
 174 ///
 175 /// Stream callbacks must be thread safe.
 176 typedef std::function<std::unique_ptr<NativeObjectStream>(unsigned Task)>
 177     AddStreamFn;
 178
 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
 185 /// to.
 186 ///
 187 /// Clients generally look like this:
 188 ///
 189 /// if (AddStreamFn AddStream = Cache(Task, Key))
 190 ///   ProduceContent(AddStream);
 191 typedef std::function<AddStreamFn(unsigned Task, StringRef Key)>
 192     NativeObjectCache;
 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 typedef std::function<std::unique_ptr<ThinBackendProc>(
 198     Config &C, ModuleSummaryIndex &CombinedIndex,
 199     StringMap<GVSummaryMapTy> &ModuleToDefinedGVSummaries,
 200     AddStreamFn AddStream, NativeObjectCache Cache)>
 201     ThinBackend;
 202
 203 /// This ThinBackend runs the individual backend jobs in-process.
 204 ThinBackend createInProcessThinBackend(unsigned ParallelismLevel);
 205
 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.
 209 ///
 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);
 225
 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
 241 ///   the link.
 242 class LTO {
 243   friend InputFile;
 244
 245 public:
 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);
 253   ~LTO();
 254
 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);
 259
 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;
 264
 265   /// Runs the LTO pipeline. This function calls the supplied AddStream
 266   /// function to add native object files to the link.
 267   ///
 268   /// The Cache parameter is optional. If supplied, it will be used to cache
 269   /// native object files and add them to the link.
 270   ///
 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);
 274
 275 private:
 276   Config Conf;
 277
 278   struct RegularLTOState {
 279     RegularLTOState(unsigned ParallelCodeGenParallelismLevel, Config &Conf);
 280     struct CommonResolution {
 281       uint64_t Size = 0;
 282       unsigned Align = 0;
 283       /// Record if at least one instance of the common was marked as prevailing
 284       bool Prevailing = false;
 285     };
 286     std::map<std::string, CommonResolution> Commons;
 287
 288     unsigned ParallelCodeGenParallelismLevel;
 289     LTOLLVMContext Ctx;
 290     std::unique_ptr<Module> CombinedModule;
 291     std::unique_ptr<IRMover> Mover;
 292
 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
 296     // summaries).
 297     struct AddedModule {
 298       std::unique_ptr<Module> M;
 299       std::vector<GlobalValue *> Keep;
 300     };
 301     std::vector<AddedModule> ModsWithSummaries;
 302   } RegularLTO;
 303
 304   struct ThinLTOState {
 305     ThinLTOState(ThinBackend Backend);
 306
 307     ThinBackend Backend;
 308     ModuleSummaryIndex CombinedIndex;
 309     MapVector<StringRef, BitcodeModule> ModuleMap;
 310     DenseMap<GlobalValue::GUID, StringRef> PrevailingModuleForGUID;
 311   } ThinLTO;
 312
 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.
 322     std::string IRName;
 323
 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
 326     /// summary).
 327     bool VisibleOutsideSummary = false;
 328
 329     bool UnnamedAddr = true;
 330
 331     /// True if module contains the prevailing definition.
 332     bool Prevailing = false;
 333
 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(); }
 338
 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.
 342     ///
 343     /// Any global that is defined or used by more than one partition, or that
 344     /// is referenced externally, may not be internalized.
 345     ///
 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
 349     /// LTO backend.
 350     unsigned Partition = Unknown;
 351
 352     /// Special partition numbers.
 353     enum : unsigned {
 354       /// A partition number has not yet been assigned to this global.
 355       Unknown = -1u,
 356
 357       /// This global is either used by more than one partition or has an
 358       /// external reference, and therefore cannot be internalized.
 359       External = -2u,
 360
 361       /// The RegularLTO partition
 362       RegularLTO = 0,
 363     };
 364   };
 365
 366   // Global mapping from mangled symbol names to resolutions.
 367   StringMap<GlobalResolution> GlobalResolutions;
 368
 369   void addModuleToGlobalRes(ArrayRef<InputFile::Symbol> Syms,
 370                             ArrayRef<SymbolResolution> Res, unsigned Partition,
 371                             bool InSummary);
 372
 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);
 379
 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);
 385
 386   Error addThinLTO(BitcodeModule BM, ArrayRef<InputFile::Symbol> Syms,
 387                    const SymbolResolution *&ResI, const SymbolResolution *ResE);
 388
 389   Error runRegularLTO(AddStreamFn AddStream);
 390   Error runThinLTO(AddStreamFn AddStream, NativeObjectCache Cache);
 391
 392   mutable bool CalledGetMaxTasks = false;
 393 };
 394
 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 {
 398   SymbolResolution()
 399       : Prevailing(0), FinalDefinitionInLinkageUnit(0), VisibleToRegularObj(0),
 400         LinkerRedefined(0) {}
 401
 402   /// The linker has chosen this definition of the symbol.
 403   unsigned Prevailing : 1;
 404
 405   /// The definition of this symbol is unpreemptable at runtime and is known to
 406   /// be in this linkage unit.
 407   unsigned FinalDefinitionInLinkageUnit : 1;
 408
 409   /// The definition of this symbol is visible outside of the LTO unit.
 410   unsigned VisibleToRegularObj : 1;
 411
 412   /// Linker redefined version of the symbol which appeared in -wrap or -defsym
 413   /// linker option.
 414   unsigned LinkerRedefined : 1;
 415 };
 416
 417 } // namespace lto
 418 } // namespace llvm
 419
 420 #endif