opcode-gen/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 ---------------------------------------------------------------------
  16 Notes on updating the sets of defined opcodes and instruction formats
  17 ---------------------------------------------------------------------
  18
  19 ##########
  20
  21 If 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
  51 If you want to add, delete, or change instruction formats:
  52
  53 This 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
  69 Testing your work:
  70
  71 The Dalvik VM tests (in the vm/tests directory) provide a convenient
  72 way to test most of the above without doing any rebuilds. In
  73 particular, test 003-omnibus-opcodes will exercise most of the
  74 opcodes.