From 5b6bfb32b0e8cdac3af1c7d655e2d2b281a90544 Mon Sep 17 00:00:00 2001 From: Dmitry Vyukov Date: Thu, 9 Jul 2020 11:42:24 +0200 Subject: docs: add explanation of flags type * docs: add explanation of flags type * Apply suggestions from code review Co-authored-by: Marco Elver --- docs/syscall_descriptions.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'docs/syscall_descriptions.md') 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 `_some_suffix`. +
### 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. +
+ +### 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 -- cgit mrf-deployment