docs: small fixes

9 files changed, 92 insertions, 51 deletions

diff --git a/docs/setup.md b/docs/setup.md
index 933db69cb..26c06062a 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -27,3 +27,5 @@ $ ./bin/syz-manager -config=my.cfg
 ```
 
 More information on the configuration file format is available [here](configuration.md).
+
+See [this page](troubleshooting.md) for troubleshooting tips.
diff --git a/docs/setup_linux-host_android-device_arm64-kernel.md b/docs/setup_linux-host_android-device_arm64-kernel.md
index 699671155..0be9cb9e8 100644
--- a/docs/setup_linux-host_android-device_arm64-kernel.md
+++ b/docs/setup_linux-host_android-device_arm64-kernel.md
@@ -39,3 +39,6 @@ bin/syz-manager:  Mach-O 64-bit executable x86_64
 ```
 
  - Start `syz-manager -config adb.cfg` as usual.
+
+If you get issues after `syz-manager` starts, consider running it with the `-debug` flag.
+Also see [this page](troubleshooting.md) for troubleshooting tips.
diff --git a/docs/setup_linux-host_isolated.md b/docs/setup_linux-host_isolated.md
index 7f26efd75..8cff007f6 100644
--- a/docs/setup_linux-host_isolated.md
+++ b/docs/setup_linux-host_isolated.md
@@ -106,3 +106,6 @@ Run syzkaller manager:
 ``` bash
 ./bin/syz-manager -config=my.cfg
 ```
+
+If you get issues after `syz-manager` starts, consider running it with the `-debug` flag.
+Also see [this page](troubleshooting.md) for troubleshooting tips.
diff --git a/docs/setup_linux-host_qemu-vm_arm64-kernel.md b/docs/setup_linux-host_qemu-vm_arm64-kernel.md
index 2c363dafc..3ace6b68b 100644
--- a/docs/setup_linux-host_qemu-vm_arm64-kernel.md
+++ b/docs/setup_linux-host_qemu-vm_arm64-kernel.md
@@ -160,3 +160,6 @@ A sample config file that exercises the required options are shown below. Modify
 ```
 
 At this point, you should be able to visit `localhost:56700` and view the results of the fuzzing.
+
+If you get issues after `syz-manager` starts, consider running it with the `-debug` flag.
+Also see [this page](troubleshooting.md) for troubleshooting tips.
diff --git a/docs/setup_ubuntu-host_odroid-c2-board_arm64-kernel.md b/docs/setup_ubuntu-host_odroid-c2-board_arm64-kernel.md
index 899beaaa8..01366f036 100644
--- a/docs/setup_ubuntu-host_odroid-c2-board_arm64-kernel.md
+++ b/docs/setup_ubuntu-host_odroid-c2-board_arm64-kernel.md
@@ -330,3 +330,6 @@ Now start syzkaller:
 ``` bash
 ./bin/syz-manager -config=odroid.cfg
 ```
+
+If you get issues after `syz-manager` starts, consider running it with the `-debug` flag.
+Also see [this page](troubleshooting.md) for troubleshooting tips.
diff --git a/docs/setup_ubuntu-host_qemu-vm_x86-64-kernel.md b/docs/setup_ubuntu-host_qemu-vm_x86-64-kernel.md
index 41e87ca88..85af3f8ee 100644
--- a/docs/setup_ubuntu-host_qemu-vm_x86-64-kernel.md
+++ b/docs/setup_ubuntu-host_qemu-vm_x86-64-kernel.md
@@ -232,3 +232,6 @@ Run syzkaller manager:
 ```
 
 Now syzkaller should be running, you can check manager status with your web browser at `127.0.0.1:56741`.
+
+If you get issues after `syz-manager` starts, consider running it with the `-debug` flag.
+Also see [this page](troubleshooting.md) for troubleshooting tips.
diff --git a/docs/syscall_descriptions_syntax.md b/docs/syscall_descriptions_syntax.md
index 83bbe2566..a0ba540fa 100644
--- a/docs/syscall_descriptions_syntax.md
+++ b/docs/syscall_descriptions_syntax.md
@@ -1,59 +1,68 @@
 # Syscall descriptions syntax
 
 Pseudo-formal grammar of syscall description:
