small docs updates typos, grammar, clarifications

5 files changed, 40 insertions, 22 deletions

diff --git a/llvm_mode/README.instrim.md b/llvm_mode/README.instrim.md
index e5e3614d..b40dbb18 100644
--- a/llvm_mode/README.instrim.md
+++ b/llvm_mode/README.instrim.md
@@ -10,7 +10,8 @@ path discovery.
 
 ## Usage
 
-Set the environment variable `AFL_LLVM_INSTRIM=1`.
+Set the environment variable `AFL_LLVM_INSTRIM=1` during compilation of
+the target.
 
 There is also an advanced mode which instruments loops in a way so that
 afl-fuzz can see which loop path has been selected but not being able to
diff --git a/llvm_mode/README.laf-intel.md b/llvm_mode/README.laf-intel.md
index d51c7e2f..c787744b 100644
--- a/llvm_mode/README.laf-intel.md
+++ b/llvm_mode/README.laf-intel.md
@@ -2,7 +2,7 @@
 
 ## Usage
 
-By default the passes will not run when you compile programs using 
+By default these passes will not run when you compile programs using 
 afl-clang-fast. Hence, you can use AFL as usual.
 To enable the passes you must set environment variables before you
 compile the target project.
@@ -15,11 +15,24 @@ Enables the split-switches pass.
 
 `export AFL_LLVM_LAF_TRANSFORM_COMPARES=1`
 
-Enables the transform-compares pass (strcmp, memcmp, strncmp, strcasecmp, strncasecmp).
+Enables the transform-compares pass (strcmp, memcmp, strncmp,
+strcasecmp, strncasecmp).
 
 `export AFL_LLVM_LAF_SPLIT_COMPARES=1`
 
 Enables the split-compares pass.
-By default it will split all compares with a bit width <= 64 bits.
-You can change this behaviour by setting `export AFL_LLVM_LAF_SPLIT_COMPARES_BITW=<bit_width>`.
-
+By default it will 
+1. simplify operators >= (and <=) into chains of > (<) and == comparisons
+2. change signed integer comparisons to a chain of sign-only comparison
+and unsigned comparisons
+3. split all unsigned integer comparisons with bit widths of
+64, 32 or 16 bits to chains of 8 bits comparisons.
+
+You can change the behaviour of the last step by setting
+`export AFL_LLVM_LAF_SPLIT_COMPARES_BITW=<bit_width>`, where 
+bit_width may be 64, 32 or 16.
+
+A new experimental feature is splitting floating point comparisons into a
+series of sign, exponent and mantissa comparisons followed by splitting each
+of them into 8 bit comparisons when necessary.
+It is activated with the `AFL_LLVM_LAF_SPLIT_COMPARES` setting.
diff --git a/llvm_mode/README.md b/llvm_mode/README.md
index f196395b..fa655ed6 100644
--- a/llvm_mode/README.md
+++ b/llvm_mode/README.md
@@ -27,7 +27,8 @@ several interesting properties:
   - The instrumentation can cope a bit better with multi-threaded targets.
 
   - Because the feature relies on the internals of LLVM, it is clang-specific
-    and will *not* work with GCC (see ../gcc_plugin/ for an alternative).
+    and will *not* work with GCC (see ../gcc_plugin/ for an alternative once
+    it is available).
 
 Once this implementation is shown to be sufficiently robust and portable, it
 will probably replace afl-clang. For now, it can be built separately and
@@ -86,7 +87,7 @@ Several options are present to make llvm_mode faster or help it rearrange
 the code to make afl-fuzz path discovery easier.
 
 If you need just to instrument specific parts of the code, you can whitelist
-which C/C++ files to actually intrument. See README.whitelist
+which C/C++ files to actually instrument. See README.whitelist
 
 For splitting memcmp, strncmp, etc. please see README.laf-intel
 
@@ -98,7 +99,7 @@ See README.instrim
 
 Finally if your llvm version is 8 or lower, you can activate a mode that
 prevents that a counter overflow result in a 0 value. This is good for
-path discovery, but the llvm implementation for intel for this functionality
+path discovery, but the llvm implementation for x86 for this functionality
 is not optimal and was only fixed in llvm 9.
 You can set this with AFL_LLVM_NOT_ZERO=1
 See README.neverzero
diff --git a/llvm_mode/README.neverzero.md b/llvm_mode/README.neverzero.md
index 5fcf7b47..1e406560 100644
--- a/llvm_mode/README.neverzero.md
+++ b/llvm_mode/README.neverzero.md
@@ -2,17 +2,20 @@
 
 ## Usage
 
-In larger, complex or reiterative programs the map that collects the edge pairs
-can easily fill up and wrap.
-This is not that much of an issue - unless by chance it wraps just to a 0
-when the program execution ends.
-In this case afl-fuzz is not able to see that the pair has been accessed and
+In larger, complex or reiterative programs the 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 0
-directly to a 1. This improves path discovery (by a very little amount)
+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.
diff --git a/llvm_mode/README.whitelist.md b/llvm_mode/README.whitelist.md
index 5aededba..6a5770c2 100644
--- a/llvm_mode/README.whitelist.md
+++ b/llvm_mode/README.whitelist.md
@@ -34,8 +34,8 @@ the compiler.
 
 The environment variable must point to a file containing all the filenames
 that should be instrumented. For matching, the filename that is being compiled
-must end in the filename contained in this whitelist (to avoid breaking the
-matching when absolute paths are used during compilation).
+must end in the filename entry contained in this whitelist (to avoid breaking
+the matching when absolute paths are used during compilation).
 
 For example if your source tree looks like this:
 
@@ -47,14 +47,14 @@ project/feature_b/b1.cpp
 project/feature_b/b2.cpp
 ```
 
-And you only want to test feature_a, then create a whitelist file containing:
+and you only want to test feature_a, then create a whitelist file containing:
 
 ```
 feature_a/a1.cpp
 feature_a/a2.cpp
 ```
 
-However if the whitelist file contains this, it works as well:
+However if the whitelist file contains only this, it works as well:
 
 ```
 a1.cpp
@@ -62,7 +62,7 @@ a2.cpp
 ```
 
 but it might lead to files being unwantedly instrumented if the same filename
-exists somewhere else in the project.
+exists somewhere else in the project directories.
 
 The created whitelist file is then set to AFL_INST_WHITELIST when you compile
 your program. For each file that didn't match the whitelist, the compiler will
@@ -72,4 +72,4 @@ didn't intend to instrument that file, then you can safely ignore that warning.
 For old LLVM versions this feature might require to be compiled with debug
 information (-g), however at least from llvm version 6.0 onwards this is not
 required anymore (and might hurt performance and crash detection, so better not
-use -g)
+use -g).