small docs updates typos, grammar, clarifications
MODIFY
llvm_mode/README.instrim.md
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

MODIFY
llvm_mode/README.laf-intel.md
llvm_mode/README.laf-intel.md
## 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.

MODIFY
llvm_mode/README.md
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

MODIFY
llvm_mode/README.neverzero.md
llvm_mode/README.neverzero.md
## 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.

MODIFY
llvm_mode/README.whitelist.md
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).

MODIFY
qemu_mode/README.md
qemu_mode/README.md
@@ -46,21 +46,21 @@ directory.
## 3) Bonus feature #1: deferred initialization
-As for LLVM mode (referes to its README for mode details) QEMU mode support
+As for LLVM mode (refer to its README for mode details) QEMU mode supports
the deferred initialization.
This can be enabled setting the environment variable AFL_ENTRYPOINT which allows
to move the forkserver to a different part, e.g. just before the file is
-opened (e.g. way after command line parsing and config file loading, etc)
+opened (e.g. way after command line parsing and config file loading, etc.)
which can be a huge speed improvement. Note that the specified address
must be an address of a basic block.
## 4) Bonus feature #2: persistent mode
-QEMU mode support also persistent mode for x86 and x86_64 targets.
+QEMU mode supports also persistent mode for x86 and x86_64 targets.
The environment variable to enable it is AFL_QEMU_PERSISTENT_ADDR=`start addr`.
In this variable you must specify the address of the function that
-have to be the body of the persistent loop.
+has to be the body of the persistent loop.
The code in this function must be stateless like in the LLVM persistent mode.
The return address on stack is patched like in WinAFL in order to repeat the
execution of such function.
@@ -70,18 +70,18 @@ With this variable assigned, instead of patching the return address, the
specified instruction is transformed to a jump towards `start addr`.
Note that the format of the addresses in such variables is hex.
-Note that the base address of PIE binaries in QEMU user is 0x4000000000.
+Note that the base address of PIE binaries in QEMU user mode is 0x4000000000.
With the env variable AFL_QEMU_PERSISTENT_GPR you can tell QEMU to save the
-original value of general purpose registers and restore them ech cycle.
-This allow to use as persistent loop functions that make use of arguments on
+original value of general purpose registers and restore them in each cycle.
+This allows to use as persistent loop functions that make use of arguments on
x86_64.
With AFL_QEMU_PERSISTENT_RETADDR_OFFSET you can specify the offset from the
-stack pointer in which QEME can find the return address when `start addr` is
+stack pointer in which QEMU can find the return address when `start addr` is
hitted.
-Use this mode with caution, problably will not work at first shot.
+Use this mode with caution, probably it will not work at the first shot.
## 5) Bonus feature #3: CompareCoverage
@@ -103,7 +103,7 @@ Highly recommended.
AFL++ QEMU can use Wine to fuzz WIn32 PE binaries. Use the -W flag of afl-fuzz.
-Note that some binaries require user interaction with GUI and must be patched.
+Note that some binaries require user interaction with the GUI and must be patched.
For examples look [here](https://github.com/andreafioraldi/WineAFLplusplusDEMO).
@@ -176,6 +176,6 @@ The best implementation is this one:
https://github.com/vanhauser-thc/afl-dyninst
The issue however is Dyninst which is not rewriting the binaries so that
-they run stable. a lot of crashes happen, especially in C++ programs that
+they run stable. A lot of crashes happen, especially in C++ programs that
use throw/catch. Try it first, and if it works for you be happy as it is
2-3x as fast as qemu_mode.

small docs updates typos, grammar, clarifications