1==== Overview ====
2
3The assembly source code is produced from custom python-based templates.
4All the architecture-specific template files are concatenated to create
5one big python script. This generated python script is then executed to
6produced the final assembly file. The template syntax is:
7 * Lines starting with % are python code. They will be copied as-is to
8   the script (without the %) and thus executed during the generation.
9 * Other lines are text, and they are essentially syntax sugar for
10   out.write('''(line text)''') and thus they write the main output.
11 * Within a text line, $ can be used insert variables from code.
12
13The final assembly sources are written into the "out" directory, where
14they are picked up by the Android build system.
15
16The best way to become familiar with the interpreter is to look at the
17generated files in the "out" directory.
18
19
20==== Instruction file format ====
21
22The assembly instruction files are simply fragments of assembly sources.
23The starting label will be provided by the generation tool, as will
24declarations for the segment type and alignment.
25
26The following global variables are generally available:
27
28  $opcode - opcode name, e.g. "OP_NOP"
29  $opnum - opcode number, e.g. 0 for OP_NOP
30  $handler_size_bytes - max size of an instruction handler, in bytes
31  $handler_size_bits - max size of an instruction handler, log 2
32
33Both C and assembly sources will be passed through the C pre-processor,
34so you can take advantage of C-style comments and preprocessor directives
35like "#define".
36
37The generation tool does *not* print a warning if your instructions
38exceed "handler-size", but the VM will abort on startup if it detects an
39oversized handler.  On architectures with fixed-width instructions this
40is easy to work with, on others this you will need to count bytes.
41
42
43==== Using C constants from assembly sources ====
44
45The file "art/runtime/asm_support.h" has some definitions for constant
46values, structure sizes, and struct member offsets.  The format is fairly
47restricted, as simple macros are used to massage it for use with both C
48(where it is verified) and assembly (where the definitions are used).
49
50If a constant in the file becomes out of sync, the VM will log an error
51message and abort during startup.
52
53
54==== Rebuilding ====
55
56If you change any of the source file fragments, you need to rebuild the
57combined source files in the "out" directory.  Make sure the files in
58"out" are editable, then:
59
60    $ cd mterp
61    $ ./gen_mterp.py
62
63The ultimate goal is to have the build system generate the necessary
64output files without requiring this separate step, but we're not yet
65ready to require Python in the build.
66
67==== Interpreter Control ====
68
69The mterp fast interpreter achieves much of its performance advantage
70over the C++ interpreter through its efficient mechanism of
71transitioning from one Dalvik bytecode to the next.  Mterp for ARM targets
72uses a computed-goto mechanism, in which the handler entrypoints are
73located at the base of the handler table + (opcode * 128).
74
75In normal operation, the dedicated register rIBASE
76(r8 for ARM, edx for x86) holds a mainHandlerTable.  If we need to switch
77to a mode that requires inter-instruction checking, rIBASE is changed
78to altHandlerTable.  Note that this change is not immediate.  What is actually
79changed is the value of curHandlerTable - which is part of the interpBreak
80structure.  Rather than explicitly check for changes, each thread will
81unconditionally refresh rIBASE at backward branches, exception throws and returns.
82