add documentation

3 files changed, 18 insertions, 2 deletions

diff --git a/README.md b/README.md
index 384ae830..c7793dff 100644
--- a/README.md
+++ b/README.md
@@ -52,6 +52,9 @@ behaviours and defaults:
     * -m none is now default, set memory limits (in MB) with e.g. -m 250
     * deterministic fuzzing is now disabled by default (unless using -M) and
       can be enabled with -D
+    * a caching of testcases can now be performed and can be enabled by
+      editing config.h for TESTCASE_CACHE or by specifying the env variable
+      `AFL_TESTCACHE_SIZE` (in MB). Good values are between 50-500.
 
 ## Contents
 
@@ -555,7 +558,7 @@ is:
 
 All labels are explained in [docs/status_screen.md](docs/status_screen.md).
 
-#### b) Using multiple cores/threads
+#### b) Using multiple cores
 
 If you want to seriously fuzz then use as many cores/threads as possible to
 fuzz your target.
@@ -563,7 +566,12 @@ fuzz your target.
 On the same machine - due to the design of how afl++ works - there is a maximum
 number of CPU cores/threads that are useful, use more and the overall performance
 degrades instead. This value depends on the target, and the limit is between 32
-and 64 cores/threads per machine.
+and 64 cores per machine.
+
+If you have the RAM, it is highly recommended run the instances with a caching
+of the testcases. Depending on the average testcase size (and those found
+during fuzzing) and their number, a value between 50-500MB is recommended.
+You can set the cache size (in MB) by setting the environment variable `AFL_TESTCACHE_SIZE`.
 
 There should be one main fuzzer (`-M main` option) and as many secondary
 fuzzers (eg `-S variant1`) as you have cores that you use.
diff --git a/docs/env_variables.md b/docs/env_variables.md
index ebb7521e..49eadcaa 100644
--- a/docs/env_variables.md
+++ b/docs/env_variables.md
@@ -282,6 +282,10 @@ checks or alter some of the more exotic semantics of the tool:
     the target. This must be equal or larger than the size the target was
     compiled with.
 
+  - AFL_TESTCACHE_SIZE allows you to overrider the define in config.h for
+    TESTCASE_CACHE. Recommended values are 50-250MB - or more if your
+    fuzzing finds a huge amount of paths for large inputs.
+
   - Setting AFL_DISABLE_TRIM tells afl-fuzz to no trim test cases. This is
     usually a bad idea!
 
diff --git a/include/afl-fuzz.h b/include/afl-fuzz.h
index 940c5602..514d558b 100644
--- a/include/afl-fuzz.h
+++ b/include/afl-fuzz.h
@@ -1164,5 +1164,9 @@ u8 *queue_testcase_get(afl_state_t *afl, struct queue_entry *q);
 void queue_testcase_retake(afl_state_t *afl, struct queue_entry *q,
                            u32 old_len);
 
+#if TESTCASE_CACHE == 1
+#error define of TESTCASE_CACHE must be zero or larger than 1
+#endif
+
 #endif