Update README.md

1 files changed, 27 insertions, 2 deletions

diff --git a/README.md b/README.md
index 8341a0dad..8d13fd701 100644
--- a/README.md
+++ b/README.md
@@ -80,7 +80,7 @@ following keys in its top-level object:
  - `http`: URL that will display information about the running `syz-manager` process.
  - `workdir`: Location of a working directory for the `syz-manager` process. Outputs here include:
      - `<workdir>/instance-x`: per VM instance temporary files
-     - `<workdir>/crashes/*`: crash output files (see [Crash Reports](#Crash Reports))
+     - `<workdir>/crashes/*`: crash output files (see [Crash Reports](#crash-reports))
      - `<workdir>/corpus/*`: corpus with interesting programs
  - `syzkaller`: Location of the `syzkaller` checkout.
  - `vmlinux`: Location of the `vmlinux` file that corresponds to the kernel being tested.
@@ -146,7 +146,32 @@ written in C++, compiled as static binary and uses shared memory for communicati
 
 ## Crash Reports
 
-TODO
+When `syzkaller` finds a crasher, it saves information about it into `workdir/crashes` directory. The directory contains one subdirectory per unique crash type. Each subdirectory contains a `description` file with a unique string identifying the crash (intended for bug identification and deduplication); and up to 100 `logN` and `reportN` files, one pair per test machine crash:
+```
+ - crashes/
+   - 6e512290efa36515a7a27e53623304d20d1c3e
+     - description
+     - log0
+     - report0
+     - log1
+     - report1
+     ...
+   - 77c578906abe311d06227b9dc3bffa4c52676f
+     - description
+     - log0
+     - report0
+     ...
+```
+
+Descriptions are extracted using a set of [regular expressions](report/report.go#L33). This set may need to be extended if you are using a different kernel architecture, or are just seeing a previously unseen kernel error messages.
+
+`logN` files contain raw `syzkaller` logs and include kernel console output as well as programs executed before the crash. These logs can be fed to `syz-repro` tool for [crash location and minimization](https://github.com/google/syzkaller/wiki/Crash-reproducer-programs), or to `syz-execprog` tool for [manual localization](https://github.com/google/syzkaller/wiki/How-to-execute-syzkaller-programs). `reportN` files contain post-processed and symbolized kernel crash reports (e.g. a KASAN report). Normally you need just 1 pair of these files (i.e. `log0` and `report0`), because they all presumably describe the same kernel bug. However, `syzkaller` saves up to 100 of them for the case when the crash is poorly reproducible, or if you just want to look at a set of crash reports to infer some similarities or differences.
+
+There are 3 special types of crashes:
+ - `no output from test machine`: the test machine produces no output whatsoever
+ - `lost connection to test machine`: the ssh connection to the machine was unexpectedly closed
+ - `test machine is not executing programs`: the machine looks alive, but no test programs were executed for long period of time
+Most likely you won't see `reportN` files for these crashes (e.g. if there is no output from the test machine, there is nothing to put into report). Sometimes these crashes indicate a bug in `syzkaller` itself (especially if you see a Go panic message in the logs). However, frequently they mean a kernel lockup or something similarly bad (here are just a few examples of bugs found this way: [1](https://groups.google.com/d/msg/syzkaller/zfuHHRXL7Zg/Tc5rK8bdCAAJ), [2](https://groups.google.com/d/msg/syzkaller/kY_ml6TCm9A/wDd5fYFXBQAJ), [3](https://groups.google.com/d/msg/syzkaller/OM7CXieBCoY/etzvFPX3AQAJ)).
 
 ## Syscall description