+
 ```
-	syscallname "(" [arg ["," arg]*] ")" [type]
-	arg = argname type
-	argname = identifier
-	type = typename [ "[" type-options "]" ]
-	typename = "const" | "intN" | "intptr" | "flags" | "array" | "ptr" |
-			"buffer" | "string" | "strconst" | "filename" |
-			"len" | "bytesize" | "vma" | "proc"
-	type-options = [type-opt ["," type-opt]]
+syscallname "(" [arg ["," arg]*] ")" [type]
+arg = argname type
+argname = identifier
+type = typename [ "[" type-options "]" ]
+typename = "const" | "intN" | "intptr" | "flags" | "array" | "ptr" |
+	   "buffer" | "string" | "strconst" | "filename" | "len" |
+	   "bytesize" | "vma" | "proc"
+type-options = [type-opt ["," type-opt]]
 ```
+
 common type-options include:
+
 ```
-	"opt" - the argument is optional (like mmap fd argument, or accept peer argument)
+"opt" - the argument is optional (like mmap fd argument, or accept peer argument)
 ```
+
 rest of the type-options are type-specific:
+
 ```
-	"const": integer constant, type-options:
-		value, underlying type (one if "intN", "intptr")
-	"intN"/"intptr": an integer without a particular meaning, type-options:
-		optional range of values (e.g. "5:10", or "-100:200")
-	"flags": a set of flags, type-options:
-		reference to flags description (see below)
-	"array": a variable/fixed-length array, type-options:
-		type of elements, optional size (fixed "5", or ranged "5:10", boundaries inclusive)
-	"ptr": a pointer to an object, type-options:
-		type of the object; direction (in/out/inout)
-	"buffer": a pointer to a memory buffer (like read/write buffer argument), type-options:
-		direction (in/out/inout)
-	"string": a zero-terminated memory buffer (no pointer indirection implied), type-options:
-		either a string value in quotes for constant strings (e.g. "foo"),
-		or a reference to string flags,
-		optionally followed by a buffer size (string values will be padded with \x00 to that size)
-	"filename": a file/link/dir name, no pointer indirection implied, in most cases you want `ptr[in, filename]`
-	"fileoff": offset within a file
-	"len": length of another field (for array it is number of elements), type-options:
-		argname of the object
-	"bytesize": similar to "len", but always denotes the size in bytes, type-options:
-		argname of the object
-	"vma": a pointer to a set of pages (used as input for mmap/munmap/mremap/madvise), type-options:
-		optional number of pages (e.g. vma[7]), or a range of pages (e.g. vma[2-4])
-	"proc": per process int (see description below), type-options:
-		underlying type, value range start, how many values per process
-	"text16", "text32", "text64": machine code of the specified bitness
+"const": integer constant, type-options:
+	value, underlying type (one if "intN", "intptr")
+"intN"/"intptr": an integer without a particular meaning, type-options:
+	optional range of values (e.g. "5:10", or "-100:200")
+"flags": a set of flags, type-options:
+	reference to flags description (see below)
+"array": a variable/fixed-length array, type-options:
+	type of elements, optional size (fixed "5", or ranged "5:10", boundaries inclusive)
+"ptr": a pointer to an object, type-options:
+	type of the object; direction (in/out/inout)
+"buffer": a pointer to a memory buffer (like read/write buffer argument), type-options:
+	direction (in/out/inout)
+"string": a zero-terminated memory buffer (no pointer indirection implied), type-options:
+	either a string value in quotes for constant strings (e.g. "foo"),
+	or a reference to string flags,
+	optionally followed by a buffer size (string values will be padded with \x00 to that size)
+"filename": a file/link/dir name, no pointer indirection implied, in most cases you want `ptr[in, filename]`
+"fileoff": offset within a file
+"len": length of another field (for array it is number of elements), type-options:
+	argname of the object
+"bytesize": similar to "len", but always denotes the size in bytes, type-options:
+	argname of the object
+"vma": a pointer to a set of pages (used as input for mmap/munmap/mremap/madvise), type-options:
+	optional number of pages (e.g. vma[7]), or a range of pages (e.g. vma[2-4])
+"proc": per process int (see description below), type-options:
+	underlying type, value range start, how many values per process
+"text16", "text32", "text64": machine code of the specified bitness
 ```
+
 flags/len/flags also have trailing underlying type type-option when used in structs/unions/pointers.
 
 Flags are described as:
+
 ```
-	flagname = const ["," const]*
+flagname = const ["," const]*
 ```
+
 or for string flags as:
+
 ```
-	flagname = "\"" literal "\"" ["," "\"" literal "\""]*
+flagname = "\"" literal "\"" ["," "\"" literal "\""]*
 ```
 
 ## Ints
