1//===-- llvm/Instruction.h - Instruction class definition -------*- C++ -*-===//
2//
3//                     The LLVM Compiler Infrastructure
4//
5// This file is distributed under the University of Illinois Open Source
6// License. See LICENSE.TXT for details.
7//
8//===----------------------------------------------------------------------===//
9//
10// This file contains the declaration of the Instruction class, which is the
11// base class for all of the LLVM instructions.
12//
13//===----------------------------------------------------------------------===//
14
15#ifndef LLVM_INSTRUCTION_H
16#define LLVM_INSTRUCTION_H
17
18#include "llvm/User.h"
19#include "llvm/ADT/ilist_node.h"
20#include "llvm/Support/DebugLoc.h"
21
22namespace llvm {
23
24class LLVMContext;
25class MDNode;
26
27template<typename ValueSubClass, typename ItemParentClass>
28  class SymbolTableListTraits;
29
30class Instruction : public User, public ilist_node<Instruction> {
31  void operator=(const Instruction &);     // Do not implement
32  Instruction(const Instruction &);        // Do not implement
33
34  BasicBlock *Parent;
35  DebugLoc DbgLoc;                         // 'dbg' Metadata cache.
36
37  enum {
38    /// HasMetadataBit - This is a bit stored in the SubClassData field which
39    /// indicates whether this instruction has metadata attached to it or not.
40    HasMetadataBit = 1 << 15
41  };
42public:
43  // Out of line virtual method, so the vtable, etc has a home.
44  ~Instruction();
45
46  /// use_back - Specialize the methods defined in Value, as we know that an
47  /// instruction can only be used by other instructions.
48  Instruction       *use_back()       { return cast<Instruction>(*use_begin());}
49  const Instruction *use_back() const { return cast<Instruction>(*use_begin());}
50
51  inline const BasicBlock *getParent() const { return Parent; }
52  inline       BasicBlock *getParent()       { return Parent; }
53
54  /// removeFromParent - This method unlinks 'this' from the containing basic
55  /// block, but does not delete it.
56  ///
57  void removeFromParent();
58
59  /// eraseFromParent - This method unlinks 'this' from the containing basic
60  /// block and deletes it.
61  ///
62  void eraseFromParent();
63
64  /// insertBefore - Insert an unlinked instructions into a basic block
65  /// immediately before the specified instruction.
66  void insertBefore(Instruction *InsertPos);
67
68  /// insertAfter - Insert an unlinked instructions into a basic block
69  /// immediately after the specified instruction.
70  void insertAfter(Instruction *InsertPos);
71
72  /// moveBefore - Unlink this instruction from its current basic block and
73  /// insert it into the basic block that MovePos lives in, right before
74  /// MovePos.
75  void moveBefore(Instruction *MovePos);
76
77  //===--------------------------------------------------------------------===//
78  // Subclass classification.
79  //===--------------------------------------------------------------------===//
80
81  /// getOpcode() returns a member of one of the enums like Instruction::Add.
82  unsigned getOpcode() const { return getValueID() - InstructionVal; }
83
84  const char *getOpcodeName() const { return getOpcodeName(getOpcode()); }
85  bool isTerminator() const { return isTerminator(getOpcode()); }
86  bool isBinaryOp() const { return isBinaryOp(getOpcode()); }
87  bool isShift() { return isShift(getOpcode()); }
88  bool isCast() const { return isCast(getOpcode()); }
89
90  static const char* getOpcodeName(unsigned OpCode);
91
92  static inline bool isTerminator(unsigned OpCode) {
93    return OpCode >= TermOpsBegin && OpCode < TermOpsEnd;
94  }
95
96  static inline bool isBinaryOp(unsigned Opcode) {
97    return Opcode >= BinaryOpsBegin && Opcode < BinaryOpsEnd;
98  }
99
100  /// @brief Determine if the Opcode is one of the shift instructions.
101  static inline bool isShift(unsigned Opcode) {
102    return Opcode >= Shl && Opcode <= AShr;
103  }
104
105  /// isLogicalShift - Return true if this is a logical shift left or a logical
106  /// shift right.
107  inline bool isLogicalShift() const {
108    return getOpcode() == Shl || getOpcode() == LShr;
109  }
110
111  /// isArithmeticShift - Return true if this is an arithmetic shift right.
112  inline bool isArithmeticShift() const {
113    return getOpcode() == AShr;
114  }
115
116  /// @brief Determine if the OpCode is one of the CastInst instructions.
117  static inline bool isCast(unsigned OpCode) {
118    return OpCode >= CastOpsBegin && OpCode < CastOpsEnd;
119  }
120
121  //===--------------------------------------------------------------------===//
122  // Metadata manipulation.
123  //===--------------------------------------------------------------------===//
124
125  /// hasMetadata() - Return true if this instruction has any metadata attached
126  /// to it.
127  bool hasMetadata() const {
128    return !DbgLoc.isUnknown() || hasMetadataHashEntry();
129  }
130
131  /// hasMetadataOtherThanDebugLoc - Return true if this instruction has
132  /// metadata attached to it other than a debug location.
133  bool hasMetadataOtherThanDebugLoc() const {
134    return hasMetadataHashEntry();
135  }
136
137  /// getMetadata - Get the metadata of given kind attached to this Instruction.
138  /// If the metadata is not found then return null.
139  MDNode *getMetadata(unsigned KindID) const {
140    if (!hasMetadata()) return 0;
141    return getMetadataImpl(KindID);
142  }
143
144  /// getMetadata - Get the metadata of given kind attached to this Instruction.
145  /// If the metadata is not found then return null.
146  MDNode *getMetadata(StringRef Kind) const {
147    if (!hasMetadata()) return 0;
148    return getMetadataImpl(Kind);
149  }
150
151  /// getAllMetadata - Get all metadata attached to this Instruction.  The first
152  /// element of each pair returned is the KindID, the second element is the
153  /// metadata value.  This list is returned sorted by the KindID.
154  void getAllMetadata(SmallVectorImpl<std::pair<unsigned, MDNode*> > &MDs)const{
155    if (hasMetadata())
156      getAllMetadataImpl(MDs);
157  }
158
159  /// getAllMetadataOtherThanDebugLoc - This does the same thing as
160  /// getAllMetadata, except that it filters out the debug location.
161  void getAllMetadataOtherThanDebugLoc(SmallVectorImpl<std::pair<unsigned,
162                                       MDNode*> > &MDs) const {
163    if (hasMetadataOtherThanDebugLoc())
164      getAllMetadataOtherThanDebugLocImpl(MDs);
165  }
166
167  /// setMetadata - Set the metadata of the specified kind to the specified
168  /// node.  This updates/replaces metadata if already present, or removes it if
169  /// Node is null.
170  void setMetadata(unsigned KindID, MDNode *Node);
171  void setMetadata(StringRef Kind, MDNode *Node);
172
173  /// setDebugLoc - Set the debug location information for this instruction.
174  void setDebugLoc(const DebugLoc &Loc) { DbgLoc = Loc; }
175
176  /// getDebugLoc - Return the debug location for this node as a DebugLoc.
177  const DebugLoc &getDebugLoc() const { return DbgLoc; }
178
179private:
180  /// hasMetadataHashEntry - Return true if we have an entry in the on-the-side
181  /// metadata hash.
182  bool hasMetadataHashEntry() const {
183    return (getSubclassDataFromValue() & HasMetadataBit) != 0;
184  }
185
186  // These are all implemented in Metadata.cpp.
187  MDNode *getMetadataImpl(unsigned KindID) const;
188  MDNode *getMetadataImpl(StringRef Kind) const;
189  void getAllMetadataImpl(SmallVectorImpl<std::pair<unsigned,MDNode*> > &)const;
190  void getAllMetadataOtherThanDebugLocImpl(SmallVectorImpl<std::pair<unsigned,
191                                           MDNode*> > &) const;
192  void clearMetadataHashEntries();
193public:
194  //===--------------------------------------------------------------------===//
195  // Predicates and helper methods.
196  //===--------------------------------------------------------------------===//
197
198
199  /// isAssociative - Return true if the instruction is associative:
200  ///
201  ///   Associative operators satisfy:  x op (y op z) === (x op y) op z
202  ///
203  /// In LLVM, the Add, Mul, And, Or, and Xor operators are associative.
204  ///
205  bool isAssociative() const { return isAssociative(getOpcode()); }
206  static bool isAssociative(unsigned op);
207
208  /// isCommutative - Return true if the instruction is commutative:
209  ///
210  ///   Commutative operators satisfy: (x op y) === (y op x)
211  ///
212  /// In LLVM, these are the associative operators, plus SetEQ and SetNE, when
213  /// applied to any type.
214  ///
215  bool isCommutative() const { return isCommutative(getOpcode()); }
216  static bool isCommutative(unsigned op);
217
218  /// isIdempotent - Return true if the instruction is idempotent:
219  ///
220  ///   Idempotent operators satisfy:  x op x === x
221  ///
222  /// In LLVM, the And and Or operators are idempotent.
223  ///
224  bool isIdempotent() const { return isIdempotent(getOpcode()); }
225  static bool isIdempotent(unsigned op);
226
227  /// isNilpotent - Return true if the instruction is nilpotent:
228  ///
229  ///   Nilpotent operators satisfy:  x op x === Id,
230  ///
231  ///   where Id is the identity for the operator, i.e. a constant such that
232  ///     x op Id === x and Id op x === x for all x.
233  ///
234  /// In LLVM, the Xor operator is nilpotent.
235  ///
236  bool isNilpotent() const { return isNilpotent(getOpcode()); }
237  static bool isNilpotent(unsigned op);
238
239  /// mayWriteToMemory - Return true if this instruction may modify memory.
240  ///
241  bool mayWriteToMemory() const;
242
243  /// mayReadFromMemory - Return true if this instruction may read memory.
244  ///
245  bool mayReadFromMemory() const;
246
247  /// mayReadOrWriteMemory - Return true if this instruction may read or
248  /// write memory.
249  ///
250  bool mayReadOrWriteMemory() const {
251    return mayReadFromMemory() || mayWriteToMemory();
252  }
253
254  /// mayThrow - Return true if this instruction may throw an exception.
255  ///
256  bool mayThrow() const;
257
258  /// mayHaveSideEffects - Return true if the instruction may have side effects.
259  ///
260  /// Note that this does not consider malloc and alloca to have side
261  /// effects because the newly allocated memory is completely invisible to
262  /// instructions which don't used the returned value.  For cases where this
263  /// matters, isSafeToSpeculativelyExecute may be more appropriate.
264  bool mayHaveSideEffects() const {
265    return mayWriteToMemory() || mayThrow();
266  }
267
268  /// clone() - Create a copy of 'this' instruction that is identical in all
269  /// ways except the following:
270  ///   * The instruction has no parent
271  ///   * The instruction has no name
272  ///
273  Instruction *clone() const;
274
275  /// isIdenticalTo - Return true if the specified instruction is exactly
276  /// identical to the current one.  This means that all operands match and any
277  /// extra information (e.g. load is volatile) agree.
278  bool isIdenticalTo(const Instruction *I) const;
279
280  /// isIdenticalToWhenDefined - This is like isIdenticalTo, except that it
281  /// ignores the SubclassOptionalData flags, which specify conditions
282  /// under which the instruction's result is undefined.
283  bool isIdenticalToWhenDefined(const Instruction *I) const;
284
285  /// When checking for operation equivalence (using isSameOperationAs) it is
286  /// sometimes useful to ignore certain attributes.
287  enum OperationEquivalenceFlags {
288    /// Check for equivalence ignoring load/store alignment.
289    CompareIgnoringAlignment = 1<<0,
290    /// Check for equivalence treating a type and a vector of that type
291    /// as equivalent.
292    CompareUsingScalarTypes = 1<<1
293  };
294
295  /// This function determines if the specified instruction executes the same
296  /// operation as the current one. This means that the opcodes, type, operand
297  /// types and any other factors affecting the operation must be the same. This
298  /// is similar to isIdenticalTo except the operands themselves don't have to
299  /// be identical.
300  /// @returns true if the specified instruction is the same operation as
301  /// the current one.
302  /// @brief Determine if one instruction is the same operation as another.
303  bool isSameOperationAs(const Instruction *I, unsigned flags = 0) const;
304
305  /// isUsedOutsideOfBlock - Return true if there are any uses of this
306  /// instruction in blocks other than the specified block.  Note that PHI nodes
307  /// are considered to evaluate their operands in the corresponding predecessor
308  /// block.
309  bool isUsedOutsideOfBlock(const BasicBlock *BB) const;
310
311
312  /// Methods for support type inquiry through isa, cast, and dyn_cast:
313  static inline bool classof(const Instruction *) { return true; }
314  static inline bool classof(const Value *V) {
315    return V->getValueID() >= Value::InstructionVal;
316  }
317
318  //----------------------------------------------------------------------
319  // Exported enumerations.
320  //
321  enum TermOps {       // These terminate basic blocks
322#define  FIRST_TERM_INST(N)             TermOpsBegin = N,
323#define HANDLE_TERM_INST(N, OPC, CLASS) OPC = N,
324#define   LAST_TERM_INST(N)             TermOpsEnd = N+1
325#include "llvm/Instruction.def"
326  };
327
328  enum BinaryOps {
329#define  FIRST_BINARY_INST(N)             BinaryOpsBegin = N,
330#define HANDLE_BINARY_INST(N, OPC, CLASS) OPC = N,
331#define   LAST_BINARY_INST(N)             BinaryOpsEnd = N+1
332#include "llvm/Instruction.def"
333  };
334
335  enum MemoryOps {
336#define  FIRST_MEMORY_INST(N)             MemoryOpsBegin = N,
337#define HANDLE_MEMORY_INST(N, OPC, CLASS) OPC = N,
338#define   LAST_MEMORY_INST(N)             MemoryOpsEnd = N+1
339#include "llvm/Instruction.def"
340  };
341
342  enum CastOps {
343#define  FIRST_CAST_INST(N)             CastOpsBegin = N,
344#define HANDLE_CAST_INST(N, OPC, CLASS) OPC = N,
345#define   LAST_CAST_INST(N)             CastOpsEnd = N+1
346#include "llvm/Instruction.def"
347  };
348
349  enum OtherOps {
350#define  FIRST_OTHER_INST(N)             OtherOpsBegin = N,
351#define HANDLE_OTHER_INST(N, OPC, CLASS) OPC = N,
352#define   LAST_OTHER_INST(N)             OtherOpsEnd = N+1
353#include "llvm/Instruction.def"
354  };
355private:
356  // Shadow Value::setValueSubclassData with a private forwarding method so that
357  // subclasses cannot accidentally use it.
358  void setValueSubclassData(unsigned short D) {
359    Value::setValueSubclassData(D);
360  }
361  unsigned short getSubclassDataFromValue() const {
362    return Value::getSubclassDataFromValue();
363  }
364
365  void setHasMetadataHashEntry(bool V) {
366    setValueSubclassData((getSubclassDataFromValue() & ~HasMetadataBit) |
367                         (V ? HasMetadataBit : 0));
368  }
369
370  friend class SymbolTableListTraits<Instruction, BasicBlock>;
371  void setParent(BasicBlock *P);
372protected:
373  // Instruction subclasses can stick up to 15 bits of stuff into the
374  // SubclassData field of instruction with these members.
375
376  // Verify that only the low 15 bits are used.
377  void setInstructionSubclassData(unsigned short D) {
378    assert((D & HasMetadataBit) == 0 && "Out of range value put into field");
379    setValueSubclassData((getSubclassDataFromValue() & HasMetadataBit) | D);
380  }
381
382  unsigned getSubclassDataFromInstruction() const {
383    return getSubclassDataFromValue() & ~HasMetadataBit;
384  }
385
386  Instruction(Type *Ty, unsigned iType, Use *Ops, unsigned NumOps,
387              Instruction *InsertBefore = 0);
388  Instruction(Type *Ty, unsigned iType, Use *Ops, unsigned NumOps,
389              BasicBlock *InsertAtEnd);
390  virtual Instruction *clone_impl() const = 0;
391
392};
393
394// Instruction* is only 4-byte aligned.
395template<>
396class PointerLikeTypeTraits<Instruction*> {
397  typedef Instruction* PT;
398public:
399  static inline void *getAsVoidPointer(PT P) { return P; }
400  static inline PT getFromVoidPointer(void *P) {
401    return static_cast<PT>(P);
402  }
403  enum { NumLowBitsAvailable = 2 };
404};
405
406} // End llvm namespace
407
408#endif
409