sys: add GEMINI.md

A basic set of instructions for writing syzkaller descriptions.

1 files changed, 67 insertions, 0 deletions

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.