History

Matthew King b56f1ef5e4 Cleanup: Fix boolean arg in fio plugin. In fio, bools are represented as ints. They have to be read into int entries in the options struct, or memory corruption may occur. Also provided a default to bring it more in line with existing fio code. Signed-off-by: Matthew King <matthew.king@xilinx.com> Change-Id: Ib718653d6597a287bf8ff96d2fb864e46295751d Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/6147 Tested-by: SPDK CI Jenkins <sys_sgci@intel.com> Community-CI: Mellanox Build Bot Reviewed-by: Shuhei Matsumoto <shuhei.matsumoto.xt@hitachi.com> Reviewed-by: Aleksey Marchuk <alexeymar@mellanox.com> Reviewed-by: Ben Walker <benjamin.walker@intel.com> Reviewed-by: <dongx.yi@intel.com>		2021-02-04 08:38:55 +00:00
..
.gitignore	bdev: Add an example fio plugin	2017-08-04 20:03:37 -04:00
bdev.json	bdev_fio: remove legacy config support	2020-10-21 20:46:20 +00:00
example_config.fio	bdev_fio: remove legacy config support	2020-10-21 20:46:20 +00:00
fio_plugin.c	Cleanup: Fix boolean arg in fio plugin.	2021-02-04 08:38:55 +00:00
full_bench.fio	doc: remove mentions of legacy config	2020-10-22 17:08:41 +00:00
Makefile	build: use DEPDIRS variables to build SPDK_LIB_LIST	2020-12-18 09:40:01 +00:00
README.md	fio_plugin: clarify thread=1	2021-01-20 08:45:21 +00:00

README.md

Introduction

This directory contains a plug-in module for fio to enable use with SPDK. Fio is free software published under version 2 of the GPL license.

Compiling fio

Clone the fio source repository from https://github.com/axboe/fio

git clone https://github.com/axboe/fio
cd fio

Compile the fio code and install:

make
make install

Compiling SPDK

Clone the SPDK source repository from https://github.com/spdk/spdk

git clone https://github.com/spdk/spdk
cd spdk
git submodule update --init

Then, run the SPDK configure script to enable fio (point it to the root of the fio repository):

cd spdk
./configure --with-fio=/path/to/fio/repo <other configuration options>

Finally, build SPDK:

make

Note to advanced users: These steps assume you're using the DPDK submodule. If you are using your own version of DPDK, the fio plugin requires that DPDK be compiled with -fPIC. You can compile DPDK with -fPIC by modifying your DPDK configuration file and adding the line:

EXTRA_CFLAGS=-fPIC

Usage

To use the SPDK fio plugin with fio, specify the plugin binary using LD_PRELOAD when running fio and set ioengine=spdk_bdev in the fio configuration file (see example_config.fio in the same directory as this README).

LD_PRELOAD=<path to spdk repo>/build/fio/spdk_bdev fio

The fio configuration file must contain one new parameter:

spdk_json_conf=./examples/bdev/fio_plugin/bdev.json

You can specify which block device to run against by setting the filename parameter to the block device name:

filename=Malloc0

Or for NVMe devices:

filename=Nvme0n1

fio by default forks a separate process for every job. It also supports just spawning a separate thread in the same process for every job. The SPDK fio plugin is limited to this latter thread usage model, so fio jobs must also specify thread=1 when using the SPDK fio plugin. The SPDK fio plugin supports multiple threads - in this case, the "1" just means "use thread mode".

fio also currently has a race condition on shutdown if dynamically loading the ioengine by specifying the engine's full path via the ioengine parameter - LD_PRELOAD is recommended to avoid this race condition.

When testing random workloads, it is recommended to set norandommap=1. fio's random map processing consumes extra CPU cycles which will degrade performance over time with the fio_plugin since all I/O are submitted and completed on a single CPU core.