docs: add explanation of flags type

* docs: add explanation of flags type
* Apply suggestions from code review
Co-authored-by: Marco Elver <marco.elver@gmail.com>

1 files changed, 19 insertions, 0 deletions

diff --git a/docs/syscall_descriptions.md b/docs/syscall_descriptions.md
index b25c343e1..a7faaf3c3 100644
--- a/docs/syscall_descriptions.md
+++ b/docs/syscall_descriptions.md
@@ -148,6 +148,9 @@ use this name for flags in descriptions as well. The same for structs, unions,
 fields, etc. For syscall variants, use the command name after the `$` sign.
 For example, `fcntl$F_GET_RW_HINT`, `ioctl$FIOCLEX`, `setsockopt$SO_TIMESTAMP`.
 
+If you need to describe several variants of the same kernel struct, the naming
+convention understood by `syz-check` is `<ORIGINAL_KERNEL_NAME>_some_suffix`.
+
 <div id="ordering"/>
 
 ### Resources for syscall ordering
@@ -187,6 +190,22 @@ operand value interception and list of typical magic values.
 
 Note: some values for flags may be undocumented only as an oversight. These values should be added to descriptions.
 
+<div id="flags"/>
+
+### Flags/enums
+
+The `flags` type is used for all of:
+
+ - sets of mutually exclusive values, where only one of them should be chosen (like C enum);
+ - sets of bit flags, where multiple values can be combined with bitwise OR (like mmap flags);
+ - any combination of the above.
+
+The fuzzer has logic to distinguish enums and bit flags, and generates values
+accordingly. So the general guideline is just to enumerate the meaningful values
+in `flags` without adding any "special" values to "help" the current fuzzer logic.
+When/if the fuzzer logic changes/improves, these manual additions may become
+unnecessary, or, worse, interfere with the fuzzer ability to generate good values.
+
 ## Description compilation internals
 
 The process of compiling the textual syscall descriptions into machine-usable