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