Merge pull request #594 from AFLplusplus/dev

push to stable

1 files changed, 35 insertions, 0 deletions

diff --git a/instrumentation/README.neverzero.md b/instrumentation/README.neverzero.md
new file mode 100644
index 00000000..5c894d6e
--- /dev/null
+++ b/instrumentation/README.neverzero.md
@@ -0,0 +1,35 @@
+# NeverZero counters for LLVM instrumentation
+
+## Usage
+
+In larger, complex or reiterative programs the byte sized counters that collect
+the edge coverage can easily fill up and wrap around.
+This is not that much of an issue - unless by chance it wraps just to a value
+of zero when the program execution ends.
+In this case afl-fuzz is not able to see that the edge has been accessed and
+will ignore it.
+
+NeverZero prevents this behaviour. If a counter wraps, it jumps over the value
+0 directly to a 1. This improves path discovery (by a very little amount)
+at a very little cost (one instruction per edge).
+
+(The alternative of saturated counters has been tested also and proved to be
+inferior in terms of path discovery.)
+
+This is implemented in afl-gcc, however for llvm_mode this is optional if
+the llvm version is below 9 - as there is a perfomance bug that is only fixed
+in version 9 and onwards.
+
+If you want to enable this for llvm versions below 9 then set
+
+```
+export AFL_LLVM_NOT_ZERO=1
+```
+
+In case you are on llvm 9 or greater and you do not want this behaviour then
+you can set:
+```
+AFL_LLVM_SKIP_NEVERZERO=1
+```
+If the target does not have extensive loops or functions that are called
+a lot then this can give a small performance boost.