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 21namespace llvm { 22 23class Constant; 24class Function; 25class GlobalIndirectSymbol; 26class GlobalVariable; 27class Instruction; 28class MDNode; 29class Metadata; 30class Type; 31class Value; 32 33using 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. 37class ValueMapTypeRemapper { 38 virtual void anchor(); // Out of line method. 39 40public: 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. 50class ValueMaterializer { 51 virtual void anchor(); // Out of line method. 52 53protected: 54 ValueMaterializer() = default; 55 ValueMaterializer(const ValueMaterializer &) = default; 56 ValueMaterializer &operator=(const ValueMaterializer &) = default; 57 ~ValueMaterializer() = default; 58 59public: 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. 66enum 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 101inline 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. 141class ValueMapper { 142 void *pImpl; 143 144public: 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. 206inline 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. 228inline 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. 236inline 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. 251inline 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. 264inline 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. 272inline 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 282