diff options
Diffstat (limited to 'llvm_mode')
| -rw-r--r-- | llvm_mode/README.instrim.md | 3 | ||||
| -rw-r--r-- | llvm_mode/README.laf-intel.md | 23 | ||||
| -rw-r--r-- | llvm_mode/README.md | 7 | ||||
| -rw-r--r-- | llvm_mode/README.neverzero.md | 17 | ||||
| -rw-r--r-- | llvm_mode/README.whitelist.md | 12 |
5 files changed, 40 insertions, 22 deletions
diff --git a/llvm_mode/README.instrim.md b/llvm_mode/README.instrim.md index e5e3614d..b40dbb18 100644 --- a/llvm_mode/README.instrim.md +++ b/llvm_mode/README.instrim.md @@ -10,7 +10,8 @@ path discovery. ## Usage -Set the environment variable `AFL_LLVM_INSTRIM=1`. +Set the environment variable `AFL_LLVM_INSTRIM=1` during compilation of +the target. 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 diff --git a/llvm_mode/README.laf-intel.md b/llvm_mode/README.laf-intel.md index d51c7e2f..c787744b 100644 --- a/llvm_mode/README.laf-intel.md +++ b/llvm_mode/README.laf-intel.md @@ -2,7 +2,7 @@ ## Usage -By default the passes will not run when you compile programs using +By default these 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. @@ -15,11 +15,24 @@ Enables the split-switches pass. `export AFL_LLVM_LAF_TRANSFORM_COMPARES=1` -Enables the transform-compares pass (strcmp, memcmp, strncmp, strcasecmp, strncasecmp). +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>`. - +By default it will +1. simplify operators >= (and <=) into chains of > (<) and == comparisons +2. change signed integer comparisons to a chain of sign-only comparison +and unsigned comparisons +3. split all unsigned integer comparisons with bit widths of +64, 32 or 16 bits to chains of 8 bits comparisons. + +You can change the behaviour of the last step by setting +`export AFL_LLVM_LAF_SPLIT_COMPARES_BITW=<bit_width>`, where +bit_width may be 64, 32 or 16. + +A new experimental feature is splitting floating point comparisons into a +series of sign, exponent and mantissa comparisons followed by splitting each +of them into 8 bit comparisons when necessary. +It is activated with the `AFL_LLVM_LAF_SPLIT_COMPARES` setting. diff --git a/llvm_mode/README.md b/llvm_mode/README.md index f196395b..fa655ed6 100644 --- a/llvm_mode/README.md +++ b/llvm_mode/README.md @@ -27,7 +27,8 @@ several interesting properties: - The instrumentation can cope a bit better with multi-threaded targets. - Because the feature relies on the internals of LLVM, it is clang-specific - and will *not* work with GCC (see ../gcc_plugin/ for an alternative). + and will *not* work with GCC (see ../gcc_plugin/ for an alternative once + it is available). Once this implementation is shown to be sufficiently robust and portable, it will probably replace afl-clang. For now, it can be built separately and @@ -86,7 +87,7 @@ Several options are present to make llvm_mode faster or help it rearrange the code to make afl-fuzz path discovery easier. If you need just to instrument specific parts of the code, you can whitelist -which C/C++ files to actually intrument. See README.whitelist +which C/C++ files to actually instrument. See README.whitelist For splitting memcmp, strncmp, etc. please see README.laf-intel @@ -98,7 +99,7 @@ See README.instrim Finally if your llvm version is 8 or lower, you can activate a mode that prevents that a counter overflow result in a 0 value. This is good for -path discovery, but the llvm implementation for intel for this functionality +path discovery, but the llvm implementation for x86 for this functionality is not optimal and was only fixed in llvm 9. You can set this with AFL_LLVM_NOT_ZERO=1 See README.neverzero diff --git a/llvm_mode/README.neverzero.md b/llvm_mode/README.neverzero.md index 5fcf7b47..1e406560 100644 --- a/llvm_mode/README.neverzero.md +++ b/llvm_mode/README.neverzero.md @@ -2,17 +2,20 @@ ## Usage -In larger, complex or reiterative programs the map that collects the edge pairs -can easily fill up and wrap. -This is not that much of an issue - unless by chance it wraps just to a 0 -when the program execution ends. -In this case afl-fuzz is not able to see that the pair has been accessed and +In larger, complex or reiterative programs the counters that collect the edge +coverage can easily fill up and wrap around. +This is not that much of an issue - unless by chance it wraps just to a value +of zero when the program execution ends. +In this case afl-fuzz is not able to see that the edge has been accessed and will ignore it. -NeverZero prevents this behaviour. If a counter wraps, it jumps over the 0 -directly to a 1. This improves path discovery (by a very little amount) +NeverZero prevents this behaviour. If a counter wraps, it jumps over the value +0 directly to a 1. This improves path discovery (by a very little amount) at a very little cost (one instruction per edge). +(The alternative of saturated counters has been tested also and proved to be +inferior in terms of path discovery.) + This is implemented in afl-gcc, however for llvm_mode this is optional if the llvm version is below 9 - as there is a perfomance bug that is only fixed in version 9 and onwards. diff --git a/llvm_mode/README.whitelist.md b/llvm_mode/README.whitelist.md index 5aededba..6a5770c2 100644 --- a/llvm_mode/README.whitelist.md +++ b/llvm_mode/README.whitelist.md @@ -34,8 +34,8 @@ the compiler. The environment variable must point to a file containing all the filenames that should be instrumented. For matching, the filename that is being compiled -must end in the filename contained in this whitelist (to avoid breaking the -matching when absolute paths are used during compilation). +must end in the filename entry contained in this whitelist (to avoid breaking +the matching when absolute paths are used during compilation). For example if your source tree looks like this: @@ -47,14 +47,14 @@ project/feature_b/b1.cpp project/feature_b/b2.cpp ``` -And you only want to test feature_a, then create a whitelist file containing: +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: +However if the whitelist file contains only this, it works as well: ``` a1.cpp @@ -62,7 +62,7 @@ a2.cpp ``` but it might lead to files being unwantedly instrumented if the same filename -exists somewhere else in the project. +exists somewhere else in the project directories. The created whitelist file is then set to AFL_INST_WHITELIST when you compile your program. For each file that didn't match the whitelist, the compiler will @@ -72,4 +72,4 @@ didn't intend to instrument that file, then you can safely ignore that warning. For old LLVM versions this feature might require to be compiled with debug information (-g), however at least from llvm version 6.0 onwards this is not required anymore (and might hurt performance and crash detection, so better not -use -g) +use -g). |