doc: add bdevperf doc section

Describe bdevperf tool usage and its config file.

Signed-off-by: Vitaliy Mysak <vitaliy.mysak@intel.com>
Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/3602 (master)

(cherry picked from commit 8e5d5b8ff6814ec8e8adc28c779b56022d2c41b8)
Change-Id: I3648e9fcf6eb9e332dadda0d73f52740a19d5ad8
Signed-off-by: Tomasz Zawadzki <tomasz.zawadzki@intel.com>
Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/3608
Tested-by: SPDK CI Jenkins <sys_sgci@intel.com>
Reviewed-by: Ben Walker <benjamin.walker@intel.com>
Reviewed-by: Jim Harris <james.r.harris@intel.com>

doc/Doxyfile

@@ -803,6 +803,7 @@ INPUT                  += \
                          accel_fw.md \
                          applications.md \
                          bdev.md \
+                         bdevperf.md \
                          bdev_module.md \
                          bdev_pg.md \
                          blob.md \

doc/bdevperf.md

@@ -0,0 +1,86 @@
+# Using bdevperf application {#bdevperf}
+
+## Introduction
+
+bdevperf is an SPDK application that is used for performance testing
+of block devices (bdevs) exposed by the SPDK bdev layer.  It is an
+alternative to the SPDK bdev fio plugin for benchmarking SPDK bdevs.
+In some cases, bdevperf can provide much lower overhead than the fio
+plugin, resulting in much better performance for tests using a limited
+number of CPU cores.
+
+bdevperf exposes command line interface that allows to specify
+SPDK framework options as well as testing options.
+Since SPDK 20.07, bdevperf supports configuration file that is similar
+to FIO. It allows user to create jobs parameterized by
+filename, cpumask, blocksize, queuesize, etc.
+
+## Config file
+
+Bdevperf's config file is similar to FIO's config file format.
+
+Below is an example config file that uses all available parameters:
+
+~~~{.ini}
+[global]
+filename=Malloc0:Malloc1
+bs=1024
+iosize=256
+rw=randrw
+rwmixread=90
+
+[A]
+cpumask=0xff
+
+[B]
+cpumask=[0-128]
+filename=Malloc1
+
+[global]
+filename=Malloc0
+rw=write
+
+[C]
+bs=4096
+iosize=128
+offset=1000000
+length=1000000
+~~~
+
+Jobs `[A]` `[B]` or `[C]`, inherit default values from `[global]`
+section residing above them. So in the example, job `[A]` inherits
+`filename` value and uses both `Malloc0` and `Malloc1` bdevs as targets,
+job `[B]` overrides its `filename` value and uses `Malloc1` and
+job `[C]` inherits value `Malloc0` for its `filename`.
+
+Interaction with CLI arguments is not the same as in FIO however.
+If bdevperf receives CLI argument, it overrides values
+of corresponding parameter for all `[global]` sections of config file.
+So if example config is used, specifying `-q` argument
+will make jobs `[A]` and `[B]` use its value.
+
+Below is a full list of supported parameters with descriptions.
+
+Param     | Default           | Description
+--------- | ----------------- | -----------
+filename  |                   | Bdevs to use, separated by ":"
+cpumask   | Maximum available | CPU mask. Format is defined at @ref cpu_mask
+bs        |                   | Block size (io size)
+iodepth   |                   | Queue depth
+rwmixread | `50`              | Percentage of a mixed workload that should be reads
+offset    | `0`               | Start I/O at the provided offset on the bdev
+length    | 100% of bdev size | End I/O at `offset`+`length` on the bdev
+rw        |                   | Type of I/O pattern
+
+Available rw types:
+- read
+- randread
+- write
+- randwrite
+- verify
+- reset
+- unmap
+- write_zeroes
+- flush
+- rw
+- randrw

doc/tools.md

@@ -2,3 +2,4 @@
 
 - @subpage spdkcli
 - @subpage nvme-cli
+- @subpage bdevperf