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 move distinct metadata instead of duplicating it
93  /// when there are module-level changes.
94  RF_MoveDistinctMDs = 4,
95
96  /// Any global values not in value map are mapped to null instead of mapping
97  /// to self.  Illegal if RF_IgnoreMissingLocals is also set.
98  RF_NullMapMissingGlobalValues = 8,
99};
100
101inline RemapFlags operator|(RemapFlags LHS, RemapFlags RHS) {
102  return RemapFlags(unsigned(LHS) | unsigned(RHS));
103}
104
105/// Context for (re-)mapping values (and metadata).
106///
107/// A shared context used for mapping and remapping of Value and Metadata
108/// instances using \a ValueToValueMapTy, \a RemapFlags, \a
109/// ValueMapTypeRemapper, and \a ValueMaterializer.
110///
111/// There are a number of top-level entry points:
112/// - \a mapValue() (and \a mapConstant());
113/// - \a mapMetadata() (and \a mapMDNode());
114/// - \a remapInstruction(); and
115/// - \a remapFunction().
116///
117/// The \a ValueMaterializer can be used as a callback, but cannot invoke any
118/// of these top-level functions recursively.  Instead, callbacks should use
119/// one of the following to schedule work lazily in the \a ValueMapper
120/// instance:
121/// - \a scheduleMapGlobalInitializer()
122/// - \a scheduleMapAppendingVariable()
123/// - \a scheduleMapGlobalIndirectSymbol()
124/// - \a scheduleRemapFunction()
125///
126/// Sometimes a callback needs a different mapping context.  Such a context can
127/// be registered using \a registerAlternateMappingContext(), which takes an
128/// alternate \a ValueToValueMapTy and \a ValueMaterializer and returns a ID to
129/// pass into the schedule*() functions.
130///
131/// TODO: lib/Linker really doesn't need the \a ValueHandle in the \a
132/// ValueToValueMapTy.  We should template \a ValueMapper (and its
133/// implementation classes), and explicitly instantiate on two concrete
134/// instances of \a ValueMap (one as \a ValueToValueMap, and one with raw \a
135/// Value pointers).  It may be viable to do away with \a TrackingMDRef in the
136/// \a Metadata side map for the lib/Linker case as well, in which case we'll
137/// need a new template parameter on \a ValueMap.
138///
139/// TODO: Update callers of \a RemapInstruction() and \a MapValue() (etc.) to
140/// use \a ValueMapper directly.
141class ValueMapper {
142  void *pImpl;
143
144public:
145  ValueMapper(ValueToValueMapTy &VM, RemapFlags Flags = RF_None,
146              ValueMapTypeRemapper *TypeMapper = nullptr,
147              ValueMaterializer *Materializer = nullptr);
148  ValueMapper(ValueMapper &&) = delete;
149  ValueMapper(const ValueMapper &) = delete;
150  ValueMapper &operator=(ValueMapper &&) = delete;
151  ValueMapper &operator=(const ValueMapper &) = delete;
152  ~ValueMapper();
153
154  /// Register an alternate mapping context.
155  ///
156  /// Returns a MappingContextID that can be used with the various schedule*()
157  /// API to switch in a different value map on-the-fly.
158  unsigned
159  registerAlternateMappingContext(ValueToValueMapTy &VM,
160                                  ValueMaterializer *Materializer = nullptr);
161
162  /// Add to the current \a RemapFlags.
163  ///
164  /// \note Like the top-level mapping functions, \a addFlags() must be called
165  /// at the top level, not during a callback in a \a ValueMaterializer.
166  void addFlags(RemapFlags Flags);
167
168  Metadata *mapMetadata(const Metadata &MD);
169  MDNode *mapMDNode(const MDNode &N);
170
171  Value *mapValue(const Value &V);
172  Constant *mapConstant(const Constant &C);
173
174  void remapInstruction(Instruction &I);
175  void remapFunction(Function &F);
176
177  void scheduleMapGlobalInitializer(GlobalVariable &GV, Constant &Init,
178                                    unsigned MappingContextID = 0);
179  void scheduleMapAppendingVariable(GlobalVariable &GV, Constant *InitPrefix,
180                                    bool IsOldCtorDtor,
181                                    ArrayRef<Constant *> NewMembers,
182                                    unsigned MappingContextID = 0);
183  void scheduleMapGlobalIndirectSymbol(GlobalIndirectSymbol &GIS,
184                                       Constant &Target,
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