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