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 
22 namespace llvm {
23 
24 class Constant;
25 class Function;
26 class GlobalAlias;
27 class GlobalVariable;
28 class Instruction;
29 class MDNode;
30 class Metadata;
31 class Type;
32 class Value;
33 
34 using 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.
38 class ValueMapTypeRemapper {
39   virtual void anchor(); // Out of line method.
40 
41 public:
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.
51 class ValueMaterializer {
52   virtual void anchor(); // Out of line method.
53 
54 protected:
55   ValueMaterializer() = default;
56   ValueMaterializer(const ValueMaterializer &) = default;
57   ValueMaterializer &operator=(const ValueMaterializer &) = default;
58   ~ValueMaterializer() = default;
59 
60 public:
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.
67 enum 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 
102 inline 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.
142 class ValueMapper {
143   void *pImpl;
144 
145 public:
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.
206 inline 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.
228 inline 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.
236 inline 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.
251 inline 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.
264 inline 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.
272 inline 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