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 */
32enum 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 */
70enum 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 */
89typedef u1 InstructionWidth;
90
91/*
92 * Opcode control flow flags, used by the verifier and JIT.
93 */
94typedef u1 OpcodeFlags;
95enum 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 */
114struct 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 */
124extern InstructionInfoTables gDexOpcodeInfo;
125
126/*
127 * Holds the contents of a decoded instruction.
128 */
129struct 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 */
142DEX_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 */
153size_t dexGetWidthFromInstruction(const u2* insns);
154
155/*
156 * Returns the flags for the specified opcode.
157 */
158DEX_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 */
167DEX_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 */
175DEX_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 */
184DEX_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 */
193void dexDecodeInstruction(const u2* insns, DecodedInstruction* pDec);
194
195#endif  // LIBDEX_INSTRUTILS_H_
196