sys: update README to describe the new 2-step generation process

1 files changed, 35 insertions, 22 deletions

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/<subsystem>.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/<new>.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/<new>.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_<ARCH>.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/<new>.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.
-