Extend the `csmith` README

1 files changed, 61 insertions, 3 deletions

diff --git a/csmith-fuzzing/README.md b/csmith-fuzzing/README.md
index e4c74243..258ab5e7 100644
--- a/csmith-fuzzing/README.md
+++ b/csmith-fuzzing/README.md
@@ -1,7 +1,65 @@
-Fuzz bindgen with `csmith` https://github.com/csmith-project/csmith .
+# Fuzzing `bindgen` with `csmith`
 
-Run with `python3 driver.py`. It will run until until it encounters an error in `bindgen`.
+[`csmith`][csmith] generates random C and C++ programs that can be used as test
+cases for compilers. When testing `bindgen` with `csmith`, we interpret the
+generated programs as header files, and emit Rust bindings to them. If `bindgen`
+panics, the emitted bindings won't compile with `rustc`, or the generated layout
+tests in the bindings fail, then we report an issue containing the test case!
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [Prerequisites](#prerequisites)
+- [Running the Fuzzer](#running-the-fuzzer)
+- [Reporting Issues](#reporting-issues)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Prerequisites
 
 Requires `python3`, `csmith` and `bindgen` to be in `$PATH`.
 
-csmith is run with `--no-checksum --nomain --max-block-size 1 --max-block-depth 1` which disables the `main` function and makes function bodies as simple as possible as bindgen does not care about them but they cannot be completely disabled in csmith. Run `csmith --help` to see what exactly those options do.
+Many OS package managers have a `csmith` package:
+
+```
+$ sudo apt install csmith
+$ brew install csmith
+$ # Etc...
+```
+
+## Running the Fuzzer
+
+Run `csmith` and test `bindgen` on the generated test cases with this command:
+
+```
+$ ./driver.py
+```
+
+The driver will keep running until it encounters an error in `bindgen`.
+
+Each invocation of `./driver.py` will use its own temporary directories, so
+running it in multiple terminals in parallel is supported.
+
+`csmith` is run with `--no-checksum --nomain --max-block-size 1
+--max-block-depth 1` which disables the `main` function, and makes function
+bodies as simple as possible as `bindgen` does not care about them, but they
+cannot be completely disabled in `csmith`. Run `csmith --help` to see what
+exactly those options do.
+
+## Reporting Issues
+
+Once the fuzz driver finds a test case that causes some kind of error in
+`bindgen` or its emitted bindings, it is helpful to
+[run C-Reduce on the test case][creducing] to remove the parts that are
+irrelevant to reproducing the error. This is ***very*** helpful for the folks
+who further investigate the issue and come up with a fix!
+
+Additionally, mention that you discovered the issue via `csmith` and we will add
+the `A-csmith` label. You can find all the issues discovered with `csmith`, and
+related to fuzzing with `csmith`, by looking up
+[all issues tagged with the `A-csmith` label][csmith-issues].
+
+[csmith]: https://github.com/csmith-project/csmith
+[creducing]: ../CONTRIBUTING.md#using-creduce-to-minimize-test-cases
+[csmith-issues]: https://github.com/rust-lang-nursery/rust-bindgen/issues?q=label%3AA-csmith