From afc0c4d4e22f5c4d432b74914ab068f54f93bf7e Mon Sep 17 00:00:00 2001 From: Aleksandr Nogikh Date: Fri, 30 Jan 2026 18:00:49 +0000 Subject: sys: add GEMINI.md A basic set of instructions for writing syzkaller descriptions. --- sys/GEMINI.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 sys/GEMINI.md (limited to 'sys') diff --git a/sys/GEMINI.md b/sys/GEMINI.md new file mode 100644 index 000000000..a4a0603a6 --- /dev/null +++ b/sys/GEMINI.md @@ -0,0 +1,67 @@ +## Prerequisites + +Syzkaller uses a special DSL called syzlang to express kernel interfaces. +Consult docs/syscall_descriptions.md and docs/syscall_descriptions_syntax.md +to learn more details. + +The descriptions are located in sys/OS_NAME/ directories. +* Descriptions themselves are in .txt files. +* .txt.const files are generated from .txt files by running `make extract`. + +## Writing descriptions for Linux + +First ensure that you are given a path to a Linux kernel checkout. +We strive to write descriptions based on the latest linux-next tag. + +When adding new syscalls and structures, try to follow the style +of existing descriptions. In particular, try to use existing types +and flags when possible. + +First, find the definitions of syscalls and their arguments in the +kernel source code. +* DO NOT rely on the syscalls(7) man page, it is often outdated. +* DO NOT search for syscall definitions on the internet. +* DO grep kernel source code, especially the include/uapi folder. + +Then, find the right file to add new descriptions. In many cases, +you will find such a file by looking at where related system calls +are described. +* IMPORTANT: DO NOT create new files unless absolutely necessary. + Often, you can put the descriptions to more generic files. + +For integer fields that look like bitmasks, try to find the flags +they could take and define them as flags in syzlang, listing all +possible const names. Note that sometimes you might have to add an +include directive. Look for inspiration to other .txt files in sys/linux. + +For integer fiels that look like file handles, try to find more details +about them and see whether they can be defined as resources. Try to find +existing resources in sys/linux/ that can be used, most likely they are +already there. + +If the integer field is used for padding, ensure that you define it as const. + +For other integer fields, explore how they are used in the Linux kernel source +code to see whether there are clear indications of the range of values they are +supposed to take. + +After adding descriptions, you should run `make extract` to extract +the newly introduced constants into the `sys/linux/` directory. + +It should only be run on latest `linux-next` tag this way: +`$ CI=true ./tools/syz-env make extract SOURCEDIR=$PATH_TO_LINUX_CHECKOUT` + +If `make extract` fails, it might indicate that you are missing some includes. + +At the end, help the user review the results by indicating the locations +in the Linux kernel source code where the new syscalls and structures +were found. + +## Testing + +Then, run `make generate` to verify that the descriptions are correct. + +Also, do not forget to run `make format` to ensure that the descriptions +are formatted correctly. + +Remember that these commands must be run inside of the syzkaller checkout. -- cgit mrf-deployment