ThinLTOCodeGenerator.h

Go to the documentation of this file.

//===-ThinLTOCodeGenerator.h - LLVM Link Time Optimizer -------------------===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
//
// This file declares the ThinLTOCodeGenerator class, similar to the
// LTOCodeGenerator but for the ThinLTO scheme. It provides an interface for
// linker plugin.
//
//===----------------------------------------------------------------------===//
 
#ifndef LLVM_LTO_LEGACY_THINLTOCODEGENERATOR_H
#define LLVM_LTO_LEGACY_THINLTOCODEGENERATOR_H
 
#include "llvm-c/lto.h"
#include "llvm/ADT/StringSet.h"
#include "llvm/IR/ModuleSummaryIndex.h"
#include "llvm/LTO/LTO.h"
#include "llvm/Support/CachePruning.h"
#include "llvm/Support/CodeGen.h"
#include "llvm/Support/Compiler.h"
#include "llvm/Support/MemoryBuffer.h"
#include "llvm/Target/TargetOptions.h"
#include "llvm/TargetParser/Triple.h"
 
#include <string>
 
namespace llvm {
class StringRef;
class TargetMachine;
 
/// ThinLTOCodeGeneratorImpl - Namespace used for ThinLTOCodeGenerator
/// implementation details. It should be considered private to the
/// implementation.
namespace ThinLTOCodeGeneratorImpl {
struct TargetMachineBuilder;
}
 
/// Helper to gather options relevant to the target machine creation
struct ThinLTOCodeGeneratorImpl::TargetMachineBuilder {
  Triple TheTriple;
  std::string MCpu;
  std::string MAttr;
  TargetOptions Options;
  std::optional<Reloc::Model> RelocModel;
  CodeGenOptLevel CGOptLevel = CodeGenOptLevel::Aggressive;
 
  LLVM_ABI std::unique_ptr<TargetMachine> create() const;
};
 
/// This class define an interface similar to the LTOCodeGenerator, but adapted
/// for ThinLTO processing.
/// The ThinLTOCodeGenerator is not intended to be reuse for multiple
/// compilation: the model is that the client adds modules to the generator and
/// ask to perform the ThinLTO optimizations / codegen, and finally destroys the
/// codegenerator.
class ThinLTOCodeGenerator {
public:
  /// The target machines and the LLVMContexts that run() creates read
  /// \p LibraryOptions, which must outlive the generator.
  explicit ThinLTOCodeGenerator(const cl::LibraryOptionsContext &LibraryOptions)
      : LibraryOptions(LibraryOptions) {
    TMBuilder.Options.MCOptions.LibraryOptions = &LibraryOptions;
  }
 
  /// Add given module to the code generator.
  LLVM_ABI void addModule(StringRef Identifier, StringRef Data);
 
  /**
   * Adds to a list of all global symbols that must exist in the final generated
   * code. If a symbol is not listed there, it will be optimized away if it is
   * inlined into every usage.
   */
  LLVM_ABI void preserveSymbol(StringRef Name);
 
  /**
   * Adds to a list of all global symbols that are cross-referenced between
   * ThinLTO files. If the ThinLTO CodeGenerator can ensure that every
   * references from a ThinLTO module to this symbol is optimized away, then
   * the symbol can be discarded.
   */
  LLVM_ABI void crossReferenceSymbol(StringRef Name);
 
  /**
   * Process all the modules that were added to the code generator in parallel.
   *
   * Client can access the resulting object files using getProducedBinaries(),
   * unless setGeneratedObjectsDirectory() has been called, in which case
   * results are available through getProducedBinaryFiles().
   */
  LLVM_ABI void run();
 
  /**
   * Return the "in memory" binaries produced by the code generator. This is
   * filled after run() unless setGeneratedObjectsDirectory() has been
   * called, in which case results are available through
   * getProducedBinaryFiles().
   */
  std::vector<std::unique_ptr<MemoryBuffer>> &getProducedBinaries() {
    return ProducedBinaries;
  }
 
  /**
   * Return the "on-disk" binaries produced by the code generator. This is
   * filled after run() when setGeneratedObjectsDirectory() has been
   * called, in which case results are available through getProducedBinaries().
   */
  std::vector<std::string> &getProducedBinaryFiles() {
    return ProducedBinaryFiles;
  }
 
  /**
   * \defgroup Options setters
   * @{
   */
 
