1 # Syscall descriptions 2 3 `syzkaller` uses declarative description of syscalls to generate, mutate, minimize, serialize and deserialize programs (sequences of syscalls). 4 Below you can see (hopefully self-explanatory) excerpt from the description: 5 6 ``` 7 open(file filename, flags flags[open_flags], mode flags[open_mode]) fd 8 read(fd fd, buf buffer[out], count len[buf]) len[buf] 9 close(fd fd) 10 open_mode = S_IRUSR, S_IWUSR, S_IXUSR, S_IRGRP, S_IWGRP, S_IXGRP, S_IROTH, S_IWOTH, S_IXOTH 11 ``` 12 13 The description is contained in `sys/linux/*.txt` files. 14 For example see the [sys/linux/sys.txt](/sys/linux/sys.txt) file. 15 16 ## Syntax 17 18 The description of the syntax can be found [here](syscall_descriptions_syntax.md). 19 20 ## Code generation 21 22 Textual syscall descriptions are translated into code used by `syzkaller`. 23 This process consists of 2 steps. 24 The first step is extraction of values of symbolic constants from Linux sources using `syz-extract` utility. 25 `syz-extract` generates a small C program that includes kernel headers referenced by `include` directives, 26 defines macros as specified by `define` directives and prints values of symbolic constants. 27 Results are stored in `.const` files, one per arch. 28 For example, [sys/linux/tty.txt](/sys/linux/tty.txt) is translated into [sys/linux/tty_amd64.const](/sys/linux/tty_amd64.const). 29 30 The second step is generation of Go code for syzkaller. 31 This step uses syscall descriptions and the const files generated during the first step. 32 You can see a result in [sys/linux/gen/amd64.go](/sys/linux/gen/amd64.go) and in [executor/syscalls.h](/executor/syscalls.h). 33 34 ## Describing new system calls 35 36 This section describes how to extend syzkaller to allow fuzz testing of a new system call; 37 this is particularly useful for kernel developers who are proposing new system calls. 38 39 First, add a declarative description of the new system call to the appropriate file: 40 - Various `sys/linux/<subsystem>.txt` files hold system calls for particular kernel 41 subsystems, for example `bpf` or `socket`. 42 - [sys/linux/sys.txt](/sys/linux/sys.txt) holds descriptions for more general system calls. 43 - An entirely new subsystem can be added as a new `sys/linux/<new>.txt` file. 44 45 The description of the syntax can be found [here](syscall_descriptions_syntax.md). 46 47 If the subsystem is present in the mainline kernel, run `make extract TARGETOS=linux SOURCEDIR=$KSRC` 48 with `$KSRC` set to the location of a kernel source tree. This will generate const files. 49 Not, that this will overwrite `.config` file you have in `$KSRC`. 50 51 If the subsystem is not present in the mainline kernel, then you need to manually run `syz-extract` binary: 52 ``` 53 make bin/syz-extract 54 bin/syz-extract -os linux -arch $ARCH -sourcedir "$LINUX" -builddir "$LINUXBLD" <new>.txt 55 ``` 56 `$ARCH` is one of `amd64`, `386` `arm64`, `arm`, `ppc64le`. 57 If the subsystem is supported on several architectures, then run `syz-extract` for each arch. 58 `$LINUX` should point to kernel source checkout, which is configured for the corresponding arch (i.e. you need to run `make someconfig && make` there first). 59 If the kernel was built into a separate directory (with `make O=...`) then also set `$LINUXBLD` to the location of the build directory. 60 61 Then, run `make generate` which will update generated code. 62 63 Rebuild syzkaller (`make clean all`) to force use of the new system call definitions. 64 65 Optionally, adjust the `enable_syscalls` configuration value for syzkaller to specifically target the new system calls. 66 67 In order to partially auto-generate system call descriptions you can use [headerparser](headerparser_usage.md). 68
