Clean up the opcode maintenance instructions.

Change-Id: Ic9d7fcfd234116099ef510e4339a9af0bc3fcb1d

1 files changed, 74 insertions, 0 deletions

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.