From 78553d22479fff5aefbe097d1643b7c7f347ac27 Mon Sep 17 00:00:00 2001 From: Dmitry Vyukov Date: Fri, 26 Aug 2016 15:20:36 +0200 Subject: sys: update README to describe the new 2-step generation process --- sys/README.md | 57 +++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 35 insertions(+), 22 deletions(-) (limited to 'sys') diff --git a/sys/README.md b/sys/README.md index 9e8b90230..6eb12f81f 100644 --- a/sys/README.md +++ b/sys/README.md @@ -70,9 +70,23 @@ but rather length of a particular chosen option (such unions can't be part of a because their size is not statically known). Description files also contain `include` directives that refer to Linux kernel header files -and `define` directives that define symbolic constant values. See +and `define` directives that define symbolic constant values. See the following section for details. -## Fuzzing new system calls +## Code generation + +Textual syscall descriptions are translated into code used by `syzkaller`. +This process consists of 2 steps. The first step is extraction of values of symbolic +constants from Linux sources using `syz-extract` utility. +`syz-extract` generates a small C program that includes kernel headers referenced +by `include` directives, defines macros as specified by `define` directives and +prints values of symbolic constants. Results are stored in `.const` files, one per arch. +For example, (sys/tty.txt)[sys/tty.txt] is translated into (sys/tty_amd64.const)[sys/tty_amd64.const]. + +The second step is generation of Go code for syzkaller. This step uses syscall descriptions +and the const files generated during the first step. You can see a result in (sys/sys_amd64.go)[sys/sys_amd64.go] +and in (executor/syscalls.h)[executor/syscalls.h]. + +## Describing new system calls This section describes how to extend syzkaller to allow fuzz testing of a new system call; this is particularly useful for kernel developers who are proposing new system calls. @@ -81,31 +95,30 @@ First, add a declarative description of the new system call to the appropriate f - Various `sys/.txt` files hold system calls for particular kernel subsystems, for example `bpf` or `socket`. - [sys/sys.txt](sys/sys.txt) holds descriptions for more general system calls. - - An entirely new subsystem can be added as a new `sys/.txt` file, but needs - the `generate` target in the [Makefile](Makefile) to be updated to include it. + - An entirely new subsystem can be added as a new `sys/.txt` file. -The description format is described [above](#syscall-description) and in the -master [sys/sys.txt](sys/sys.txt) file. +The description format is described [above](#syntax). -Next, run `make LINUX=$KSRC generate` with `KSRC` set to the location of a kernel -source tree (for up to date kernel headers); if the kernel was built into a separate -directory (with `make O=...`) then also set `LINUXBLD=$KBLD` to the location of the -build directory. +If the subsystem is present in the mainline kernel, add the new txt file to `extract.sh` +file and run `make extract LINUX=$KSRC` with `KSRC` set to the location of a kernel +source tree. This will generate const files. -This will re-create the following source code files: - - `sys/sys.go`: Code to initialize a Go [data structure](sys/decl.go) with information - about all of the available system calls. - - `prog/consts.go`: Constant definitions for all the named constants that are - mentioned in the system call descriptions. - - `sys/sys_.go`: Data structure to map syzkaller internal syscall IDs to - (per-architecture) kernel syscall numbers. - - `executor/syscalls.h`: Constant definitions (in C) for all system call numbers. +If the subsystem is not present in the mainline kernel, then you need to manually +run `syz-extract` binary: +``` +make bin/syz-extract +bin/syz-extract -arch $ARCH -linux "$LINUX" -linuxbld "$LINUXBLD" sys/.txt +``` +`$ARCH` is one of `amd64`, `arm64`, `ppc64le`. If the subsystem is supported on several architectures, +then run `syz-exctact` for each arch. +`$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). If the kernel was built into a separate +directory (with `make O=...`) then also set `$LINUXBLD` to the location of the +build directory. -If there are problems with this step, run `bin/syz-sysgen` directly and add -the use `-v=5` flag to show more details of the generation process. +Then, run `make generate` which will update generated code. Rebuild syzkaller (`make clean all`) to force use of the new system call definitions. -Finally, adjust the `enable_syscalls` configuration value for syzkaller to specifically target the +Optionally, adjust the `enable_syscalls` configuration value for syzkaller to specifically target the new system calls. - -- cgit mrf-deployment