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==== Interpreter Control ====
55
56The nterp fast interpreter achieves much of its performance advantage
57over the C++ "switch" interpreter through its efficient mechanism of
58transitioning from one Dalvik bytecode to the next.  Nterp uses a computed-goto
59mechanism, in which the handler entrypoints are located at the base of the
60handler table + (opcode * 128).
61
62In normal operation, the dedicated register rIBASE
63(r8 for ARM, edx for x86) holds a mainHandlerTable.  If we need to switch
64to a mode that requires inter-instruction checking, rIBASE is changed
65to altHandlerTable.  Note that this change is not immediate.  What is actually
66changed is the value of curHandlerTable - which is part of the interpBreak
67structure.  Rather than explicitly check for changes, each thread will
68unconditionally refresh rIBASE at backward branches, exception throws and returns.
69