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