LLVM 20.0.0git
ValueMapper.h
Go to the documentation of this file.
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"
19#include "llvm/IR/ValueHandle.h"
20#include "llvm/IR/ValueMap.h"
21
22namespace llvm {
23
24class Constant;
25class DIBuilder;
26class DbgRecord;
27class Function;
28class GlobalVariable;
29class Instruction;
30class MDNode;
31class Metadata;
32class Module;
33class Type;
34class Value;
35
36using ValueToValueMapTy = ValueMap<const Value *, WeakTrackingVH>;
38
39/// This is a class that can be implemented by clients to remap types when
40/// cloning constants and instructions.
42 virtual void anchor(); // Out of line method.
43
44public:
45 virtual ~ValueMapTypeRemapper() = default;
46
47 /// The client should implement this method if they want to remap types while
48 /// mapping values.
49 virtual Type *remapType(Type *SrcTy) = 0;
50};
51
52/// This is a class that can be implemented by clients to materialize Values on
53/// demand.
55 virtual void anchor(); // Out of line method.
56
57protected:
58 ValueMaterializer() = default;
61 ~ValueMaterializer() = default;
62
63public:
64 /// This method can be implemented to generate a mapped Value on demand. For
65 /// example, if linking lazily. Returns null if the value is not materialized.
66 virtual Value *materialize(Value *V) = 0;
67};
68
69/// These are flags that the value mapping APIs allow.
72
73 /// If this flag is set, the remapper knows that only local values within a
74 /// function (such as an instruction or argument) are mapped, not global
75 /// values like functions and global metadata.
77
78 /// If this flag is set, the remapper ignores missing function-local entries
79 /// (Argument, Instruction, BasicBlock) that are not in the value map. If it
80 /// is unset, it aborts if an operand is asked to be remapped which doesn't
81 /// exist in the mapping.
82 ///
83 /// There are no such assertions in MapValue(), whose results are almost
84 /// unchanged by this flag. This flag mainly changes the assertion behaviour
85 /// in RemapInstruction().
86 ///
87 /// Since an Instruction's metadata operands (even that point to SSA values)
88 /// aren't guaranteed to be dominated by their definitions, MapMetadata will
89 /// return "!{}" instead of "null" for \a LocalAsMetadata instances whose SSA
90 /// values are unmapped when this flag is set. Otherwise, \a MapValue()
91 /// completely ignores this flag.
92 ///
93 /// \a MapMetadata() always ignores this flag.
95
96 /// Instruct the remapper to reuse and mutate distinct metadata (remapping
97 /// them in place) instead of cloning remapped copies. This flag has no
98 /// effect when RF_NoModuleLevelChanges, since that implies an identity
99 /// mapping.
101
102 /// Any global values not in value map are mapped to null instead of mapping
103 /// to self. Illegal if RF_IgnoreMissingLocals is also set.
105};
106
108 return RemapFlags(unsigned(LHS) | unsigned(RHS));
109}
110
111/// Context for (re-)mapping values (and metadata).
112///
113/// A shared context used for mapping and remapping of Value and Metadata
114/// instances using \a ValueToValueMapTy, \a RemapFlags, \a
115/// ValueMapTypeRemapper, and \a ValueMaterializer.
116///
117/// There are a number of top-level entry points:
118/// - \a mapValue() (and \a mapConstant());
119/// - \a mapMetadata() (and \a mapMDNode());
120/// - \a remapInstruction();
121/// - \a remapFunction(); and
122/// - \a remapGlobalObjectMetadata().
123///
124/// The \a ValueMaterializer can be used as a callback, but cannot invoke any
125/// of these top-level functions recursively. Instead, callbacks should use
126/// one of the following to schedule work lazily in the \a ValueMapper
127/// instance:
128/// - \a scheduleMapGlobalInitializer()
129/// - \a scheduleMapAppendingVariable()
130/// - \a scheduleMapGlobalAlias()
131/// - \a scheduleMapGlobalIFunc()
132/// - \a scheduleRemapFunction()
133///
134/// Sometimes a callback needs a different mapping context. Such a context can
135/// be registered using \a registerAlternateMappingContext(), which takes an
136/// alternate \a ValueToValueMapTy and \a ValueMaterializer and returns a ID to
137/// pass into the schedule*() functions.
138///
139/// TODO: lib/Linker really doesn't need the \a ValueHandle in the \a
140/// ValueToValueMapTy. We should template \a ValueMapper (and its
141/// implementation classes), and explicitly instantiate on two concrete
142/// instances of \a ValueMap (one as \a ValueToValueMap, and one with raw \a
143/// Value pointers). It may be viable to do away with \a TrackingMDRef in the
144/// \a Metadata side map for the lib/Linker case as well, in which case we'll
145/// need a new template parameter on \a ValueMap.
146///
147/// TODO: Update callers of \a RemapInstruction() and \a MapValue() (etc.) to
148/// use \a ValueMapper directly.
150 void *pImpl;
151
152public:
154 ValueMapTypeRemapper *TypeMapper = nullptr,
155 ValueMaterializer *Materializer = nullptr);
157 ValueMapper(const ValueMapper &) = delete;
160 ~ValueMapper();
161
162 /// Register an alternate mapping context.
163 ///
164 /// Returns a MappingContextID that can be used with the various schedule*()
165 /// API to switch in a different value map on-the-fly.
166 unsigned
168 ValueMaterializer *Materializer = nullptr);
169
170 /// Add to the current \a RemapFlags.
171 ///
172 /// \note Like the top-level mapping functions, \a addFlags() must be called
173 /// at the top level, not during a callback in a \a ValueMaterializer.
174 void addFlags(RemapFlags Flags);
175
176 Metadata *mapMetadata(const Metadata &MD);
177 MDNode *mapMDNode(const MDNode &N);
178
179 Value *mapValue(const Value &V);
181
183 void remapDbgRecord(Module *M, DbgRecord &V);
185 void remapFunction(Function &F);
187
189 unsigned MappingContextID = 0);
191 bool IsOldCtorDtor,
192 ArrayRef<Constant *> NewMembers,
193 unsigned MappingContextID = 0);
195 unsigned MappingContextID = 0);
197 unsigned MappingContextID = 0);
198 void scheduleRemapFunction(Function &F, unsigned MappingContextID = 0);
199};
200
201/// Look up or compute a value in the value map.
202///
203/// Return a mapped value for a function-local value (Argument, Instruction,
204/// BasicBlock), or compute and memoize a value for a Constant.
205///
206/// 1. If \c V is in VM, return the result.
207/// 2. Else if \c V can be materialized with \c Materializer, do so, memoize
208/// it in \c VM, and return it.
209/// 3. Else if \c V is a function-local value, return nullptr.
210/// 4. Else if \c V is a \a GlobalValue, return \c nullptr or \c V depending
211/// on \a RF_NullMapMissingGlobalValues.
212/// 5. Else if \c V is a \a MetadataAsValue wrapping a LocalAsMetadata,
213/// recurse on the local SSA value, and return nullptr or "metadata !{}" on
214/// missing depending on RF_IgnoreMissingValues.
215/// 6. Else if \c V is a \a MetadataAsValue, rewrap the return of \a
216/// MapMetadata().
217/// 7. Else, compute the equivalent constant, and return it.
218inline Value *MapValue(const Value *V, ValueToValueMapTy &VM,
219 RemapFlags Flags = RF_None,
220 ValueMapTypeRemapper *TypeMapper = nullptr,
221 ValueMaterializer *Materializer = nullptr) {
222 return ValueMapper(VM, Flags, TypeMapper, Materializer).mapValue(*V);
223}
224
225/// Lookup or compute a mapping for a piece of metadata.
226///
227/// Compute and memoize a mapping for \c MD.
228///
229/// 1. If \c MD is mapped, return it.
230/// 2. Else if \a RF_NoModuleLevelChanges or \c MD is an \a MDString, return
231/// \c MD.
232/// 3. Else if \c MD is a \a ConstantAsMetadata, call \a MapValue() and
233/// re-wrap its return (returning nullptr on nullptr).
234/// 4. Else, \c MD is an \a MDNode. These are remapped, along with their
235/// transitive operands. Distinct nodes are duplicated or moved depending
236/// on \a RF_MoveDistinctNodes. Uniqued nodes are remapped like constants.
237///
238/// \note \a LocalAsMetadata is completely unsupported by \a MapMetadata.
239/// Instead, use \a MapValue() with its wrapping \a MetadataAsValue instance.
241 RemapFlags Flags = RF_None,
242 ValueMapTypeRemapper *TypeMapper = nullptr,
243 ValueMaterializer *Materializer = nullptr) {
244 return ValueMapper(VM, Flags, TypeMapper, Materializer).mapMetadata(*MD);
245}
246
247/// Version of MapMetadata with type safety for MDNode.
249 RemapFlags Flags = RF_None,
250 ValueMapTypeRemapper *TypeMapper = nullptr,
251 ValueMaterializer *Materializer = nullptr) {
252 return ValueMapper(VM, Flags, TypeMapper, Materializer).mapMDNode(*MD);
253}
254
255/// Convert the instruction operands from referencing the current values into
256/// those specified by VM.
257///
258/// If \a RF_IgnoreMissingLocals is set and an operand can't be found via \a
259/// MapValue(), use the old value. Otherwise assert that this doesn't happen.
260///
261/// Note that \a MapValue() only returns \c nullptr for SSA values missing from
262/// \c VM.
264 RemapFlags Flags = RF_None,
265 ValueMapTypeRemapper *TypeMapper = nullptr,
266 ValueMaterializer *Materializer = nullptr) {
267 ValueMapper(VM, Flags, TypeMapper, Materializer).remapInstruction(*I);
268}
269
270/// Remap the Values used in the DbgRecord \a DR using the value map \a
271/// VM.
273 RemapFlags Flags = RF_None,
274 ValueMapTypeRemapper *TypeMapper = nullptr,
275 ValueMaterializer *Materializer = nullptr) {
276 ValueMapper(VM, Flags, TypeMapper, Materializer).remapDbgRecord(M, *DR);
277}
278
279/// Remap the Values used in the DbgRecords \a Range using the value map \a
280/// VM.
284 RemapFlags Flags = RF_None,
285 ValueMapTypeRemapper *TypeMapper = nullptr,
286 ValueMaterializer *Materializer = nullptr) {
287 ValueMapper(VM, Flags, TypeMapper, Materializer)
289}
290
291/// Remap the operands, metadata, arguments, and instructions of a function.
292///
293/// Calls \a MapValue() on prefix data, prologue data, and personality
294/// function; calls \a MapMetadata() on each attached MDNode; remaps the
295/// argument types using the provided \c TypeMapper; and calls \a
296/// RemapInstruction() on every instruction.
298 RemapFlags Flags = RF_None,
299 ValueMapTypeRemapper *TypeMapper = nullptr,
300 ValueMaterializer *Materializer = nullptr) {
301 ValueMapper(VM, Flags, TypeMapper, Materializer).remapFunction(F);
302}
303
304/// Version of MapValue with type safety for Constant.
306 RemapFlags Flags = RF_None,
307 ValueMapTypeRemapper *TypeMapper = nullptr,
308 ValueMaterializer *Materializer = nullptr) {
309 return ValueMapper(VM, Flags, TypeMapper, Materializer).mapConstant(*V);
310}
311
312} // end namespace llvm
313
314#endif // LLVM_TRANSFORMS_UTILS_VALUEMAPPER_H
RelocType Type
Definition: COFFYAML.cpp:391
dxil translate DXIL Translate Metadata
#define F(x, y, z)
Definition: MD5.cpp:55
#define I(x, y, z)
Definition: MD5.cpp:58
Machine Check Debug Module
ConstantRange Range(APInt(BitWidth, Low), APInt(BitWidth, High))
Value * RHS
Value * LHS
ArrayRef - Represent a constant reference to an array (0 or more elements consecutively in memory),...
Definition: ArrayRef.h:41
This is an important base class in LLVM.
Definition: Constant.h:42
Base class for non-instruction debug metadata records that have positions within IR.
Metadata node.
Definition: Metadata.h:1069
Root of the metadata hierarchy.
Definition: Metadata.h:62
A Module instance is used to store all the information related to an LLVM module.
Definition: Module.h:65
Interface for looking up the initializer for a variable name, used by Init::resolveReferences.
Definition: Record.h:2212
The instances of the Type class are immutable: once they are created, they are never changed.
Definition: Type.h:45
This is a class that can be implemented by clients to remap types when cloning constants and instruct...
Definition: ValueMapper.h:41
virtual ~ValueMapTypeRemapper()=default
virtual Type * remapType(Type *SrcTy)=0
The client should implement this method if they want to remap types while mapping values.
Context for (re-)mapping values (and metadata).
Definition: ValueMapper.h:149
void remapDbgRecord(Module *M, DbgRecord &V)
void remapDbgRecordRange(Module *M, iterator_range< DbgRecordIterator > Range)
MDNode * mapMDNode(const MDNode &N)
Metadata * mapMetadata(const Metadata &MD)
ValueMapper & operator=(const ValueMapper &)=delete
void remapInstruction(Instruction &I)
ValueMapper(ValueMapper &&)=delete
void scheduleMapGlobalInitializer(GlobalVariable &GV, Constant &Init, unsigned MappingContextID=0)
void scheduleRemapFunction(Function &F, unsigned MappingContextID=0)
void scheduleMapGlobalIFunc(GlobalIFunc &GI, Constant &Resolver, unsigned MappingContextID=0)
unsigned registerAlternateMappingContext(ValueToValueMapTy &VM, ValueMaterializer *Materializer=nullptr)
Register an alternate mapping context.
ValueMapper(const ValueMapper &)=delete
void remapFunction(Function &F)
Constant * mapConstant(const Constant &C)
ValueMapper & operator=(ValueMapper &&)=delete
void scheduleMapAppendingVariable(GlobalVariable &GV, Constant *InitPrefix, bool IsOldCtorDtor, ArrayRef< Constant * > NewMembers, unsigned MappingContextID=0)
void scheduleMapGlobalAlias(GlobalAlias &GA, Constant &Aliasee, unsigned MappingContextID=0)
void remapGlobalObjectMetadata(GlobalObject &GO)
Value * mapValue(const Value &V)
void addFlags(RemapFlags Flags)
Add to the current RemapFlags.
This is a class that can be implemented by clients to materialize Values on demand.
Definition: ValueMapper.h:54
ValueMaterializer & operator=(const ValueMaterializer &)=default
virtual Value * materialize(Value *V)=0
This method can be implemented to generate a mapped Value on demand.
ValueMaterializer(const ValueMaterializer &)=default
LLVM Value Representation.
Definition: Value.h:74
A range adaptor for a pair of iterators.
typename ilist_select_iterator_type< OptionsT::has_iterator_bits, OptionsT, false, false >::type iterator
Definition: simple_ilist.h:97
@ C
The default llvm calling convention, compatible with C.
Definition: CallingConv.h:34
This is an optimization pass for GlobalISel generic memory operations.
Definition: AddressRanges.h:18
simple_ilist< DbgRecord >::iterator DbgRecordIterator
Definition: ValueMapper.h:37
void RemapDbgRecord(Module *M, DbgRecord *DR, ValueToValueMapTy &VM, RemapFlags Flags=RF_None, ValueMapTypeRemapper *TypeMapper=nullptr, ValueMaterializer *Materializer=nullptr)
Remap the Values used in the DbgRecord DR using the value map VM.
Definition: ValueMapper.h:272
Metadata * MapMetadata(const Metadata *MD, ValueToValueMapTy &VM, RemapFlags Flags=RF_None, ValueMapTypeRemapper *TypeMapper=nullptr, ValueMaterializer *Materializer=nullptr)
Lookup or compute a mapping for a piece of metadata.
Definition: ValueMapper.h:240
RemapFlags
These are flags that the value mapping APIs allow.
Definition: ValueMapper.h:70
@ RF_IgnoreMissingLocals
If this flag is set, the remapper ignores missing function-local entries (Argument,...
Definition: ValueMapper.h:94
@ RF_NullMapMissingGlobalValues
Any global values not in value map are mapped to null instead of mapping to self.
Definition: ValueMapper.h:104
@ RF_None
Definition: ValueMapper.h:71
@ RF_NoModuleLevelChanges
If this flag is set, the remapper knows that only local values within a function (such as an instruct...
Definition: ValueMapper.h:76
@ RF_ReuseAndMutateDistinctMDs
Instruct the remapper to reuse and mutate distinct metadata (remapping them in place) instead of clon...
Definition: ValueMapper.h:100
void RemapInstruction(Instruction *I, ValueToValueMapTy &VM, RemapFlags Flags=RF_None, ValueMapTypeRemapper *TypeMapper=nullptr, ValueMaterializer *Materializer=nullptr)
Convert the instruction operands from referencing the current values into those specified by VM.
Definition: ValueMapper.h:263
Value * MapValue(const Value *V, ValueToValueMapTy &VM, RemapFlags Flags=RF_None, ValueMapTypeRemapper *TypeMapper=nullptr, ValueMaterializer *Materializer=nullptr)
Look up or compute a value in the value map.
Definition: ValueMapper.h:218
ValueMap< const Value *, WeakTrackingVH > ValueToValueMapTy
void RemapFunction(Function &F, ValueToValueMapTy &VM, RemapFlags Flags=RF_None, ValueMapTypeRemapper *TypeMapper=nullptr, ValueMaterializer *Materializer=nullptr)
Remap the operands, metadata, arguments, and instructions of a function.
Definition: ValueMapper.h:297
APInt operator|(APInt a, const APInt &b)
Definition: APInt.h:2090
void RemapDbgRecordRange(Module *M, iterator_range< DbgRecordIterator > Range, ValueToValueMapTy &VM, RemapFlags Flags=RF_None, ValueMapTypeRemapper *TypeMapper=nullptr, ValueMaterializer *Materializer=nullptr)
Remap the Values used in the DbgRecords Range using the value map VM.
Definition: ValueMapper.h:281
#define N