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