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
22namespace llvm {
23
24class Constant;
25class DPValue;
26class Function;
27class GlobalVariable;
28class Instruction;
29class MDNode;
30class Metadata;
31class Module;
32class Type;
33class Value;
34
35using ValueToValueMapTy = ValueMap<const Value *, WeakTrackingVH>;
36using 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.
40class ValueMapTypeRemapper {
41 virtual void anchor(); // Out of line method.
42
43public:
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.
53class ValueMaterializer {
54 virtual void anchor(); // Out of line method.
55
56protected:
57 ValueMaterializer() = default;
58 ValueMaterializer(const ValueMaterializer &) = default;
59 ValueMaterializer &operator=(const ValueMaterializer &) = default;
60 ~ValueMaterializer() = default;
61
62public:
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.
69enum 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
106inline 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.
148class ValueMapper {
149 void *pImpl;
150
151public:
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.
217inline 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.
239inline 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.
247inline 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.
262inline 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.
270inline 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.
278inline 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.
291inline 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.
299inline 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

source code of llvm/include/llvm/Transforms/Utils/ValueMapper.h