@@ -80,22 +89,25 @@ example_struct {
 ## Structs
 
 Structs are described as:
+
 ```
-	structname "{" "\n"
-		(fieldname type "\n")+
-	"}"
+structname "{" "\n"
+	(fieldname type "\n")+
+"}"
 ```
-Structs can have trailing attributes "packed" and "align_N",
-they are specified in square brackets after the struct.
+
+Structs can have trailing attributes `packed` and `align_N`, they are specified in square brackets after the struct.
 
 ## Unions
 
 Unions are described as:
+
 ```
-	unionname "[" "\n"
-		(fieldname type "\n")+
-	"]"
+unionname "[" "\n"
+	(fieldname type "\n")+
+"]"
 ```
+
 Unions can have a trailing "varlen" attribute (specified in square brackets after the union),
 which means that union length is not maximum of all option lengths,
 but rather length of a particular chosen option.
@@ -103,11 +115,14 @@ but rather length of a particular chosen option.
 ## Resources
 
 Custom resources are described as:
+
 ```
-	resource identifier "[" underlying_type "]" [ ":" const ("," const)* ]
+resource identifier "[" underlying_type "]" [ ":" const ("," const)* ]
 ```
+
 `underlying_type` is either one of `int8`, `int16`, `int32`, `int64`, `intptr` or another resource.
 Resources can then be used as types. For example:
+
 ```
 resource fd[int32]: 0xffffffffffffffff, AT_FDCWD, 1000000
 resource sock[fd]
@@ -121,6 +136,7 @@ listen(fd sock, backlog int32)
 ## Length
 
 You can specify length of a particular field in struct or a named argument by using `len` and `bytesize` types, for example:
+
 ```
 write(fd fd, buf buffer[in], count len[buf]) len[buf]
 
@@ -136,6 +152,7 @@ To denote the length of a field in N-byte words use `bytesizeN`, possible values
 
 To denote the length of the parent struct, you can use `len[parent, int8]`.
 To denote the length of the higher level parent when structs are embedded into one another, you can specify the type name of the particular parent:
+
 ```
 struct s1 {
     f0      len[s2]  # length of s2
@@ -159,5 +176,6 @@ As a result the executor number `n` will get values in the `[20000 + n * 4, 2000
 
 ## Misc
 
-Description files also contain `include` directives that refer to Linux kernel header files, `incdir` directives that refer to custom Linux kernel header directories 
-and `define` directives that define symbolic constant values. See the following section for details.
+Description files also contain `include` directives that refer to Linux kernel header files,
+`incdir` directives that refer to custom Linux kernel header directories 
+and `define` directives that define symbolic constant values.
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index da041ca1b..4e78ceb80 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -25,6 +25,10 @@ Here are some things to check if there are problems running syzkaller.
       `VMLINUX` is the vmlinux file, as per the `vmlinux` config value), to confirm
       that symbols for the kernel are available.
 
+ - Use the `-debug` command line option to make syzkaller print all possible debug output,
+   from both the `syz-manager` top-level program and the `syz-fuzzer` instances. With this option
+   syzkaller will only run one VM instance.
+
  - Use the `-v N` command line option to increase the amount of logging output, from both
    the `syz-manager` top-level program and the `syz-fuzzer` instances (which go to the
    output files in the `crashes` subdirectory of the working directory). Higher values of
@@ -41,4 +45,6 @@ Here are some things to check if there are problems running syzkaller.
        In this case, running the `syz-execprog` test with the `-nobody=0` option fixes the problem,
        so the main configuration needs to be updated to set `dropprivs` to `false`.
 
-If none of the above helps, file a bug on [the bug tracker](https://github.com/google/syzkaller/issues) or ask us directly on the syzkaller@googlegroups.com mailing list.
+If none of the above helps, file a bug on [the bug tracker](https://github.com/google/syzkaller/issues)
+or ask us directly on the syzkaller@googlegroups.com mailing list.
+Please include syzkaller commit id that you use and `syz-manager` output with `-debug` flag enabled if applicable.
diff --git a/docs/usage.md b/docs/usage.md
index 93794a643..e639258ed 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -33,4 +33,4 @@ Check [here](linux_kernel_reporting_bugs.md) for the instructions on how to repo
 
 ## Other
 
-[How to connect several managers via Hub](connecting_several_managers.md)
+[How to connect several managers via Hub](hub.md)