[PATCH 6/6] docs: document fuzzer support

[Daniel Axtens]

This is basic documentation.

There are a few extra, super-hacky things we can do to get asan or afl++ going 
which
are a bit too messy at the moment to commit to the docs. But, so as they are 
not lost
to time, here's the invocations that currently work for me:

libfuzzer + ASan:
./configure CC=clang --with-platform=emu --enable-fuzzers=yes; make clean
ASAN_OPTIONS=detect_leaks=0 make CFLAGS='-fsanitize=address 
-Wl,--allow-multiple-definition' -j4 -k || \
  echo "the compile is expected to fail eventually, but the fuzzers should 
still build"

AFL++:
./configure CC=clang --with-platform=emu --enable-fuzzers=yes; make clean
make CC=/path/to/afl-cc CFLAGS="-Wl,--allow-multiple-definition" -j4 -k || \
  echo "the compile is expected to fail eventually, but the fuzzers should 
still build"

AFL++ + ASan:
./configure CC=clang --with-platform=emu --enable-fuzzers=yes; make clean
AFL_USE_ASAN=1 ASAN_OPTIONS=detect_leaks=0 make CC=/path/to/afl-cc 
CFLAGS="-Wl,--allow-multiple-definition" -j4 -k || \
  echo "the compile is expected to fail eventually, but the fuzzers should 
still build"

In these cases the compilation of grub-emu(-lite) will fail, but the fuzzers 
themselves will
be built and can be run as desired.
---
 docs/grub-dev.texi | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/docs/grub-dev.texi b/docs/grub-dev.texi
index 31eb99ea2994..11a92d04eda0 100644
--- a/docs/grub-dev.texi
+++ b/docs/grub-dev.texi
@@ -88,6 +88,7 @@ This edition documents version @value{VERSION}.
 * Graphical Menu Software Design::
 * Verifiers framework::
 * Lockdown framework::
+* Fuzzing the GRUB::
 * Copying This Manual::         Copying This Manual
 * Index::
 @end menu
@@ -2165,6 +2166,25 @@ when the GRUB is in lockdown mode.
 
 @end itemize
 
+@node Fuzzing the GRUB
+@chapter Fuzzing the GRUB
+
+The GRUB has support for in-process fuzzing of various image format
+parsers, based on libfuzzer.
+
+Fuzzers are compiled by default if the host compiler supports the
+@code{-fsanitize=fuzzer} compile flag. Fuzzers can be explictly enabled with
+@code{./configure --enable-fuzzers=yes}, such that configuration will not
+succeed unless they can be built. Fuzzers are built as @code{grub-fuzz-XXX}
+binaries in the top-level directory.
+
+These fuzzers build with clang out of the box. When built with clang they
+can be run against a corpus as e.g. @code{./grub-fuzz-jpeg jpeg-corpus}.
+Consult the LLVM libfuzzer documentation for more details and options.
+
+Building the fuzzers with other sanitizers (such as AddressSanitizer) or
+with AFL++ can provide better results, but the process is not yet stable.
+
 @node Copying This Manual
 @appendix Copying This Manual
 
-- 
2.25.1