modernize llvm_mode readmes
RENAME
llvm_mode/README.instrim
llvm_mode/README.instrim.md
# InsTrim
-InsTrim: Lightweight Instrumentation for Coverage-guided Fuzzing
+InsTrim: Lightweight Instrumentation for Coverage-guided Fuzzing
## Introduction
@@ -8,17 +8,15 @@ InsTrim uses CFG and markers to instrument just what is necessary in the
binary in llvm_mode. It is about 20-25% faster but as a cost has a lower
path discovery.
-
## Usage
-Set the environment variable AFL_LLVM_INSTRIM=1
+Set the environment variable `AFL_LLVM_INSTRIM=1`.
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
see how often the loop has been rerun.
This again is a tradeoff for speed for less path information.
-To enable this mode set AFL_LLVM_INSTRIM_LOOPHEAD=1
-
+To enable this mode set `AFL_LLVM_INSTRIM_LOOPHEAD=1`.
## Background

DELETE
llvm_mode/README.laf-intel
-Usage
-=====
-
-By default the 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.
-
-The following options exist:
-
-export AFL_LLVM_LAF_SPLIT_SWITCHES=1 Enables the split-switches pass.
-
-export AFL_LLVM_LAF_TRANSFORM_COMPARES=1 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>.
-

ADD
llvm_mode/README.laf-intel.md
+# laf-intel instrumentation
+
+## Usage
+
+By default the 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.
+
+The following options exist:
+
+`export AFL_LLVM_LAF_SPLIT_SWITCHES=1`
+
+Enables the split-switches pass.
+
+`export AFL_LLVM_LAF_TRANSFORM_COMPARES=1`
+
+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>`.
+

RENAME
llvm_mode/README.llvm
llvm_mode/README.md
-============================================
-Fast LLVM-based instrumentation for afl-fuzz
-============================================
+# Fast LLVM-based instrumentation for afl-fuzz
(See ../docs/README for the general instruction manual.)
(See ../gcc_plugin/README.gcc for the GCC-based instrumentation.)
-1) Introduction
----------------
+## 1) Introduction
! llvm_mode works with llvm versions 3.8.0 up to 9 !
@@ -38,8 +35,7 @@ co-exists with the original code.
The idea and much of the implementation comes from Laszlo Szekeres.
-2) How to use this
-------------------
+## 2) How to use this
In order to leverage this mechanism, you need to have clang installed on your
system. You should also make sure that the llvm-config tool is in your path
@@ -63,8 +59,10 @@ called afl-clang-fast and afl-clang-fast++ in the parent directory. Once this
is done, you can instrument third-party code in a way similar to the standard
operating mode of AFL, e.g.:
+```
CC=/path/to/afl/afl-clang-fast ./configure [...options...]
make
+```
Be sure to also include CXX set to afl-clang-fast++ for C++ code.
@@ -78,7 +76,7 @@ Note: if you want the LLVM helper to be installed on your system for all
users, you need to build it before issuing 'make install' in the parent
directory.
-3) Options
+## 3) Options
Several options are present to make llvm_mode faster or help it rearrange
the code to make afl-fuzz path discovery easier.
@@ -101,15 +99,12 @@ is not optimal and was only fixed in llvm 9.
You can set this with AFL_LLVM_NOT_ZERO=1
See README.neverzero
-
-4) Gotchas, feedback, bugs
---------------------------
+## 4) Gotchas, feedback, bugs
This is an early-stage mechanism, so field reports are welcome. You can send bug
reports to <afl-users@googlegroups.com>.
-5) Bonus feature #1: deferred initialization
---------------------------------------------
+## 5) Bonus feature #1: deferred initialization
AFL tries to optimize performance by executing the targeted binary just once,
stopping it just before main(), and then cloning this "master" process to get
@@ -145,9 +140,11 @@ a location after:
With the location selected, add this code in the appropriate spot:
+```c
#ifdef __AFL_HAVE_MANUAL_CONTROL
__AFL_INIT();
#endif
+```
You don't need the #ifdef guards, but including them ensures that the program
will keep working normally when compiled with a tool other than afl-clang-fast.
@@ -155,8 +152,7 @@ will keep working normally when compiled with a tool other than afl-clang-fast.
Finally, recompile the program with afl-clang-fast (afl-gcc or afl-clang will
*not* generate a deferred-initialization binary) - and you should be all set!
-6) Bonus feature #2: persistent mode
-------------------------------------
+## 6) Bonus feature #2: persistent mode
Some libraries provide APIs that are stateless, or whose state can be reset in
between processing different input files. When such a reset is performed, a
@@ -165,6 +161,7 @@ eliminating the need for repeated fork() calls and the associated OS overhead.
The basic structure of the program that does this would be:
+```c
while (__AFL_LOOP(1000)) {
/* Read input data. */
@@ -174,6 +171,7 @@ The basic structure of the program that does this would be:
}
/* Exit normally */
+```
The numerical value specified within the loop controls the maximum number
of iterations before AFL will restart the process from scratch. This minimizes
@@ -182,8 +180,8 @@ and going much higher increases the likelihood of hiccups without giving you
any real performance benefits.
A more detailed template is shown in ../experimental/persistent_demo/.
-Similarly to the previous mode, the feature works only with afl-clang-fast;
-#ifdef guards can be used to suppress it when using other compilers.
+Similarly to the previous mode, the feature works only with afl-clang-fast; #ifdef
+guards can be used to suppress it when using other compilers.
Note that as with the previous mode, the feature is easy to misuse; if you
do not fully reset the critical state, you may end up with false positives or
@@ -195,8 +193,7 @@ PS. Because there are task switches still involved, the mode isn't as fast as
faster than the normal fork() model, and compared to in-process fuzzing,
should be a lot more robust.
-8) Bonus feature #3: new 'trace-pc-guard' mode
-----------------------------------------------
+## 8) Bonus feature #3: new 'trace-pc-guard' mode
Recent versions of LLVM are shipping with a built-in execution tracing feature
that provides AFL with the necessary tracing data without the need to
@@ -207,7 +204,9 @@ post-process the assembly or install any compiler plugins. See:
If you have a sufficiently recent compiler and want to give it a try, build
afl-clang-fast this way:
+```
AFL_TRACE_PC=1 make clean all
+```
Note that this mode is currently about 20% slower than "vanilla" afl-clang-fast,
and about 5-10% slower than afl-clang. This is likely because the

RENAME
llvm_mode/README.neverzero
llvm_mode/README.neverzero.md
-Usage
-=====
+# NeverZero counters for LLVM instrumentation
+
+## Usage
In larger, complex or reiterative programs the map that collects the edge pairs
can easily fill up and wrap.
@@ -18,5 +19,6 @@ in version 9 and onwards.
If you want to enable this for llvm < 9 then set
+```
export AFL_LLVM_NOT_ZERO=1
-
+```

RENAME
llvm_mode/README.whitelist
llvm_mode/README.whitelist.md
-========================================
-Using afl++ with partial instrumentation
-========================================
+# Using afl++ with partial instrumentation
This file describes how you can selectively instrument only the source files
that are interesting to you using the LLVM instrumentation provided by
@@ -8,9 +6,7 @@ Using afl++ with partial instrumentation
Originally developed by Christian Holler (:decoder) <choller@mozilla.com>.
-
-1) Description and purpose
---------------------------
+## 1) Description and purpose
When building and testing complex programs where only a part of the program is
the fuzzing target, it often helps to only instrument the necessary parts of
@@ -23,15 +19,13 @@ mode of AFLFuzz that allows you to specify on a source file level which files
should be compiled with or without instrumentation.
-2) Building the LLVM module
----------------------------
+## 2) Building the LLVM module
The new code is part of the existing afl++ LLVM module in the llvm_mode/
subdirectory. There is nothing specifically to do :)
-3) How to use the partial instrumentation mode
-----------------------------------------------
+## 3) How to use the partial instrumentation mode
In order to build with partial instrumentation, you need to build with
afl-clang-fast and afl-clang-fast++ respectively. The only required change is
@@ -45,21 +39,27 @@ matching when absolute paths are used during compilation).
For example if your source tree looks like this:
+```
project/
project/feature_a/a1.cpp
project/feature_a/a2.cpp
project/feature_b/b1.cpp
project/feature_b/b2.cpp
+```
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:
+```
a1.cpp
a2.cpp
+```
but it might lead to files being unwantedly instrumented if the same filename
exists somewhere else in the project.

modernize llvm_mode readmes