README.txt
1# Copyright (C) 2010 The Android Open Source Project
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7# http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14
15---------------------------------------------------------------------
16Notes on updating the sets of defined opcodes and instruction formats
17---------------------------------------------------------------------
18
19##########
20
21If you want to add, delete, or change opcodes:
22
23* Update the file bytecode.txt, in this directory.
24
25* Run the regen-all script, in this directory. This will regenerate a
26 number of tables, definitions, and declarations in the code, in
27 dalvik/dx, dalvik/libdex, and libcore/dalvik.
28
29* Implement/update the opcode in C in vm/mterp/c/...
30 * Verify new code by running with "dalvik.vm.execution-mode = int:portable"
31 or "-Xint:portable".
32
33* Implement/update the instruction in assembly in vm/mterp/{arm*,x86*}/...
34 * Verify by enabling the assembly (e.g. ARM) handler for that instruction
35 in mterp/config-* and running "int:fast" as above.
36
37* Implement/update the instruction in
38 vm/compiler/codegen/{arm,x86}/CodegenDriver.c.
39
40* Rebuild the interpreter code. See the notes in vm/mterp/ReadMe.txt for
41 details.
42
43* Look in the directory vm/analysis at the files CodeVerify.c,
44 DexVerify.c, and Optimize.c. You may need to update them to account
45 for your changes.
46 * If you change anything here, be sure to try running the system with
47 the verifier enabled (which is in fact the default).
48
49##########
50
51If you want to add, delete, or change instruction formats:
52
53This is a more manual affair than changing opcodes.
54
55* Update the file bytecode.txt, and run regen-all, as per above.
56
57* Update the instruction format list in libdex/InstrUtils.h.
58
59* Update dexDecodeInstruction() in libdex/InstrUtils.c.
60
61* Update dumpInstruction() and its helper code in dexdump/DexDump.c.
62
63* Update the switch inside dvmCompilerMIR2LIR() in
64 vm/compiler/codegen/{arm,x86}/CodegenDriver.c. (There may be other
65 architectures to deal with too.)
66
67##########
68
69Testing your work:
70
71The Dalvik VM tests (in the vm/tests directory) provide a convenient
72way to test most of the above without doing any rebuilds. In
73particular, test 003-omnibus-opcodes will exercise most of the
74opcodes.
75