1//===-- llvm/Instruction.h - Instruction class definition -------*- 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 contains the declaration of the Instruction class, which is the
10// base class for all of the LLVM instructions.
11//
12//===----------------------------------------------------------------------===//
13
14#ifndef LLVM_IR_INSTRUCTION_H
15#define LLVM_IR_INSTRUCTION_H
16
17#include "llvm/ADT/ArrayRef.h"
18#include "llvm/ADT/Bitfields.h"
19#include "llvm/ADT/None.h"
20#include "llvm/ADT/StringRef.h"
21#include "llvm/ADT/ilist_node.h"
22#include "llvm/IR/DebugLoc.h"
23#include "llvm/IR/SymbolTableListTraits.h"
24#include "llvm/IR/User.h"
25#include "llvm/IR/Value.h"
26#include "llvm/Support/AtomicOrdering.h"
27#include "llvm/Support/Casting.h"
28#include <algorithm>
29#include <cassert>
30#include <cstdint>
31#include <utility>
32
33namespace llvm {
34
35class BasicBlock;
36class FastMathFlags;
37class MDNode;
38class Module;
39struct AAMDNodes;
40
41template <> struct ilist_alloc_traits<Instruction> {
42 static inline void deleteNode(Instruction *V);
43};
44
45class Instruction : public User,
46 public ilist_node_with_parent<Instruction, BasicBlock> {
47 BasicBlock *Parent;
48 DebugLoc DbgLoc; // 'dbg' Metadata cache.
49
50 /// Relative order of this instruction in its parent basic block. Used for
51 /// O(1) local dominance checks between instructions.
52 mutable unsigned Order = 0;
53
54protected:
55 // The 15 first bits of `Value::SubclassData` are available for subclasses of
56 // `Instruction` to use.
57 using OpaqueField = Bitfield::Element<uint16_t, 0, 15>;
58
59 // Template alias so that all Instruction storing alignment use the same
60 // definiton.
61 // Valid alignments are powers of two from 2^0 to 2^MaxAlignmentExponent =
62 // 2^29. We store them as Log2(Alignment), so we need 5 bits to encode the 30
63 // possible values.
64 template <unsigned Offset>
65 using AlignmentBitfieldElementT =
66 typename Bitfield::Element<unsigned, Offset, 5,
67 Value::MaxAlignmentExponent>;
68
69 template <unsigned Offset>
70 using BoolBitfieldElementT = typename Bitfield::Element<bool, Offset, 1>;
71
72 template <unsigned Offset>
73 using AtomicOrderingBitfieldElementT =
74 typename Bitfield::Element<AtomicOrdering, Offset, 3,
75 AtomicOrdering::LAST>;
76
77private:
78 // The last bit is used to store whether the instruction has metadata attached
79 // or not.
80 using HasMetadataField = Bitfield::Element<bool, 15, 1>;
81
82protected:
83 ~Instruction(); // Use deleteValue() to delete a generic Instruction.
84
85public:
86 Instruction(const Instruction &) = delete;
87 Instruction &operator=(const Instruction &) = delete;
88
89 /// Specialize the methods defined in Value, as we know that an instruction
90 /// can only be used by other instructions.
91 Instruction *user_back() { return cast<Instruction>(*user_begin());}
92 const Instruction *user_back() const { return cast<Instruction>(*user_begin());}
93
94 inline const BasicBlock *getParent() const { return Parent; }
95 inline BasicBlock *getParent() { return Parent; }
96
97 /// Return the module owning the function this instruction belongs to
98 /// or nullptr it the function does not have a module.
99 ///
100 /// Note: this is undefined behavior if the instruction does not have a
101 /// parent, or the parent basic block does not have a parent function.
102 const Module *getModule() const;
103 Module *getModule() {
104 return const_cast<Module *>(
105 static_cast<const Instruction *>(this)->getModule());
106 }
107
108 /// Return the function this instruction belongs to.
109 ///
110 /// Note: it is undefined behavior to call this on an instruction not
111 /// currently inserted into a function.
112 const Function *getFunction() const;
113 Function *getFunction() {
114 return const_cast<Function *>(
115 static_cast<const Instruction *>(this)->getFunction());
116 }
117
118 /// This method unlinks 'this' from the containing basic block, but does not
119 /// delete it.
120 void removeFromParent();
121
122 /// This method unlinks 'this' from the containing basic block and deletes it.
123 ///
124 /// \returns an iterator pointing to the element after the erased one
125 SymbolTableList<Instruction>::iterator eraseFromParent();
126
127 /// Insert an unlinked instruction into a basic block immediately before
128 /// the specified instruction.
129 void insertBefore(Instruction *InsertPos);
130
131 /// Insert an unlinked instruction into a basic block immediately after the
132 /// specified instruction.
133 void insertAfter(Instruction *InsertPos);
134
135 /// Unlink this instruction from its current basic block and insert it into
136 /// the basic block that MovePos lives in, right before MovePos.
137 void moveBefore(Instruction *MovePos);
138
139 /// Unlink this instruction and insert into BB before I.
140 ///
141 /// \pre I is a valid iterator into BB.
142 void moveBefore(BasicBlock &BB, SymbolTableList<Instruction>::iterator I);
143
144 /// Unlink this instruction from its current basic block and insert it into
145 /// the basic block that MovePos lives in, right after MovePos.
146 void moveAfter(Instruction *MovePos);
147
148 /// Given an instruction Other in the same basic block as this instruction,
149 /// return true if this instruction comes before Other. In this worst case,
150 /// this takes linear time in the number of instructions in the block. The
151 /// results are cached, so in common cases when the block remains unmodified,
152 /// it takes constant time.
153 bool comesBefore(const Instruction *Other) const;
154
155 //===--------------------------------------------------------------------===//
156 // Subclass classification.
157 //===--------------------------------------------------------------------===//
158
159 /// Returns a member of one of the enums like Instruction::Add.
160 unsigned getOpcode() const { return getValueID() - InstructionVal; }
161
162 const char *getOpcodeName() const { return getOpcodeName(getOpcode()); }
163 bool isTerminator() const { return isTerminator(getOpcode()); }
164 bool isUnaryOp() const { return isUnaryOp(getOpcode()); }
165 bool isBinaryOp() const { return isBinaryOp(getOpcode()); }
166 bool isIntDivRem() const { return isIntDivRem(getOpcode()); }
167 bool isShift() const { return isShift(getOpcode()); }
168 bool isCast() const { return isCast(getOpcode()); }
169 bool isFuncletPad() const { return isFuncletPad(getOpcode()); }
170 bool isExceptionalTerminator() const {
171 return isExceptionalTerminator(getOpcode());
172 }
173 bool isIndirectTerminator() const {
174 return isIndirectTerminator(getOpcode());
175 }
176
177 static const char* getOpcodeName(unsigned OpCode);
178
179 static inline bool isTerminator(unsigned OpCode) {
180 return OpCode >= TermOpsBegin && OpCode < TermOpsEnd;
181 }
182
183 static inline bool isUnaryOp(unsigned Opcode) {
184 return Opcode >= UnaryOpsBegin && Opcode < UnaryOpsEnd;
185 }
186 static inline bool isBinaryOp(unsigned Opcode) {
187 return Opcode >= BinaryOpsBegin && Opcode < BinaryOpsEnd;
188 }
189
190 static inline bool isIntDivRem(unsigned Opcode) {
191 return Opcode == UDiv || Opcode == SDiv || Opcode == URem || Opcode == SRem;
192 }
193
194 /// Determine if the Opcode is one of the shift instructions.
195 static inline bool isShift(unsigned Opcode) {
196 return Opcode >= Shl && Opcode <= AShr;
197 }
198
199 /// Return true if this is a logical shift left or a logical shift right.
200 inline bool isLogicalShift() const {
201 return getOpcode() == Shl || getOpcode() == LShr;
202 }
203
204 /// Return true if this is an arithmetic shift right.
205 inline bool isArithmeticShift() const {
206 return getOpcode() == AShr;
207 }
208
209 /// Determine if the Opcode is and/or/xor.
210 static inline bool isBitwiseLogicOp(unsigned Opcode) {
211 return Opcode == And || Opcode == Or || Opcode == Xor;
212 }
213
214 /// Return true if this is and/or/xor.
215 inline bool isBitwiseLogicOp() const {
216 return isBitwiseLogicOp(getOpcode());
217 }
218
219 /// Determine if the OpCode is one of the CastInst instructions.
220 static inline bool isCast(unsigned OpCode) {
221 return OpCode >= CastOpsBegin && OpCode < CastOpsEnd;
222 }
223
224 /// Determine if the OpCode is one of the FuncletPadInst instructions.
225 static inline bool isFuncletPad(unsigned OpCode) {
226 return OpCode >= FuncletPadOpsBegin && OpCode < FuncletPadOpsEnd;
227 }
228
229 /// Returns true if the OpCode is a terminator related to exception handling.
230 static inline bool isExceptionalTerminator(unsigned OpCode) {
231 switch (OpCode) {
232 case Instruction::CatchSwitch:
233 case Instruction::CatchRet:
234 case Instruction::CleanupRet:
235 case Instruction::Invoke:
236 case Instruction::Resume:
237 return true;
238 default:
239 return false;
240 }
241 }
242
243 /// Returns true if the OpCode is a terminator with indirect targets.
244 static inline bool isIndirectTerminator(unsigned OpCode) {
245 switch (OpCode) {
246 case Instruction::IndirectBr:
247 case Instruction::CallBr:
248 return true;
249 default:
250 return false;
251 }
252 }
253
254 //===--------------------------------------------------------------------===//
255 // Metadata manipulation.
256 //===--------------------------------------------------------------------===//
257
258 /// Return true if this instruction has any metadata attached to it.
259 bool hasMetadata() const { return DbgLoc || Value::hasMetadata(); }
260
261 /// Return true if this instruction has metadata attached to it other than a
262 /// debug location.
263 bool hasMetadataOtherThanDebugLoc() const { return Value::hasMetadata(); }
264
265 /// Return true if this instruction has the given type of metadata attached.
266 bool hasMetadata(unsigned KindID) const {
267 return getMetadata(KindID) != nullptr;
268 }
269
270 /// Return true if this instruction has the given type of metadata attached.
271 bool hasMetadata(StringRef Kind) const {
272 return getMetadata(Kind) != nullptr;
273 }
274
275 /// Get the metadata of given kind attached to this Instruction.
276 /// If the metadata is not found then return null.
277 MDNode *getMetadata(unsigned KindID) const {
278 if (!hasMetadata()) return nullptr;
279 return getMetadataImpl(KindID);
280 }
281
282 /// Get the metadata of given kind attached to this Instruction.
283 /// If the metadata is not found then return null.
284 MDNode *getMetadata(StringRef Kind) const {
285 if (!hasMetadata()) return nullptr;
286 return getMetadataImpl(Kind);
287 }
288
289 /// Get all metadata attached to this Instruction. The first element of each
290 /// pair returned is the KindID, the second element is the metadata value.
291 /// This list is returned sorted by the KindID.
292 void
293 getAllMetadata(SmallVectorImpl<std::pair<unsigned, MDNode *>> &MDs) const {
294 if (hasMetadata())
295 getAllMetadataImpl(MDs);
296 }
297
298 /// This does the same thing as getAllMetadata, except that it filters out the
299 /// debug location.
300 void getAllMetadataOtherThanDebugLoc(
301 SmallVectorImpl<std::pair<unsigned, MDNode *>> &MDs) const {
302 Value::getAllMetadata(MDs);
303 }
304
305 /// Fills the AAMDNodes structure with AA metadata from this instruction.
306 /// When Merge is true, the existing AA metadata is merged with that from this
307 /// instruction providing the most-general result.
308 void getAAMetadata(AAMDNodes &N, bool Merge = false) const;
309
310 /// Set the metadata of the specified kind to the specified node. This updates
311 /// or replaces metadata if already present, or removes it if Node is null.
312 void setMetadata(unsigned KindID, MDNode *Node);
313 void setMetadata(StringRef Kind, MDNode *Node);
314
315 /// Copy metadata from \p SrcInst to this instruction. \p WL, if not empty,
316 /// specifies the list of meta data that needs to be copied. If \p WL is
317 /// empty, all meta data will be copied.
318 void copyMetadata(const Instruction &SrcInst,
319 ArrayRef<unsigned> WL = ArrayRef<unsigned>());
320
321 /// If the instruction has "branch_weights" MD_prof metadata and the MDNode
322 /// has three operands (including name string), swap the order of the
323 /// metadata.
324 void swapProfMetadata();
325
326 /// Drop all unknown metadata except for debug locations.
327 /// @{
328 /// Passes are required to drop metadata they don't understand. This is a
329 /// convenience method for passes to do so.
330 void dropUnknownNonDebugMetadata(ArrayRef<unsigned> KnownIDs);
331 void dropUnknownNonDebugMetadata() {
332 return dropUnknownNonDebugMetadata(None);
333 }
334 void dropUnknownNonDebugMetadata(unsigned ID1) {
335 return dropUnknownNonDebugMetadata(makeArrayRef(ID1));
336 }
337 void dropUnknownNonDebugMetadata(unsigned ID1, unsigned ID2) {
338 unsigned IDs[] = {ID1, ID2};
339 return dropUnknownNonDebugMetadata(IDs);
340 }
341 /// @}
342
343 /// Adds an !annotation metadata node with \p Annotation to this instruction.
344 /// If this instruction already has !annotation metadata, append \p Annotation
345 /// to the existing node.
346 void addAnnotationMetadata(StringRef Annotation);
347
348 /// Sets the metadata on this instruction from the AAMDNodes structure.
349 void setAAMetadata(const AAMDNodes &N);
350
351 /// Retrieve the raw weight values of a conditional branch or select.
352 /// Returns true on success with profile weights filled in.
353 /// Returns false if no metadata or invalid metadata was found.
354 bool extractProfMetadata(uint64_t &TrueVal, uint64_t &FalseVal) const;
355
356 /// Retrieve total raw weight values of a branch.
357 /// Returns true on success with profile total weights filled in.
358 /// Returns false if no metadata was found.
359 bool extractProfTotalWeight(uint64_t &TotalVal) const;
360
361 /// Set the debug location information for this instruction.
362 void setDebugLoc(DebugLoc Loc) { DbgLoc = std::move(Loc); }
363
364 /// Return the debug location for this node as a DebugLoc.
365 const DebugLoc &getDebugLoc() const { return DbgLoc; }
366
367 /// Set or clear the nuw flag on this instruction, which must be an operator
368 /// which supports this flag. See LangRef.html for the meaning of this flag.
369 void setHasNoUnsignedWrap(bool b = true);
370
371 /// Set or clear the nsw flag on this instruction, which must be an operator
372 /// which supports this flag. See LangRef.html for the meaning of this flag.
373 void setHasNoSignedWrap(bool b = true);
374
375 /// Set or clear the exact flag on this instruction, which must be an operator
376 /// which supports this flag. See LangRef.html for the meaning of this flag.
377 void setIsExact(bool b = true);
378
379 /// Determine whether the no unsigned wrap flag is set.
380 bool hasNoUnsignedWrap() const;
381
382 /// Determine whether the no signed wrap flag is set.
383 bool hasNoSignedWrap() const;
384
385 /// Drops flags that may cause this instruction to evaluate to poison despite
386 /// having non-poison inputs.
387 void dropPoisonGeneratingFlags();
388
389 /// Determine whether the exact flag is set.
390 bool isExact() const;
391
392 /// Set or clear all fast-math-flags on this instruction, which must be an
393 /// operator which supports this flag. See LangRef.html for the meaning of
394 /// this flag.
395 void setFast(bool B);
396
397 /// Set or clear the reassociation flag on this instruction, which must be
398 /// an operator which supports this flag. See LangRef.html for the meaning of
399 /// this flag.
400 void setHasAllowReassoc(bool B);
401
402 /// Set or clear the no-nans flag on this instruction, which must be an
403 /// operator which supports this flag. See LangRef.html for the meaning of
404 /// this flag.
405 void setHasNoNaNs(bool B);
406
407 /// Set or clear the no-infs flag on this instruction, which must be an
408 /// operator which supports this flag. See LangRef.html for the meaning of
409 /// this flag.
410 void setHasNoInfs(bool B);
411
412 /// Set or clear the no-signed-zeros flag on this instruction, which must be
413 /// an operator which supports this flag. See LangRef.html for the meaning of
414 /// this flag.
415 void setHasNoSignedZeros(bool B);
416
417 /// Set or clear the allow-reciprocal flag on this instruction, which must be
418 /// an operator which supports this flag. See LangRef.html for the meaning of
419 /// this flag.
420 void setHasAllowReciprocal(bool B);
421
422 /// Set or clear the allow-contract flag on this instruction, which must be
423 /// an operator which supports this flag. See LangRef.html for the meaning of
424 /// this flag.
425 void setHasAllowContract(bool B);
426
427 /// Set or clear the approximate-math-functions flag on this instruction,
428 /// which must be an operator which supports this flag. See LangRef.html for
429 /// the meaning of this flag.
430 void setHasApproxFunc(bool B);
431
432 /// Convenience function for setting multiple fast-math flags on this
433 /// instruction, which must be an operator which supports these flags. See
434 /// LangRef.html for the meaning of these flags.
435 void setFastMathFlags(FastMathFlags FMF);
436
437 /// Convenience function for transferring all fast-math flag values to this
438 /// instruction, which must be an operator which supports these flags. See
439 /// LangRef.html for the meaning of these flags.
440 void copyFastMathFlags(FastMathFlags FMF);
441
442 /// Determine whether all fast-math-flags are set.
443 bool isFast() const;
444
445 /// Determine whether the allow-reassociation flag is set.
446 bool hasAllowReassoc() const;
447
448 /// Determine whether the no-NaNs flag is set.
449 bool hasNoNaNs() const;
450
451 /// Determine whether the no-infs flag is set.
452 bool hasNoInfs() const;
453
454 /// Determine whether the no-signed-zeros flag is set.
455 bool hasNoSignedZeros() const;
456
457 /// Determine whether the allow-reciprocal flag is set.
458 bool hasAllowReciprocal() const;
459
460 /// Determine whether the allow-contract flag is set.
461 bool hasAllowContract() const;
462
463 /// Determine whether the approximate-math-functions flag is set.
464 bool hasApproxFunc() const;
465
466 /// Convenience function for getting all the fast-math flags, which must be an
467 /// operator which supports these flags. See LangRef.html for the meaning of
468 /// these flags.
469 FastMathFlags getFastMathFlags() const;
470
471 /// Copy I's fast-math flags
472 void copyFastMathFlags(const Instruction *I);
473
474 /// Convenience method to copy supported exact, fast-math, and (optionally)
475 /// wrapping flags from V to this instruction.
476 void copyIRFlags(const Value *V, bool IncludeWrapFlags = true);
477
478 /// Logical 'and' of any supported wrapping, exact, and fast-math flags of
479 /// V and this instruction.
480 void andIRFlags(const Value *V);
481
482 /// Merge 2 debug locations and apply it to the Instruction. If the
483 /// instruction is a CallIns, we need to traverse the inline chain to find
484 /// the common scope. This is not efficient for N-way merging as each time
485 /// you merge 2 iterations, you need to rebuild the hashmap to find the
486 /// common scope. However, we still choose this API because:
487 /// 1) Simplicity: it takes 2 locations instead of a list of locations.
488 /// 2) In worst case, it increases the complexity from O(N*I) to
489 /// O(2*N*I), where N is # of Instructions to merge, and I is the
490 /// maximum level of inline stack. So it is still linear.
491 /// 3) Merging of call instructions should be extremely rare in real
492 /// applications, thus the N-way merging should be in code path.
493 /// The DebugLoc attached to this instruction will be overwritten by the
494 /// merged DebugLoc.
495 void applyMergedLocation(const DILocation *LocA, const DILocation *LocB);
496
497 /// Updates the debug location given that the instruction has been hoisted
498 /// from a block to a predecessor of that block.
499 /// Note: it is undefined behavior to call this on an instruction not
500 /// currently inserted into a function.
501 void updateLocationAfterHoist();
502
503 /// Drop the instruction's debug location. This does not guarantee removal
504 /// of the !dbg source location attachment, as it must set a line 0 location
505 /// with scope information attached on call instructions. To guarantee
506 /// removal of the !dbg attachment, use the \ref setDebugLoc() API.
507 /// Note: it is undefined behavior to call this on an instruction not
508 /// currently inserted into a function.
509 void dropLocation();
510
511private:
512 // These are all implemented in Metadata.cpp.
513 MDNode *getMetadataImpl(unsigned KindID) const;
514 MDNode *getMetadataImpl(StringRef Kind) const;
515 void
516 getAllMetadataImpl(SmallVectorImpl<std::pair<unsigned, MDNode *>> &) const;
517
518public:
519 //===--------------------------------------------------------------------===//
520 // Predicates and helper methods.
521 //===--------------------------------------------------------------------===//
522
523 /// Return true if the instruction is associative:
524 ///
525 /// Associative operators satisfy: x op (y op z) === (x op y) op z
526 ///
527 /// In LLVM, the Add, Mul, And, Or, and Xor operators are associative.
528 ///
529 bool isAssociative() const LLVM_READONLY;
530 static bool isAssociative(unsigned Opcode) {
531 return Opcode == And || Opcode == Or || Opcode == Xor ||
532 Opcode == Add || Opcode == Mul;
533 }
534
535 /// Return true if the instruction is commutative:
536 ///
537 /// Commutative operators satisfy: (x op y) === (y op x)
538 ///
539 /// In LLVM, these are the commutative operators, plus SetEQ and SetNE, when
540 /// applied to any type.
541 ///
542 bool isCommutative() const LLVM_READONLY;
543 static bool isCommutative(unsigned Opcode) {
544 switch (Opcode) {
545 case Add: case FAdd:
546 case Mul: case FMul:
547 case And: case Or: case Xor:
548 return true;
549 default:
550 return false;
551 }
552 }
553
554 /// Return true if the instruction is idempotent:
555 ///
556 /// Idempotent operators satisfy: x op x === x
557 ///
558 /// In LLVM, the And and Or operators are idempotent.
559 ///
560 bool isIdempotent() const { return isIdempotent(getOpcode()); }
561 static bool isIdempotent(unsigned Opcode) {
562 return Opcode == And || Opcode == Or;
563 }
564
565 /// Return true if the instruction is nilpotent:
566 ///
567 /// Nilpotent operators satisfy: x op x === Id,
568 ///
569 /// where Id is the identity for the operator, i.e. a constant such that
570 /// x op Id === x and Id op x === x for all x.
571 ///
572 /// In LLVM, the Xor operator is nilpotent.
573 ///
574 bool isNilpotent() const { return isNilpotent(getOpcode()); }
575 static bool isNilpotent(unsigned Opcode) {
576 return Opcode == Xor;
577 }
578
579 /// Return true if this instruction may modify memory.
580 bool mayWriteToMemory() const;
581
582 /// Return true if this instruction may read memory.
583 bool mayReadFromMemory() const;
584
585 /// Return true if this instruction may read or write memory.
586 bool mayReadOrWriteMemory() const {
587 return mayReadFromMemory() || mayWriteToMemory();
588 }
589
590 /// Return true if this instruction has an AtomicOrdering of unordered or
591 /// higher.
592 bool isAtomic() const;
593
594 /// Return true if this atomic instruction loads from memory.
595 bool hasAtomicLoad() const;
596
597 /// Return true if this atomic instruction stores to memory.
598 bool hasAtomicStore() const;
599
600 /// Return true if this instruction has a volatile memory access.
601 bool isVolatile() const;
602
603 /// Return true if this instruction may throw an exception.
604 bool mayThrow() const;
605
606 /// Return true if this instruction behaves like a memory fence: it can load
607 /// or store to memory location without being given a memory location.
608 bool isFenceLike() const {
609 switch (getOpcode()) {
610 default:
611 return false;
612 // This list should be kept in sync with the list in mayWriteToMemory for
613 // all opcodes which don't have a memory location.
614 case Instruction::Fence:
615 case Instruction::CatchPad:
616 case Instruction::CatchRet:
617 case Instruction::Call:
618 case Instruction::Invoke:
619 return true;
620 }
621 }
622
623 /// Return true if the instruction may have side effects.
624 ///
625 /// Note that this does not consider malloc and alloca to have side
626 /// effects because the newly allocated memory is completely invisible to
627 /// instructions which don't use the returned value. For cases where this
628 /// matters, isSafeToSpeculativelyExecute may be more appropriate.
629 bool mayHaveSideEffects() const { return mayWriteToMemory() || mayThrow(); }
630
631 /// Return true if the instruction can be removed if the result is unused.
632 ///
633 /// When constant folding some instructions cannot be removed even if their
634 /// results are unused. Specifically terminator instructions and calls that
635 /// may have side effects cannot be removed without semantically changing the
636 /// generated program.
637 bool isSafeToRemove() const;
638
639 /// Return true if the instruction will return (unwinding is considered as
640 /// a form of returning control flow here).
641 bool willReturn() const;
642
643 /// Return true if the instruction is a variety of EH-block.
644 bool isEHPad() const {
645 switch (getOpcode()) {
646 case Instruction::CatchSwitch:
647 case Instruction::CatchPad:
648 case Instruction::CleanupPad:
649 case Instruction::LandingPad:
650 return true;
651 default:
652 return false;
653 }
654 }
655
656 /// Return true if the instruction is a llvm.lifetime.start or
657 /// llvm.lifetime.end marker.
658 bool isLifetimeStartOrEnd() const;
659
660 /// Return true if the instruction is a llvm.launder.invariant.group or
661 /// llvm.strip.invariant.group.
662 bool isLaunderOrStripInvariantGroup() const;
663
664 /// Return true if the instruction is a DbgInfoIntrinsic or PseudoProbeInst.
665 bool isDebugOrPseudoInst() const;
666
667 /// Return a pointer to the next non-debug instruction in the same basic
668 /// block as 'this', or nullptr if no such instruction exists. Skip any pseudo
669 /// operations if \c SkipPseudoOp is true.
670 const Instruction *
671 getNextNonDebugInstruction(bool SkipPseudoOp = false) const;
672 Instruction *getNextNonDebugInstruction(bool SkipPseudoOp = false) {
673 return const_cast<Instruction *>(
674 static_cast<const Instruction *>(this)->getNextNonDebugInstruction(
675 SkipPseudoOp));
676 }
677
678 /// Return a pointer to the previous non-debug instruction in the same basic
679 /// block as 'this', or nullptr if no such instruction exists. Skip any pseudo
680 /// operations if \c SkipPseudoOp is true.
681 const Instruction *
682 getPrevNonDebugInstruction(bool SkipPseudoOp = false) const;
683 Instruction *getPrevNonDebugInstruction(bool SkipPseudoOp = false) {
684 return const_cast<Instruction *>(
685 static_cast<const Instruction *>(this)->getPrevNonDebugInstruction(
686 SkipPseudoOp));
687 }
688
689 /// Create a copy of 'this' instruction that is identical in all ways except
690 /// the following:
691 /// * The instruction has no parent
692 /// * The instruction has no name
693 ///
694 Instruction *clone() const;
695
696 /// Return true if the specified instruction is exactly identical to the
697 /// current one. This means that all operands match and any extra information
698 /// (e.g. load is volatile) agree.
699 bool isIdenticalTo(const Instruction *I) const;
700
701 /// This is like isIdenticalTo, except that it ignores the
702 /// SubclassOptionalData flags, which may specify conditions under which the
703 /// instruction's result is undefined.
704 bool isIdenticalToWhenDefined(const Instruction *I) const;
705
706 /// When checking for operation equivalence (using isSameOperationAs) it is
707 /// sometimes useful to ignore certain attributes.
708 enum OperationEquivalenceFlags {
709 /// Check for equivalence ignoring load/store alignment.
710 CompareIgnoringAlignment = 1<<0,
711 /// Check for equivalence treating a type and a vector of that type
712 /// as equivalent.
713 CompareUsingScalarTypes = 1<<1
714 };
715
716 /// This function determines if the specified instruction executes the same
717 /// operation as the current one. This means that the opcodes, type, operand
718 /// types and any other factors affecting the operation must be the same. This
719 /// is similar to isIdenticalTo except the operands themselves don't have to
720 /// be identical.
721 /// @returns true if the specified instruction is the same operation as
722 /// the current one.
723 /// Determine if one instruction is the same operation as another.
724 bool isSameOperationAs(const Instruction *I, unsigned flags = 0) const;
725
726 /// Return true if there are any uses of this instruction in blocks other than
727 /// the specified block. Note that PHI nodes are considered to evaluate their
728 /// operands in the corresponding predecessor block.
729 bool isUsedOutsideOfBlock(const BasicBlock *BB) const;
730
731 /// Return the number of successors that this instruction has. The instruction
732 /// must be a terminator.
733 unsigned getNumSuccessors() const;
734
735 /// Return the specified successor. This instruction must be a terminator.
736 BasicBlock *getSuccessor(unsigned Idx) const;
737
738 /// Update the specified successor to point at the provided block. This
739 /// instruction must be a terminator.
740 void setSuccessor(unsigned Idx, BasicBlock *BB);
741
742 /// Replace specified successor OldBB to point at the provided block.
743 /// This instruction must be a terminator.
744 void replaceSuccessorWith(BasicBlock *OldBB, BasicBlock *NewBB);
745
746 /// Methods for support type inquiry through isa, cast, and dyn_cast:
747 static bool classof(const Value *V) {
748 return V->getValueID() >= Value::InstructionVal;
749 }
750
751 //----------------------------------------------------------------------
752 // Exported enumerations.
753 //
754 enum TermOps { // These terminate basic blocks
755#define FIRST_TERM_INST(N) TermOpsBegin = N,
756#define HANDLE_TERM_INST(N, OPC, CLASS) OPC = N,
757#define LAST_TERM_INST(N) TermOpsEnd = N+1
758#include "llvm/IR/Instruction.def"
759 };
760
761 enum UnaryOps {
762#define FIRST_UNARY_INST(N) UnaryOpsBegin = N,
763#define HANDLE_UNARY_INST(N, OPC, CLASS) OPC = N,
764#define LAST_UNARY_INST(N) UnaryOpsEnd = N+1
765#include "llvm/IR/Instruction.def"
766 };
767
768 enum BinaryOps {
769#define FIRST_BINARY_INST(N) BinaryOpsBegin = N,
770#define HANDLE_BINARY_INST(N, OPC, CLASS) OPC = N,
771#define LAST_BINARY_INST(N) BinaryOpsEnd = N+1
772#include "llvm/IR/Instruction.def"
773 };
774
775 enum MemoryOps {
776#define FIRST_MEMORY_INST(N) MemoryOpsBegin = N,
777#define HANDLE_MEMORY_INST(N, OPC, CLASS) OPC = N,
778#define LAST_MEMORY_INST(N) MemoryOpsEnd = N+1
779#include "llvm/IR/Instruction.def"
780 };
781
782 enum CastOps {
783#define FIRST_CAST_INST(N) CastOpsBegin = N,
784#define HANDLE_CAST_INST(N, OPC, CLASS) OPC = N,
785#define LAST_CAST_INST(N) CastOpsEnd = N+1
786#include "llvm/IR/Instruction.def"
787 };
788
789 enum FuncletPadOps {
790#define FIRST_FUNCLETPAD_INST(N) FuncletPadOpsBegin = N,
791#define HANDLE_FUNCLETPAD_INST(N, OPC, CLASS) OPC = N,
792#define LAST_FUNCLETPAD_INST(N) FuncletPadOpsEnd = N+1
793#include "llvm/IR/Instruction.def"
794 };
795
796 enum OtherOps {
797#define FIRST_OTHER_INST(N) OtherOpsBegin = N,
798#define HANDLE_OTHER_INST(N, OPC, CLASS) OPC = N,
799#define LAST_OTHER_INST(N) OtherOpsEnd = N+1
800#include "llvm/IR/Instruction.def"
801 };
802
803private:
804 friend class SymbolTableListTraits<Instruction>;
805 friend class BasicBlock; // For renumbering.
806
807 // Shadow Value::setValueSubclassData with a private forwarding method so that
808 // subclasses cannot accidentally use it.
809 void setValueSubclassData(unsigned short D) {
810 Value::setValueSubclassData(D);
811 }
812
813 unsigned short getSubclassDataFromValue() const {
814 return Value::getSubclassDataFromValue();
815 }
816
817 void setParent(BasicBlock *P);
818
819protected:
820 // Instruction subclasses can stick up to 15 bits of stuff into the
821 // SubclassData field of instruction with these members.
822
823 template <typename BitfieldElement>
824 typename BitfieldElement::Type getSubclassData() const {
825 static_assert(
826 std::is_same<BitfieldElement, HasMetadataField>::value ||
827 !Bitfield::isOverlapping<BitfieldElement, HasMetadataField>(),
828 "Must not overlap with the metadata bit");
829 return Bitfield::get<BitfieldElement>(getSubclassDataFromValue());
830 }
831
832 template <typename BitfieldElement>
833 void setSubclassData(typename BitfieldElement::Type Value) {
834 static_assert(
835 std::is_same<BitfieldElement, HasMetadataField>::value ||
836 !Bitfield::isOverlapping<BitfieldElement, HasMetadataField>(),
837 "Must not overlap with the metadata bit");
838 auto Storage = getSubclassDataFromValue();
839 Bitfield::set<BitfieldElement>(Storage, Value);
840 setValueSubclassData(Storage);
841 }
842
843 Instruction(Type *Ty, unsigned iType, Use *Ops, unsigned NumOps,
844 Instruction *InsertBefore = nullptr);
845 Instruction(Type *Ty, unsigned iType, Use *Ops, unsigned NumOps,
846 BasicBlock *InsertAtEnd);
847
848private:
849 /// Create a copy of this instruction.
850 Instruction *cloneImpl() const;
851};
852
853inline void ilist_alloc_traits<Instruction>::deleteNode(Instruction *V) {
854 V->deleteValue();
855}
856
857} // end namespace llvm
858
859#endif // LLVM_IR_INSTRUCTION_H
860