Calculation of immediate operand in logical immediate instructions was done wrong...
[dyninst.git] / instructionAPI / h / Instruction.h
1 /*
2  * See the dyninst/COPYRIGHT file for copyright information.
3  *
4  * We provide the Paradyn Tools (below described as "Paradyn")
5  * on an AS IS basis, and do not warrant its validity or performance.
6  * We reserve the right to update, modify, or discontinue this
7  * software at any time.  We shall have no obligation to supply such
8  * updates or modifications or any other form of support to you.
9  *
10  * By your use of Paradyn, you understand and agree that we (or any
11  * other person or entity with proprietary rights in Paradyn) are
12  * under no obligation to provide either maintenance services,
13  * update services, notices of latent defects, or correction of
14  * defects for Paradyn.
15  *
16  * This library is free software; you can redistribute it and/or
17  * modify it under the terms of the GNU Lesser General Public
18  * License as published by the Free Software Foundation; either
19  * version 2.1 of the License, or (at your option) any later version.
20  *
21  * This library is distributed in the hope that it will be useful,
22  * but WITHOUT ANY WARRANTY; without even the implied warranty of
23  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
24  * Lesser General Public License for more details.
25  *
26  * You should have received a copy of the GNU Lesser General Public
27  * License along with this library; if not, write to the Free Software
28  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
29  */
30
31 #if !defined(INSTRUCTION_H)
32 #define INSTRUCTION_H
33
34
35 #include <vector>
36 #include <set>
37 #include <list>
38 #include "Expression.h"
39 #include "Operation.h"
40 #include "Operand.h"
41 #include "InstructionCategories.h"
42
43 #include "util.h"
44
45 namespace Dyninst
46 {
47   namespace InstructionAPI
48   {
49       class InstructionDecoder;
50     /// The %Instruction class is a generic instruction representation that contains operands,
51     /// read/write semantic information about those operands, and information about
52     /// what other registers and memory locations are affected by the operation the instruction performs.
53     ///
54     /// The purpose of an %Instruction object is to join an %Operation with a sequence of %Operands, and provide
55     /// an interface for some common summary analyses (namely, the read/write sets, memory access information,
56     /// and control flow information).
57     ///
58     /// The %Operation contains knowledge about its mnemonic and sufficient semantic
59     /// details to answer the following questions:
60     ///   - What %Operands are read/written?
61     ///   - What registers are implicitly read/written?
62     ///   - What memory locations are implicitly read/written?
63     ///   - What are the possible control flow successors of this instruction?
64     ///
65     /// Each %Operand is an AST built from %RegisterAST and %Immediate leaves.  For each %Operand, you may determine:
66     ///   - Registers read
67     ///   - Registers written
68     ///   - Whether memory is read or written
69     ///   - Which memory addresses are read or written, given the state of all relevant registers
70     ///
71     /// Instructions should be constructed from an \c unsigned \c char* pointing to machine language, using the
72     /// %InstructionDecoder class.  See InstructionDecoder for more details.
73     ///
74     class Instruction
75     {
76         /// Component version information corresponding to \c libInstructionAPI.so.(major).(minor).(maintenance)
77         /// Note that \c maintenance may be absent from the binary (in which case, it will be zero in the interface).
78
79         INSTRUCTION_EXPORT static void version(int& major, int& minor, int& maintenance);
80       union raw_insn_T
81       {
82 #if defined(__powerpc__) || defined(__powerpc64__)
83         unsigned int small_insn;
84 #else
85         uintptr_t small_insn;
86 #endif
87         unsigned char* large_insn;
88       };
89     public:
90         friend class InstructionDecoder_x86;
91         friend class InstructionDecoder_power;
92         friend class InstructionDecoder_aarch64;
93
94         struct CFT
95         {
96             Expression::Ptr target;
97             bool isCall;
98             bool isIndirect;
99             bool isConditional;
100             bool isFallthrough;
101             CFT(Expression::Ptr t, bool call, bool indir, bool cond, bool ft) :
102                     target(t), isCall(call), isIndirect(indir), isConditional(cond), isFallthrough(ft) {}
103         };
104       /// \param what Opcode of the instruction
105       /// \param operandSource Contains the %Expressions to be transformed into %Operands
106       /// \param size Contains the number of bytes occupied by the corresponding machine instruction
107       /// \param raw Contains a pointer to the buffer from which this instruction object
108       /// was decoded.
109       ///
110       /// Construct an %Instruction from an %Operation and a collection of %Expressions.  This
111       /// method is not intended to be used except by the %InstructionDecoder class, which serves as a
112       /// factory class for producing %Instruction objects.  While an %Instruction object may be built
113       /// "by hand" if desired, using the decoding interface ensures that the operation and operands
114       /// are a sensible combination, and that the size reported is based on the actual size of a legal
115       /// encoding of the machine instruction represented.
116       /// In the course of constructing an %Instruction, the %Expressions in \c operandSource
117       /// will be transformed to %Operand objects.  This transformation will map the semantic information about
118       /// which operands are read and written
119       /// in the %Operation object \c what to the value computations in \c operandSource.
120
121       INSTRUCTION_EXPORT Instruction(Operation::Ptr what, size_t size, const unsigned char* raw,
122                                      Dyninst::Architecture arch);
123       INSTRUCTION_EXPORT Instruction();
124
125       INSTRUCTION_EXPORT virtual ~Instruction();
126
127       INSTRUCTION_EXPORT Instruction(const Instruction& o);
128       INSTRUCTION_EXPORT const Instruction& operator=(const Instruction& rhs);
129
130
131       /// \return The %Operation used by the %Instruction
132       ///
133       /// See Operation for details of the %Operation interface.
134       INSTRUCTION_EXPORT const Operation& getOperation() const;
135
136       /// The vector \c operands has the instruction's operands appended to it
137       /// in the same order that they were decoded.
138       INSTRUCTION_EXPORT void getOperands(std::vector<Operand>& operands) const;
139
140       /// The \c getOperand method returns the operand at position \c index, or
141       /// an empty operand if \c index does not correspond to a valid operand in this
142       /// instruction.
143       INSTRUCTION_EXPORT Operand getOperand(int index) const;
144
145       /// Returns a pointer to the buffer from which this instruction
146       /// was decoded.
147       INSTRUCTION_EXPORT unsigned char rawByte(unsigned int index) const;
148
149       /// Returns the size of the corresponding machine instruction, in bytes.
150       INSTRUCTION_EXPORT size_t size() const;
151
152       /// Returns a pointer to the raw byte representation of the corresponding
153       /// machine instruction.
154       INSTRUCTION_EXPORT const void* ptr() const;
155
156       /// \param regsWritten Insert the set of registers written by the instruction into \c regsWritten.
157       ///
158       /// The list of registers returned in \c regsWritten includes registers that are explicitly written as destination
159       /// operands (like the destination of a move).  It also includes registers
160       /// that are implicitly written (like the
161       /// stack pointer in a push or pop instruction).  It does not include
162       /// any registers used only in computing the effective address of a write.
163       /// \c pop \c *eax, for example, writes to \c esp, reads \c esp, and reads \c eax,
164       /// but despite the fact that \c *eax is the destination operand, \c eax is not
165       /// itself written.
166       ///
167       /// For both the write set and the read set (below), it is possible to determine whether a register
168       /// is accessed implicitly or explicitly by examining the %Operands.  An explicitly accessed register appears
169       /// as an operand that is written or read; also, any registers used in any address calculations are explicitly
170       /// read.  Any element of the write set or read set that is not explicitly written or read is implicitly
171       /// written or read.
172
173       INSTRUCTION_EXPORT void getWriteSet(std::set<RegisterAST::Ptr>& regsWritten) const;
174
175       /// \param regsRead Insert the set of registers read by the instruction into \c regsRead.
176       ///
177       /// If an operand is used to compute an effective address, the registers
178       /// involved are read but not written, regardless of the effect on the operand.
179       INSTRUCTION_EXPORT void getReadSet(std::set<RegisterAST::Ptr>& regsRead) const;
180
181       /// \param candidate Subexpression to search for among the values read by this %Instruction object.
182       ///
183       /// Returns true if \c candidate is read by this %Instruction.
184       INSTRUCTION_EXPORT bool isRead(Expression::Ptr candidate) const;
185
186       /// \param candidate Subexpression to search for among the values written by this %Instruction object.
187       ///
188       /// Returns true if \c candidate is written by this %Instruction.
189       INSTRUCTION_EXPORT bool isWritten(Expression::Ptr candidate) const;
190
191
192       /// \return Returns true if the instruction reads at least one memory address as data.
193       ///
194       /// If any operand containing a  %Dereference object is read, the instruction
195       /// reads the memory at that address.
196       /// Also, on platforms where a stack pop is guaranteed to read memory,
197       /// \c readsMemory will return true for a pop operation.
198       INSTRUCTION_EXPORT bool readsMemory() const;
199
200       /// \return Returns true if the instruction writes at least one memory address.
201       ///
202       /// If any operand containing a  %Dereference object is written, the instruction
203       /// writes the memory at that address.
204       /// Also, on platforms where a stack push is guaranteed to write memory,
205       /// \c writesMemory will return true for a push operation.
206       INSTRUCTION_EXPORT bool writesMemory() const;
207
208       /// \param memAccessors Addresses read by this instruction are inserted into \c memAccessors
209       ///
210       /// The addresses read are in the form of %Expressions, which may be evaluated once all of the
211       /// registers that they use have had their values set.
212       /// Note that this method returns ASTs representing address computations, and not address accesses.  For instance,
213       /// an instruction accessing memory through a register dereference would return a %Expression tree containing
214       /// just the register that determines the address being accessed, not a tree representing a dereference of that register.
215       INSTRUCTION_EXPORT void getMemoryReadOperands(std::set<Expression::Ptr>& memAccessors) const;
216
217       /// \param memAccessors Addresses written by this instruction are inserted into \c memAccessors
218       ///
219       /// The addresses written are in the same form as those returned by \c getMemoryReadOperands above.
220       INSTRUCTION_EXPORT void getMemoryWriteOperands(std::set<Expression::Ptr>& memAccessors) const;
221
222       /// \return An expression evaluating to the non-fallthrough control flow targets, if any, of this instruction.
223       ///
224       /// When called on an explicitly control-flow altering instruction, returns the
225       /// non-fallthrough control flow destination.  When called on any other instruction,
226       /// returns \c NULL.
227       ///
228       /// For direct absolute branch instructions, \c getControlFlowTarget will return an immediate value.
229       /// For direct relative branch instructions, \c getControlFlowTarget will return the expression
230       /// \c PC + offset.
231       /// In the case of indirect branches and calls, it returns a dereference of a register (or possibly
232       /// a dereference of a more complicated expression).  In this case,
233       /// data flow analysis will often allow the determination of the possible targets of the
234       /// instruction.  We do not do analysis beyond the single-instruction level
235       /// in the %Instruction API; if other code performs this type of analysis,
236       /// it may update the information in the %Dereference object using the setValue method in the %Expression interface.
237       /// More details about this may be found in Expression and Dereference.
238       INSTRUCTION_EXPORT Expression::Ptr getControlFlowTarget() const;
239
240       /// \return False if control flow will unconditionally go to the result of
241       /// \c getControlFlowTarget after executing this instruction.
242       INSTRUCTION_EXPORT bool allowsFallThrough() const;
243
244       /// \return The instruction as a string of assembly language
245       ///
246       /// \c format is principally a helper function; %Instructions are meant to be written to
247       /// output streams via \c operator<<.  \c format is included in the public interface for
248       /// diagnostic purposes.
249       INSTRUCTION_EXPORT std::string format(Address addr = 0) const;
250
251       /// Returns true if this %Instruction object is valid.  Invalid instructions indicate that
252       /// an %InstructionDecoder has reached the end of its assigned range, and that decoding should terminate.
253       INSTRUCTION_EXPORT bool isValid() const;
254
255       /// Returns true if this %Instruction object represents a legal instruction, as specified by the architecture
256       /// used to decode this instruction.
257       INSTRUCTION_EXPORT bool isLegalInsn() const;
258
259       INSTRUCTION_EXPORT Architecture getArch() const;
260
261       /// ALPHA: Returns the category that an instruction falls into.  This feature is presently incomplete, and we welcome feedback
262       /// on ways to extend it usefully.
263       ///
264       /// Currently, the valid categories are c_CallInsn, c_ReturnInsn, c_BranchInsn, c_CompareInsn,
265       /// and c_NoCategory, as defined in %InstructionCategories.h.
266       INSTRUCTION_EXPORT InsnCategory getCategory() const;
267
268       typedef std::list<CFT>::const_iterator cftConstIter;
269       INSTRUCTION_EXPORT cftConstIter cft_begin() const {
270           return m_Successors.begin();
271       }
272         INSTRUCTION_EXPORT cftConstIter cft_end() const {
273             return m_Successors.end();
274         }
275
276
277       typedef boost::shared_ptr<Instruction> Ptr;
278         public:
279           //Should be private, but we're working around some compilers mis-using the 'friend' declaration.
280       void appendOperand(Expression::Ptr e, bool isRead, bool isWritten) const;
281     private:
282       void decodeOperands() const;
283       void addSuccessor(Expression::Ptr e, bool isCall, bool isIndirect, bool isConditional, bool isFallthrough) const;
284       void copyRaw(size_t size, const unsigned char* raw);
285       Expression::Ptr makeReturnExpression() const;
286       mutable std::list<Operand> m_Operands;
287       Operation::Ptr m_InsnOp;
288       bool m_Valid;
289       raw_insn_T m_RawInsn;
290       unsigned int m_size;
291       Architecture arch_decoded_from;
292       mutable std::list<CFT> m_Successors;
293       static int numInsnsAllocated;
294
295     };
296   };
297 };
298
299
300
301 #endif //!defined(INSTRUCTION_H)