1 files changed, 52 insertions, 0 deletions
diff --git a/src/spdk/test/app/fuzz/nvme_fuzz/README.md b/src/spdk/test/app/fuzz/nvme_fuzz/README.md
new file mode 100644
index 000000000..2f188b5b8
--- /dev/null
+++ b/src/spdk/test/app/fuzz/nvme_fuzz/README.md
@@ -0,0 +1,52 @@
+# Overview
+
+This application is intended to fuzz test the NVMe-oF target or a physical NVMe drive by
+submitting randomized NVMe commands through the SPDK NVMe initiator. Both local and remote
+drives are configured through a .ini style config file (See the -C option on the application).
+Multiple controllers and namespaces can be exposed to the fuzzer at a time. In order to
+handle multiple namespaces, the fuzzer will round robin assign a thread to each namespace and
+submit commands to that thread at a set queue depth. (currently 128 for I/O, 16 for Admin). The
+application will terminate under three conditions:
+
+1. The user specified run time expires (see the -t flag).
+2. One of the target controllers stops completing I/O operations back to the fuzzer i.e. controller timeout.
+3. The user specified a json file containing operations to run and the fuzzer has received valid completions for all of them.
+
+# Output
+
+By default, the fuzzer will print commands that:
+
+1. Complete successfully back from the target, or
+2. Are outstanding at the time of a controller timeout.
+
+Commands are dumped as named objects in json format which can then be supplied back to the
+script for targeted debugging on a subsequent run. See `Debugging` below.
+By default no output is generated when a specific command is returned with a failed status.
+This can be overridden with the -V flag. if -V is specified, each command will be dumped as
+it is completed in the JSON format specified above.
+At the end of each test run, a summary is printed for each namespace in the following format:
+
+~~~
+NS: 0x200079262300 admin qp, Total commands completed: 462459, total successful commands: 1960, random_seed: 4276918833
+~~~
+
+# Debugging
+
+If a controller hangs when processing I/O generated by the fuzzer, the fuzzer will stop
+submitting I/O and dump out all outstanding I/O on the qpair that timed out. The I/O are
+dumped as valid json. You can combine the dumped commands from the fuzzer into a json
+array in a file and then pass them to the fuzzer using the -j option. Please see the
+example.json file in this directory for an example of a properly formed array of command
+structures.
+
+Please note that you can also craft your own custom command values by using the output
+from the fuzzer as a template.
+
+# JSON Format
+
+Most of the variables in the spdk_nvme_cmd structure are represented as numbers in JSON.
+The only exception to this rule is the dptr union. This is a 16 byte union structure that
+is represented as a base64 string. If writing custom commands for input, please note this
+distinction or the application will be unable to load your custom input.
+
+Happy Fuzzing!