Fixing readme & docs (#730)

* fix

* fix

* add

* add

* fmt

README.md

@@ -79,6 +79,12 @@ cd docs && mdbook serve
 We collect all example fuzzers in [`./fuzzers`](./fuzzers/).
 Be sure to read their documentation (and source), this is *the natural way to get started!*
 
+You can run each example fuzzer with
+```
+cargo make run
+```
+as long as the fuzzer directory has `Makefile.toml` file.
+
 The best-tested fuzzer is [`./fuzzers/libfuzzer_libpng`](./fuzzers/libfuzzer_libpng), a multicore libfuzzer-like fuzzer using LibAFL for a libpng harness.
 
 ## Resources

docs/src/core_concepts/executor.md

@@ -11,13 +11,13 @@ In our model, it can also hold a set of Observers connected with each execution.
 
 In Rust, we bind this concept to the [`Executor`](https://docs.rs/libafl/0/libafl/executors/trait.Executor.html) trait. A structure implementing this trait must implement [`HasObservers`](https://docs.rs/libafl/0/libafl/executors/trait.HasObservers.html) too if wants to hold a set of Observers.
 
-By default, we implement some commonly used Executors such as [`InProcessExecutor`](https://docs.rs/libafl/0/libafl/executors/inprocess/struct.InProcessExecutor.html) is which the target is a harness function providing in-process crash detection. Another Executor is the [`ForkserverExecutor`](https://docs.rs/libafl/0/libafl/executors/forkserver/struct.ForkserverExecutor.html) that implements an AFL-like mechanism to spawn child processes to fuzz.
+By default, we implement some commonly used Executors such as [`InProcessExecutor`](https://docs.rs/libafl/0/libafl/executors/inprocess/struct.InProcessExecutor.html) in which the target is a harness function providing in-process crash detection. Another Executor is the [`ForkserverExecutor`](https://docs.rs/libafl/0/libafl/executors/forkserver/struct.ForkserverExecutor.html) that implements an AFL-like mechanism to spawn child processes to fuzz.
 
 A common pattern when creating an Executor is wrapping an existing one, for instance [`TimeoutExecutor`](https://docs.rs/libafl/0.6.1/libafl/executors/timeout/struct.TimeoutExecutor.html) wraps an executor and install a timeout callback before calling the original run function of the wrapped executor.
 
 ## InProcessExecutor
 Let's begin with the base case; `InProcessExecutor`.
-This executor uses [_SanitizerCoverage_](https://clang.llvm.org/docs/SanitizerCoverage.html) as its backend, as you can find the related code in `libafl_targets/src/sancov_pcguards`. Here we allocate a map called `EDGES_MAP` and then our compiler wrapper compiles the harness to write the coverage into this map.
+This executor executes the harness program (function) inside the fuzzer process.
 
 When you want to execute the harness as fast as possible, you will most probably want to use this `InprocessExecutor`.
 

fuzzers/frida_libpng/README.md

@@ -12,6 +12,8 @@ Then, it will link (the fuzzer)[./src/fuzzer.rs] against (the C++ harness)[./har
 Afterwards, the fuzzer will be ready to run, from `target/frida_libpng`.  
 On unix platforms, you'll need [libc++](https://libcxx.llvm.org/) to build it.
 
+Alternatively you can run `cargo make run` and this command will automatically build and run the fuzzer
+
 ### Build For Android
 When building for android using a cross-compiler, make sure you have a _standalone toolchain_, and then add the following:
 1. In the ~/.cargo/config file add a target with the correct cross-compiler toolchain name (in this case aarch64-linux-android, but names may vary)
@@ -27,8 +29,8 @@ This example uses in-process-fuzzing, using the `launcher` feature, in combinati
 This means running --cores each client will start itself again to listen for crashes and timeouts.
 By restarting the actual fuzzer, it can recover from these exit conditions.
 
-After building the libpng-harness, too, you can run `find . -name libpng-harness.so` to find the location of your harness, then run
+After building the libpng-harness, you can run `find . -name libpng-harness.so` to find the location of your harness, then run
-`./target/release/frida_libpng ./libpng-harness.so LLVMFuzzerTestOneInput ./libpng-harness.so --cores=0 --input=./corpus`
+`./frida_fuzzer -F LLVMFuzzerTestOneInput -H ./libpng-harness.so -l ./libpng-harness.so`
 
 ## Windows
 You can also fuzz libpng-1.6.37 on windows with frida mode
@@ -58,6 +60,6 @@ clang++ -L.\zlib.dll .\harness.o .\libpng16.lib -lzlib -shared -o .\libpng-harne
 ```
 5. Run the fuzzer
 ```
-./frida_libpng.exe ./libpng-harness.dll LLVMFuzzerTestOneInput ./libpng-harness.dll --cores=0 --input=./corpus
+./frida_fuzzer.exe ./libpng-harness.dll LLVMFuzzerTestOneInput ./libpng-harness.dll
 ```
 

libafl/src/fuzzer/mod.rs

@@ -154,6 +154,9 @@ where
 {
     /// Fuzz for a single iteration.
     /// Returns the index of the last fuzzed corpus item.
+    /// (Note: An iteration represents a complete run of every stage.
+    /// Therefore it does not mean that the harness is executed for once,
+    /// because each stage could run the harness for multiple times)
     ///
     /// If you use this fn in a restarting scenario to only run for `n` iterations,
     /// before exiting, make sure you call `event_mgr.on_restart(&mut state)?;`.
@@ -184,6 +187,9 @@ where
 
     /// Fuzz for n iterations.
     /// Returns the index of the last fuzzed corpus item.
+    /// (Note: An iteration represents a complete run of every stage.
+    /// therefore the number n is not always equal to the number of the actual harness executions,
+    /// because each stage could run the harness for multiple times)
     ///
     /// If you use this fn in a restarting scenario to only run for `n` iterations,
     /// before exiting, make sure you call `event_mgr.on_restart(&mut state)?;`.