1 /*
2  * Copyright (C) 2008 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 /*
18  * Dalvik instruction utility functions.
19  */
20 #ifndef LIBDEX_INSTRUTILS_H_
21 #define LIBDEX_INSTRUTILS_H_
22 
23 #include "DexFile.h"
24 #include "DexOpcodes.h"
25 
26 /*
27  * Possible instruction formats associated with Dalvik opcodes.
28  *
29  * See the file opcode-gen/README.txt for information about updating
30  * opcodes and instruction formats.
31  */
32 enum InstructionFormat {
33     kFmt00x = 0,    // unknown format (also used for "breakpoint" opcode)
34     kFmt10x,        // op
35     kFmt12x,        // op vA, vB
36     kFmt11n,        // op vA, #+B
37     kFmt11x,        // op vAA
38     kFmt10t,        // op +AA
39     kFmt20bc,       // [opt] op AA, thing@BBBB
40     kFmt20t,        // op +AAAA
41     kFmt22x,        // op vAA, vBBBB
42     kFmt21t,        // op vAA, +BBBB
43     kFmt21s,        // op vAA, #+BBBB
44     kFmt21h,        // op vAA, #+BBBB00000[00000000]
45     kFmt21c,        // op vAA, thing@BBBB
46     kFmt23x,        // op vAA, vBB, vCC
47     kFmt22b,        // op vAA, vBB, #+CC
48     kFmt22t,        // op vA, vB, +CCCC
49     kFmt22s,        // op vA, vB, #+CCCC
50     kFmt22c,        // op vA, vB, thing@CCCC
51     kFmt22cs,       // [opt] op vA, vB, field offset CCCC
52     kFmt30t,        // op +AAAAAAAA
53     kFmt32x,        // op vAAAA, vBBBB
54     kFmt31i,        // op vAA, #+BBBBBBBB
55     kFmt31t,        // op vAA, +BBBBBBBB
56     kFmt31c,        // op vAA, string@BBBBBBBB
57     kFmt35c,        // op {vC,vD,vE,vF,vG}, thing@BBBB
58     kFmt35ms,       // [opt] invoke-virtual+super
59     kFmt3rc,        // op {vCCCC .. v(CCCC+AA-1)}, thing@BBBB
60     kFmt3rms,       // [opt] invoke-virtual+super/range
61     kFmt51l,        // op vAA, #+BBBBBBBBBBBBBBBB
62     kFmt35mi,       // [opt] inline invoke
63     kFmt3rmi,       // [opt] inline invoke/range
64 };
65 
66 /*
67  * Types of indexed reference that are associated with opcodes whose
68  * formats include such an indexed reference (e.g., 21c and 35c).
69  */
70 enum InstructionIndexType {
71     kIndexUnknown = 0,
72     kIndexNone,         // has no index
73     kIndexVaries,       // "It depends." Used for throw-verification-error
74     kIndexTypeRef,      // type reference index
75     kIndexStringRef,    // string reference index
76     kIndexMethodRef,    // method reference index
77     kIndexFieldRef,     // field reference index
78     kIndexInlineMethod, // inline method index (for inline linked methods)
79     kIndexVtableOffset, // vtable offset (for static linked methods)
80     kIndexFieldOffset   // field offset (for static linked fields)
81 };
82 
83 /*
84  * Instruction width implied by an opcode's format; a value in the
85  * range 0 to 5. Note that there are special "pseudo-instructions"
86  * which are used to encode switch and data tables, and these don't
87  * have a fixed width. See dexGetWidthFromInstruction(), below.
88  */
89 typedef u1 InstructionWidth;
90 
91 /*
92  * Opcode control flow flags, used by the verifier and JIT.
93  */
94 typedef u1 OpcodeFlags;
95 enum OpcodeFlagsBits {
96     kInstrCanBranch     = 1,        // conditional or unconditional branch
97     kInstrCanContinue   = 1 << 1,   // flow can continue to next statement
98     kInstrCanSwitch     = 1 << 2,   // switch statement
99     kInstrCanThrow      = 1 << 3,   // could cause an exception to be thrown
100     kInstrCanReturn     = 1 << 4,   // returns, no additional statements
101     kInstrInvoke        = 1 << 5,   // a flavor of invoke
102 };
103 
104 /*
105  * Struct that includes a pointer to each of the opcode information
106  * tables.
107  *
108  * Note: We use "u1*" here instead of the names of the enumerated
109  * types to guarantee that elements don't use much space. We hold out
110  * hope for a standard way to indicate the size of an enumerated type
111  * that works for both C and C++, but in the mean time, this will
112  * suffice.
113  */
114 struct InstructionInfoTables {
115     u1*                formats;    /* InstructionFormat elements */
116     u1*                indexTypes; /* InstructionIndexType elements */
117     OpcodeFlags*       flags;
118     InstructionWidth*  widths;
119 };
120 
121 /*
122  * Global InstructionInfoTables struct.
123  */
124 extern InstructionInfoTables gDexOpcodeInfo;
125 
126 /*
127  * Holds the contents of a decoded instruction.
128  */
129 struct DecodedInstruction {
130     u4      vA;
131     u4      vB;
132     u8      vB_wide;        /* for kFmt51l */
133     u4      vC;
134     u4      arg[5];         /* vC/D/E/F/G in invoke or filled-new-array */
135     Opcode  opcode;
136     InstructionIndexType indexType;
137 };
138 
139 /*
140  * Return the instruction width of the specified opcode, or 0 if not defined.
141  */
dexGetWidthFromOpcode(Opcode opcode)142 DEX_INLINE size_t dexGetWidthFromOpcode(Opcode opcode)
143 {
144     assert((u4) opcode < kNumPackedOpcodes);
145     return gDexOpcodeInfo.widths[opcode];
146 }
147 
148 /*
149  * Return the width of the specified instruction, or 0 if not defined.  Also
150  * works for special OP_NOP entries, including switch statement data tables
151  * and array data.
152  */
153 size_t dexGetWidthFromInstruction(const u2* insns);
154 
155 /*
156  * Returns the flags for the specified opcode.
157  */
dexGetFlagsFromOpcode(Opcode opcode)158 DEX_INLINE OpcodeFlags dexGetFlagsFromOpcode(Opcode opcode)
159 {
160     assert((u4) opcode < kNumPackedOpcodes);
161     return gDexOpcodeInfo.flags[opcode];
162 }
163 
164 /*
165  * Returns true if the given flags represent a goto (unconditional branch).
166  */
dexIsGoto(OpcodeFlags flags)167 DEX_INLINE bool dexIsGoto(OpcodeFlags flags)
168 {
169     return (flags & (kInstrCanBranch | kInstrCanContinue)) == kInstrCanBranch;
170 }
171 
172 /*
173  * Return the instruction format for the specified opcode.
174  */
dexGetFormatFromOpcode(Opcode opcode)175 DEX_INLINE InstructionFormat dexGetFormatFromOpcode(Opcode opcode)
176 {
177     assert((u4) opcode < kNumPackedOpcodes);
178     return (InstructionFormat) gDexOpcodeInfo.formats[opcode];
179 }
180 
181 /*
182  * Return the instruction index type for the specified opcode.
183  */
dexGetIndexTypeFromOpcode(Opcode opcode)184 DEX_INLINE InstructionIndexType dexGetIndexTypeFromOpcode(Opcode opcode)
185 {
186     assert((u4) opcode < kNumPackedOpcodes);
187     return (InstructionIndexType) gDexOpcodeInfo.indexTypes[opcode];
188 }
189 
190 /*
191  * Decode the instruction pointed to by "insns".
192  */
193 void dexDecodeInstruction(const u2* insns, DecodedInstruction* pDec);
194 
195 #endif  // LIBDEX_INSTRUTILS_H_
196