diff options
Diffstat (limited to 'src/spdk/test/app/fuzz/nvme_fuzz/README.md')
-rw-r--r-- | src/spdk/test/app/fuzz/nvme_fuzz/README.md | 52 |
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! |