merge from master

10 files changed, 81 insertions, 75 deletions

diff --git a/include/debug.h b/include/debug.h
index 349aa650..c0044280 100644
--- a/include/debug.h
+++ b/include/debug.h
@@ -198,8 +198,8 @@
 
 #define FATAL(x...) do { \
     SAYF(bSTOP RESET_G1 CURSOR_SHOW cRST cLRD "\n[-] PROGRAM ABORT : " \
-         cBRI x); \
-    SAYF(cLRD "\n         Location : " cRST "%s(), %s:%d\n\n", \
+         cRST x); \
+    SAYF(cLRD "\n         Location : " cRST "%s(), %s:%u\n\n", \
          __FUNCTION__, __FILE__, __LINE__); \
     exit(1); \
   } while (0)
@@ -208,8 +208,8 @@
 
 #define ABORT(x...) do { \
     SAYF(bSTOP RESET_G1 CURSOR_SHOW cRST cLRD "\n[-] PROGRAM ABORT : " \
-         cBRI x); \
-    SAYF(cLRD "\n    Stop location : " cRST "%s(), %s:%d\n\n", \
+         cRST x); \
+    SAYF(cLRD "\n    Stop location : " cRST "%s(), %s:%u\n\n", \
          __FUNCTION__, __FILE__, __LINE__); \
     abort(); \
   } while (0)
@@ -219,8 +219,8 @@
 #define PFATAL(x...) do { \
     fflush(stdout); \
     SAYF(bSTOP RESET_G1 CURSOR_SHOW cRST cLRD "\n[-]  SYSTEM ERROR : " \
-         cBRI x); \
-    SAYF(cLRD "\n    Stop location : " cRST "%s(), %s:%d\n", \
+         cRST x); \
+    SAYF(cLRD "\n    Stop location : " cRST "%s(), %s:%u\n", \
          __FUNCTION__, __FILE__, __LINE__); \
     SAYF(cLRD "       OS message : " cRST "%s\n", strerror(errno)); \
     exit(1); \
diff --git a/libdislocator/README.dislocator b/libdislocator/README.md
index 837e7466..5d5a1464 100644
--- a/libdislocator/README.dislocator
+++ b/libdislocator/README.md
@@ -1,6 +1,4 @@
-===================================
-libdislocator, an abusive allocator
-===================================
+# libdislocator, an abusive allocator
 
   (See ../docs/README for the general instruction manual.)
 
@@ -45,7 +43,9 @@ when fuzzing small, self-contained binaries.
 
 To use this library, run AFL like so:
 
+```
 AFL_PRELOAD=/path/to/libdislocator.so ./afl-fuzz [...other params...]
+```
 
 You *have* to specify path, even if it's just ./libdislocator.so or
 $PWD/libdislocator.so.
diff --git a/libtokencap/README.tokencap b/libtokencap/README.md
index 650739f2..baf69da1 100644
--- a/libtokencap/README.tokencap
+++ b/libtokencap/README.md
@@ -1,10 +1,8 @@
-=========================================
-strcmp() / memcmp() token capture library
-=========================================
+# strcmp() / memcmp() token capture library
 
   (See ../docs/README for the general instruction manual.)
 
-This Linux-only companion library allows you to instrument strcmp(), memcmp(),
+This Linux-only companion library allows you to instrument `strcmp()`, `memcmp()`,
 and related functions to automatically extract syntax tokens passed to any of
 these libcalls. The resulting list of tokens may be then given as a starting
 dictionary to afl-fuzz (the -x option) to improve coverage on subsequent
@@ -31,15 +29,18 @@ with -fno-builtin and is linked dynamically. If you wish to automate the first
 part without mucking with CFLAGS in Makefiles, you can set AFL_NO_BUILTIN=1
 when using afl-gcc. This setting specifically adds the following flags:
 
+```
   -fno-builtin-strcmp -fno-builtin-strncmp -fno-builtin-strcasecmp
   -fno-builtin-strcasencmp -fno-builtin-memcmp -fno-builtin-strstr
   -fno-builtin-strcasestr
+```
 
 The next step is simply loading this library via LD_PRELOAD. The optimal usage
 pattern is to allow afl-fuzz to fuzz normally for a while and build up a corpus,
 and then fire off the target binary, with libtokencap.so loaded, on every file
 found by AFL in that earlier run. This demonstrates the basic principle:
 
