about summary refs log tree commit diff
path: root/llvm_mode/README.instrument_list.md
diff options
context:
space:
mode:
Diffstat (limited to 'llvm_mode/README.instrument_list.md')
-rw-r--r--llvm_mode/README.instrument_list.md86
1 files changed, 0 insertions, 86 deletions
diff --git a/llvm_mode/README.instrument_list.md b/llvm_mode/README.instrument_list.md
deleted file mode 100644
index 1fc06414..00000000
--- a/llvm_mode/README.instrument_list.md
+++ /dev/null
@@ -1,86 +0,0 @@
-# Using afl++ with partial instrumentation
-
-  This file describes how you can selectively instrument only the source files
-  or functions that are interesting to you using the LLVM instrumentation
-  provided by afl++
-
-## 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
-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
-is provided by afl++ that allows you to specify on a source file and function
-level which function should be compiled with or without instrumentation.
-
-Note: When using PCGUARD mode - and have llvm 12+ - you can use this instead:
-https://clang.llvm.org/docs/SanitizerCoverage.html#partially-disabling-instrumentation
-
-The llvm sancov list format is fully supported by afl++, however afl++ has
-more flexibility.
-
-## 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
-
-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++.
-The only required change is that you need to set either the environment variable
-AFL_LLVM_ALLOWLIST or AFL_LLVM_DENYLIST set with a filename.
-
-That file then contains the filenames or functions that should be instrumented
-(AFL_LLVM_ALLOWLIST) or should specifically NOT be instrumented (AFL_LLVM_DENYLIST).
-
-For matching, the function/filename that is being compiled must end in the
-function/filename entry contained in this instrument file list (to avoid
-breaking the matching when absolute paths are used during compilation).
-
-**NOTE:** In builds with optimization enabled functions might be inlined and would not match!
-
-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 instrument file list file containing:
-```
-feature_a/a1.cpp
-feature_a/a2.cpp
-```
-
-However if the instrument file list file contains only 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 directories.
-
-You can also specify function names. Note that for C++ the function names
-must be mangled to match!
-
-afl++ is able to identify if an entry is a filename or a function.
-However if you want to be sure (and compliant to the sancov allow/blocklist
-format), you can specify source file entries like this:
-```
-src: *malloc.c
-```
-and function entries like this:
-```
-fun: MallocFoo
-```
-Note that whitespace is ignored and comments (`# foo`) are supported.
-
-## 4) UNIX-style pattern matching
-You can add UNIX-style pattern matching in the the instrument file list entries.
-See `man fnmatch` for the syntax. We do not set any of the `fnmatch` flags.