Vendor import of llvm release_39 branch r276489:vendor/llvm/llvm-release_39-r276489

https://llvm.org/svn/llvm-project/llvm/branches/release_39@276489

1 files changed, 578 insertions, 177 deletions

diff --git a/docs/LibFuzzer.rst b/docs/LibFuzzer.rst
index 84adff3616f7..92937c2d0b52 100644
--- a/docs/LibFuzzer.rst
+++ b/docs/LibFuzzer.rst
@@ -1,90 +1,373 @@
-========================================================
-LibFuzzer -- a library for coverage-guided fuzz testing.
-========================================================
+=======================================================
+libFuzzer – a library for coverage-guided fuzz testing.
+=======================================================
 .. contents::
    :local:
-   :depth: 4
+   :depth: 1
 
 Introduction
 ============
 
-This library is intended primarily for in-process coverage-guided fuzz testing
-(fuzzing) of other libraries. The typical workflow looks like this:
-
-* Build the Fuzzer library as a static archive (or just a set of .o files).
-  Note that the Fuzzer contains the main() function.
-  Preferably do *not* use sanitizers while building the Fuzzer.
-* Build the library you are going to test with
-  `-fsanitize-coverage={bb,edge}[,indirect-calls,8bit-counters]`
-  and one of the sanitizers. We recommend to build the library in several
-  different modes (e.g. asan, msan, lsan, ubsan, etc) and even using different
-  optimizations options (e.g. -O0, -O1, -O2) to diversify testing.
-* Build a test driver using the same options as the library.
-  The test driver is a C/C++ file containing interesting calls to the library
-  inside a single function  ``extern "C" int LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size);``.
-  Currently, the only expected return value is 0, others are reserved for future.
-* Link the Fuzzer, the library and the driver together into an executable
-  using the same sanitizer options as for the library.
-* Collect the initial corpus of inputs for the
-  fuzzer (a directory with test inputs, one file per input).
-  The better your inputs are the faster you will find something interesting.
-  Also try to keep your inputs small, otherwise the Fuzzer will run too slow.
-  By default, the Fuzzer limits the size of every input to 64 bytes
-  (use ``-max_len=N`` to override).
-* Run the fuzzer with the test corpus. As new interesting test cases are
-  discovered they will be added to the corpus. If a bug is discovered by
-  the sanitizer (asan, etc) it will be reported as usual and the reproducer
-  will be written to disk.
-  Each Fuzzer process is single-threaded (unless the library starts its own
-  threads). You can run the Fuzzer on the same corpus in multiple processes
-  in parallel.
-
-
-The Fuzzer is similar in concept to AFL_,
-but uses in-process Fuzzing, which is more fragile, more restrictive, but
-potentially much faster as it has no overhead for process start-up.
-It uses LLVM's SanitizerCoverage_ instrumentation to get in-process
-coverage-feedback
-
-The code resides in the LLVM repository, requires the fresh Clang compiler to build
-and is used to fuzz various parts of LLVM,
-but the Fuzzer itself does not (and should not) depend on any
-part of LLVM and can be used for other projects w/o requiring the rest of LLVM.
-
-Flags
-=====
-The most important flags are::
-
-  seed                               	0	Random seed. If 0, seed is generated.
-  runs                               	-1	Number of individual test runs (-1 for infinite runs).
-  max_len                            	64	Maximum length of the test input.
-  cross_over                         	1	If 1, cross over inputs.
-  mutate_depth                       	5	Apply this number of consecutive mutations to each input.
-  timeout                            	1200	Timeout in seconds (if positive). If one unit runs more than this number of seconds the process will abort.
-  max_total_time                        0       If positive, indicates the maximal total time in seconds to run the fuzzer.
-  help                               	0	Print help.
-  merge                                 0       If 1, the 2-nd, 3-rd, etc corpora will be merged into the 1-st corpus. Only interesting units will be taken.
-  jobs                               	0	Number of jobs to run. If jobs >= 1 we spawn this number of jobs in separate worker processes with stdout/stderr redirected to fuzz-JOB.log.
-  workers                            	0	Number of simultaneous worker processes to run the jobs. If zero, "min(jobs,NumberOfCpuCores()/2)" is used.
-  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
-  only_ascii                            0       If 1, generate only ASCII (isprint+isspace) inputs.
-  test_single_input                     ""      Use specified file content as test input. Test will be run only once. Useful for debugging a particular case.
-  artifact_prefix                       ""      Write fuzzing artifacts (crash, timeout, or slow inputs) as $(artifact_prefix)file
-  exact_artifact_path                   ""      Write the single artifact on failure (crash, timeout) as $(exact_artifact_path). This overrides -artifact_prefix and will not use checksum in the file name. Do not use the same path for several parallel processes.
+LibFuzzer is a library for in-process, coverage-guided, evolutionary fuzzing
+of other libraries.
+
+LibFuzzer is similar in concept to American Fuzzy Lop (AFL_), but it performs
+all of its fuzzing inside a single process.  This in-process fuzzing can be more
+restrictive and fragile, but is potentially much faster as there is no overhead
+for process start-up.
+
+The fuzzer is linked with the library under test, and feeds fuzzed inputs to the
+library via a specific fuzzing entrypoint (aka "target function"); the fuzzer
+then tracks which areas of the code are reached, and generates mutations on the
+corpus of input data in order to maximize the code coverage.  The code coverage
+information for libFuzzer is provided by LLVM's SanitizerCoverage_
+instrumentation.
+
+Contact: libfuzzer(#)googlegroups.com
+
+Versions
+========
+
+LibFuzzer is under active development so a current (or at least very recent)
+version of Clang is the only supported variant.
+
+(If `building Clang from trunk`_ is too time-consuming or difficult, then
+the Clang binaries that the Chromium developers build are likely to be
+fairly recent:
+
+.. code-block:: console
+
+  mkdir TMP_CLANG
+  cd TMP_CLANG
+  git clone https://chromium.googlesource.com/chromium/src/tools/clang
+  cd ..
+  TMP_CLANG/clang/scripts/update.py
+
+This installs the Clang binary as
+``./third_party/llvm-build/Release+Asserts/bin/clang``)
+
+The libFuzzer code resides in the LLVM repository, and requires a recent Clang
+compiler to build (and is used to `fuzz various parts of LLVM itself`_).
+However the fuzzer itself does not (and should not) depend on any part of LLVM
+infrastructure and can be used for other projects without requiring the rest
+of LLVM.
+
+
+
+Getting Started
+===============
+
+.. contents::
+   :local:
+   :depth: 1
+
+Building
+--------
+
+The first step for using libFuzzer on a library is to implement a fuzzing
+target function that accepts a sequence of bytes, like this:
+
+.. code-block:: c++
+
+  // fuzz_target.cc
+  extern "C" int LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size) {
+    DoSomethingInterestingWithMyAPI(Data, Size);
+    return 0;  // Non-zero return values are reserved for future use.
+  }
+
+Next, build the libFuzzer library as a static archive, without any sanitizer
+options. Note that the libFuzzer library contains the ``main()`` function:
+
+.. code-block:: console
+
+  svn co http://llvm.org/svn/llvm-project/llvm/trunk/lib/Fuzzer
+  # Alternative: get libFuzzer from a dedicated git mirror:
+  # git clone https://chromium.googlesource.com/chromium/llvm-project/llvm/lib/Fuzzer
+  clang++ -c -g -O2 -std=c++11 Fuzzer/*.cpp -IFuzzer
+  ar ruv libFuzzer.a Fuzzer*.o
+
+Then build the fuzzing target function and the library under test using
+the SanitizerCoverage_ option, which instruments the code so that the fuzzer
+can retrieve code coverage information (to guide the fuzzing).  Linking with
+the libFuzzer code then gives an fuzzer executable.
+
+You should also enable one or more of the *sanitizers*, which help to expose
+latent bugs by making incorrect behavior generate errors at runtime:
+
+ - AddressSanitizer_ (ASAN) detects memory access errors. Use `-fsanitize=address`.
+ - UndefinedBehaviorSanitizer_ (UBSAN) detects the use of various features of C/C++ that are explicitly
+   listed as resulting in undefined behavior.  Use `-fsanitize=undefined -fno-sanitize-recover=undefined`
+   or any individual UBSAN check, e.g.  `-fsanitize=signed-integer-overflow -fno-sanitize-recover=undefined`.
+   You may combine ASAN and UBSAN in one build.
+ - MemorySanitizer_ (MSAN) detects uninitialized reads: code whose behavior relies on memory
+   contents that have not been initialized to a specific value. Use `-fsanitize=memory`.
+   MSAN can not be combined with other sanirizers and should be used as a seprate build.
+
+Finally, link with ``libFuzzer.a``::
+
+  clang -fsanitize-coverage=edge -fsanitize=address your_lib.cc fuzz_target.cc libFuzzer.a -o my_fuzzer
+
+Corpus
+------
+
+Coverage-guided fuzzers like libFuzzer rely on a corpus of sample inputs for the
+code under test.  This corpus should ideally be seeded with a varied collection
+of valid and invalid inputs for the code under test; for example, for a graphics
+library the initial corpus might hold a variety of different small PNG/JPG/GIF
+files.  The fuzzer generates random mutations based around the sample inputs in
+the current corpus.  If a mutation triggers execution of a previously-uncovered
+path in the code under test, then that mutation is saved to the corpus for
+future variations.
+
+LibFuzzer will work without any initial seeds, but will be less
+efficient if the library under test accepts complex,
+structured inputs.
+
+The corpus can also act as a sanity/regression check, to confirm that the
+fuzzing entrypoint still works and that all of the sample inputs run through
+the code under test without problems.
+
+If you have a large corpus (either generated by fuzzing or acquired by other means)
+you may want to minimize it while still preserving the full coverage. One way to do that
+is to use the `-merge=1` flag:
+
+.. code-block:: console
+
+  mkdir NEW_CORPUS_DIR  # Store minimized corpus here.
+  ./my_fuzzer -merge=1 NEW_CORPUS_DIR FULL_CORPUS_DIR
+
+You may use the same flag to add more interesting items to an existing corpus.
+Only the inputs that trigger new coverage will be added to the first corpus.
+
+.. code-block:: console
+
+  ./my_fuzzer -merge=1 CURRENT_CORPUS_DIR NEW_POTENTIALLY_INTERESTING_INPUTS_DIR
+
+
+Running
+-------
+
+To run the fuzzer, first create a Corpus_ directory that holds the
+initial "seed" sample inputs:
+
+.. code-block:: console
+
+  mkdir CORPUS_DIR
+  cp /some/input/samples/* CORPUS_DIR
+
+Then run the fuzzer on the corpus directory:
+
+.. code-block:: console
+
+  ./my_fuzzer CORPUS_DIR  # -max_len=1000 -jobs=20 ...
+
+As the fuzzer discovers new interesting test cases (i.e. test cases that
+trigger coverage of new paths through the code under test), those test cases
+will be added to the corpus directory.
+
+By default, the fuzzing process will continue indefinitely – at least until
+a bug is found.  Any crashes or sanitizer failures will be reported as usual,
+stopping the fuzzing process, and the particular input that triggered the bug
+will be written to disk (typically as ``crash-<sha1>``, ``leak-<sha1>``,
+or ``timeout-<sha1>``).
+
+
+Parallel Fuzzing
+----------------
+
+Each libFuzzer process is single-threaded, unless the library under test starts
+its own threads.  However, it is possible to run multiple libFuzzer processes in
+parallel with a shared corpus directory; this has the advantage that any new
+inputs found by one fuzzer process will be available to the other fuzzer
+processes (unless you disable this with the ``-reload=0`` option).
+
+This is primarily controlled by the ``-jobs=N`` option, which indicates that
+that `N` fuzzing jobs should be run to completion (i.e. until a bug is found or
+time/iteration limits are reached).  These jobs will be run across a set of
+worker processes, by default using half of the available CPU cores; the count of
+worker processes can be overridden by the ``-workers=N`` option.  For example,
+running with ``-jobs=30`` on a 12-core machine would run 6 workers by default,
+with each worker averaging 5 bugs by completion of the entire process.
+
+
+Options
+=======
+
+To run the fuzzer, pass zero or more corpus directories as command line
+arguments.  The fuzzer will read test inputs from each of these corpus
+directories, and any new test inputs that are generated will be written
+back to the first corpus directory:
+
+.. code-block:: console
+
+  ./fuzzer [-flag1=val1 [-flag2=val2 ...] ] [dir1 [dir2 ...] ]
+
+If a list of files (rather than directories) are passed to the fuzzer program,
+then it will re-run those files as test inputs but will not perform any fuzzing.
+In this mode the fuzzer binary can be used as a regression test (e.g. on a
+continuous integration system) to check the target function and saved inputs
+still work.
+
+The most important command line options are:
+
+``-help``
+  Print help message.
+``-seed``
+  Random seed. If 0 (the default), the seed is generated.
+``-runs``
+  Number of individual test runs, -1 (the default) to run indefinitely.
+``-max_len``
+  Maximum length of a test input. If 0 (the default), libFuzzer tries to guess
+  a good value based on the corpus (and reports it).
+``-timeout``
+  Timeout in seconds, default 1200. If an input takes longer than this timeout,
+  the process is treated as a failure case.
+``-rss_limit_mb``
+  Memory usage limit in Mb, default 2048. Use 0 to disable the limit.
+  If an input requires more than this amount of RSS memory to execute,
+  the process is treated as a failure case.
+  The limit is checked in a separate thread every second.
+  If running w/o ASAN/MSAN, you may use 'ulimit -v' instead.
+``-timeout_exitcode``
+  Exit code (default 77) to emit when terminating due to timeout, when
+  ``-abort_on_timeout`` is not set.
+``-max_total_time``
+  If positive, indicates the maximum total time in seconds to run the fuzzer.
+  If 0 (the default), run indefinitely.
+``-merge``
+  If set to 1, any corpus inputs from the 2nd, 3rd etc. corpus directories
+  that trigger new code coverage will be merged into the first corpus
+  directory.  Defaults to 0. This flag can be used to minimize a corpus.
+``-reload``
+  If set to 1 (the default), the corpus directory is re-read periodically to
+  check for new inputs; this allows detection of new inputs that were discovered
+  by other fuzzing processes.
+``-jobs``
+  Number of fuzzing jobs to run to completion. Default value is 0, which runs a
+  single fuzzing process until completion.  If the value is >= 1, then this
+  number of jobs performing fuzzing are run, in a collection of parallel
+  separate worker processes; each such worker process has its
+  ``stdout``/``stderr`` redirected to ``fuzz-<JOB>.log``.
+``-workers``
+  Number of simultaneous worker processes to run the fuzzing jobs to completion
+  in. If 0 (the default), ``min(jobs, NumberOfCpuCores()/2)`` is used.
+``-dict``
+  Provide a dictionary of input keywords; see Dictionaries_.
+``-use_counters``
+  Use `coverage counters`_ to generate approximate counts of how often code
+  blocks are hit; defaults to 1.
+``-use_traces``
+  Use instruction traces (experimental, defaults to 0); see `Data-flow-guided fuzzing`_.
+``-only_ascii``
+  If 1, generate only ASCII (``isprint``+``isspace``) inputs. Defaults to 0.
+``-artifact_prefix``
+  Provide a prefix to use when saving fuzzing artifacts (crash, timeout, or
+  slow inputs) as ``$(artifact_prefix)file``.  Defaults to empty.
+``-exact_artifact_path``
+  Ignored if empty (the default).  If non-empty, write the single artifact on
+  failure (crash, timeout) as ``$(exact_artifact_path)``. This overrides
+  ``-artifact_prefix`` and will not use checksum in the file name. Do not use
+  the same path for several parallel processes.
+``-print_final_stats``
+  If 1, print statistics at exit.  Defaults to 0.
+``-detect-leaks``
+  If 1 (default) and if LeakSanitizer is enabled
+  try to detect memory leaks during fuzzing (i.e. not only at shut down).
+``-close_fd_mask``
+  Indicate output streams to close at startup. Be careful, this will
+  remove diagnostic output from target code (e.g. messages on assert failure).
+
+   - 0 (default): close neither ``stdout`` nor ``stderr``
+   - 1 : close ``stdout``
+   - 2 : close ``stderr``
+   - 3 : close both ``stdout`` and ``stderr``.
 
 For the full list of flags run the fuzzer binary with ``-help=1``.
 
-Usage examples
-==============
+Output
+======
+
+During operation the fuzzer prints information to ``stderr``, for example::
+
+  INFO: Seed: 3338750330
+  Loaded 1024/1211 files from corpus/
+  INFO: -max_len is not provided, using 64
+  #0	READ   units: 1211 exec/s: 0
+  #1211	INITED cov: 2575 bits: 8855 indir: 5 units: 830 exec/s: 1211
+  #1422	NEW    cov: 2580 bits: 8860 indir: 5 units: 831 exec/s: 1422 L: 21 MS: 1 ShuffleBytes-
+  #1688	NEW    cov: 2581 bits: 8865 indir: 5 units: 832 exec/s: 1688 L: 19 MS: 2 EraseByte-CrossOver-
+  #1734	NEW    cov: 2583 bits: 8879 indir: 5 units: 833 exec/s: 1734 L: 27 MS: 3 ChangeBit-EraseByte-ShuffleBytes-
+  ...
+
+The early parts of the output include information about the fuzzer options and
+configuration, including the current random seed (in the ``Seed:`` line; this
+can be overridden with the ``-seed=N`` flag).
+
+Further output lines have the form of an event code and statistics.  The
+possible event codes are:
+
+``READ``
+  The fuzzer has read in all of the provided input samples from the corpus
+  directories.
+``INITED``
+  The fuzzer has completed initialization, which includes running each of
+  the initial input samples through the code under test.
+``NEW``
+  The fuzzer has created a test input that covers new areas of the code
+  under test.  This input will be saved to the primary corpus directory.
+``pulse``
+  The fuzzer has generated 2\ :sup:`n` inputs (generated periodically to reassure
+  the user that the fuzzer is still working).
+``DONE``
+  The fuzzer has completed operation because it has reached the specified
+  iteration limit (``-runs``) or time limit (``-max_total_time``).
+``MIN<n>``
+  The fuzzer is minimizing the combination of input corpus directories into
+  a single unified corpus (due to the ``-merge`` command line option).
+``RELOAD``
+  The fuzzer is performing a periodic reload of inputs from the corpus
+  directory; this allows it to discover any inputs discovered by other
+  fuzzer processes (see `Parallel Fuzzing`_).
+
+Each output line also reports the following statistics (when non-zero):
+
+``cov:``
+  Total number of code blocks or edges covered by the executing the current
+  corpus.
+``bits:``
+  Rough measure of the number of code blocks or edges covered, and how often;
+  only valid if the fuzzer is run with ``-use_counters=1``.
+``indir:``
+  Number of distinct function `caller-callee pairs`_ executed with the
+  current corpus; only valid if the code under test was built with
+  ``-fsanitize-coverage=indirect-calls``.
+``units:``
+  Number of entries in the current input corpus.
+``exec/s:``
+  Number of fuzzer iterations per second.
+
+For ``NEW`` events, the output line also includes information about the mutation
+operation that produced the new input:
+
+``L:``
+  Size of the new input in bytes.
+``MS: <n> <operations>``
+  Count and list of the mutation operations used to generate the input.
+
+
+Examples
+========
+.. contents::
+   :local:
+   :depth: 1
 
 Toy example
 -----------
 
-A simple function that does something interesting if it receives the input "HI!"::
+A simple function that does something interesting if it receives the input
+"HI!"::
 
-  cat << EOF >> test_fuzzer.cc
+  cat << EOF > test_fuzzer.cc
   #include <stdint.h>
   #include <stddef.h>
   extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
@@ -95,32 +378,37 @@ A simple function that does something interesting if it receives the input "HI!"
     return 0;
   }
   EOF
-  # Get lib/Fuzzer. Assuming that you already have fresh clang in PATH.
-  svn co http://llvm.org/svn/llvm-project/llvm/trunk/lib/Fuzzer
-  # Build lib/Fuzzer files.
-  clang -c -g -O2 -std=c++11 Fuzzer/*.cpp -IFuzzer
-  # Build test_fuzzer.cc with asan and link against lib/Fuzzer.
-  clang++ -fsanitize=address -fsanitize-coverage=edge test_fuzzer.cc Fuzzer*.o
+  # Build test_fuzzer.cc with asan and link against libFuzzer.a
+  clang++ -fsanitize=address -fsanitize-coverage=edge test_fuzzer.cc libFuzzer.a
   # Run the fuzzer with no corpus.
   ./a.out
 
-You should get ``Illegal instruction (core dumped)`` pretty quickly.
+You should get an error pretty quickly::
+
+  #0  READ   units: 1 exec/s: 0
+  #1  INITED cov: 3 units: 1 exec/s: 0
+  #2  NEW    cov: 5 units: 2 exec/s: 0 L: 64 MS: 0
+  #19237  NEW    cov: 9 units: 3 exec/s: 0 L: 64 MS: 0
+  #20595  NEW    cov: 10 units: 4 exec/s: 0 L: 1 MS: 4 ChangeASCIIInt-ShuffleBytes-ChangeByte-CrossOver-
+  #34574  NEW    cov: 13 units: 5 exec/s: 0 L: 2 MS: 3 ShuffleBytes-CrossOver-ChangeBit-
+  #34807  NEW    cov: 15 units: 6 exec/s: 0 L: 3 MS: 1 CrossOver-
+  ==31511== ERROR: libFuzzer: deadly signal
+  ...
+  artifact_prefix='./'; Test unit written to ./crash-b13e8756b13a00cf168300179061fb4b91fefbed
+
 
 PCRE2
 -----
 
-Here we show how to use lib/Fuzzer on something real, yet simple: pcre2_::
+Here we show how to use libFuzzer on something real, yet simple: pcre2_::
 
   COV_FLAGS=" -fsanitize-coverage=edge,indirect-calls,8bit-counters"
   # Get PCRE2
-  svn co svn://vcs.exim.org/pcre2/code/trunk pcre
-  # Get lib/Fuzzer. Assuming that you already have fresh clang in PATH.
-  svn co http://llvm.org/svn/llvm-project/llvm/trunk/lib/Fuzzer
-  # Build PCRE2 with AddressSanitizer and coverage.
-  (cd pcre; ./autogen.sh; CC="clang -fsanitize=address $COV_FLAGS" ./configure --prefix=`pwd`/../inst && make -j && make install)
-  # Build lib/Fuzzer files.
-  clang -c -g -O2 -std=c++11 Fuzzer/*.cpp -IFuzzer
-  # Build the actual function that does something interesting with PCRE2.
+  wget ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/pcre2-10.20.tar.gz
+  tar xf pcre2-10.20.tar.gz
+  # Build PCRE2 with AddressSanitizer and coverage; requires autotools.
+  (cd pcre2-10.20; ./autogen.sh; CC="clang -fsanitize=address $COV_FLAGS" ./configure --prefix=`pwd`/../inst && make -j && make install)
+  # Build the fuzzing target function that does something interesting with PCRE2.
   cat << EOF > pcre_fuzzer.cc
   #include <string.h>
   #include <stdint.h>
@@ -141,61 +429,67 @@ Here we show how to use lib/Fuzzer on something real, yet simple: pcre2_::
   EOF
   clang++ -g -fsanitize=address $COV_FLAGS -c -std=c++11  -I inst/include/ pcre_fuzzer.cc
   # Link.
-  clang++ -g -fsanitize=address -Wl,--whole-archive inst/lib/*.a -Wl,-no-whole-archive Fuzzer*.o pcre_fuzzer.o -o pcre_fuzzer
+  clang++ -g -fsanitize=address -Wl,--whole-archive inst/lib/*.a -Wl,-no-whole-archive libFuzzer.a pcre_fuzzer.o -o pcre_fuzzer
 
 This will give you a binary of the fuzzer, called ``pcre_fuzzer``.
-Now, create a directory that will hold the test corpus::
+Now, create a directory that will hold the test corpus:
+
+.. code-block:: console
 
   mkdir -p CORPUS
 
 For simple input languages like regular expressions this is all you need.
-For more complicated inputs populate the directory with some input samples.
-Now run the fuzzer with the corpus dir as the only parameter::
+For more complicated/structured inputs, the fuzzer works much more efficiently
+if you can populate the corpus directory with a variety of valid and invalid
+inputs for the code under test.
+Now run the fuzzer with the corpus directory as the only parameter:
 
-  ./pcre_fuzzer ./CORPUS
+.. code-block:: console
 
-You will see output like this::
+  ./pcre_fuzzer ./CORPUS
 
-  Seed: 1876794929
-  #0      READ   cov 0 bits 0 units 1 exec/s 0
-  #1      pulse  cov 3 bits 0 units 1 exec/s 0
-  #1      INITED cov 3 bits 0 units 1 exec/s 0
-  #2      pulse  cov 208 bits 0 units 1 exec/s 0
-  #2      NEW    cov 208 bits 0 units 2 exec/s 0 L: 64
-  #3      NEW    cov 217 bits 0 units 3 exec/s 0 L: 63
-  #4      pulse  cov 217 bits 0 units 3 exec/s 0
+Initially, you will see Output_ like this::
 
-* The ``Seed:`` line shows you the current random seed (you can change it with ``-seed=N`` flag).
-* The ``READ``  line shows you how many input files were read (since you passed an empty dir there were inputs, but one dummy input was synthesised).
-* The ``INITED`` line shows you that how many inputs will be fuzzed.
-* The ``NEW`` lines appear with the fuzzer finds a new interesting input, which is saved to the CORPUS dir. If multiple corpus dirs are given, the first one is used.
-* The ``pulse`` lines appear periodically to show the current status.
+  INFO: Seed: 2938818941
+  INFO: -max_len is not provided, using 64
+  INFO: A corpus is not provided, starting from an empty corpus
+  #0	READ   units: 1 exec/s: 0
+  #1	INITED cov: 3 bits: 3 units: 1 exec/s: 0
+  #2	NEW    cov: 176 bits: 176 indir: 3 units: 2 exec/s: 0 L: 64 MS: 0
+  #8	NEW    cov: 176 bits: 179 indir: 3 units: 3 exec/s: 0 L: 63 MS: 2 ChangeByte-EraseByte-
+  ...
+  #14004	NEW    cov: 1500 bits: 4536 indir: 5 units: 406 exec/s: 0 L: 54 MS: 3 ChangeBit-ChangeBit-CrossOver-
 
 Now, interrupt the fuzzer and run it again the same way. You will see::
 
-  Seed: 1879995378
-  #0      READ   cov 0 bits 0 units 564 exec/s 0
-  #1      pulse  cov 502 bits 0 units 564 exec/s 0
+  INFO: Seed: 3398349082
+  INFO: -max_len is not provided, using 64
+  #0	READ   units: 405 exec/s: 0
+  #405	INITED cov: 1499 bits: 4535 indir: 5 units: 286 exec/s: 0
+  #587	NEW    cov: 1499 bits: 4540 indir: 5 units: 287 exec/s: 0 L: 52 MS: 2 InsertByte-EraseByte-
+  #667	NEW    cov: 1501 bits: 4542 indir: 5 units: 288 exec/s: 0 L: 39 MS: 2 ChangeBit-InsertByte-
+  #672	NEW    cov: 1501 bits: 4543 indir: 5 units: 289 exec/s: 0 L: 15 MS: 2 ChangeASCIIInt-ChangeBit-
+  #739	NEW    cov: 1501 bits: 4544 indir: 5 units: 290 exec/s: 0 L: 64 MS: 4 ShuffleBytes-ChangeASCIIInt-InsertByte-ChangeBit-
   ...
-  #512    pulse  cov 2933 bits 0 units 564 exec/s 512
-  #564    INITED cov 2991 bits 0 units 344 exec/s 564
-  #1024   pulse  cov 2991 bits 0 units 344 exec/s 1024
-  #1455   NEW    cov 2995 bits 0 units 345 exec/s 1455 L: 49
 
-This time you were running the fuzzer with a non-empty input corpus (564 items).
-As the first step, the fuzzer minimized the set to produce 344 interesting items (the ``INITED`` line)
+On the second execution the fuzzer has a non-empty input corpus (405 items).  As
+the first step, the fuzzer minimized this corpus (the ``INITED`` line) to
+produce 286 interesting items, omitting inputs that do not hit any additional
+code.
 
-It is quite convenient to store test corpuses in git.
-As an example, here is a git repository with test inputs for the above PCRE2 fuzzer::
+(Aside: although the fuzzer only saves new inputs that hit additional code, this
+does not mean that the corpus as a whole is kept minimized.  For example, if
+an input hitting A-B-C then an input that hits A-B-C-D are generated,
+they will both be saved, even though the latter subsumes the former.)
 
-  git clone https://github.com/kcc/fuzzing-with-sanitizers.git
-  ./pcre_fuzzer ./fuzzing-with-sanitizers/pcre2/C1/
 
-You may run ``N`` independent fuzzer jobs in parallel on ``M`` CPUs::
+You may run ``N`` independent fuzzer jobs in parallel on ``M`` CPUs:
+
+.. code-block:: console
 
   N=100; M=4; ./pcre_fuzzer ./CORPUS -jobs=$N -workers=$M
 
-By default (``-reload=1``) the fuzzer processes will periodically scan the CORPUS directory
+By default (``-reload=1``) the fuzzer processes will periodically scan the corpus directory
 and reload any new tests. This way the test inputs found by one process will be picked up
 by all others.
 
@@ -205,15 +499,15 @@ Heartbleed
 ----------
 Remember Heartbleed_?
 As it was recently `shown <https://blog.hboeck.de/archives/868-How-Heartbleed-couldve-been-found.html>`_,
-fuzzing with AddressSanitizer can find Heartbleed. Indeed, here are the step-by-step instructions
-to find Heartbleed with LibFuzzer::
+fuzzing with AddressSanitizer_ can find Heartbleed. Indeed, here are the step-by-step instructions
+to find Heartbleed with libFuzzer::
 
   wget https://www.openssl.org/source/openssl-1.0.1f.tar.gz
   tar xf openssl-1.0.1f.tar.gz
   COV_FLAGS="-fsanitize-coverage=edge,indirect-calls" # -fsanitize-coverage=8bit-counters
   (cd openssl-1.0.1f/ && ./config &&
     make -j 32 CC="clang -g -fsanitize=address $COV_FLAGS")
-  # Get and build LibFuzzer
+  # Get and build libFuzzer
   svn co http://llvm.org/svn/llvm-project/llvm/trunk/lib/Fuzzer
   clang -c -g -O2 -std=c++11 Fuzzer/*.cpp -IFuzzer
   # Get examples of key/pem files.
@@ -267,14 +561,16 @@ Voila::
       #2 0x580be3 in ssl3_read_bytes openssl-1.0.1f/ssl/s3_pkt.c:1092:4
 
 Note: a `similar fuzzer <https://boringssl.googlesource.com/boringssl/+/HEAD/FUZZING.md>`_
-is now a part of the boringssl source tree.
+is now a part of the BoringSSL_ source tree.
 
 Advanced features
 =================
+.. contents::
+   :local:
+   :depth: 1
 
 Dictionaries
 ------------
-*EXPERIMENTAL*.
 LibFuzzer supports user-supplied dictionaries with input language keywords
 or other interesting byte sequences (e.g. multi-byte magic values).
 Use ``-dict=DICTIONARY_FILE``. For some input languages using a dictionary
@@ -304,16 +600,51 @@ It will later use those recorded inputs during mutations.
 
 This mode can be combined with DataFlowSanitizer_ to achieve better sensitivity.
 
+Fuzzer-friendly build mode
+---------------------------
+Sometimes the code under test is not fuzzing-friendly. Examples:
+
+  - The target code uses a PRNG seeded e.g. by system time and
+    thus two consequent invocations may potentially execute different code paths
+    even if the end result will be the same. This will cause a fuzzer to treat
+    two similar inputs as significantly different and it will blow up the test corpus.
+    E.g. libxml uses ``rand()`` inside its hash table.
+  - The target code uses checksums to protect from invalid inputs.
+    E.g. png checks CRC for every chunk.
+
+In many cases it makes sense to build a special fuzzing-friendly build
+with certain fuzzing-unfriendly features disabled. We propose to use a common build macro
+for all such cases for consistency: ``FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION``.
+
+.. code-block:: c++
+
+  void MyInitPRNG() {
+  #ifdef FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION
+    // In fuzzing mode the behavior of the code should be deterministic.
+    srand(0);
+  #else
+    srand(time(0));
+  #endif
+  }
+
+
+
 AFL compatibility
 -----------------
-LibFuzzer can be used in parallel with AFL_ on the same test corpus.
+LibFuzzer can be used together with AFL_ on the same test corpus.
 Both fuzzers expect the test corpus to reside in a directory, one file per input.
-You can run both fuzzers on the same corpus in parallel::
+You can run both fuzzers on the same corpus, one after another:
+
+.. code-block:: console
 
-  ./afl-fuzz -i testcase_dir -o findings_dir /path/to/program -r @@
+  ./afl-fuzz -i testcase_dir -o findings_dir /path/to/program @@
   ./llvm-fuzz testcase_dir findings_dir  # Will write new tests to testcase_dir
 
 Periodically restart both fuzzers so that they can use each other's findings.
+Currently, there is no simple way to run both fuzzing engines in parallel while sharing the same corpus dir.
+
+You may also use AFL on your target function ``LLVMFuzzerTestOneInput``:
+see an example `here <https://github.com/llvm-mirror/llvm/blob/master/lib/Fuzzer/afl/afl_driver.cpp>`__.
 
 How good is my fuzzer?
 ----------------------
@@ -321,14 +652,20 @@ How good is my fuzzer?
 Once you implement your target function ``LLVMFuzzerTestOneInput`` and fuzz it to death,
 you will want to know whether the function or the corpus can be improved further.
 One easy to use metric is, of course, code coverage.
-You can get the coverage for your corpus like this::
+You can get the coverage for your corpus like this:
+
+.. code-block:: console
+
+  ASAN_OPTIONS=coverage=1:html_cov_report=1 ./fuzzer CORPUS_DIR -runs=0
 
-  ASAN_OPTIONS=coverage_pcs=1 ./fuzzer CORPUS_DIR -runs=0
+This will run all tests in the CORPUS_DIR but will not perform any fuzzing.
+At the end of the process it will dump a single html file with coverage information.
+See SanitizerCoverage_ for details.
 
-This will run all the tests in the CORPUS_DIR but will not generate any new tests
-and dump covered PCs to disk before exiting.
-Then you can subtract the set of covered PCs from the set of all instrumented PCs in the binary,
-see SanitizerCoverage_ for details.
+You may also use other ways to visualize coverage,
+e.g. using `Clang coverage <http://clang.llvm.org/docs/SourceBasedCodeCoverage.html>`_,
+but those will require
+you to rebuild the code with different compiler flags.
 
 User-supplied mutators
 ----------------------
@@ -336,21 +673,83 @@ User-supplied mutators
 LibFuzzer allows to use custom (user-supplied) mutators,
 see FuzzerInterface.h_
 
+Startup initialization
+----------------------
+If the library being tested needs to be initialized, there are several options.
+
+The simplest way is to have a statically initialized global object inside
+`LLVMFuzzerTestOneInput` (or in global scope if that works for you):
+
+.. code-block:: c++
+
+  extern "C" int LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size) {
+    static bool Initialized = DoInitialization();
+    ...
+
+Alternatively, you may define an optional init function and it will receive
+the program arguments that you can read and modify. Do this **only** if you
+realy need to access ``argv``/``argc``.
+
+.. code-block:: c++
+
+   extern "C" int LLVMFuzzerInitialize(int *argc, char ***argv) {
+    ReadAndMaybeModify(argc, argv);
+    return 0;
+   }
+
+
+Leaks
+-----
+
+Binaries built with AddressSanitizer_ or LeakSanitizer_ will try to detect
+memory leaks at the process shutdown.
+For in-process fuzzing this is inconvenient
+since the fuzzer needs to report a leak with a reproducer as soon as the leaky
+mutation is found. However, running full leak detection after every mutation
+is expensive.
+
+By default (``-detect_leaks=1``) libFuzzer will count the number of
+``malloc`` and ``free`` calls when executing every mutation.
+If the numbers don't match (which by itself doesn't mean there is a leak)
+libFuzzer will invoke the more expensive LeakSanitizer_
+pass and if the actual leak is found, it will be reported with the reproducer
+and the process will exit.
+
+If your target has massive leaks and the leak detection is disabled
+you will eventually run out of RAM (see the ``-rss_limit_mb`` flag).
+
+
+Developing libFuzzer
+====================
+
+Building libFuzzer as a part of LLVM project and running its test requires
+fresh clang as the host compiler and special CMake configuration:
+
+.. code-block:: console
+
+    cmake -GNinja  -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DLLVM_USE_SANITIZER=Address -DLLVM_USE_SANITIZE_COVERAGE=YES -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_ASSERTIONS=ON /path/to/llvm
+    ninja check-fuzzer
+
+
 Fuzzing components of LLVM
 ==========================
+.. contents::
+   :local:
+   :depth: 1
+
+To build any of the LLVM fuzz targets use the build instructions above.
 
 clang-format-fuzzer
 -------------------
 The inputs are random pieces of C++-like text.
 
-Build (make sure to use fresh clang as the host compiler)::
+.. code-block:: console
 
-    cmake -GNinja  -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DLLVM_USE_SANITIZER=Address -DLLVM_USE_SANITIZE_COVERAGE=YES -DCMAKE_BUILD_TYPE=Release /path/to/llvm
     ninja clang-format-fuzzer
     mkdir CORPUS_DIR
     ./bin/clang-format-fuzzer CORPUS_DIR
 
-Optionally build other kinds of binaries (asan+Debug, msan, ubsan, etc).
+Optionally build other kinds of binaries (ASan+Debug, MSan, UBSan, etc).
 
 Tracking bug: https://llvm.org/bugs/show_bug.cgi?id=23052
 
@@ -380,37 +779,27 @@ finds an invalid instruction or runs out of data.
 Please note that the command line interface differs slightly from that of other
 fuzzers. The fuzzer arguments should follow ``--fuzzer-args`` and should have
 a single dash, while other arguments control the operation mode and target in a
-similar manner to ``llvm-mc`` and should have two dashes. For example::
+similar manner to ``llvm-mc`` and should have two dashes. For example:
+
+.. code-block:: console
 
   llvm-mc-fuzzer --triple=aarch64-linux-gnu --disassemble --fuzzer-args -max_len=4 -jobs=10
 
 Buildbot
 --------
 
-We have a buildbot that runs the above fuzzers for LLVM components
-24/7/365 at http://lab.llvm.org:8011/builders/sanitizer-x86_64-linux-fuzzer .
-
-Pre-fuzzed test inputs in git
------------------------------
-
-The buildbot occumulates large test corpuses over time.
-The corpuses are stored in git on github and can be used like this::
-
-  git clone https://github.com/kcc/fuzzing-with-sanitizers.git
-  bin/clang-format-fuzzer fuzzing-with-sanitizers/llvm/clang-format/C1
-  bin/clang-fuzzer        fuzzing-with-sanitizers/llvm/clang/C1/
-  bin/llvm-as-fuzzer      fuzzing-with-sanitizers/llvm/llvm-as/C1  -only_ascii=1
-
+A buildbot continuously runs the above fuzzers for LLVM components, with results
+shown at http://lab.llvm.org:8011/builders/sanitizer-x86_64-linux-fuzzer .
 
 FAQ
 =========================
 
-Q. Why Fuzzer does not use any of the LLVM support?
----------------------------------------------------
+Q. Why doesn't libFuzzer use any of the LLVM support?
+-----------------------------------------------------
 
 There are two reasons.
 
-First, we want this library to be used outside of the LLVM w/o users having to
+First, we want this library to be used outside of the LLVM without users having to
 build the rest of LLVM. This may sound unconvincing for many LLVM folks,
 but in practice the need for building the whole LLVM frightens many potential
 users -- and we want more users to use this code.
@@ -422,19 +811,17 @@ coverage set of the process (since the fuzzer is in-process). In other words, by
 using more external dependencies we will slow down the fuzzer while the main
 reason for it to exist is extreme speed.
 
-Q. What about Windows then? The Fuzzer contains code that does not build on Windows.
+Q. What about Windows then? The fuzzer contains code that does not build on Windows.
 ------------------------------------------------------------------------------------
 
-The sanitizer coverage support does not work on Windows either as of 01/2015.
-Once it's there, we'll need to re-implement OS-specific parts (I/O, signals).
+Volunteers are welcome.
 
 Q. When this Fuzzer is not a good solution for a problem?
 ---------------------------------------------------------
 
 * If the test inputs are validated by the target library and the validator
-  asserts/crashes on invalid inputs, the in-process fuzzer is not applicable
-  (we could use fork() w/o exec, but it comes with extra overhead).
-* Bugs in the target library may accumulate w/o being detected. E.g. a memory
+  asserts/crashes on invalid inputs, in-process fuzzing is not applicable.
+* Bugs in the target library may accumulate without being detected. E.g. a memory
   corruption that goes undetected at first and then leads to a crash while
   testing another input. This is why it is highly recommended to run this
   in-process fuzzer with all sanitizers to detect most bugs on the spot.
@@ -442,7 +829,7 @@ Q. When this Fuzzer is not a good solution for a problem?
   consumption and infinite loops in the target library (still possible).
 * The target library should not have significant global state that is not
   reset between the runs.
-* Many interesting target libs are not designed in a way that supports
+* Many interesting target libraries are not designed in a way that supports
   the in-process fuzzer interface (e.g. require a file path instead of a
   byte array).
 * If a single test run takes a considerable fraction of a second (or
@@ -454,18 +841,16 @@ Q. So, what exactly this Fuzzer is good for?
 --------------------------------------------
 
 This Fuzzer might be a good choice for testing libraries that have relatively
-small inputs, each input takes < 1ms to run, and the library code is not expected
+small inputs, each input takes < 10ms to run, and the library code is not expected
 to crash on invalid inputs.
-Examples: regular expression matchers, text or binary format parsers.
+Examples: regular expression matchers, text or binary format parsers, compression,
+network, crypto.
 
 Trophies
 ========
 * GLIBC: https://sourceware.org/glibc/wiki/FuzzingLibc
 
-* MUSL LIBC:
-
-  * http://git.musl-libc.org/cgit/musl/commit/?id=39dfd58417ef642307d90306e1c7e50aaec5a35c
-  * http://www.openwall.com/lists/oss-security/2015/03/30/3
+* MUSL LIBC: `[1] <http://git.musl-libc.org/cgit/musl/commit/?id=39dfd58417ef642307d90306e1c7e50aaec5a35c>`__ `[2] <http://www.openwall.com/lists/oss-security/2015/03/30/3>`__
 
 * `pugixml <https://github.com/zeux/pugixml/issues/39>`_
 
@@ -482,23 +867,39 @@ Trophies
 
 * `Python <http://bugs.python.org/issue25388>`_
 
-* OpenSSL/BoringSSL: `[1] <https://boringssl.googlesource.com/boringssl/+/cb852981cd61733a7a1ae4fd8755b7ff950e857d>`_
+* OpenSSL/BoringSSL: `[1] <https://boringssl.googlesource.com/boringssl/+/cb852981cd61733a7a1ae4fd8755b7ff950e857d>`_ `[2] <https://openssl.org/news/secadv/20160301.txt>`_ `[3] <https://boringssl.googlesource.com/boringssl/+/2b07fa4b22198ac02e0cee8f37f3337c3dba91bc>`_ `[4] <https://boringssl.googlesource.com/boringssl/+/6b6e0b20893e2be0e68af605a60ffa2cbb0ffa64>`_  `[5] <https://github.com/openssl/openssl/pull/931/commits/dd5ac557f052cc2b7f718ac44a8cb7ac6f77dca8>`_ `[6] <https://github.com/openssl/openssl/pull/931/commits/19b5b9194071d1d84e38ac9a952e715afbc85a81>`_
 
 * `Libxml2
-  <https://bugzilla.gnome.org/buglist.cgi?bug_status=__all__&content=libFuzzer&list_id=68957&order=Importance&product=libxml2&query_format=specific>`_
+  <https://bugzilla.gnome.org/buglist.cgi?bug_status=__all__&content=libFuzzer&list_id=68957&order=Importance&product=libxml2&query_format=specific>`_ and `[HT206167] <https://support.apple.com/en-gb/HT206167>`_ (CVE-2015-5312, CVE-2015-7500, CVE-2015-7942)
 
 * `Linux Kernel's BPF verifier <https://github.com/iovisor/bpf-fuzzer>`_
 
+* Capstone: `[1] <https://github.com/aquynh/capstone/issues/600>`__ `[2] <https://github.com/aquynh/capstone/commit/6b88d1d51eadf7175a8f8a11b690684443b11359>`__
+
+* file:`[1] <http://bugs.gw.com/view.php?id=550>`__  `[2] <http://bugs.gw.com/view.php?id=551>`__  `[3] <http://bugs.gw.com/view.php?id=553>`__  `[4] <http://bugs.gw.com/view.php?id=554>`__
+
+* Radare2: `[1] <https://github.com/revskills?tab=contributions&from=2016-04-09>`__
+
+* gRPC: `[1] <https://github.com/grpc/grpc/pull/6071/commits/df04c1f7f6aec6e95722ec0b023a6b29b6ea871c>`__ `[2] <https://github.com/grpc/grpc/pull/6071/commits/22a3dfd95468daa0db7245a4e8e6679a52847579>`__ `[3] <https://github.com/grpc/grpc/pull/6071/commits/9cac2a12d9e181d130841092e9d40fa3309d7aa7>`__ `[4] <https://github.com/grpc/grpc/pull/6012/commits/82a91c91d01ce9b999c8821ed13515883468e203>`__ `[5] <https://github.com/grpc/grpc/pull/6202/commits/2e3e0039b30edaf89fb93bfb2c1d0909098519fa>`__ `[6] <https://github.com/grpc/grpc/pull/6106/files>`__
+
+* WOFF2: `[1] <https://github.com/google/woff2/commit/a15a8ab>`__
+
 * LLVM: `Clang <https://llvm.org/bugs/show_bug.cgi?id=23057>`_, `Clang-format <https://llvm.org/bugs/show_bug.cgi?id=23052>`_, `libc++ <https://llvm.org/bugs/show_bug.cgi?id=24411>`_, `llvm-as <https://llvm.org/bugs/show_bug.cgi?id=24639>`_, Disassembler: http://reviews.llvm.org/rL247405, http://reviews.llvm.org/rL247414, http://reviews.llvm.org/rL247416, http://reviews.llvm.org/rL247417, http://reviews.llvm.org/rL247420, http://reviews.llvm.org/rL247422.
 
 .. _pcre2: http://www.pcre.org/
-
 .. _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
-
+.. _AddressSanitizer: http://clang.llvm.org/docs/AddressSanitizer.html
+.. _LeakSanitizer: http://clang.llvm.org/docs/LeakSanitizer.html
 .. _Heartbleed: http://en.wikipedia.org/wiki/Heartbleed
-
 .. _FuzzerInterface.h: https://github.com/llvm-mirror/llvm/blob/master/lib/Fuzzer/FuzzerInterface.h
+.. _3.7.0: http://llvm.org/releases/3.7.0/docs/LibFuzzer.html
+.. _building Clang from trunk: http://clang.llvm.org/get_started.html
+.. _MemorySanitizer: http://clang.llvm.org/docs/MemorySanitizer.html
+.. _UndefinedBehaviorSanitizer: http://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html
+.. _`coverage counters`: http://clang.llvm.org/docs/SanitizerCoverage.html#coverage-counters
+.. _`caller-callee pairs`: http://clang.llvm.org/docs/SanitizerCoverage.html#caller-callee-coverage
+.. _BoringSSL: https://boringssl.googlesource.com/boringssl/
+.. _`fuzz various parts of LLVM itself`: `Fuzzing components of LLVM`_