From fda3aafd14e4e6e5d97e5b9b7ec7d8c3c48b0e98 Mon Sep 17 00:00:00 2001 From: Vitaliy Mysak Date: Thu, 30 Jul 2020 11:56:05 +0200 Subject: [PATCH] doc: add bdevperf doc section Describe bdevperf tool usage and its config file. Signed-off-by: Vitaliy Mysak 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 Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/3608 Tested-by: SPDK CI Jenkins Reviewed-by: Ben Walker Reviewed-by: Jim Harris --- doc/Doxyfile | 1 + doc/bdevperf.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++ doc/tools.md | 1 + 3 files changed, 88 insertions(+) create mode 100644 doc/bdevperf.md diff --git a/doc/Doxyfile b/doc/Doxyfile index d5091d70e..3c33ab339 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -803,6 +803,7 @@ INPUT += \ accel_fw.md \ applications.md \ bdev.md \ + bdevperf.md \ bdev_module.md \ bdev_pg.md \ blob.md \ diff --git a/doc/bdevperf.md b/doc/bdevperf.md new file mode 100644 index 000000000..8c5c5828c --- /dev/null +++ b/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 diff --git a/doc/tools.md b/doc/tools.md index 6fa7faefe..234017ba7 100644 --- a/doc/tools.md +++ b/doc/tools.md @@ -2,3 +2,4 @@ - @subpage spdkcli - @subpage nvme-cli +- @subpage bdevperf