Home | History | Annotate | Download | only in opcode-gen
      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.
     75