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