diff options
| -rw-r--r-- | libdex/InstrUtils.h | 7 | ||||
| -rw-r--r-- | libdex/OpCode.h | 47 | ||||
| -rw-r--r-- | opcode-gen/README.txt | 74 |
3 files changed, 79 insertions, 49 deletions
diff --git a/libdex/InstrUtils.h b/libdex/InstrUtils.h index c7f57bc9e..840e83b7e 100644 --- a/libdex/InstrUtils.h +++ b/libdex/InstrUtils.h @@ -30,11 +30,8 @@ * of the table. This isn't necessary with some compilers, which use an * integer width appropriate for the number of enum values.) * - * If you add or delete a format, you have to change some or all of: - * - this enum - * - the switch inside dexDecodeInstruction() in InstrUtils.c - * - the switch inside dumpInstruction() in DexDump.c - * - the switch inside dvmCompilerMIR2LIR() in CodegenDriver.c + * See the file opcode-gen/README.txt for information about updating + * opcodes and instruction formats. */ typedef unsigned char InstructionFormat; enum InstructionFormat { diff --git a/libdex/OpCode.h b/libdex/OpCode.h index 4c5ae5220..0d0078334 100644 --- a/libdex/OpCode.h +++ b/libdex/OpCode.h @@ -20,55 +20,14 @@ * IMPORTANT NOTE: The contents of this file are mostly generated * automatically by the opcode-gen tool. Any edits to the generated * sections will get wiped out the next time the tool is run. + * + * See the file opcode-gen/README.txt for information about updating + * opcodes and instruction formats. */ #ifndef _LIBDEX_OPCODE #define _LIBDEX_OPCODE -/* - * If you add, delete, or renumber instructions, you need to change things - * in various places. Renumbering really only affects the "unused" opcodes, - * which are given explicit enumeration values to make it easier to find - * the places in the code that need to be updated when making changes -- - * if you replace "OP_UNUSED_2D" and neglect to update a switch statement, - * the compiler will complain about an unknown value. - * - * Bytecode definition and generated code: - * - * - update bytecode.txt in the opcode-gen directory - * - run opcode-gen/regen-all; this will regenerate a number of tables, - * definitions, and declarations in the code, including the ones - * immediately below in this file. - * - * Opcode definitions and attributes: - * - update the instruction decoder in InstrUtils.c if you added a new - * instruction format. - * - update the instruction format list in InstrUtils.h, if necessary - * - update the parallel definitions in the class dalvik.bytecode.Opcodes - * - * Interpreter: - * - implement/update the instruction in C in mterp/c/... - * - verify new code by running with "dalvik.vm.execution-mode = - * int:portable" or "-Xint:portable" - * - implement/update the instruction in ARM in mterp/armv5/... - * - verify by enabling ARM handler for that instruction in mterp config - * and running int:fast as above - * - repeat for other platforms (x86, ...) - * (see notes in mterp/ReadMe.txt for rebuilding instructions) - * - * Verifier / optimizer: - * - update some stuff in analysis/Optimize.c, analysis/DexVerify.c, - * and/or analysis/CodeVerify.c as needed - * - verify by running with verifier enabled (it's on by default) - * - * Tools: - * - update dexdump/DexDump.c if an instruction format has changed - * - * Note: The Dalvik VM tests (in the tests subdirectory) provide a convenient - * way to test most of the above without doing any rebuilds. In particular, - * test 003-omnibus-opcodes will exercise most of the opcodes. - */ - /* the highest opcode value of a valid Dalvik opcode, plus one */ #define kNumDalvikInstructions 256 diff --git a/opcode-gen/README.txt b/opcode-gen/README.txt new file mode 100644 index 000000000..a210842d8 --- /dev/null +++ b/opcode-gen/README.txt @@ -0,0 +1,74 @@ +# Copyright (C) 2010 The Android Open Source Project +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +--------------------------------------------------------------------- +Notes on updating the sets of defined opcodes and instruction formats +--------------------------------------------------------------------- + +########## + +If you want to add, delete, or change opcodes: + +* Update the file bytecode.txt, in this directory. + +* Run the regen-all script, in this directory. This will regenerate a + number of tables, definitions, and declarations in the code, in + dalvik/dx, dalvik/libdex, and libcore/dalvik. + +* Implement/update the opcode in C in vm/mterp/c/... + * Verify new code by running with "dalvik.vm.execution-mode = int:portable" + or "-Xint:portable". + +* Implement/update the instruction in assembly in vm/mterp/{arm*,x86*}/... + * Verify by enabling the assembly (e.g. ARM) handler for that instruction + in mterp/config-* and running "int:fast" as above. + +* Implement/update the instruction in + vm/compiler/codegen/{arm,x86}/CodegenDriver.c. + +* Rebuild the interpreter code. See the notes in vm/mterp/ReadMe.txt for + details. + +* Look in the directory vm/analysis at the files CodeVerify.c, + DexVerify.c, and Optimize.c. You may need to update them to account + for your changes. + * If you change anything here, be sure to try running the system with + the verifier enabled (which is in fact the default). + +########## + +If you want to add, delete, or change instruction formats: + +This is a more manual affair than changing opcodes. + +* Update the file bytecode.txt, and run regen-all, as per above. + +* Update the instruction format list in libdex/InstrUtils.h. + +* Update dexDecodeInstruction() in libdex/InstrUtils.c. + +* Update dumpInstruction() and its helper code in dexdump/DexDump.c. + +* Update the switch inside dvmCompilerMIR2LIR() in + vm/compiler/codegen/{arm,x86}/CodegenDriver.c. (There may be other + architectures to deal with too.) + +########## + +Testing your work: + +The Dalvik VM tests (in the vm/tests directory) provide a convenient +way to test most of the above without doing any rebuilds. In +particular, test 003-omnibus-opcodes will exercise most of the +opcodes. |