1 //===- ValueMapper.h - Remapping for constants and metadata -----*- C++ -*-===//
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
7 //===----------------------------------------------------------------------===//
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.
12 //===----------------------------------------------------------------------===//
14 #ifndef LLVM_TRANSFORMS_UTILS_VALUEMAPPER_H
15 #define LLVM_TRANSFORMS_UTILS_VALUEMAPPER_H
17 #include "llvm/ADT/ArrayRef.h"
18 #include "llvm/IR/ValueHandle.h"
19 #include "llvm/IR/ValueMap.h"
32 using ValueToValueMapTy = ValueMap<const Value *, WeakTrackingVH>;
34 /// This is a class that can be implemented by clients to remap types when
35 /// cloning constants and instructions.
36 class ValueMapTypeRemapper {
37 virtual void anchor(); // Out of line method.
40 virtual ~ValueMapTypeRemapper() = default;
42 /// The client should implement this method if they want to remap types while
44 virtual Type *remapType(Type *SrcTy) = 0;
47 /// This is a class that can be implemented by clients to materialize Values on
49 class ValueMaterializer {
50 virtual void anchor(); // Out of line method.
53 ValueMaterializer() = default;
54 ValueMaterializer(const ValueMaterializer &) = default;
55 ValueMaterializer &operator=(const ValueMaterializer &) = default;
56 ~ValueMaterializer() = default;
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;
64 /// These are flags that the value mapping APIs allow.
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.
71 RF_NoModuleLevelChanges = 1,
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.
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().
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.
88 /// \a MapMetadata() always ignores this flag.
89 RF_IgnoreMissingLocals = 2,
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
95 RF_ReuseAndMutateDistinctMDs = 4,
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.
99 RF_NullMapMissingGlobalValues = 8,
102 inline RemapFlags operator|(RemapFlags LHS, RemapFlags RHS) {
103 return RemapFlags(unsigned(LHS) | unsigned(RHS));
106 /// Context for (re-)mapping values (and metadata).
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.
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();
116 /// - \a remapFunction(); and
117 /// - \a remapGlobalObjectMetadata().
119 /// The \a ValueMaterializer can be used as a callback, but cannot invoke any
120 /// of these top-level functions recursively. Instead, callbacks should use
121 /// one of the following to schedule work lazily in the \a ValueMapper
123 /// - \a scheduleMapGlobalInitializer()
124 /// - \a scheduleMapAppendingVariable()
125 /// - \a scheduleMapGlobalAlias()
126 /// - \a scheduleMapGlobalIFunc()
127 /// - \a scheduleRemapFunction()
129 /// Sometimes a callback needs a different mapping context. Such a context can
130 /// be registered using \a registerAlternateMappingContext(), which takes an
131 /// alternate \a ValueToValueMapTy and \a ValueMaterializer and returns a ID to
132 /// pass into the schedule*() functions.
134 /// TODO: lib/Linker really doesn't need the \a ValueHandle in the \a
135 /// ValueToValueMapTy. We should template \a ValueMapper (and its
136 /// implementation classes), and explicitly instantiate on two concrete
137 /// instances of \a ValueMap (one as \a ValueToValueMap, and one with raw \a
138 /// Value pointers). It may be viable to do away with \a TrackingMDRef in the
139 /// \a Metadata side map for the lib/Linker case as well, in which case we'll
140 /// need a new template parameter on \a ValueMap.
142 /// TODO: Update callers of \a RemapInstruction() and \a MapValue() (etc.) to
143 /// use \a ValueMapper directly.
148 ValueMapper(ValueToValueMapTy &VM, RemapFlags Flags = RF_None,
149 ValueMapTypeRemapper *TypeMapper = nullptr,
150 ValueMaterializer *Materializer = nullptr);
151 ValueMapper(ValueMapper &&) = delete;
152 ValueMapper(const ValueMapper &) = delete;
153 ValueMapper &operator=(ValueMapper &&) = delete;
154 ValueMapper &operator=(const ValueMapper &) = delete;
157 /// Register an alternate mapping context.
159 /// Returns a MappingContextID that can be used with the various schedule*()
160 /// API to switch in a different value map on-the-fly.
162 registerAlternateMappingContext(ValueToValueMapTy &VM,
163 ValueMaterializer *Materializer = nullptr);
165 /// Add to the current \a RemapFlags.
167 /// \note Like the top-level mapping functions, \a addFlags() must be called
168 /// at the top level, not during a callback in a \a ValueMaterializer.
169 void addFlags(RemapFlags Flags);
171 Metadata *mapMetadata(const Metadata &MD);
172 MDNode *mapMDNode(const MDNode &N);
174 Value *mapValue(const Value &V);
175 Constant *mapConstant(const Constant &C);
177 void remapInstruction(Instruction &I);
178 void remapFunction(Function &F);
179 void remapGlobalObjectMetadata(GlobalObject &GO);
181 void scheduleMapGlobalInitializer(GlobalVariable &GV, Constant &Init,
182 unsigned MappingContextID = 0);
183 void scheduleMapAppendingVariable(GlobalVariable &GV, Constant *InitPrefix,
185 ArrayRef<Constant *> NewMembers,
186 unsigned MappingContextID = 0);
187 void scheduleMapGlobalAlias(GlobalAlias &GA, Constant &Aliasee,
188 unsigned MappingContextID = 0);
189 void scheduleMapGlobalIFunc(GlobalIFunc &GI, Constant &Resolver,
190 unsigned MappingContextID = 0);
191 void scheduleRemapFunction(Function &F, unsigned MappingContextID = 0);
194 /// Look up or compute a value in the value map.
196 /// Return a mapped value for a function-local value (Argument, Instruction,
197 /// BasicBlock), or compute and memoize a value for a Constant.
199 /// 1. If \c V is in VM, return the result.
200 /// 2. Else if \c V can be materialized with \c Materializer, do so, memoize
201 /// it in \c VM, and return it.
202 /// 3. Else if \c V is a function-local value, return nullptr.
203 /// 4. Else if \c V is a \a GlobalValue, return \c nullptr or \c V depending
204 /// on \a RF_NullMapMissingGlobalValues.
205 /// 5. Else if \c V is a \a MetadataAsValue wrapping a LocalAsMetadata,
206 /// recurse on the local SSA value, and return nullptr or "metadata !{}" on
207 /// missing depending on RF_IgnoreMissingValues.
208 /// 6. Else if \c V is a \a MetadataAsValue, rewrap the return of \a
210 /// 7. Else, compute the equivalent constant, and return it.
211 inline Value *MapValue(const Value *V, ValueToValueMapTy &VM,
212 RemapFlags Flags = RF_None,
213 ValueMapTypeRemapper *TypeMapper = nullptr,
214 ValueMaterializer *Materializer = nullptr) {
215 return ValueMapper(VM, Flags, TypeMapper, Materializer).mapValue(*V);
218 /// Lookup or compute a mapping for a piece of metadata.
220 /// Compute and memoize a mapping for \c MD.
222 /// 1. If \c MD is mapped, return it.
223 /// 2. Else if \a RF_NoModuleLevelChanges or \c MD is an \a MDString, return
225 /// 3. Else if \c MD is a \a ConstantAsMetadata, call \a MapValue() and
226 /// re-wrap its return (returning nullptr on nullptr).
227 /// 4. Else, \c MD is an \a MDNode. These are remapped, along with their
228 /// transitive operands. Distinct nodes are duplicated or moved depending
229 /// on \a RF_MoveDistinctNodes. Uniqued nodes are remapped like constants.
231 /// \note \a LocalAsMetadata is completely unsupported by \a MapMetadata.
232 /// Instead, use \a MapValue() with its wrapping \a MetadataAsValue instance.
233 inline Metadata *MapMetadata(const Metadata *MD, ValueToValueMapTy &VM,
234 RemapFlags Flags = RF_None,
235 ValueMapTypeRemapper *TypeMapper = nullptr,
236 ValueMaterializer *Materializer = nullptr) {
237 return ValueMapper(VM, Flags, TypeMapper, Materializer).mapMetadata(*MD);
240 /// Version of MapMetadata with type safety for MDNode.
241 inline MDNode *MapMetadata(const MDNode *MD, ValueToValueMapTy &VM,
242 RemapFlags Flags = RF_None,
243 ValueMapTypeRemapper *TypeMapper = nullptr,
244 ValueMaterializer *Materializer = nullptr) {
245 return ValueMapper(VM, Flags, TypeMapper, Materializer).mapMDNode(*MD);
248 /// Convert the instruction operands from referencing the current values into
249 /// those specified by VM.
251 /// If \a RF_IgnoreMissingLocals is set and an operand can't be found via \a
252 /// MapValue(), use the old value. Otherwise assert that this doesn't happen.
254 /// Note that \a MapValue() only returns \c nullptr for SSA values missing from
256 inline void RemapInstruction(Instruction *I, ValueToValueMapTy &VM,
257 RemapFlags Flags = RF_None,
258 ValueMapTypeRemapper *TypeMapper = nullptr,
259 ValueMaterializer *Materializer = nullptr) {
260 ValueMapper(VM, Flags, TypeMapper, Materializer).remapInstruction(*I);
263 /// Remap the operands, metadata, arguments, and instructions of a function.
265 /// Calls \a MapValue() on prefix data, prologue data, and personality
266 /// function; calls \a MapMetadata() on each attached MDNode; remaps the
267 /// argument types using the provided \c TypeMapper; and calls \a
268 /// RemapInstruction() on every instruction.
269 inline void RemapFunction(Function &F, ValueToValueMapTy &VM,
270 RemapFlags Flags = RF_None,
271 ValueMapTypeRemapper *TypeMapper = nullptr,
272 ValueMaterializer *Materializer = nullptr) {
273 ValueMapper(VM, Flags, TypeMapper, Materializer).remapFunction(F);
276 /// Version of MapValue with type safety for Constant.
277 inline Constant *MapValue(const Constant *V, ValueToValueMapTy &VM,
278 RemapFlags Flags = RF_None,
279 ValueMapTypeRemapper *TypeMapper = nullptr,
280 ValueMaterializer *Materializer = nullptr) {
281 return ValueMapper(VM, Flags, TypeMapper, Materializer).mapConstant(*V);
284 } // end namespace llvm
286 #endif // LLVM_TRANSFORMS_UTILS_VALUEMAPPER_H