• Home
Name
Date
Size
#Lines
LOC

..--

README.mdD06-Sep-20243.5 KiB9160

api_analysis.pyD06-Sep-202419.1 KiB471314

api_analysis_test.pyD06-Sep-202425 KiB745657

custom_syscalls.jsonD06-Sep-20246.4 KiB307306

extract_syscalls_from_kernel_src.pyD06-Sep-20248 KiB312205

gen_kernel_syscalls_mapping.pyD06-Sep-20242.5 KiB9454

gen_kernel_syscalls_numbers.pyD06-Sep-20242.2 KiB8746

gen_kernel_syscalls_symbols.pyD06-Sep-2024964 3813

gen_kernel_syscalls_translation.pyD06-Sep-20247.5 KiB230138

kernel_api_arm.jsonD06-Sep-2024300.5 KiB10,81810,173

kernel_api_arm64.jsonD06-Sep-2024159 KiB9,2089,208

kernel_api_riscv64.jsonD06-Sep-2024158.7 KiB9,1889,188

kernel_api_x86.jsonD06-Sep-2024316.8 KiB11,42110,729

kernel_api_x86_64.jsonD06-Sep-2024182.2 KiB10,53510,535

kernel_syscalls.jsonD06-Sep-2024141.5 KiB8,3148,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