From b17e298a64875ee4296590e631b672f9ff3b87d6 Mon Sep 17 00:00:00 2001
From: Kostya Serebryany <kcc@google.com>
Date: Fri, 31 Jul 2015 21:48:10 +0000
Subject: [PATCH] [libFuzzer] minimal documentation on data-flow-guided fuzzing

llvm-svn: 243793
---
 clang/docs/SanitizerCoverage.rst | 27 +++++++++++++++++++++++++++
 llvm/docs/LibFuzzer.rst          | 16 ++++++++++++++++
 2 files changed, 43 insertions(+)

diff --git a/clang/docs/SanitizerCoverage.rst b/clang/docs/SanitizerCoverage.rst
index 65af6ffbf010..efcb49e6eb42 100644
--- a/clang/docs/SanitizerCoverage.rst
+++ b/clang/docs/SanitizerCoverage.rst
@@ -249,6 +249,33 @@ These counters may also be used for in-process coverage-guided fuzzers. See
     uintptr_t
     __sanitizer_update_counter_bitset_and_clear_counters(uint8_t *bitset);
 
+Tracing data flow
+=================
+
+An *experimental* feature to support data-flow-guided fuzzing.
+With ``-fsanitize-coverage=trace-cmp`` the compiler will insert extra instrumentation
+around comparison instructions and switch statements.
+The fuzzer will need to define the following functions,
+they will be called by the instrumented code.
+
+.. code-block:: c++
+
+  // Called before a comparison instruction.
+  // SizeAndType is a packed value containing
+  //   - [63:32] the Size of the operands of comparison in bits
+  //   - [31:0] the Type of comparison (one of ICMP_EQ, ... ICMP_SLE)
+  // Arg1 and Arg2 are arguments of the comparison.
+  void __sanitizer_cov_trace_cmp(uint64_t SizeAndType, uint64_t Arg1, uint64_t Arg2);
+
+  // Called before a switch statement.
+  // Val is the switch operand.
+  // Cases[0] is the number of case constants.
+  // Cases[1] is the size of Val in bits.
+  // Cases[2:] are the case constants.
+  void __sanitizer_cov_trace_switch(uint64_t Val, uint64_t *Cases);
+
+This interface is a subject to change.
+
 Output directory
 ================
 
diff --git a/llvm/docs/LibFuzzer.rst b/llvm/docs/LibFuzzer.rst
index 1ac75a406985..3b074aad6a13 100644
--- a/llvm/docs/LibFuzzer.rst
+++ b/llvm/docs/LibFuzzer.rst
@@ -68,6 +68,8 @@ The most important flags are::
   apply_tokens                       	0	Read the given input file, substitute bytes  with tokens and write the result to stdout.
   sync_command                       	0	Execute an external command "<sync_command> <test_corpus>" to synchronize the test corpus.
   sync_timeout                       	600	Minimum timeout between syncs.
+  use_traces                            0       Experimental: use instruction traces
+
 
 For the full list of flags run the fuzzer binary with ``-help=1``.
 
@@ -273,6 +275,18 @@ The fuzzer itself will still be mutating a string of bytes
 but before passing this input to the target library it will replace every byte ``b`` with the ``b``-th token.
 If there are less than ``b`` tokens, a space will be added instead.
 
+Data-flow-guided fuzzing
+------------------------
+
+*EXPERIMENTAL*.
+With an additional compiler flag ``-fsanitize-coverage=trace-cmp`` (see SanitizerCoverageTraceDataFlow_)
+and extra run-time flag ``-use_traces=1`` the fuzzer will try to apply *data-flow-guided fuzzing*.
+That is, the fuzzer will record the inputs to comparison instructions, switch statements,
+and several libc functions (``memcmp``, ``strncmp``, etc).
+It will later use those recorded inputs during mutations.
+
+This mode can be combined with DataFlowSanitizer_ to achieve better sensitivity.
+
 AFL compatibility
 -----------------
 LibFuzzer can be used in parallel with AFL_ on the same test corpus.
@@ -412,6 +426,8 @@ Examples: regular expression matchers, text or binary format parsers.
 .. _AFL: http://lcamtuf.coredump.cx/afl/
 
 .. _SanitizerCoverage: http://clang.llvm.org/docs/SanitizerCoverage.html
+.. _SanitizerCoverageTraceDataFlow: http://clang.llvm.org/docs/SanitizerCoverage.html#tracing-data-flow
+.. _DataFlowSanitizer: http://clang.llvm.org/docs/DataFlowSanitizer.html
 
 .. _Heartbleed: http://en.wikipedia.org/wiki/Heartbleed