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