include/llvm/Transforms/Utils/ValueMapper.h

   1 //===- ValueMapper.h - Remapping for constants and metadata -----*- C++ -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8 //
   9 // This file defines the MapValue interface which is used by various parts of
  10 // the Transforms/Utils library to implement cloning and linking facilities.
  11 //
  12 //===----------------------------------------------------------------------===//
  13
  14 #ifndef LLVM_TRANSFORMS_UTILS_VALUEMAPPER_H
  15 #define LLVM_TRANSFORMS_UTILS_VALUEMAPPER_H
  16
  17 #include "llvm/ADT/ArrayRef.h"
  18 #include "llvm/IR/ValueHandle.h"
  19 #include "llvm/IR/ValueMap.h"
  20
  21 namespace llvm {
  22
  23 class Constant;
  24 class Function;
  25 class GlobalIndirectSymbol;
  26 class GlobalVariable;
  27 class Instruction;
  28 class MDNode;
  29 class Metadata;
  30 class Type;
  31 class Value;
  32
  33 using ValueToValueMapTy = ValueMap<const Value *, WeakTrackingVH>;
  34
  35 /// This is a class that can be implemented by clients to remap types when
  36 /// cloning constants and instructions.
  37 class ValueMapTypeRemapper {
  38   virtual void anchor(); // Out of line method.
  39
  40 public:
  41   virtual ~ValueMapTypeRemapper() = default;
  42
  43   /// The client should implement this method if they want to remap types while
  44   /// mapping values.
  45   virtual Type *remapType(Type *SrcTy) = 0;
  46 };
  47
  48 /// This is a class that can be implemented by clients to materialize Values on
  49 /// demand.
  50 class ValueMaterializer {
  51   virtual void anchor(); // Out of line method.
  52
  53 protected:
  54   ValueMaterializer() = default;
  55   ValueMaterializer(const ValueMaterializer &) = default;
  56   ValueMaterializer &operator=(const ValueMaterializer &) = default;
  57   ~ValueMaterializer() = default;
  58
  59 public:
  60   /// This method can be implemented to generate a mapped Value on demand. For
  61   /// example, if linking lazily. Returns null if the value is not materialized.
  62   virtual Value *materialize(Value *V) = 0;
  63 };
  64
  65 /// These are flags that the value mapping APIs allow.
  66 enum RemapFlags {
  67   RF_None = 0,
  68
  69   /// If this flag is set, the remapper knows that only local values within a
  70   /// function (such as an instruction or argument) are mapped, not global
  71   /// values like functions and global metadata.
  72   RF_NoModuleLevelChanges = 1,
  73
  74   /// If this flag is set, the remapper ignores missing function-local entries
  75   /// (Argument, Instruction, BasicBlock) that are not in the value map.  If it
  76   /// is unset, it aborts if an operand is asked to be remapped which doesn't
  77   /// exist in the mapping.
  78   ///
  79   /// There are no such assertions in MapValue(), whose results are almost
  80   /// unchanged by this flag.  This flag mainly changes the assertion behaviour
  81   /// in RemapInstruction().
  82   ///
  83   /// Since an Instruction's metadata operands (even that point to SSA values)
  84   /// aren't guaranteed to be dominated by their definitions, MapMetadata will
  85   /// return "!{}" instead of "null" for \a LocalAsMetadata instances whose SSA
  86   /// values are unmapped when this flag is set.  Otherwise, \a MapValue()
  87   /// completely ignores this flag.
  88   ///
  89   /// \a MapMetadata() always ignores this flag.
  90   RF_IgnoreMissingLocals = 2,
  91
  92   /// Instruct the remapper to move distinct metadata instead of duplicating it
  93   /// when there are module-level changes.
  94   RF_MoveDistinctMDs = 4,
  95
  96   /// Any global values not in value map are mapped to null instead of mapping
  97   /// to self.  Illegal if RF_IgnoreMissingLocals is also set.
  98   RF_NullMapMissingGlobalValues = 8,
  99 };
 100
 101 inline RemapFlags operator|(RemapFlags LHS, RemapFlags RHS) {
 102   return RemapFlags(unsigned(LHS) | unsigned(RHS));
 103 }
 104
 105 /// Context for (re-)mapping values (and metadata).
 106 ///
 107 /// A shared context used for mapping and remapping of Value and Metadata
 108 /// instances using \a ValueToValueMapTy, \a RemapFlags, \a
 109 /// ValueMapTypeRemapper, and \a ValueMaterializer.
 110 ///
 111 /// There are a number of top-level entry points:
 112 /// - \a mapValue() (and \a mapConstant());
 113 /// - \a mapMetadata() (and \a mapMDNode());
 114 /// - \a remapInstruction(); and
 115 /// - \a remapFunction().
 116 ///
 117 /// The \a ValueMaterializer can be used as a callback, but cannot invoke any
 118 /// of these top-level functions recursively.  Instead, callbacks should use
 119 /// one of the following to schedule work lazily in the \a ValueMapper
 120 /// instance:
 121 /// - \a scheduleMapGlobalInitializer()
 122 /// - \a scheduleMapAppendingVariable()
 123 /// - \a scheduleMapGlobalIndirectSymbol()
 124 /// - \a scheduleRemapFunction()
 125 ///
 126 /// Sometimes a callback needs a different mapping context.  Such a context can
 127 /// be registered using \a registerAlternateMappingContext(), which takes an
 128 /// alternate \a ValueToValueMapTy and \a ValueMaterializer and returns a ID to
 129 /// pass into the schedule*() functions.
 130 ///
 131 /// TODO: lib/Linker really doesn't need the \a ValueHandle in the \a
 132 /// ValueToValueMapTy.  We should template \a ValueMapper (and its
 133 /// implementation classes), and explicitly instantiate on two concrete
 134 /// instances of \a ValueMap (one as \a ValueToValueMap, and one with raw \a
 135 /// Value pointers).  It may be viable to do away with \a TrackingMDRef in the
 136 /// \a Metadata side map for the lib/Linker case as well, in which case we'll
 137 /// need a new template parameter on \a ValueMap.
 138 ///
 139 /// TODO: Update callers of \a RemapInstruction() and \a MapValue() (etc.) to
 140 /// use \a ValueMapper directly.
 141 class ValueMapper {
 142   void *pImpl;
 143
 144 public:
 145   ValueMapper(ValueToValueMapTy &VM, RemapFlags Flags = RF_None,
 146               ValueMapTypeRemapper *TypeMapper = nullptr,
 147               ValueMaterializer *Materializer = nullptr);
 148   ValueMapper(ValueMapper &&) = delete;
 149   ValueMapper(const ValueMapper &) = delete;
 150   ValueMapper &operator=(ValueMapper &&) = delete;
 151   ValueMapper &operator=(const ValueMapper &) = delete;
 152   ~ValueMapper();
 153
 154   /// Register an alternate mapping context.
 155   ///
 156   /// Returns a MappingContextID that can be used with the various schedule*()
 157   /// API to switch in a different value map on-the-fly.
 158   unsigned
 159   registerAlternateMappingContext(ValueToValueMapTy &VM,
 160                                   ValueMaterializer *Materializer = nullptr);
 161
 162   /// Add to the current \a RemapFlags.
 163   ///
 164   /// \note Like the top-level mapping functions, \a addFlags() must be called
 165   /// at the top level, not during a callback in a \a ValueMaterializer.
 166   void addFlags(RemapFlags Flags);
 167
 168   Metadata *mapMetadata(const Metadata &MD);
 169   MDNode *mapMDNode(const MDNode &N);
 170
 171   Value *mapValue(const Value &V);
 172   Constant *mapConstant(const Constant &C);
 173
 174   void remapInstruction(Instruction &I);
 175   void remapFunction(Function &F);
 176
 177   void scheduleMapGlobalInitializer(GlobalVariable &GV, Constant &Init,
 178                                     unsigned MappingContextID = 0);
 179   void scheduleMapAppendingVariable(GlobalVariable &GV, Constant *InitPrefix,
 180                                     bool IsOldCtorDtor,
 181                                     ArrayRef<Constant *> NewMembers,
 182                                     unsigned MappingContextID = 0);
 183   void scheduleMapGlobalIndirectSymbol(GlobalIndirectSymbol &GIS,
 184                                        Constant &Target,
 185                                        unsigned MappingContextID = 0);
 186   void scheduleRemapFunction(Function &F, unsigned MappingContextID = 0);
 187 };
 188
 189 /// Look up or compute a value in the value map.
 190 ///
 191 /// Return a mapped value for a function-local value (Argument, Instruction,
 192 /// BasicBlock), or compute and memoize a value for a Constant.
 193 ///
 194 ///  1. If \c V is in VM, return the result.
 195 ///  2. Else if \c V can be materialized with \c Materializer, do so, memoize
 196 ///     it in \c VM, and return it.
 197 ///  3. Else if \c V is a function-local value, return nullptr.
 198 ///  4. Else if \c V is a \a GlobalValue, return \c nullptr or \c V depending
 199 ///     on \a RF_NullMapMissingGlobalValues.
 200 ///  5. Else if \c V is a \a MetadataAsValue wrapping a LocalAsMetadata,
 201 ///     recurse on the local SSA value, and return nullptr or "metadata !{}" on
 202 ///     missing depending on RF_IgnoreMissingValues.
 203 ///  6. Else if \c V is a \a MetadataAsValue, rewrap the return of \a
 204 ///     MapMetadata().
 205 ///  7. Else, compute the equivalent constant, and return it.
 206 inline Value *MapValue(const Value *V, ValueToValueMapTy &VM,
 207                        RemapFlags Flags = RF_None,
 208                        ValueMapTypeRemapper *TypeMapper = nullptr,
 209                        ValueMaterializer *Materializer = nullptr) {
 210   return ValueMapper(VM, Flags, TypeMapper, Materializer).mapValue(*V);
 211 }
 212
 213 /// Lookup or compute a mapping for a piece of metadata.
 214 ///
 215 /// Compute and memoize a mapping for \c MD.
 216 ///
 217 ///  1. If \c MD is mapped, return it.
 218 ///  2. Else if \a RF_NoModuleLevelChanges or \c MD is an \a MDString, return
 219 ///     \c MD.
 220 ///  3. Else if \c MD is a \a ConstantAsMetadata, call \a MapValue() and
 221 ///     re-wrap its return (returning nullptr on nullptr).
 222 ///  4. Else, \c MD is an \a MDNode.  These are remapped, along with their
 223 ///     transitive operands.  Distinct nodes are duplicated or moved depending
 224 ///     on \a RF_MoveDistinctNodes.  Uniqued nodes are remapped like constants.
 225 ///
 226 /// \note \a LocalAsMetadata is completely unsupported by \a MapMetadata.
 227 /// Instead, use \a MapValue() with its wrapping \a MetadataAsValue instance.
 228 inline Metadata *MapMetadata(const Metadata *MD, ValueToValueMapTy &VM,
 229                              RemapFlags Flags = RF_None,
 230                              ValueMapTypeRemapper *TypeMapper = nullptr,
 231                              ValueMaterializer *Materializer = nullptr) {
 232   return ValueMapper(VM, Flags, TypeMapper, Materializer).mapMetadata(*MD);
 233 }
 234
 235 /// Version of MapMetadata with type safety for MDNode.
 236 inline MDNode *MapMetadata(const MDNode *MD, ValueToValueMapTy &VM,
 237                            RemapFlags Flags = RF_None,
 238                            ValueMapTypeRemapper *TypeMapper = nullptr,
 239                            ValueMaterializer *Materializer = nullptr) {
 240   return ValueMapper(VM, Flags, TypeMapper, Materializer).mapMDNode(*MD);
 241 }
 242
 243 /// Convert the instruction operands from referencing the current values into
 244 /// those specified by VM.
 245 ///
 246 /// If \a RF_IgnoreMissingLocals is set and an operand can't be found via \a
 247 /// MapValue(), use the old value.  Otherwise assert that this doesn't happen.
 248 ///
 249 /// Note that \a MapValue() only returns \c nullptr for SSA values missing from
 250 /// \c VM.
 251 inline void RemapInstruction(Instruction *I, ValueToValueMapTy &VM,
 252                              RemapFlags Flags = RF_None,
 253                              ValueMapTypeRemapper *TypeMapper = nullptr,
 254                              ValueMaterializer *Materializer = nullptr) {
 255   ValueMapper(VM, Flags, TypeMapper, Materializer).remapInstruction(*I);
 256 }
 257
 258 /// Remap the operands, metadata, arguments, and instructions of a function.
 259 ///
 260 /// Calls \a MapValue() on prefix data, prologue data, and personality
 261 /// function; calls \a MapMetadata() on each attached MDNode; remaps the
 262 /// argument types using the provided \c TypeMapper; and calls \a
 263 /// RemapInstruction() on every instruction.
 264 inline void RemapFunction(Function &F, ValueToValueMapTy &VM,
 265                           RemapFlags Flags = RF_None,
 266                           ValueMapTypeRemapper *TypeMapper = nullptr,
 267                           ValueMaterializer *Materializer = nullptr) {
 268   ValueMapper(VM, Flags, TypeMapper, Materializer).remapFunction(F);
 269 }
 270
 271 /// Version of MapValue with type safety for Constant.
 272 inline Constant *MapValue(const Constant *V, ValueToValueMapTy &VM,
 273                           RemapFlags Flags = RF_None,
 274                           ValueMapTypeRemapper *TypeMapper = nullptr,
 275                           ValueMaterializer *Materializer = nullptr) {
 276   return ValueMapper(VM, Flags, TypeMapper, Materializer).mapConstant(*V);
 277 }
 278
 279 } // end namespace llvm
 280
 281 #endif // LLVM_TRANSFORMS_UTILS_VALUEMAPPER_H