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