1//===- llvm/Value.h - Definition of the Value class -------------*- 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 declares the Value class.
10//
11//===----------------------------------------------------------------------===//
12
13#ifndef LLVM_IR_VALUE_H
14#define LLVM_IR_VALUE_H
15
16#include "llvm-c/Types.h"
17#include "llvm/ADT/STLExtras.h"
18#include "llvm/ADT/StringRef.h"
19#include "llvm/ADT/iterator_range.h"
20#include "llvm/IR/Use.h"
21#include "llvm/Support/Alignment.h"
22#include "llvm/Support/CBindingWrapping.h"
23#include "llvm/Support/Casting.h"
24#include <cassert>
25#include <iterator>
26#include <memory>
27
28namespace llvm {
29
30class APInt;
31class Argument;
32class BasicBlock;
33class Constant;
34class ConstantData;
35class ConstantAggregate;
36class DataLayout;
37class Function;
38class GlobalAlias;
39class GlobalIFunc;
40class GlobalObject;
41class GlobalValue;
42class GlobalVariable;
43class InlineAsm;
44class Instruction;
45class LLVMContext;
46class MDNode;
47class Module;
48class ModuleSlotTracker;
49class raw_ostream;
50template<typename ValueTy> class StringMapEntry;
51class Twine;
52class Type;
53class User;
54
55using ValueName = StringMapEntry<Value *>;
56
57//===----------------------------------------------------------------------===//
58// Value Class
59//===----------------------------------------------------------------------===//
60
61/// LLVM Value Representation
62///
63/// This is a very important LLVM class. It is the base class of all values
64/// computed by a program that may be used as operands to other values. Value is
65/// the super class of other important classes such as Instruction and Function.
66/// All Values have a Type. Type is not a subclass of Value. Some values can
67/// have a name and they belong to some Module. Setting the name on the Value
68/// automatically updates the module's symbol table.
69///
70/// Every value has a "use list" that keeps track of which other Values are
71/// using this Value. A Value can also have an arbitrary number of ValueHandle
72/// objects that watch it and listen to RAUW and Destroy events. See
73/// llvm/IR/ValueHandle.h for details.
74class Value {
75 const unsigned char SubclassID; // Subclass identifier (for isa/dyn_cast)
76 unsigned char HasValueHandle : 1; // Has a ValueHandle pointing to this?
77
78protected:
79 /// Hold subclass data that can be dropped.
80 ///
81 /// This member is similar to SubclassData, however it is for holding
82 /// information which may be used to aid optimization, but which may be
83 /// cleared to zero without affecting conservative interpretation.
84 unsigned char SubclassOptionalData : 7;
85
86private:
87 /// Hold arbitrary subclass data.
88 ///
89 /// This member is defined by this class, but is not used for anything.
90 /// Subclasses can use it to hold whatever state they find useful. This
91 /// field is initialized to zero by the ctor.
92 unsigned short SubclassData;
93
94protected:
95 /// The number of operands in the subclass.
96 ///
97 /// This member is defined by this class, but not used for anything.
98 /// Subclasses can use it to store their number of operands, if they have
99 /// any.
100 ///
101 /// This is stored here to save space in User on 64-bit hosts. Since most
102 /// instances of Value have operands, 32-bit hosts aren't significantly
103 /// affected.
104 ///
105 /// Note, this should *NOT* be used directly by any class other than User.
106 /// User uses this value to find the Use list.
107 enum : unsigned { NumUserOperandsBits = 27 };
108 unsigned NumUserOperands : NumUserOperandsBits;
109
110 // Use the same type as the bitfield above so that MSVC will pack them.
111 unsigned IsUsedByMD : 1;
112 unsigned HasName : 1;
113 unsigned HasMetadata : 1; // Has metadata attached to this?
114 unsigned HasHungOffUses : 1;
115 unsigned HasDescriptor : 1;
116
117private:
118 Type *VTy;
119 Use *UseList;
120
121 friend class ValueAsMetadata; // Allow access to IsUsedByMD.
122 friend class ValueHandleBase; // Allow access to HasValueHandle.
123
124 template <typename UseT> // UseT == 'Use' or 'const Use'
125 class use_iterator_impl {
126 friend class Value;
127
128 UseT *U;
129
130 explicit use_iterator_impl(UseT *u) : U(u) {}
131
132 public:
133 using iterator_category = std::forward_iterator_tag;
134 using value_type = UseT *;
135 using difference_type = std::ptrdiff_t;
136 using pointer = value_type *;
137 using reference = value_type &;
138
139 use_iterator_impl() : U() {}
140
141 bool operator==(const use_iterator_impl &x) const { return U == x.U; }
142 bool operator!=(const use_iterator_impl &x) const { return !operator==(x); }
143
144 use_iterator_impl &operator++() { // Preincrement
145 assert(U && "Cannot increment end iterator!");
146 U = U->getNext();
147 return *this;
148 }
149
150 use_iterator_impl operator++(int) { // Postincrement
151 auto tmp = *this;
152 ++*this;
153 return tmp;
154 }
155
156 UseT &operator*() const {
157 assert(U && "Cannot dereference end iterator!");
158 return *U;
159 }
160
161 UseT *operator->() const { return &operator*(); }
162
163 operator use_iterator_impl<const UseT>() const {
164 return use_iterator_impl<const UseT>(U);
165 }
166 };
167
168 template <typename UserTy> // UserTy == 'User' or 'const User'
169 class user_iterator_impl {
170 use_iterator_impl<Use> UI;
171 explicit user_iterator_impl(Use *U) : UI(U) {}
172 friend class Value;
173
174 public:
175 using iterator_category = std::forward_iterator_tag;
176 using value_type = UserTy *;
177 using difference_type = std::ptrdiff_t;
178 using pointer = value_type *;
179 using reference = value_type &;
180
181 user_iterator_impl() = default;
182
183 bool operator==(const user_iterator_impl &x) const { return UI == x.UI; }
184 bool operator!=(const user_iterator_impl &x) const { return !operator==(x); }
185
186 /// Returns true if this iterator is equal to user_end() on the value.
187 bool atEnd() const { return *this == user_iterator_impl(); }
188
189 user_iterator_impl &operator++() { // Preincrement
190 ++UI;
191 return *this;
192 }
193
194 user_iterator_impl operator++(int) { // Postincrement
195 auto tmp = *this;
196 ++*this;
197 return tmp;
198 }
199
200 // Retrieve a pointer to the current User.
201 UserTy *operator*() const {
202 return UI->getUser();
203 }
204
205 UserTy *operator->() const { return operator*(); }
206
207 operator user_iterator_impl<const UserTy>() const {
208 return user_iterator_impl<const UserTy>(*UI);
209 }
210
211 Use &getUse() const { return *UI; }
212 };
213
214protected:
215 Value(Type *Ty, unsigned scid);
216
217 /// Value's destructor should be virtual by design, but that would require
218 /// that Value and all of its subclasses have a vtable that effectively
219 /// duplicates the information in the value ID. As a size optimization, the
220 /// destructor has been protected, and the caller should manually call
221 /// deleteValue.
222 ~Value(); // Use deleteValue() to delete a generic Value.
223
224public:
225 Value(const Value &) = delete;
226 Value &operator=(const Value &) = delete;
227
228 /// Delete a pointer to a generic Value.
229 void deleteValue();
230
231 /// Support for debugging, callable in GDB: V->dump()
232 void dump() const;
233
234 /// Implement operator<< on Value.
235 /// @{
236 void print(raw_ostream &O, bool IsForDebug = false) const;
237 void print(raw_ostream &O, ModuleSlotTracker &MST,
238 bool IsForDebug = false) const;
239 /// @}
240
241 /// Print the name of this Value out to the specified raw_ostream.
242 ///
243 /// This is useful when you just want to print 'int %reg126', not the
244 /// instruction that generated it. If you specify a Module for context, then
245 /// even constants get pretty-printed; for example, the type of a null
246 /// pointer is printed symbolically.
247 /// @{
248 void printAsOperand(raw_ostream &O, bool PrintType = true,
249 const Module *M = nullptr) const;
250 void printAsOperand(raw_ostream &O, bool PrintType,
251 ModuleSlotTracker &MST) const;
252 /// @}
253
254 /// All values are typed, get the type of this value.
255 Type *getType() const { return VTy; }
256
257 /// All values hold a context through their type.
258 LLVMContext &getContext() const;
259
260 // All values can potentially be named.
261 bool hasName() const { return HasName; }
262 ValueName *getValueName() const;
263 void setValueName(ValueName *VN);
264
265private:
266 void destroyValueName();
267 enum class ReplaceMetadataUses { No, Yes };
268 void doRAUW(Value *New, ReplaceMetadataUses);
269 void setNameImpl(const Twine &Name);
270
271public:
272 /// Return a constant reference to the value's name.
273 ///
274 /// This guaranteed to return the same reference as long as the value is not
275 /// modified. If the value has a name, this does a hashtable lookup, so it's
276 /// not free.
277 StringRef getName() const;
278
279 /// Change the name of the value.
280 ///
281 /// Choose a new unique name if the provided name is taken.
282 ///
283 /// \param Name The new name; or "" if the value's name should be removed.
284 void setName(const Twine &Name);
285
286 /// Transfer the name from V to this value.
287 ///
288 /// After taking V's name, sets V's name to empty.
289 ///
290 /// \note It is an error to call V->takeName(V).
291 void takeName(Value *V);
292
293#ifndef NDEBUG
294 std::string getNameOrAsOperand() const;
295#endif
296
297 /// Change all uses of this to point to a new Value.
298 ///
299 /// Go through the uses list for this definition and make each use point to
300 /// "V" instead of "this". After this completes, 'this's use list is
301 /// guaranteed to be empty.
302 void replaceAllUsesWith(Value *V);
303
304 /// Change non-metadata uses of this to point to a new Value.
305 ///
306 /// Go through the uses list for this definition and make each use point to
307 /// "V" instead of "this". This function skips metadata entries in the list.
308 void replaceNonMetadataUsesWith(Value *V);
309
310 /// Go through the uses list for this definition and make each use point
311 /// to "V" if the callback ShouldReplace returns true for the given Use.
312 /// Unlike replaceAllUsesWith() this function does not support basic block
313 /// values.
314 void replaceUsesWithIf(Value *New,
315 llvm::function_ref<bool(Use &U)> ShouldReplace);
316
317 /// replaceUsesOutsideBlock - Go through the uses list for this definition and
318 /// make each use point to "V" instead of "this" when the use is outside the
319 /// block. 'This's use list is expected to have at least one element.
320 /// Unlike replaceAllUsesWith() this function does not support basic block
321 /// values.
322 void replaceUsesOutsideBlock(Value *V, BasicBlock *BB);
323
324 //----------------------------------------------------------------------
325 // Methods for handling the chain of uses of this Value.
326 //
327 // Materializing a function can introduce new uses, so these methods come in
328 // two variants:
329 // The methods that start with materialized_ check the uses that are
330 // currently known given which functions are materialized. Be very careful
331 // when using them since you might not get all uses.
332 // The methods that don't start with materialized_ assert that modules is
333 // fully materialized.
334 void assertModuleIsMaterializedImpl() const;
335 // This indirection exists so we can keep assertModuleIsMaterializedImpl()
336 // around in release builds of Value.cpp to be linked with other code built
337 // in debug mode. But this avoids calling it in any of the release built code.
338 void assertModuleIsMaterialized() const {
339#ifndef NDEBUG
340 assertModuleIsMaterializedImpl();
341#endif
342 }
343
344 bool use_empty() const {
345 assertModuleIsMaterialized();
346 return UseList == nullptr;
347 }
348
349 bool materialized_use_empty() const {
350 return UseList == nullptr;
351 }
352
353 using use_iterator = use_iterator_impl<Use>;
354 using const_use_iterator = use_iterator_impl<const Use>;
355
356 use_iterator materialized_use_begin() { return use_iterator(UseList); }
357 const_use_iterator materialized_use_begin() const {
358 return const_use_iterator(UseList);
359 }
360 use_iterator use_begin() {
361 assertModuleIsMaterialized();
362 return materialized_use_begin();
363 }
364 const_use_iterator use_begin() const {
365 assertModuleIsMaterialized();
366 return materialized_use_begin();
367 }
368 use_iterator use_end() { return use_iterator(); }
369 const_use_iterator use_end() const { return const_use_iterator(); }
370 iterator_range<use_iterator> materialized_uses() {
371 return make_range(x: materialized_use_begin(), y: use_end());
372 }
373 iterator_range<const_use_iterator> materialized_uses() const {
374 return make_range(x: materialized_use_begin(), y: use_end());
375 }
376 iterator_range<use_iterator> uses() {
377 assertModuleIsMaterialized();
378 return materialized_uses();
379 }
380 iterator_range<const_use_iterator> uses() const {
381 assertModuleIsMaterialized();
382 return materialized_uses();
383 }
384
385 bool user_empty() const {
386 assertModuleIsMaterialized();
387 return UseList == nullptr;
388 }
389
390 using user_iterator = user_iterator_impl<User>;
391 using const_user_iterator = user_iterator_impl<const User>;
392
393 user_iterator materialized_user_begin() { return user_iterator(UseList); }
394 const_user_iterator materialized_user_begin() const {
395 return const_user_iterator(UseList);
396 }
397 user_iterator user_begin() {
398 assertModuleIsMaterialized();
399 return materialized_user_begin();
400 }
401 const_user_iterator user_begin() const {
402 assertModuleIsMaterialized();
403 return materialized_user_begin();
404 }
405 user_iterator user_end() { return user_iterator(); }
406 const_user_iterator user_end() const { return const_user_iterator(); }
407 User *user_back() {
408 assertModuleIsMaterialized();
409 return *materialized_user_begin();
410 }
411 const User *user_back() const {
412 assertModuleIsMaterialized();
413 return *materialized_user_begin();
414 }
415 iterator_range<user_iterator> materialized_users() {
416 return make_range(x: materialized_user_begin(), y: user_end());
417 }
418 iterator_range<const_user_iterator> materialized_users() const {
419 return make_range(x: materialized_user_begin(), y: user_end());
420 }
421 iterator_range<user_iterator> users() {
422 assertModuleIsMaterialized();
423 return materialized_users();
424 }
425 iterator_range<const_user_iterator> users() const {
426 assertModuleIsMaterialized();
427 return materialized_users();
428 }
429
430 /// Return true if there is exactly one use of this value.
431 ///
432 /// This is specialized because it is a common request and does not require
433 /// traversing the whole use list.
434 bool hasOneUse() const { return hasSingleElement(C: uses()); }
435
436 /// Return true if this Value has exactly N uses.
437 bool hasNUses(unsigned N) const;
438
439 /// Return true if this value has N uses or more.
440 ///
441 /// This is logically equivalent to getNumUses() >= N.
442 bool hasNUsesOrMore(unsigned N) const;
443
444 /// Return true if there is exactly one user of this value.
445 ///
446 /// Note that this is not the same as "has one use". If a value has one use,
447 /// then there certainly is a single user. But if value has several uses,
448 /// it is possible that all uses are in a single user, or not.
449 ///
450 /// This check is potentially costly, since it requires traversing,
451 /// in the worst case, the whole use list of a value.
452 bool hasOneUser() const;
453
454 /// Return true if there is exactly one use of this value that cannot be
455 /// dropped.
456 Use *getSingleUndroppableUse();
457 const Use *getSingleUndroppableUse() const {
458 return const_cast<Value *>(this)->getSingleUndroppableUse();
459 }
460
461 /// Return true if there is exactly one unique user of this value that cannot be
462 /// dropped (that user can have multiple uses of this value).
463 User *getUniqueUndroppableUser();
464 const User *getUniqueUndroppableUser() const {
465 return const_cast<Value *>(this)->getUniqueUndroppableUser();
466 }
467
468 /// Return true if there this value.
469 ///
470 /// This is specialized because it is a common request and does not require
471 /// traversing the whole use list.
472 bool hasNUndroppableUses(unsigned N) const;
473
474 /// Return true if this value has N uses or more.
475 ///
476 /// This is logically equivalent to getNumUses() >= N.
477 bool hasNUndroppableUsesOrMore(unsigned N) const;
478
479 /// Remove every uses that can safely be removed.
480 ///
481 /// This will remove for example uses in llvm.assume.
482 /// This should be used when performing want to perform a tranformation but
483 /// some Droppable uses pervent it.
484 /// This function optionally takes a filter to only remove some droppable
485 /// uses.
486 void dropDroppableUses(llvm::function_ref<bool(const Use *)> ShouldDrop =
487 [](const Use *) { return true; });
488
489 /// Remove every use of this value in \p User that can safely be removed.
490 void dropDroppableUsesIn(User &Usr);
491
492 /// Remove the droppable use \p U.
493 static void dropDroppableUse(Use &U);
494
495 /// Check if this value is used in the specified basic block.
496 bool isUsedInBasicBlock(const BasicBlock *BB) const;
497
498 /// This method computes the number of uses of this Value.
499 ///
500 /// This is a linear time operation. Use hasOneUse, hasNUses, or
501 /// hasNUsesOrMore to check for specific values.
502 unsigned getNumUses() const;
503
504 /// This method should only be used by the Use class.
505 void addUse(Use &U) { U.addToList(List: &UseList); }
506
507 /// Concrete subclass of this.
508 ///
509 /// An enumeration for keeping track of the concrete subclass of Value that
510 /// is actually instantiated. Values of this enumeration are kept in the
511 /// Value classes SubclassID field. They are used for concrete type
512 /// identification.
513 enum ValueTy {
514#define HANDLE_VALUE(Name) Name##Val,
515#include "llvm/IR/Value.def"
516
517 // Markers:
518#define HANDLE_CONSTANT_MARKER(Marker, Constant) Marker = Constant##Val,
519#include "llvm/IR/Value.def"
520 };
521
522 /// Return an ID for the concrete type of this object.
523 ///
524 /// This is used to implement the classof checks. This should not be used
525 /// for any other purpose, as the values may change as LLVM evolves. Also,
526 /// note that for instructions, the Instruction's opcode is added to
527 /// InstructionVal. So this means three things:
528 /// # there is no value with code InstructionVal (no opcode==0).
529 /// # there are more possible values for the value type than in ValueTy enum.
530 /// # the InstructionVal enumerator must be the highest valued enumerator in
531 /// the ValueTy enum.
532 unsigned getValueID() const {
533 return SubclassID;
534 }
535
536 /// Return the raw optional flags value contained in this value.
537 ///
538 /// This should only be used when testing two Values for equivalence.
539 unsigned getRawSubclassOptionalData() const {
540 return SubclassOptionalData;
541 }
542
543 /// Clear the optional flags contained in this value.
544 void clearSubclassOptionalData() {
545 SubclassOptionalData = 0;
546 }
547
548 /// Check the optional flags for equality.
549 bool hasSameSubclassOptionalData(const Value *V) const {
550 return SubclassOptionalData == V->SubclassOptionalData;
551 }
552
553 /// Return true if there is a value handle associated with this value.
554 bool hasValueHandle() const { return HasValueHandle; }
555
556 /// Return true if there is metadata referencing this value.
557 bool isUsedByMetadata() const { return IsUsedByMD; }
558
559protected:
560 /// Get the current metadata attachments for the given kind, if any.
561 ///
562 /// These functions require that the value have at most a single attachment
563 /// of the given kind, and return \c nullptr if such an attachment is missing.
564 /// @{
565 MDNode *getMetadata(unsigned KindID) const {
566 if (!HasMetadata)
567 return nullptr;
568 return getMetadataImpl(KindID);
569 }
570 MDNode *getMetadata(StringRef Kind) const;
571 /// @}
572
573 /// Appends all attachments with the given ID to \c MDs in insertion order.
574 /// If the Value has no attachments with the given ID, or if ID is invalid,
575 /// leaves MDs unchanged.
576 /// @{
577 void getMetadata(unsigned KindID, SmallVectorImpl<MDNode *> &MDs) const;
578 void getMetadata(StringRef Kind, SmallVectorImpl<MDNode *> &MDs) const;
579 /// @}
580
581 /// Appends all metadata attached to this value to \c MDs, sorting by
582 /// KindID. The first element of each pair returned is the KindID, the second
583 /// element is the metadata value. Attachments with the same ID appear in
584 /// insertion order.
585 void
586 getAllMetadata(SmallVectorImpl<std::pair<unsigned, MDNode *>> &MDs) const;
587
588 /// Return true if this value has any metadata attached to it.
589 bool hasMetadata() const { return (bool)HasMetadata; }
590
591 /// Return true if this value has the given type of metadata attached.
592 /// @{
593 bool hasMetadata(unsigned KindID) const {
594 return getMetadata(KindID) != nullptr;
595 }
596 bool hasMetadata(StringRef Kind) const {
597 return getMetadata(Kind) != nullptr;
598 }
599 /// @}
600
601 /// Set a particular kind of metadata attachment.
602 ///
603 /// Sets the given attachment to \c MD, erasing it if \c MD is \c nullptr or
604 /// replacing it if it already exists.
605 /// @{
606 void setMetadata(unsigned KindID, MDNode *Node);
607 void setMetadata(StringRef Kind, MDNode *Node);
608 /// @}
609
610 /// Add a metadata attachment.
611 /// @{
612 void addMetadata(unsigned KindID, MDNode &MD);
613 void addMetadata(StringRef Kind, MDNode &MD);
614 /// @}
615
616 /// Erase all metadata attachments with the given kind.
617 ///
618 /// \returns true if any metadata was removed.
619 bool eraseMetadata(unsigned KindID);
620
621 /// Erase all metadata attachments matching the given predicate.
622 void eraseMetadataIf(function_ref<bool(unsigned, MDNode *)> Pred);
623
624 /// Erase all metadata attached to this Value.
625 void clearMetadata();
626
627 /// Get metadata for the given kind, if any.
628 /// This is an internal function that must only be called after
629 /// checking that `hasMetadata()` returns true.
630 MDNode *getMetadataImpl(unsigned KindID) const;
631
632public:
633 /// Return true if this value is a swifterror value.
634 ///
635 /// swifterror values can be either a function argument or an alloca with a
636 /// swifterror attribute.
637 bool isSwiftError() const;
638
639 /// Strip off pointer casts, all-zero GEPs and address space casts.
640 ///
641 /// Returns the original uncasted value. If this is called on a non-pointer
642 /// value, it returns 'this'.
643 const Value *stripPointerCasts() const;
644 Value *stripPointerCasts() {
645 return const_cast<Value *>(
646 static_cast<const Value *>(this)->stripPointerCasts());
647 }
648
649 /// Strip off pointer casts, all-zero GEPs, address space casts, and aliases.
650 ///
651 /// Returns the original uncasted value. If this is called on a non-pointer
652 /// value, it returns 'this'.
653 const Value *stripPointerCastsAndAliases() const;
654 Value *stripPointerCastsAndAliases() {
655 return const_cast<Value *>(
656 static_cast<const Value *>(this)->stripPointerCastsAndAliases());
657 }
658
659 /// Strip off pointer casts, all-zero GEPs and address space casts
660 /// but ensures the representation of the result stays the same.
661 ///
662 /// Returns the original uncasted value with the same representation. If this
663 /// is called on a non-pointer value, it returns 'this'.
664 const Value *stripPointerCastsSameRepresentation() const;
665 Value *stripPointerCastsSameRepresentation() {
666 return const_cast<Value *>(static_cast<const Value *>(this)
667 ->stripPointerCastsSameRepresentation());
668 }
669
670 /// Strip off pointer casts, all-zero GEPs, single-argument phi nodes and
671 /// invariant group info.
672 ///
673 /// Returns the original uncasted value. If this is called on a non-pointer
674 /// value, it returns 'this'. This function should be used only in
675 /// Alias analysis.
676 const Value *stripPointerCastsForAliasAnalysis() const;
677 Value *stripPointerCastsForAliasAnalysis() {
678 return const_cast<Value *>(static_cast<const Value *>(this)
679 ->stripPointerCastsForAliasAnalysis());
680 }
681
682 /// Strip off pointer casts and all-constant inbounds GEPs.
683 ///
684 /// Returns the original pointer value. If this is called on a non-pointer
685 /// value, it returns 'this'.
686 const Value *stripInBoundsConstantOffsets() const;
687 Value *stripInBoundsConstantOffsets() {
688 return const_cast<Value *>(
689 static_cast<const Value *>(this)->stripInBoundsConstantOffsets());
690 }
691
692 /// Accumulate the constant offset this value has compared to a base pointer.
693 /// Only 'getelementptr' instructions (GEPs) are accumulated but other
694 /// instructions, e.g., casts, are stripped away as well.
695 /// The accumulated constant offset is added to \p Offset and the base
696 /// pointer is returned.
697 ///
698 /// The APInt \p Offset has to have a bit-width equal to the IntPtr type for
699 /// the address space of 'this' pointer value, e.g., use
700 /// DataLayout::getIndexTypeSizeInBits(Ty).
701 ///
702 /// If \p AllowNonInbounds is true, offsets in GEPs are stripped and
703 /// accumulated even if the GEP is not "inbounds".
704 ///
705 /// If \p AllowInvariantGroup is true then this method also looks through
706 /// strip.invariant.group and launder.invariant.group intrinsics.
707 ///
708 /// If \p ExternalAnalysis is provided it will be used to calculate a offset
709 /// when a operand of GEP is not constant.
710 /// For example, for a value \p ExternalAnalysis might try to calculate a
711 /// lower bound. If \p ExternalAnalysis is successful, it should return true.
712 ///
713 /// If this is called on a non-pointer value, it returns 'this' and the
714 /// \p Offset is not modified.
715 ///
716 /// Note that this function will never return a nullptr. It will also never
717 /// manipulate the \p Offset in a way that would not match the difference
718 /// between the underlying value and the returned one. Thus, if no constant
719 /// offset was found, the returned value is the underlying one and \p Offset
720 /// is unchanged.
721 const Value *stripAndAccumulateConstantOffsets(
722 const DataLayout &DL, APInt &Offset, bool AllowNonInbounds,
723 bool AllowInvariantGroup = false,
724 function_ref<bool(Value &Value, APInt &Offset)> ExternalAnalysis =
725 nullptr) const;
726 Value *stripAndAccumulateConstantOffsets(const DataLayout &DL, APInt &Offset,
727 bool AllowNonInbounds,
728 bool AllowInvariantGroup = false) {
729 return const_cast<Value *>(
730 static_cast<const Value *>(this)->stripAndAccumulateConstantOffsets(
731 DL, Offset, AllowNonInbounds, AllowInvariantGroup));
732 }
733
734 /// This is a wrapper around stripAndAccumulateConstantOffsets with the
735 /// in-bounds requirement set to false.
736 const Value *stripAndAccumulateInBoundsConstantOffsets(const DataLayout &DL,
737 APInt &Offset) const {
738 return stripAndAccumulateConstantOffsets(DL, Offset,
739 /* AllowNonInbounds */ AllowNonInbounds: false);
740 }
741 Value *stripAndAccumulateInBoundsConstantOffsets(const DataLayout &DL,
742 APInt &Offset) {
743 return stripAndAccumulateConstantOffsets(DL, Offset,
744 /* AllowNonInbounds */ AllowNonInbounds: false);
745 }
746
747 /// Strip off pointer casts and inbounds GEPs.
748 ///
749 /// Returns the original pointer value. If this is called on a non-pointer
750 /// value, it returns 'this'.
751 const Value *stripInBoundsOffsets(function_ref<void(const Value *)> Func =
752 [](const Value *) {}) const;
753 inline Value *stripInBoundsOffsets(function_ref<void(const Value *)> Func =
754 [](const Value *) {}) {
755 return const_cast<Value *>(
756 static_cast<const Value *>(this)->stripInBoundsOffsets(Func));
757 }
758
759 /// If this ptr is provably equal to \p Other plus a constant offset, return
760 /// that offset in bytes. Essentially `ptr this` subtract `ptr Other`.
761 std::optional<int64_t> getPointerOffsetFrom(const Value *Other,
762 const DataLayout &DL) const;
763
764 /// Return true if the memory object referred to by V can by freed in the
765 /// scope for which the SSA value defining the allocation is statically
766 /// defined. E.g. deallocation after the static scope of a value does not
767 /// count, but a deallocation before that does.
768 bool canBeFreed() const;
769
770 /// Returns the number of bytes known to be dereferenceable for the
771 /// pointer value.
772 ///
773 /// If CanBeNull is set by this function the pointer can either be null or be
774 /// dereferenceable up to the returned number of bytes.
775 ///
776 /// IF CanBeFreed is true, the pointer is known to be dereferenceable at
777 /// point of definition only. Caller must prove that allocation is not
778 /// deallocated between point of definition and use.
779 uint64_t getPointerDereferenceableBytes(const DataLayout &DL,
780 bool &CanBeNull,
781 bool &CanBeFreed) const;
782
783 /// Returns an alignment of the pointer value.
784 ///
785 /// Returns an alignment which is either specified explicitly, e.g. via
786 /// align attribute of a function argument, or guaranteed by DataLayout.
787 Align getPointerAlignment(const DataLayout &DL) const;
788
789 /// Translate PHI node to its predecessor from the given basic block.
790 ///
791 /// If this value is a PHI node with CurBB as its parent, return the value in
792 /// the PHI node corresponding to PredBB. If not, return ourself. This is
793 /// useful if you want to know the value something has in a predecessor
794 /// block.
795 const Value *DoPHITranslation(const BasicBlock *CurBB,
796 const BasicBlock *PredBB) const;
797 Value *DoPHITranslation(const BasicBlock *CurBB, const BasicBlock *PredBB) {
798 return const_cast<Value *>(
799 static_cast<const Value *>(this)->DoPHITranslation(CurBB, PredBB));
800 }
801
802 /// The maximum alignment for instructions.
803 ///
804 /// This is the greatest alignment value supported by load, store, and alloca
805 /// instructions, and global values.
806 static constexpr unsigned MaxAlignmentExponent = 32;
807 static constexpr uint64_t MaximumAlignment = 1ULL << MaxAlignmentExponent;
808
809 /// Mutate the type of this Value to be of the specified type.
810 ///
811 /// Note that this is an extremely dangerous operation which can create
812 /// completely invalid IR very easily. It is strongly recommended that you
813 /// recreate IR objects with the right types instead of mutating them in
814 /// place.
815 void mutateType(Type *Ty) {
816 VTy = Ty;
817 }
818
819 /// Sort the use-list.
820 ///
821 /// Sorts the Value's use-list by Cmp using a stable mergesort. Cmp is
822 /// expected to compare two \a Use references.
823 template <class Compare> void sortUseList(Compare Cmp);
824
825 /// Reverse the use-list.
826 void reverseUseList();
827
828private:
829 /// Merge two lists together.
830 ///
831 /// Merges \c L and \c R using \c Cmp. To enable stable sorts, always pushes
832 /// "equal" items from L before items from R.
833 ///
834 /// \return the first element in the list.
835 ///
836 /// \note Completely ignores \a Use::Prev (doesn't read, doesn't update).
837 template <class Compare>
838 static Use *mergeUseLists(Use *L, Use *R, Compare Cmp) {
839 Use *Merged;
840 Use **Next = &Merged;
841
842 while (true) {
843 if (!L) {
844 *Next = R;
845 break;
846 }
847 if (!R) {
848 *Next = L;
849 break;
850 }
851 if (Cmp(*R, *L)) {
852 *Next = R;
853 Next = &R->Next;
854 R = R->Next;
855 } else {
856 *Next = L;
857 Next = &L->Next;
858 L = L->Next;
859 }
860 }
861
862 return Merged;
863 }
864
865protected:
866 unsigned short getSubclassDataFromValue() const { return SubclassData; }
867 void setValueSubclassData(unsigned short D) { SubclassData = D; }
868};
869
870struct ValueDeleter { void operator()(Value *V) { V->deleteValue(); } };
871
872/// Use this instead of std::unique_ptr<Value> or std::unique_ptr<Instruction>.
873/// Those don't work because Value and Instruction's destructors are protected,
874/// aren't virtual, and won't destroy the complete object.
875using unique_value = std::unique_ptr<Value, ValueDeleter>;
876
877inline raw_ostream &operator<<(raw_ostream &OS, const Value &V) {
878 V.print(O&: OS);
879 return OS;
880}
881
882void Use::set(Value *V) {
883 if (Val) removeFromList();
884 Val = V;
885 if (V) V->addUse(U&: *this);
886}
887
888Value *Use::operator=(Value *RHS) {
889 set(RHS);
890 return RHS;
891}
892
893const Use &Use::operator=(const Use &RHS) {
894 set(RHS.Val);
895 return *this;
896}
897
898template <class Compare> void Value::sortUseList(Compare Cmp) {
899 if (!UseList || !UseList->Next)
900 // No need to sort 0 or 1 uses.
901 return;
902
903 // Note: this function completely ignores Prev pointers until the end when
904 // they're fixed en masse.
905
906 // Create a binomial vector of sorted lists, visiting uses one at a time and
907 // merging lists as necessary.
908 const unsigned MaxSlots = 32;
909 Use *Slots[MaxSlots];
910
911 // Collect the first use, turning it into a single-item list.
912 Use *Next = UseList->Next;
913 UseList->Next = nullptr;
914 unsigned NumSlots = 1;
915 Slots[0] = UseList;
916
917 // Collect all but the last use.
918 while (Next->Next) {
919 Use *Current = Next;
920 Next = Current->Next;
921
922 // Turn Current into a single-item list.
923 Current->Next = nullptr;
924
925 // Save Current in the first available slot, merging on collisions.
926 unsigned I;
927 for (I = 0; I < NumSlots; ++I) {
928 if (!Slots[I])
929 break;
930
931 // Merge two lists, doubling the size of Current and emptying slot I.
932 //
933 // Since the uses in Slots[I] originally preceded those in Current, send
934 // Slots[I] in as the left parameter to maintain a stable sort.
935 Current = mergeUseLists(Slots[I], Current, Cmp);
936 Slots[I] = nullptr;
937 }
938 // Check if this is a new slot.
939 if (I == NumSlots) {
940 ++NumSlots;
941 assert(NumSlots <= MaxSlots && "Use list bigger than 2^32");
942 }
943
944 // Found an open slot.
945 Slots[I] = Current;
946 }
947
948 // Merge all the lists together.
949 assert(Next && "Expected one more Use");
950 assert(!Next->Next && "Expected only one Use");
951 UseList = Next;
952 for (unsigned I = 0; I < NumSlots; ++I)
953 if (Slots[I])
954 // Since the uses in Slots[I] originally preceded those in UseList, send
955 // Slots[I] in as the left parameter to maintain a stable sort.
956 UseList = mergeUseLists(Slots[I], UseList, Cmp);
957
958 // Fix the Prev pointers.
959 for (Use *I = UseList, **Prev = &UseList; I; I = I->Next) {
960 I->Prev = Prev;
961 Prev = &I->Next;
962 }
963}
964
965// isa - Provide some specializations of isa so that we don't have to include
966// the subtype header files to test to see if the value is a subclass...
967//
968template <> struct isa_impl<Constant, Value> {
969 static inline bool doit(const Value &Val) {
970 static_assert(Value::ConstantFirstVal == 0, "Val.getValueID() >= Value::ConstantFirstVal");
971 return Val.getValueID() <= Value::ConstantLastVal;
972 }
973};
974
975template <> struct isa_impl<ConstantData, Value> {
976 static inline bool doit(const Value &Val) {
977 return Val.getValueID() >= Value::ConstantDataFirstVal &&
978 Val.getValueID() <= Value::ConstantDataLastVal;
979 }
980};
981
982template <> struct isa_impl<ConstantAggregate, Value> {
983 static inline bool doit(const Value &Val) {
984 return Val.getValueID() >= Value::ConstantAggregateFirstVal &&
985 Val.getValueID() <= Value::ConstantAggregateLastVal;
986 }
987};
988
989template <> struct isa_impl<Argument, Value> {
990 static inline bool doit (const Value &Val) {
991 return Val.getValueID() == Value::ArgumentVal;
992 }
993};
994
995template <> struct isa_impl<InlineAsm, Value> {
996 static inline bool doit(const Value &Val) {
997 return Val.getValueID() == Value::InlineAsmVal;
998 }
999};
1000
1001template <> struct isa_impl<Instruction, Value> {
1002 static inline bool doit(const Value &Val) {
1003 return Val.getValueID() >= Value::InstructionVal;
1004 }
1005};
1006
1007template <> struct isa_impl<BasicBlock, Value> {
1008 static inline bool doit(const Value &Val) {
1009 return Val.getValueID() == Value::BasicBlockVal;
1010 }
1011};
1012
1013template <> struct isa_impl<Function, Value> {
1014 static inline bool doit(const Value &Val) {
1015 return Val.getValueID() == Value::FunctionVal;
1016 }
1017};
1018
1019template <> struct isa_impl<GlobalVariable, Value> {
1020 static inline bool doit(const Value &Val) {
1021 return Val.getValueID() == Value::GlobalVariableVal;
1022 }
1023};
1024
1025template <> struct isa_impl<GlobalAlias, Value> {
1026 static inline bool doit(const Value &Val) {
1027 return Val.getValueID() == Value::GlobalAliasVal;
1028 }
1029};
1030
1031template <> struct isa_impl<GlobalIFunc, Value> {
1032 static inline bool doit(const Value &Val) {
1033 return Val.getValueID() == Value::GlobalIFuncVal;
1034 }
1035};
1036
1037template <> struct isa_impl<GlobalValue, Value> {
1038 static inline bool doit(const Value &Val) {
1039 return isa<GlobalObject>(Val) || isa<GlobalAlias>(Val);
1040 }
1041};
1042
1043template <> struct isa_impl<GlobalObject, Value> {
1044 static inline bool doit(const Value &Val) {
1045 return isa<GlobalVariable>(Val) || isa<Function>(Val) ||
1046 isa<GlobalIFunc>(Val);
1047 }
1048};
1049
1050// Create wrappers for C Binding types (see CBindingWrapping.h).
1051DEFINE_ISA_CONVERSION_FUNCTIONS(Value, LLVMValueRef)
1052
1053// Specialized opaque value conversions.
1054inline Value **unwrap(LLVMValueRef *Vals) {
1055 return reinterpret_cast<Value**>(Vals);
1056}
1057
1058template<typename T>
1059inline T **unwrap(LLVMValueRef *Vals, unsigned Length) {
1060#ifndef NDEBUG
1061 for (LLVMValueRef *I = Vals, *E = Vals + Length; I != E; ++I)
1062 unwrap<T>(*I); // For side effect of calling assert on invalid usage.
1063#endif
1064 (void)Length;
1065 return reinterpret_cast<T**>(Vals);
1066}
1067
1068inline LLVMValueRef *wrap(const Value **Vals) {
1069 return reinterpret_cast<LLVMValueRef*>(const_cast<Value**>(Vals));
1070}
1071
1072} // end namespace llvm
1073
1074#endif // LLVM_IR_VALUE_H
1075