From 41841c71339e1e3d9137ea7d263e38e05e1342f5 Mon Sep 17 00:00:00 2001
From: kdeme <kim.demey@gmail.com>
Date: Tue, 3 Dec 2019 13:48:47 +0100
Subject: [PATCH] Add libnfuzz documentation [skip ci]

---
 nfuzz/README.md  | 40 ++++++++++++++++++++++++++++++++++++++++
 nfuzz/libnfuzz.h |  5 +++++
 2 files changed, 45 insertions(+)
 create mode 100644 nfuzz/README.md

diff --git a/nfuzz/README.md b/nfuzz/README.md
new file mode 100644
index 000000000..aa9df3e05
--- /dev/null
+++ b/nfuzz/README.md
@@ -0,0 +1,40 @@
+# Introduction
+
+`libnfuzz` is a wrapper library that exports to C, a set of fuzzing test cases
+written in Nim and making use of nim-beacon-chain.
+
+
+# Building
+
+To build the wrapper library (for more details follow first the instructions from
+[nim-beacon-chain](../README.md)):
+
+```bash
+git clone https://github.com/status-im/nim-beacon-chain.git
+cd nim-beacon-chain
+make
+# static library
+make libnfuzz.a
+# dynamic loaded library
+make libnfuzz.so
+```
+
+For the library to be useful for fuzzing with libFuzzer (e.g. for
+integration with [beacon-fuzz](https://github.com/sigp/beacon-fuzz)) we can pass
+additional Nim arguments, e.g.:
+
+```bash
+make libnfuzz.a NIMFLAGS="--cc:clang --passC:'-fsanitize=fuzzer' --passL='-fsanitize=fuzzer'"
+```
+
+Other useful options might include: `--clang.path:<path>`, `--clang.exe:<exe>`, `--clang.linkerexe:<exe>`.
+
+It might also deem useful to lower the log level, e.g. by adding `-d:chronicles_log_level=fatal`.
+
+# Usage
+There is a `libnfuzz.h` file provided for easy including in C or C++ projects.
+
+It is most important that before any of the exported tests are called, the
+`NimMain()` call is done first. Additionally, all following library calls need
+to be done from the same thread as from where the original `NimMain()` call was
+done.
diff --git a/nfuzz/libnfuzz.h b/nfuzz/libnfuzz.h
index fffe20a76..aaf5d5876 100644
--- a/nfuzz/libnfuzz.h
+++ b/nfuzz/libnfuzz.h
@@ -5,8 +5,13 @@
 extern "C" {
 #endif
 
+/** Initialize Nim & Garbage Collector. Must be called before anything else
+ * of the API. Also, all following calls must come from the same thread as from
+ * which this call was done.
+ */
 void NimMain();
 
+/** Supported fuzzing tests */
 bool nfuzz_block(uint8_t* input_ptr, size_t input_size,
   uint8_t* output_ptr, size_t* output_size);
 bool nfuzz_attestation(uint8_t* input_ptr, size_t input_size,