[ceph.git] / ceph / src / spdk / test / app / fuzz / nvme_fuzz / README.md

# 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!
Commit	Line	Data
f67539c2 TL	1	# Overview
	2
	3	This application is intended to fuzz test the NVMe-oF target or a physical NVMe drive by
	4	submitting randomized NVMe commands through the SPDK NVMe initiator. Both local and remote
	5	drives are configured through a .ini style config file (See the -C option on the application).
	6	Multiple controllers and namespaces can be exposed to the fuzzer at a time. In order to
	7	handle multiple namespaces, the fuzzer will round robin assign a thread to each namespace and
	8	submit commands to that thread at a set queue depth. (currently 128 for I/O, 16 for Admin). The
	9	application will terminate under three conditions:
	10
	11	1. The user specified run time expires (see the -t flag).
	12	2. One of the target controllers stops completing I/O operations back to the fuzzer i.e. controller timeout.
	13	3. The user specified a json file containing operations to run and the fuzzer has received valid completions for all of them.
	14
	15	# Output
	16
	17	By default, the fuzzer will print commands that:
	18
	19	1. Complete successfully back from the target, or
	20	2. Are outstanding at the time of a controller timeout.
	21
	22	Commands are dumped as named objects in json format which can then be supplied back to the
	23	script for targeted debugging on a subsequent run. See `Debugging` below.
	24	By default no output is generated when a specific command is returned with a failed status.
	25	This can be overridden with the -V flag. if -V is specified, each command will be dumped as
	26	it is completed in the JSON format specified above.
	27	At the end of each test run, a summary is printed for each namespace in the following format:
	28
	29	~~~
	30	NS: 0x200079262300 admin qp, Total commands completed: 462459, total successful commands: 1960, random_seed: 4276918833
	31	~~~
	32
	33	# Debugging
	34
	35	If a controller hangs when processing I/O generated by the fuzzer, the fuzzer will stop
	36	submitting I/O and dump out all outstanding I/O on the qpair that timed out. The I/O are
	37	dumped as valid json. You can combine the dumped commands from the fuzzer into a json
	38	array in a file and then pass them to the fuzzer using the -j option. Please see the
	39	example.json file in this directory for an example of a properly formed array of command
	40	structures.
	41
	42	Please note that you can also craft your own custom command values by using the output
	43	from the fuzzer as a template.
	44
	45	# JSON Format
	46
	47	Most of the variables in the spdk_nvme_cmd structure are represented as numbers in JSON.
	48	The only exception to this rule is the dptr union. This is a 16 byte union structure that
	49	is represented as a base64 string. If writing custom commands for input, please note this
	50	distinction or the application will be unable to load your custom input.
	51
	52	Happy Fuzzing!