include/llvm/CodeGen/GCStrategy.h

   1 //===-- llvm/CodeGen/GCStrategy.h - Garbage collection ----------*- C++ -*-===//
   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 // GCStrategy coordinates code generation algorithms and implements some itself
  11 // in order to generate code compatible with a target code generator as
  12 // specified in a function's 'gc' attribute. Algorithms are enabled by setting
  13 // flags in a subclass's constructor, and some virtual methods can be
  14 // overridden.
  15 //
  16 // GCStrategy is relevant for implementations using either gc.root or
  17 // gc.statepoint based lowering strategies, but is currently focused mostly on
  18 // options for gc.root.  This will change over time.
  19 //
  20 // When requested by a subclass of GCStrategy, the gc.root implementation will
  21 // populate GCModuleInfo and GCFunctionInfo with that about each Function in
  22 // the Module that opts in to garbage collection.  Specifically:
  23 //
  24 // - Safe points
  25 //   Garbage collection is generally only possible at certain points in code.
  26 //   GCStrategy can request that the collector insert such points:
  27 //
  28 //     - At and after any call to a subroutine
  29 //     - Before returning from the current function
  30 //     - Before backwards branches (loops)
  31 //
  32 // - Roots
  33 //   When a reference to a GC-allocated object exists on the stack, it must be
  34 //   stored in an alloca registered with llvm.gcoot.
  35 //
  36 // This information can used to emit the metadata tables which are required by
  37 // the target garbage collector runtime.
  38 //
  39 // When used with gc.statepoint, information about safepoint and roots can be
  40 // found in the binary StackMap section after code generation.  Safepoint
  41 // placement is currently the responsibility of the frontend, though late
  42 // insertion support is planned.  gc.statepoint does not currently support
  43 // custom stack map formats; such can be generated by parsing the standard
  44 // stack map section if desired.
  45 //
  46 // The read and write barrier support can be used with either implementation.
  47 //
  48 //===----------------------------------------------------------------------===//
  49
  50 #ifndef LLVM_CODEGEN_GCSTRATEGY_H
  51 #define LLVM_CODEGEN_GCSTRATEGY_H
  52
  53 #include "llvm/CodeGen/GCMetadata.h"
  54 #include "llvm/CodeGen/MachineFunction.h"
  55 #include "llvm/Support/Registry.h"
  56 #include <string>
  57
  58 namespace llvm {
  59   /// GCStrategy describes a garbage collector algorithm's code generation
  60   /// requirements, and provides overridable hooks for those needs which cannot
  61   /// be abstractly described.  GCStrategy objects currently must be looked up
  62   /// through the GCModuleInfo analysis pass.  They are owned by the analysis
  63   /// pass and recreated every time that pass is invalidated.
  64   class GCStrategy {
  65   private:
  66     std::string Name;
  67     friend class GCModuleInfo;
  68
  69   protected:
  70     unsigned NeededSafePoints; ///< Bitmask of required safe points.
  71     bool CustomReadBarriers;   ///< Default is to insert loads.
  72     bool CustomWriteBarriers;  ///< Default is to insert stores.
  73     bool CustomRoots;          ///< Default is to pass through to backend.
  74     bool CustomSafePoints;     ///< Default is to use NeededSafePoints
  75                                ///< to find safe points.
  76     bool InitRoots;            ///< If set, roots are nulled during lowering.
  77     bool UsesMetadata;         ///< If set, backend must emit metadata tables.
  78
  79   public:
  80     GCStrategy();
  81     virtual ~GCStrategy() {}
  82
  83     /// Return the name of the GC strategy.  This is the value of the collector
  84     /// name string specified on functions which use this strategy.
  85     const std::string &getName() const { return Name; }
  86
  87     /// By default, write barriers are replaced with simple store
  88     /// instructions. If true, then performCustomLowering must instead lower
  89     /// them.
  90     bool customWriteBarrier() const { return CustomWriteBarriers; }
  91
  92     /// By default, read barriers are replaced with simple load
  93     /// instructions. If true, then performCustomLowering must instead lower
  94     /// them.
  95     bool customReadBarrier() const { return CustomReadBarriers; }
  96
  97     /** @name GCRoot Specific Properties
  98      * These properties and overrides only apply to collector strategies using
  99      * GCRoot.
 100      */
 101     ///@{
 102
 103     /// True if safe points of any kind are required. By default, none are
 104     /// recorded.
 105     bool needsSafePoints() const {
 106       return CustomSafePoints || NeededSafePoints != 0;
 107     }
 108
 109     /// True if the given kind of safe point is required. By default, none are
 110     /// recorded.
 111     bool needsSafePoint(GC::PointKind Kind) const {
 112       return (NeededSafePoints & 1 << Kind) != 0;
 113     }
 114
 115     /// By default, roots are left for the code generator so it can generate a
 116     /// stack map. If true, then performCustomLowering must delete them.
 117     bool customRoots() const { return CustomRoots; }
 118
 119     /// By default, the GC analysis will find safe points according to
 120     /// NeededSafePoints. If true, then findCustomSafePoints must create them.
 121     bool customSafePoints() const { return CustomSafePoints; }
 122
 123     /// If set, gcroot intrinsics should initialize their allocas to null
 124     /// before the first use. This is necessary for most GCs and is enabled by
 125     /// default.
 126     bool initializeRoots() const { return InitRoots; }
 127
 128     /// If set, appropriate metadata tables must be emitted by the back-end
 129     /// (assembler, JIT, or otherwise).
 130     bool usesMetadata() const { return UsesMetadata; }
 131
 132     ///@}
 133
 134     /// initializeCustomLowering/performCustomLowering - If any of the actions
 135     /// are set to custom, performCustomLowering must be overriden to transform
 136     /// the corresponding actions to LLVM IR. initializeCustomLowering is
 137     /// optional to override. These are the only GCStrategy methods through
 138     /// which the LLVM IR can be modified.  These methods apply mostly to
 139     /// gc.root based implementations, but can be overriden to provide custom
 140     /// barrier lowerings with gc.statepoint as well.
 141     ///@{
 142     virtual bool initializeCustomLowering(Module &F) {
 143       // No changes made
 144       return false;
 145     }
 146     virtual bool performCustomLowering(Function &F) {
 147       llvm_unreachable("GCStrategy subclass specified a configuration which"
 148                        "requires a custom lowering without providing one");
 149     }
 150     ///@}
 151     /// Called if customSafepoints returns true, used only by gc.root
 152     /// implementations.
 153     virtual bool findCustomSafePoints(GCFunctionInfo& FI, MachineFunction& MF) {
 154       llvm_unreachable("GCStrategy subclass specified a configuration which"
 155                        "requests custom safepoint identification without"
 156                        "providing an implementation for such");
 157     }
 158   };
 159
 160   /// Subclasses of GCStrategy are made available for use during compilation by
 161   /// adding them to the global GCRegistry.  This can done either within the
 162   /// LLVM source tree or via a loadable plugin.  An example registeration
 163   /// would be:
 164   /// static GCRegistry::Add<CustomGC> X("custom-name",
 165   ///        "my custom supper fancy gc strategy");
 166   ///
 167   /// Note that to use a custom GCMetadataPrinter w/gc.roots, you must also
 168   /// register your GCMetadataPrinter subclass with the
 169   /// GCMetadataPrinterRegistery as well.
 170   typedef Registry<GCStrategy> GCRegistry;
 171 }
 172
 173 #endif