Name |
Date |
Size |
#Lines |
LOC |
||
---|---|---|---|---|---|---|
.. | - | - | ||||
README.md | D | 06-Sep-2024 | 3.5 KiB | 91 | 60 | |
api_analysis.py | D | 06-Sep-2024 | 19.1 KiB | 471 | 314 | |
api_analysis_test.py | D | 06-Sep-2024 | 25 KiB | 745 | 657 | |
custom_syscalls.json | D | 06-Sep-2024 | 6.4 KiB | 307 | 306 | |
extract_syscalls_from_kernel_src.py | D | 06-Sep-2024 | 8 KiB | 312 | 205 | |
gen_kernel_syscalls_mapping.py | D | 06-Sep-2024 | 2.5 KiB | 94 | 54 | |
gen_kernel_syscalls_numbers.py | D | 06-Sep-2024 | 2.2 KiB | 87 | 46 | |
gen_kernel_syscalls_symbols.py | D | 06-Sep-2024 | 964 | 38 | 13 | |
gen_kernel_syscalls_translation.py | D | 06-Sep-2024 | 7.5 KiB | 230 | 138 | |
kernel_api_arm.json | D | 06-Sep-2024 | 300.5 KiB | 10,818 | 10,173 | |
kernel_api_arm64.json | D | 06-Sep-2024 | 159 KiB | 9,208 | 9,208 | |
kernel_api_riscv64.json | D | 06-Sep-2024 | 158.7 KiB | 9,188 | 9,188 | |
kernel_api_x86.json | D | 06-Sep-2024 | 316.8 KiB | 11,421 | 10,729 | |
kernel_api_x86_64.json | D | 06-Sep-2024 | 182.2 KiB | 10,535 | 10,535 | |
kernel_syscalls.json | D | 06-Sep-2024 | 141.5 KiB | 8,314 | 8,313 |
README.md
1# System calls translation 2 3The pipeline uses kernel as a source of truth. Unfortunately, all other options proved to be either 4incomplete or imprecise. 5 6System call names, numbers and entry points are extracted from kernel sources. 7 8*TODO: consider extracting names, numbers and entry points from vmlinux!* 9 10System call parameters are extracted from vmlinux DWARF. 11 12Automatic translation happens between system calls with the same entry point if entry point 13parameters are compatible. 14 15### Checkout kernel 16 17Assume the kernel checkout is at `$KERNEL_SRC`. 18 19### Extract system calls names, numbers and entry points 20 21This is specific for architectures. The script does extraction for `arm`, `arm64`, `x86`, 22`x86_64` and `riscv64`. 23 24In addition, the script checks entry point prototypes and marks those without parameters. System 25calls without parameters do not need compatibility checking (and they don't have corresponding 26`__do_sys_*` functions, see "Extract system calls parameters"). 27 28Unfortunately, extracting full info about parameters from prototypes is a bad idea. Most 29architectures have specific calling conventions for system calls, so even the number of parameters 30may vary. But, hopefully, "no parameters" means the same thing everywhere. 31 32```./extract_syscalls_from_kernel_src.py $KERNEL_SRC/common > ./kernel_syscalls.json``` 33 34### Extract system calls parameters 35 36Entry point `sys_foo` is a function that gets system call parameters in a form of `struct ptregs*`. 37`SYSCALL_DEFINEx` macro unpacks parameters and calls implementation function `__do_sys_foo` which 38receives parameters normally. 39 40`__do_sys_foo` functions are usually inlined and do not exist in symbols table. However, DWARF 41should still have these functions. 42 43To get parameters info in our common .json API form, do: 44 45Build kernel for arch with debug info. Assume this is `VMLINUX_RISCV64`. 46 47Extract the list of `__do_sys_*` functions for arch: 48 49```./gen_kernel_syscalls_symbols.py riscv64 ./kernel_syscalls.json > ./symbols_riscv64.txt``` 50 51Use `dwarf_reader` to get .json API info for these functions: 52 53```dwarf_reader --filter=symbols_riscv64.txt VMLINUX_RISCV64 > ./kernel_api_riscv64.json``` 54 55### Generate system calls translation 56 57Now there should be files like: 58 59``` 60kernel_syscalls.json (common system calls info) 61kernel_api_riscv64.json (src arch system calls API) 62kernel_api_x86_64.json (dst arch system calls API) 63custom_syscalls.json (translation exceptions) 64``` 65 66Run the script to generate code for translation function: 67 68``` 69gen_kernel_syscalls_translation.py riscv64 x86_64 \ 70> kernel_api/gen_syscall_emulation_riscv64_to_x86_64-inl.h 71``` 72 73### Generate system call numbers 74 75Each guest architecture must provide two files for system call numbers: 761. `gen_syscall_numbers_arch.h`, which contains constants for that guest architecture's syscall 77 numbers. This file is generated by `gen_kernel_syscalls_numbers.py`. 782. `gen_syscall_numbers.cc`, which contains function definitions for mapping between host and guest 79 syscall numbers. This file is generated by `gen_kernel_syscalls_mapping.py`. 80 81Both of these files are generated from `kernel_syscalls.json` and should be regenerated whenever 82that file changes. The command-line arguments for both scripts are `<src-arch> <dst-arch> 83<path-to-kernel_syscalls.json>`: 84 85``` 86./gen_kernel_syscalls_numbers.py riscv64 x86_64 ./kernel_syscalls.json \ 87> ../../guest_os_primitives/riscv64/include/berberis/guest_os_primitives/gen_syscall_numbers_arch.h 88./gen_kernel_syscalls_mapping.py riscv64 x86_64 ./kernel_syscalls.json \ 89> ../../guest_os_primitives/riscv64/gen_syscall_numbers.cc 90``` 91