  /**
   * \defgroup Cache controlling options
   *
   * These entry points control the ThinLTO cache. The cache is intended to
   * support incremental build, and thus needs to be persistent accross build.
   * The client enabled the cache by supplying a path to an existing directory.
   * The code generator will use this to store objects files that may be reused
   * during a subsequent build.
   * To avoid filling the disk space, a few knobs are provided:
   *  - The pruning interval limit the frequency at which the garbage collector
   *    will try to scan the cache directory to prune it from expired entries.
   *    Setting to -1 disable the pruning (default). Setting to 0 will force
   *    pruning to occur.
   *  - The pruning expiration time indicates to the garbage collector how old
   *    an entry needs to be to be removed.
   *  - Finally, the garbage collector can be instructed to prune the cache till
   *    the occupied space goes below a threshold.
   * @{
   */
 
  struct CachingOptions {
    std::string Path;                    // Path to the cache, empty to disable.
    CachePruningPolicy Policy;
  };
 
  /// Provide a path to a directory where to store the cached files for
  /// incremental build.
  void setCacheDir(std::string Path) { CacheOptions.Path = std::move(Path); }
 
  /// Cache policy: interval (seconds) between two prunes of the cache. Set to a
  /// negative value to disable pruning. A value of 0 will force pruning to
  /// occur.
  void setCachePruningInterval(int Interval) {
    if(Interval < 0)
      CacheOptions.Policy.Interval.reset();
    else
      CacheOptions.Policy.Interval = std::chrono::seconds(Interval);
  }
 
  /// Cache policy: expiration (in seconds) for an entry.
  /// A value of 0 will be ignored.
  void setCacheEntryExpiration(unsigned Expiration) {
    if (Expiration)
      CacheOptions.Policy.Expiration = std::chrono::seconds(Expiration);
  }
 
  /**
   * Sets the maximum cache size that can be persistent across build, in terms
   * of percentage of the available space on the disk. Set to 100 to indicate
   * no limit, 50 to indicate that the cache size will not be left over
   * half the available space. A value over 100 will be reduced to 100, and a
   * value of 0 will be ignored.
   *
   *
   * The formula looks like:
   *  AvailableSpace = FreeSpace + ExistingCacheSize
   *  NewCacheSize = AvailableSpace * P/100
   *
   */
  void setMaxCacheSizeRelativeToAvailableSpace(unsigned Percentage) {
    if (Percentage)
      CacheOptions.Policy.MaxSizePercentageOfAvailableSpace = Percentage;
  }
 
  /// Cache policy: the maximum size for the cache directory in bytes. A value
  /// over the amount of available space on the disk will be reduced to the
  /// amount of available space. A value of 0 will be ignored.
  void setCacheMaxSizeBytes(uint64_t MaxSizeBytes) {
    if (MaxSizeBytes)
      CacheOptions.Policy.MaxSizeBytes = MaxSizeBytes;
  }
 
  /// Cache policy: the maximum number of files in the cache directory. A value
  /// of 0 will be ignored.
  void setCacheMaxSizeFiles(unsigned MaxSizeFiles) {
    if (MaxSizeFiles)
      CacheOptions.Policy.MaxSizeFiles = MaxSizeFiles;
  }
 
  /**@}*/
 
  /// Set the path to a directory where to save temporaries at various stages of
  /// the processing.
  void setSaveTempsDir(std::string Path) { SaveTempsDir = std::move(Path); }
 
  /// Set the path to a directory where to save generated object files. This
  /// path can be used by a linker to request on-disk files instead of in-memory
  /// buffers. When set, results are available through getProducedBinaryFiles()
  /// instead of getProducedBinaries().
  void setGeneratedObjectsDirectory(std::string Path) {
    SavedObjectsDirectoryPath = std::move(Path);
  }
 
  /// CPU to use to initialize the TargetMachine
  void setCpu(std::string Cpu) { TMBuilder.MCpu = std::move(Cpu); }
 
  /// Subtarget attributes
  void setAttr(std::string MAttr) { TMBuilder.MAttr = std::move(MAttr); }
 
  /// TargetMachine options
  void setTargetOptions(TargetOptions Options) {
    TMBuilder.Options = std::move(Options);
    TMBuilder.Options.MCOptions.LibraryOptions = &LibraryOptions;
  }
 
  /// Enable the Freestanding mode: indicate that the optimizer should not
  /// assume builtins are present on the target.
  void setFreestanding(bool Enabled) { Freestanding = Enabled; }
 
  /// CodeModel
  void setCodePICModel(std::optional<Reloc::Model> Model) {
    TMBuilder.RelocModel = Model;
  }
 
  /// CodeGen optimization level
  void setCodeGenOptLevel(CodeGenOptLevel CGOptLevel) {
    TMBuilder.CGOptLevel = CGOptLevel;
  }
 
  /// IR optimization level: from 0 to 3.
  void setOptLevel(unsigned NewOptLevel) {
    OptLevel = (NewOptLevel > 3) ? 3 : NewOptLevel;
  }
 
  /// Enable or disable debug output for the new pass manager.
  void setDebugPassManager(unsigned Enabled) { DebugPassManager = Enabled; }
 
