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