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