  /// Set the -mllvm arguments to include in the cache key.
  void setMllvmArgs(ArrayRef<std::string> Args) {
    MllvmArgs.assign(Args.begin(), Args.end());
  }
 
  /// Disable CodeGen, only run the stages till codegen and stop. The output
  /// will be bitcode.
  void disableCodeGen(bool Disable) { DisableCodeGen = Disable; }
 
  /// Perform CodeGen only: disable all other stages.
  void setCodeGenOnly(bool CGOnly) { CodeGenOnly = CGOnly; }
 
  /**@}*/
 
  /**
   * \defgroup Set of APIs to run individual stages in isolation.
   * @{
   */
 
  /**
   * Produce the combined summary index from all the bitcode files:
   * "thin-link".
   */
  LLVM_ABI std::unique_ptr<ModuleSummaryIndex> linkCombinedIndex();
 
  /**
   * Perform promotion and renaming of exported internal functions,
   * and additionally resolve weak and linkonce symbols.
   * Index is updated to reflect linkage changes from weak resolution.
   */
  LLVM_ABI void promote(Module &Module, ModuleSummaryIndex &Index,
                        const lto::InputFile &File);
 
  /**
   * Compute and emit the imported files for module at \p ModulePath.
   */
  LLVM_ABI void emitImports(Module &Module, StringRef OutputName,
                            ModuleSummaryIndex &Index,
                            const lto::InputFile &File);
 
  /**
   * Perform cross-module importing for the module identified by
   * ModuleIdentifier.
   */
  LLVM_ABI void crossModuleImport(Module &Module, ModuleSummaryIndex &Index,
                                  const lto::InputFile &File);
 
  /**
   * Compute the list of summaries and the subset of declaration summaries
   * needed for importing into module.
   */
  LLVM_ABI void gatherImportedSummariesForModule(
      Module &Module, ModuleSummaryIndex &Index,
      ModuleToSummariesForIndexTy &ModuleToSummariesForIndex,
      GVSummaryPtrSet &DecSummaries, const lto::InputFile &File);
 
  /**
   * Perform internalization. Index is updated to reflect linkage changes.
   */
  LLVM_ABI void internalize(Module &Module, ModuleSummaryIndex &Index,
                            const lto::InputFile &File);
 
  /**
   * Perform post-importing ThinLTO optimizations.
   */
  LLVM_ABI void optimize(Module &Module);
 
  /**
   * Write temporary object file to SavedObjectDirectoryPath, write symlink
   * to Cache directory if needed. Returns the path to the generated file in
   * SavedObjectsDirectoryPath.
   */
  LLVM_ABI std::string writeGeneratedObject(int count, StringRef CacheEntryPath,
                                            const MemoryBuffer &OutputBuffer);
  /**@}*/
 
private:
  const cl::LibraryOptionsContext &LibraryOptions;
 
  /// Helper factory to build a TargetMachine
  ThinLTOCodeGeneratorImpl::TargetMachineBuilder TMBuilder;
 
  /// Vector holding the in-memory buffer containing the produced binaries, when
  /// SavedObjectsDirectoryPath isn't set.
  std::vector<std::unique_ptr<MemoryBuffer>> ProducedBinaries;
 
  /// Path to generated files in the supplied SavedObjectsDirectoryPath if any.
  std::vector<std::string> ProducedBinaryFiles;
 
  /// Vector holding the input buffers containing the bitcode modules to
  /// process.
  std::vector<std::unique_ptr<lto::InputFile>> Modules;
 
  /// Set of symbols that need to be preserved outside of the set of bitcode
  /// files.
  StringSet<> PreservedSymbols;
 
  /// Set of symbols that are cross-referenced between bitcode files.
  StringSet<> CrossReferencedSymbols;
 
  /// Control the caching behavior.
  CachingOptions CacheOptions;
 
  /// Path to a directory to save the temporary bitcode files.
  std::string SaveTempsDir;
 
  /// Path to a directory to save the generated object files.
  std::string SavedObjectsDirectoryPath;
 
  /// Flag to enable/disable CodeGen. When set to true, the process stops after
  /// optimizations and a bitcode is produced.
  bool DisableCodeGen = false;
 
  /// Flag to indicate that only the CodeGen will be performed, no cross-module
  /// importing or optimization.
  bool CodeGenOnly = false;
 
  /// Flag to indicate that the optimizer should not assume builtins are present
  /// on the target.
  bool Freestanding = false;
 
  /// IR Optimization Level [0-3].
  unsigned OptLevel = 3;
 
  /// Flag to indicate whether debug output should be enabled for the new pass
  /// manager.
  bool DebugPassManager = false;
 
  /// -mllvm arguments included in the cache key.
  std::vector<std::string> MllvmArgs;
};
}
#endif