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>

2 files changed, 22 insertions, 1 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
diff --git a/docs/syscall_descriptions_syntax.md b/docs/syscall_descriptions_syntax.md
index 38b31caa1..7f4033079 100644
--- a/docs/syscall_descriptions_syntax.md
+++ b/docs/syscall_descriptions_syntax.md
@@ -28,7 +28,7 @@ rest of the type-options are type-specific:
 "intN"/"intptr": an integer without a particular meaning, type-options:
 	optional range of values (e.g. "5:10", or "100:200"),
 	optionally followed by an alignment parameter
-"flags": a set of flags, type-options:
+"flags": a set of values, type-options:
 	reference to flags description (see below), underlying int type (e.g. "int32")
 "array": a variable/fixed-length array, type-options:
 	type of elements, optional size (fixed "5", or ranged "5:10", boundaries inclusive)
@@ -351,3 +351,5 @@ that can be used as any other syscall in a description file. These pseudo
 system calls expand to literal C code and can perform user-defined
 custom actions. You can find some examples in
 [executor/common_linux.h](../executor/common_linux.h).
+
+Also see [tips](syscall_descriptions.md#tips) on writing good descriptions.