From 47a05720aaad0ae1ce31ee00391aa5102c88da75 Mon Sep 17 00:00:00 2001
From: Christian Reitter <invd@inhq.net>
Date: Wed, 8 Dec 2021 13:11:13 +0100
Subject: [PATCH] docs(crypto): update fuzzer documentation

---
 crypto/fuzzer/README.md | 27 ++++++++++++++++++++-------
 1 file changed, 20 insertions(+), 7 deletions(-)

diff --git a/crypto/fuzzer/README.md b/crypto/fuzzer/README.md
index 217aeee24..d9bb37243 100644
--- a/crypto/fuzzer/README.md
+++ b/crypto/fuzzer/README.md
@@ -18,8 +18,8 @@ Recommended: ASAN / UBSAN / MSAN flags for error detection can be specified via
 
 Examples:
 
-  * `SANFLAGS="-fsanitize=address,undefined"`
-  * `SANFLAGS="-fsanitize=memory -fsanitize-memory-track-origins"`
+* `SANFLAGS="-fsanitize=address,undefined"`
+* `SANFLAGS="-fsanitize=memory -fsanitize-memory-track-origins"`
 
 ### Optimizations
 
@@ -27,18 +27,26 @@ Override `OPTFLAGS` to test the library at different optimization levels or simp
 
 Examples:
 
-  * `OPTFLAGS="-O0 -ggdb3"`
-  * `OPTFLAGS="-O3 -march=native"`
+* `OPTFLAGS="-O0 -ggdb3"`
+* `OPTFLAGS="-O3 -march=native"`
 
-To be determined: use of `-fsanitize-ignorelist` to reduce sanitizer overhead on hot functions
+To be determined:
+
+* use of `-fsanitize-ignorelist` to reduce sanitizer overhead on hot functions
+* `-flto` and `-flto=thin` link time optimization
 
+Advanced usage:
+* [Profile guided optimization](https://clang.llvm.org/docs/UsersManual.html#profile-guided-optimization)
 ### Other Flags
 
 To be determined:
+
 * `-DNDEBUG`
-* `-DUSE_BIP39_CACHE=0 -DUSE_BIP32_CACHE=0`
-* `-D_FORTIFY_SOURCE=2`
+* `-DUSE_BIP39_CACHE=0 -DUSE_BIP32_CACHE=0` to avoid persistent side effects through the cache
+* `-D_FORTIFY_SOURCE=2` together with optimization flag -O2 or above
 * `-fstack-protector-strong` or `-fstack-protector-all`
+* `-m32` to closer evaluate the 32 bit behavior
+    * this requires 32bit build support for gcc-multilib, libc and others
 
 ## Operation
 
@@ -79,3 +87,8 @@ The resulting file can be used as a fuzzer dictionary.
   1. render the data `llvm-cov show fuzzer/fuzzer -instr-profile=default.profdata -format=html -output-dir=coverage-report`
   1. analyze report at `coverage-report/index.html`
   1. (optional) remove artifacts with `rm default.profraw default.profdata && rm -r coverage-report`
+
+## Using Honggfuzz Fuzzer
+
+Although this code is designed primarily for libFuzzer, it can also be used with [Honggfuzz](https://honggfuzz.dev).
+However, the usage details are out of scope of this document.