1 2# Ahead Of Time Compilation 3 4This document describes Ahead Of Time compilation in Ark VM. 5 6## File format 7 8AOT file has `.an` extension and it is a valid ELF file. 9 10### ELF layout 11 12At the current moment it has following segments and sections layout: 13 14| Segment | Flags | Sections | 15|---------|-------|----------| 16| LAOD | R | .hash .dynstr .dynsym .aot | 17| LAOD | R-W | .aot_got | 18| LAOD | R-E | .text | 19| DYNAMIC | R-W | .dynamic | 20| LAOD | R-W | .dynamic | 21 22- `.hash`, `.dynstr`, `.dynsym`, `.dynamic` - Standard ELF sections. 23- `.text` - Contains compiled native code. Code of each compiled method is placed sequentially into this section with 24special alignment, mostly it is 16 bytes (see `CODE_ALIGNMENT` in `libpandabase/utils/arch.h` file). 25- `.aot_got` - Contains table of the runtime's entrypoint handlers. Must be placed right before `.text` section. 26- `.aot` - Contains all information that describes AOT structure. All used structures can be found at 27`compiler/aot/aot_headers.h`. 28 29To access to the `.text` and `.aot` sections from AOT loader following symbols are defined: 30- `code` - points to the start of `.text` section 31- `code_end` - points to the end of `.text` section 32- `aot` - points to the start of `.aot` section 33- `aot_end` - points to the end of `.aot` section 34 35### AOT headers 36 37`.aot` section contains combination of the following structures: 38- `AotHeader` - This header describes main information, such as version, file name string, command line string, 39offsets to other headers, etc. 40- `PandaFileHeader` - Describes corresponding panda file. 41- `ClassHeader` - Describes single class. 42- `MethodHeader` - Describe single method. 43 44More details about AOT headers you can find in `<src>/compiler/aot/aot_headers.h`. 45 46Classes and methods are uniquely identified (inside one file) by their panda file id (`panda_file::File::EntityId`), 47therefore compiled Ark bytecode file must be bit by bit equal to the file loaded in runtime. 48 49## Special `.aot_got` section 50 51There is one strict rule: `.text` section must be placed right after `.aot_got` section, and this special section is 52filled with appropriate data during AOT file loading at runtime. This data allows compiler's codegen to generate 53runtime calls and work with [PLT](../compiler/docs/plt.md) resolvers. 54 55``` 56========= .aot_got ======== 57; PLT-GOT table, see the PLT link above 58 . . . 59; Three PLT resolvers addresses 60-NN-24: PLT InitClass Resolver 61-NN-16: PLT Class Resolver 62-NN-08: PLT VirtualCall Resolver 63; start of entrypoint table 64-NN: address of handler 0, NN = N * 8 65 . . . 66-16: address of handler N-1 67-08: address of handler N 68========== .text ========== 6900: 70 . . . 71``` 72 73## Runtime calls 74 75Knowing offset to the `.aot_got` table, codegen calculates offset to the corresponding entrypoint and make load 76instruction from this address. Example for arm64: 77 78``` 79========= .aot_got ======== 80 . . . 81; start of entrypoint table 82-NN: address of handler 0, NN = N * 8 83 . . . 84-16: address of handler N-1 85-08: address of handler N <----- 86========== .text ========== | 8700: | 88 . . . ; First funcion header | 89; Function executable code | 9048: | 91 . . . | 9280: adr x30, #-88 -------------- ; Put to the x30 address of last entry in the table 9384: ldr x30, [x30] ; Load address of the entrypoint handler 9488: blr x30 ; Jump to the handler 95 . . . 96``` 97 98<sup>*</sup> Aarch64 `adr` instruction has restriction to the maximum offset, thus in case of big offset `adrp` 99instruction is used. 100 101## PLT Resolvers 102 103In AOT mode for `CallStatic`, `CallVirtual`, and opcodes related to `Class` resolving there exists a special way 104to cache pointers which are recieved from runtime calls - PLT resolvers. They are described in a separate [doc](../compiler/docs/plt.md). 105 106## String resolution 107 108AOT-compiled code may use special PLT-slots to load resolved string without runtime calls. 109Refer to [doc](../compiler/docs/aot_resolve_string.md) for details. 110 111## Usage 112 113#### Compilation 114 115`ark_aot` tool aims to compile input panda files into the single AOT file that can be consumed by 116Panda runtime. 117 118ark_aot has following options: 119 120- `--panda-files` - list of input panda files to be compiled 121- `--output` - path to the output AOT file (default is `out.an`) 122- `--location` - path where panda files are actually stored in the device 123- `--arch` - target architecture: arm, arm64, x86, x86_64 (default is arm64) 124 125Paoc uses Panda runtime inside, thus, runtime's options are also may be specified. If paoc is ran not from the build 126directory then path to `arkstdlib.abc` should be specified via `--boot-panda-files` option. 127 128Additional information could be found [here](../compiler/docs/paoc.md). 129 130#### AOT in Panda 131 132To pass AOT file to the Panda `--aot-file` option should be specified: 133 134`ark --aot-file file.an file.abc _GLOBAL::main` 135 136- `--panda-files` parameter specifies list of `ark_aot` or `ark` necessary input panda files which is not within `--boot-panda-files` 137 138Example of usage: 139 140`ark_aot --panda-files=file1.abc:file2.abc --output file.an` 141 142Panda file shall be passed with same name as it was compiled by ark_aot, otherwise AOT loader won't find the file because 143of different names. To avoid this restriction `--location` ark_aot's option may be used. 144 145Example: 146``` 147Good: 148 ark_aot --panda-files file.abc --output file.an 149 ark --aot-file file.an file.abc _GLOBAL::main 150 151Bad ("file.abc" != "/local/data/tmp/file.abc"): 152 ark_aot --panda-files file.abc --output file.an 153 ark --aot-file file.an /local/data/tmp/file.abc _GLOBAL::main 154 155Solution: 156 ark_aot --panda-files file.abc --output file.an --location /local/data/tmp 157 ark --aot-file file.an /local/data/tmp/file.abc _GLOBAL::main 158``` 159 160#### AOT debugging 161 162There is tool, named `ark_aotdump`, that aims to dump content of AOT files in yaml format. It can print compiled code 163as disassembly(`--show-code disasm`) or in base64 binary(`--show-code binary`) 164 165Example of usage: 166 167`ark_aotdump --show-code disasm file.an` 168 169Sometimes it is interesting to see what code had generated for specific IR instruction, to do so there is an option 170`--compiler-disasm-dump` that dumps disassembler, IR instruction and all generated native code for it after each compiler optimization pass. 171Disassembler creates files with following name format `disasm-<METHOD_NAME>.txt`. IR dumps are written into files with name `<METHOD_NAME>.ir` 172 in `ir_dump` folder if option `--compiler-dump-folder` is not set. Also option `--compiler-dump-bytecode` 173enables printing byte code instruction after ir instruction in dump ir. There is one more option `--compiler-dump-final` which enables 174to dump ir only after last (codegen) pass. All of these options are used at compile time. 175 176Example of usage: 177 178`ark_aot --compiler-disasm-dump --panda-files file.abc --output file.an` 179 180`ark_disasm` prints full IR disassembler. 181 182Example of usage: 183 184`ark_disasm <input panda-bytecode file> <output file>` 185