selective instrumentation documented

docs/Changelog.md

@@ -9,8 +9,11 @@ Want to stay in the loop on major new features? Join our mailing list by
 sending a mail to <afl-users+subscribe@googlegroups.com>.
 
 
-### Version ++3.01a (release)
+### Version ++3.01a (dev)
   - Mac OS ARM64 support
+  - New selective instrumentation option with __AFL_COVERAGE_... commands
+    to be placed in the source code.
+    Check out instrumentation/README.instrument_list.md
   - afl-fuzz
     - fix crash for very, very fast targets+systems (thanks to mhlakhani
       for reporting)

include/config.h

@@ -186,7 +186,9 @@
 #define TRIM_START_STEPS 16
 #define TRIM_END_STEPS 1024
 
-/* Maximum size of input file, in bytes (keep under 100MB): */
+/* Maximum size of input file, in bytes (keep under 100MB, default 1MB):
+   (note that if this value is changed, several areas in afl-cc.c, afl-fuzz.c
+   and afl-fuzz-state.c have to be changed as well! */
 
 #define MAX_FILE (1 * 1024 * 1024U)
 

instrumentation/README.instrument_list.md

@@ -1,8 +1,9 @@
 # Using afl++ with partial instrumentation
 
-  This file describes how to selectively instrument only source files
+  This file describes two different mechanisms to selectively instrument
-  or functions that are of interest to you using the LLVM and GCC_PLUGIN
+  only specific parts in the target.
-  instrumentation provided by afl++.
+
+  Both mechanisms work for LLVM and GCC_PLUGIN, but not for afl-clang/afl-gcc.
 
 ## 1) Description and purpose
 
@@ -12,28 +13,42 @@ the program, leaving the rest uninstrumented. This helps to focus the fuzzer
 on the important parts of the program, avoiding undesired noise and
 disturbance by uninteresting code being exercised.
 
-For this purpose, a "partial instrumentation" support en par with llvm sancov
+For this purpose, "partial instrumentation" support is provided by afl++ that
-is provided by afl++ that allows to specify on a source file and function
+allows to specify what should be instrumented and what not.
-level which function should be compiled with or without instrumentation.
 
-Note: When using PCGUARD mode - and llvm 12+ - you can use this instead:
+Both mechanisms can be used together.
-https://clang.llvm.org/docs/SanitizerCoverage.html#partially-disabling-instrumentation
 
-The llvm sancov list format is fully supported by afl++, however afl++ has
+## 2) Selective instrumentation with __AFL_COVERAGE_... directives
-more flexibility.
 
-## 2a) Building the LLVM module
+In this mechanism the selective instrumentation is done in the source code.
 
-The new code is part of the existing afl++ LLVM module in the instrumentation/
+After the includes a special define has to be made, eg.:
-subdirectory. There is nothing specifically to do for the build :)
 
-## 2b) Building the GCC module
+```
+#include <stdio.h>
+#include <stdint.h>
+// ...
+ 
+__AFL_COVERAGE();  // <- required for this feature to work
+```
 
-The new code is part of the existing afl++ GCC_PLUGIN module in the
+If you want to disable the coverage at startup until you specify coverage
-instrumentation/ subdirectory. There is nothing specifically to do for
+should be started, then add `__AFL_COVERAGE_START_OFF();` at that position.
-the build :)
 
-## 3) How to use the partial instrumentation mode
+From here on out you have the following macros available that you can use
+in any function where you want:
+
+  * `__AFL_COVERAGE_ON();` - enable coverage from this point onwards
+  * `__AFL_COVERAGE_OFF();` - disable coverage from this point onwards
+  * `__AFL_COVERAGE_DISCARD();` - reset all coverage gathered until this point
+  * `__AFL_COVERAGE_ABORT();` - mark this test case as unimportant. Whatever happens, afl-fuzz will ignore it.
+
+## 3) Selective instrumenation with AFL_LLVM_ALLOWLIST/AFL_LLVM_DENYLIST
+
+This feature is equivalent to llvm 12 sancov feature and allows to specify
+on a filename and/or function name level to instrument these or skip them.
+
+### 3a) How to use the partial instrumentation mode
 
 In order to build with partial instrumentation, you need to build with
 afl-clang-fast/afl-clang-fast++ or afl-clang-lto/afl-clang-lto++.
@@ -90,7 +105,7 @@ fun: MallocFoo
 ```
 Note that whitespace is ignored and comments (`# foo`) are supported.
 
-## 4) UNIX-style pattern matching
+### 3b) UNIX-style pattern matching
 
 You can add UNIX-style pattern matching in the "instrument file list" entries.
 See `man fnmatch` for the syntax. We do not set any of the `fnmatch` flags.

src/afl-cc.c

@@ -827,6 +827,20 @@ static void edit_params(u32 argc, char **argv, char **envp) {
       "extern unsigned char *__afl_fuzz_ptr;"
       "unsigned char __afl_fuzz_alt[1048576];"
       "unsigned char *__afl_fuzz_alt_ptr = __afl_fuzz_alt;";
+  cc_params[cc_par_cnt++] =
+      "-D__AFL_COVERAGE()=int __afl_selective_coverage = 1;"
+      "void __afl_coverage_discard();"
+      "void __afl_coverage_abort();"
+      "void __afl_coverage_on();"
+      "void __afl_coverage_off();";
+  cc_params[cc_par_cnt++] =
+      "-D__AFL_COVERAGE_START_OFF()=int __afl_selective_coverage_start_off = "
+      "1;";
+  cc_params[cc_par_cnt++] = "-D__AFL_COVERAGE_ON()=__afl_coverage_on()";
+  cc_params[cc_par_cnt++] = "-D__AFL_COVERAGE_OFF()=__afl_coverage_off()";
+  cc_params[cc_par_cnt++] =
+      "-D__AFL_COVERAGE_DISCARD()=__afl_coverage_discard()";
+  cc_params[cc_par_cnt++] = "-D__AFL_COVERAGE_ABORT()=__afl_coverage_abort()";
   cc_params[cc_par_cnt++] =
       "-D__AFL_FUZZ_TESTCASE_BUF=(__afl_fuzz_ptr ? __afl_fuzz_ptr : "
       "__afl_fuzz_alt_ptr)";