+```
   export AFL_TOKEN_FILE=$PWD/temp_output.txt
 
   for i in <out_dir>/queue/id*; do
@@ -48,6 +49,7 @@ found by AFL in that earlier run. This demonstrates the basic principle:
   done
 
   sort -u temp_output.txt >afl_dictionary.txt
+```
 
 If you don't get any results, the target library is probably not using strcmp()
 and memcmp() to parse input; or you haven't compiled it with -fno-builtin; or
@@ -55,7 +57,7 @@ the whole thing isn't dynamically linked, and LD_PRELOAD is having no effect.
 
 PS. The library is Linux-only because there is probably no particularly portable
 and non-invasive way to distinguish between read-only and read-write memory
-mappings. The __tokencap_load_mappings() function is the only thing that would
+mappings. The `__tokencap_load_mappings()` function is the only thing that would
 need to be changed for other OSes. Porting to platforms with /proc/<pid>/maps
 (e.g., FreeBSD) should be trivial.
 
diff --git a/llvm_mode/README.instrim b/llvm_mode/README.instrim.md
index 956a9856..e5e3614d 100644
--- a/llvm_mode/README.instrim
+++ b/llvm_mode/README.instrim.md
@@ -1,6 +1,6 @@
 # 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
 
diff --git a/llvm_mode/README.laf-intel b/llvm_mode/README.laf-intel
deleted file mode 100644
index 340216c3..00000000
--- a/llvm_mode/README.laf-intel
+++ /dev/null
@@ -1,20 +0,0 @@
-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>.
-
diff --git a/llvm_mode/README.laf-intel.md b/llvm_mode/README.laf-intel.md
new file mode 100644
index 00000000..d51c7e2f
--- /dev/null
+++ b/llvm_mode/README.laf-intel.md
@@ -0,0 +1,25 @@
+# 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>`.
+
diff --git a/llvm_mode/README.llvm b/llvm_mode/README.md
index 9bb091ac..c7ef4b45 100644
--- a/llvm_mode/README.llvm
+++ b/llvm_mode/README.md
@@ -1,12 +1,9 @@
-============================================
-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
diff --git a/llvm_mode/README.neverzero b/llvm_mode/README.neverzero.md
index ef873acb..5fcf7b47 100644
--- a/llvm_mode/README.neverzero
+++ b/llvm_mode/README.neverzero.md
@@ -1,5 +1,6 @@
-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
-
+```
diff --git a/llvm_mode/README.whitelist b/llvm_mode/README.whitelist.md
index ae044749..5aededba 100644
--- a/llvm_mode/README.whitelist
+++ b/llvm_mode/README.whitelist.md
@@ -1,6 +1,4 @@
-========================================
-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.
diff --git a/qemu_mode/libcompcov/README.compcov b/qemu_mode/libcompcov/README.md
index 9be13d88..5aaa3dd8 100644
--- a/qemu_mode/libcompcov/README.compcov
+++ b/qemu_mode/libcompcov/README.md
@@ -1,10 +1,8 @@
-================================================================
-strcmp() / memcmp() CompareCoverage library for AFLplusplus-QEMU
-================================================================
+# strcmp() / memcmp() CompareCoverage library for afl++ QEMU
 
   Written by Andrea Fioraldi <andreafioraldi@gmail.com>
 
-This Linux-only companion library allows you to instrument strcmp(), memcmp(),
+This Linux-only companion library allows you to instrument `strcmp()`, `memcmp()`,
 and related functions to log the CompareCoverage of these libcalls.
 
 Use this with caution. While this can speedup a lot the bypass of hard
@@ -22,10 +20,12 @@ library and QEMU but build it with afl-clang-fast and the laf-intel options.
 
 To use this library make sure to preload it with AFL_PRELOAD.
 
+```
   export AFL_PRELOAD=/path/to/libcompcov.so
   export AFL_COMPCOV_LEVEL=1
   
   afl-fuzz -Q -i input -o output <your options> -- <target args>
+```
 
 The AFL_COMPCOV_LEVEL tells to QEMU and libcompcov how to log comaprisons.
 Level 1 logs just comparison with immediates / read-only memory and level 2