several documentation fixes

4 files changed, 42 insertions, 32 deletions

diff --git a/docs/ChangeLog b/docs/ChangeLog
index f2709877..be50215c 100644
--- a/docs/ChangeLog
+++ b/docs/ChangeLog
@@ -30,7 +30,7 @@ Version ++2.52d (tbd):
     path discovery. See llvm_mode/README.instrim (https://github.com/csienslab/instrim)
   - added MOpt (github.com/puppet-meteor/MOpt-AFL) mode, see docs/README.MOpt
   - added code to make it more portable to other platforms than Intel Linux
-  - added never zero counters for afl-gcc and optional (because of an
+  - added never zero counters for afl-gcc and optionally (because of an
     optimization issue in llvm < 9) for llvm_mode (AFL_LLVM_NEVER_ZERO=1)
   - added a new doc about binary only fuzzing: docs/binaryonly_fuzzing.txt
   - more cpu power for afl-system-config
@@ -45,8 +45,8 @@ Version ++2.52d (tbd):
     debugging
   - added -V time and -E execs option to better comparison runs, runs afl-fuzz
     for a specific time/executions.
-  - added a  -s seed  switch to allow afl run with a fixed initial
-    seed that is not updated. this is good for performance and path discovery
+  - added a -s seed switch to allow afl run with a fixed initial
+    seed that is not updated. This is good for performance and path discovery
     tests as the random numbers are deterministic then
   - llvm_mode LAF_... env variables can now be specified as AFL_LLVM_LAF_...
     that is longer but in line with other llvm specific env vars
@@ -59,7 +59,7 @@ Version ++2.52c (2019-06-05):
   - Applied community patches. See docs/PATCHES for the full list.
     LLVM and Qemu modes are now faster.
     Important changes:
-      afl-fuzz: -e EXTENSION  commandline option
+      afl-fuzz: -e EXTENSION commandline option
       llvm_mode: LAF-intel performance (needs activation, see llvm/README.laf-intel)
       a few new environment variables for afl-fuzz, llvm and qemu, see docs/env_variables.txt
   - Added the power schedules of AFLfast by Marcel Boehme, but set the default
diff --git a/docs/README.MOpt b/docs/README.MOpt
index 5575189c..94e63959 100644
--- a/docs/README.MOpt
+++ b/docs/README.MOpt
@@ -17,7 +17,8 @@ We open source all the seed sets used in the paper
 
 ### 4. Experiment Results
 The experiment results can be found in 
-https://drive.google.com/drive/folders/184GOzkZGls1H2NuLuUfSp9gfqp1E2-lL?usp=sharing.  We only open source the crash files since the space is limited. 
+https://drive.google.com/drive/folders/184GOzkZGls1H2NuLuUfSp9gfqp1E2-lL?usp=sharing.
+We only open source the crash files since the space is limited. 
 
 ### 5. Technical Report
 MOpt_TechReport.pdf is the technical report of the paper 
@@ -26,18 +27,25 @@ MOpt_TechReport.pdf is the technical report of the paper
 ### 6. Parameter Introduction
 Most important, you must add the parameter `-L` (e.g., `-L 0`) to launch the
 MOpt scheme. 
-<br>`-L` controls the time to move on to the pacemaker fuzzing mode.
-<br>`-L t:` when MOpt-AFL finishes the mutation of one input, if it has not
-discovered any new unique crash or path for more than t min, MOpt-AFL will
+
+Option '-L' controls the time to move on to the pacemaker fuzzing mode.
+'-L t': when MOpt-AFL finishes the mutation of one input, if it has not
+discovered any new unique crash or path for more than t minutes, MOpt-AFL will
 enter the pacemaker fuzzing mode. 
-<br>Setting 0 will enter the pacemaker fuzzing mode at first, which is
+
+Setting 0 will enter the pacemaker fuzzing mode at first, which is
 recommended in a short time-scale evaluation. 
 
 Other important parameters can be found in afl-fuzz.c, for instance, 
-<br>`swarm_num:` the number of the PSO swarms used in the fuzzing process.
-<br>`period_pilot:` how many times MOpt-AFL will execute the target program in the pilot fuzzing module, then it will enter the core fuzzing module. 
-<br>`period_core:` how many times MOpt-AFL will execute the target program in the core fuzzing module, then it will enter the PSO updating module. 
-<br>`limit_time_bound:` control how many interesting test cases need to be found before MOpt-AFL quits the pacemaker fuzzing mode and reuses the deterministic stage. 
-0 < `limit_time_bound` < 1, MOpt-AFL-tmp.  `limit_time_bound` >= 1, MOpt-AFL-ever. 
 
-Having fun with MOpt in AFL!
+'swarm_num': the number of the PSO swarms used in the fuzzing process.
+'period_pilot': how many times MOpt-AFL will execute the target program
+	in the pilot fuzzing module, then it will enter the core fuzzing module.
+'period_core': how many times MOpt-AFL will execute the target program in the
+	core fuzzing module, then it will enter the PSO updating module.
+'limit_time_bound': control how many interesting test cases need to be found
+	before MOpt-AFL quits the pacemaker fuzzing mode and reuses the deterministic stage.
+	0 < 'limit_time_bound' < 1, MOpt-AFL-tmp.
+	'limit_time_bound' >= 1, MOpt-AFL-ever.
+
+Have fun with MOpt in AFL!
diff --git a/docs/binaryonly_fuzzing.txt b/docs/binaryonly_fuzzing.txt
index f370ec74..ae5269f0 100644
--- a/docs/binaryonly_fuzzing.txt
+++ b/docs/binaryonly_fuzzing.txt
@@ -11,7 +11,7 @@ then standard afl++ (dumb mode) is not effective.
 The following is a description of how these can be fuzzed with afl++
 
 !!!!!
-DTLR: try DYNINST with afl-dyninst. If it produces too many crashes then
+TL;DR: try DYNINST with afl-dyninst. If it produces too many crashes then
       use afl -Q qemu_mode.
 !!!!!
 
@@ -22,7 +22,7 @@ Qemu is the "native" solution to the program.
 It is available in the ./qemu_mode/ directory and once compiled it can
 be accessed by the afl-fuzz -Q command line option.
 The speed decrease is at about 50%
-It the easiest to use alternative and even works for cross-platform binaries.
+It is the easiest to use alternative and even works for cross-platform binaries.
 
 As it is included in afl++ this needs no URL.
 
@@ -30,7 +30,7 @@ As it is included in afl++ this needs no URL.
 DYNINST
 -------
 Dyninst is a binary instrumentation framework similar to Pintool and Dynamorio
-(see far below). Howver whereas Pintool and Dynamorio work at runtime, dyninst
+(see far below). However whereas Pintool and Dynamorio work at runtime, dyninst
 instruments the target at load time, and then let it run.
 This is great for some things, e.g. fuzzing, and not so effective for others,
 e.g. malware analysis.
@@ -38,15 +38,15 @@ e.g. malware analysis.
 So what we can do with dyninst is taking every basic block, and put afl's
 instrumention code in there - and then save the binary.
 Afterwards we can just fuzz the newly saved target binary with afl-fuzz.
-Sounds great? It is. The issue though - this is a non-trivial problem to
-insert instructions, which changes addresses in the process space and that
-everything still works afterwards. Hence more often than not binaries
-crash when they are run.
+Sounds great? It is. The issue though - it is a non-trivial problem to
+insert instructions, which change addresses in the process space, so
+everything is still working afterwards. Hence more often than not binaries
+crash when they are run (because of instrumentation).
 
 The speed decrease is about 15-35%, depending on the optimization options
 used with afl-dyninst.
 
-So if dyninst works, its the best option available. Otherwise it just doesn't
+So if dyninst works, it is the best option available. Otherwise it just doesn't
 work well.
 
 https://github.com/vanhauser-thc/afl-dyninst
@@ -54,13 +54,14 @@ https://github.com/vanhauser-thc/afl-dyninst
 
 INTEL-PT
 --------
+If you have a newer Intel CPU, you can make use of Intels processor trace.
 The big issue with Intel's PT is the small buffer size and the complex
 encoding of the debug information collected through PT.
 This makes the decoding very CPU intensive and hence slow.
 As a result, the overall speed decrease is about 70-90% (depending on
-the implementation and other factors)
+the implementation and other factors).
 
-there are two afl intel-pt implementations:
+There are two afl intel-pt implementations:
 
 1. https://github.com/junxzm1990/afl-pt
  => this needs Ubuntu 14.04.05 without any updates and the 4.4 kernel.
@@ -73,13 +74,13 @@ there are two afl intel-pt implementations:
 CORESIGHT
 ---------
 
-Coresight is the ARM answer to Intel's PT.
+Coresight is ARM's answer to Intel's PT.
 There is no implementation so far which handle coresight and getting
-it working on an ARM Linux is very difficult due custom kernel building
+it working on an ARM Linux is very difficult due to custom kernel building
 on embedded systems is difficult. And finding one that has coresight in
 the ARM chip is difficult too.
 My guess is that it is slower than Qemu, but faster than Intel PT.
-If anyone finds any coresight implemention for afl please ping me:
+If anyone finds any coresight implementation for afl please ping me:
 vh@thc.org
 
 
diff --git a/docs/env_variables.txt b/docs/env_variables.txt
index 338df36f..1703a947 100644
--- a/docs/env_variables.txt
+++ b/docs/env_variables.txt
@@ -90,7 +90,8 @@ Then there are a few specific features that are only available in llvm_mode:
   LAF-INTEL
   =========
     This great feature will split compares to series of single byte comparisons
-    to allow afl-fuzz to find otherwise rather impossible paths.
+    to allow afl-fuzz to find otherwise rather impossible paths. It is not
+    restricted to Intel CPUs ;-)
 
     - Setting AFL_LLVM_LAF_SPLIT_SWITCHES will split switch()es
 
@@ -105,20 +106,20 @@ Then there are a few specific features that are only available in llvm_mode:
     This feature allows selectively instrumentation of the source
 
     - Setting AFL_LLVM_WHITELIST with a filename will only instrument those
-      files that match these names.
+      files that match the names listed in this file.
 
     See llvm_mode/README.whitelist for more information.
 
   INSTRIM
   =======
     This feature increases the speed by whopping 20% but at the cost of a
-    lower path discovery and thefore coverage.
+    lower path discovery and therefore coverage.
 
     - Setting AFL_LLVM_INSTRIM activates this mode
 
     - Setting AFL_LLVM_INSTRIM_LOOPHEAD=1 expands on INSTRIM to optimize loops.
       afl-fuzz will only be able to see the path the loop took, but not how
-      many times it was called (unless its a complex loop).
+      many times it was called (unless it is a complex loop).
 
     See llvm_mode/README.instrim