ceph/src/spdk/examples/bdev/fio_plugin/README.md

   1 # Introduction
   2
   3 This directory contains a plug-in module for fio to enable use
   4 with SPDK. Fio is free software published under version 2 of
   5 the GPL license.
   6
   7 # Compiling fio
   8
   9 Clone the fio source repository from https://github.com/axboe/fio
  10
  11     git clone https://github.com/axboe/fio
  12     cd fio
  13
  14 Compile the fio code and install:
  15
  16     make
  17     make install
  18
  19 # Compiling SPDK
  20
  21 Clone the SPDK source repository from https://github.com/spdk/spdk
  22
  23     git clone https://github.com/spdk/spdk
  24     cd spdk
  25     git submodule update --init
  26
  27 Then, run the SPDK configure script to enable fio (point it to the root of the fio repository):
  28
  29     cd spdk
  30     ./configure --with-fio=/path/to/fio/repo <other configuration options>
  31
  32 Finally, build SPDK:
  33
  34     make
  35
  36 **Note to advanced users**: These steps assume you're using the DPDK submodule. If you are using your
  37 own version of DPDK, the fio plugin requires that DPDK be compiled with -fPIC. You can compile DPDK
  38 with -fPIC by modifying your DPDK configuration file and adding the line:
  39
  40     EXTRA_CFLAGS=-fPIC
  41
  42 # Usage
  43
  44 To use the SPDK fio plugin with fio, specify the plugin binary using LD_PRELOAD when running
  45 fio and set ioengine=spdk_bdev in the fio configuration file (see example_config.fio in the same
  46 directory as this README).
  47
  48     LD_PRELOAD=<path to spdk repo>/build/fio/spdk_bdev fio
  49
  50 The fio configuration file must contain one new parameter:
  51
  52     spdk_conf=./examples/bdev/fio_plugin/bdev.conf
  53
  54 This must point at an SPDK configuration file. There are a number of example configuration
  55 files in the SPDK repository under etc/spdk.
  56
  57 You can specify which block device to run against by setting the filename parameter
  58 to the block device name:
  59
  60     filename=Malloc0
  61
  62 Or for NVMe devices:
  63
  64     filename=Nvme0n1
  65
  66 Currently the SPDK fio plugin is limited to the thread usage model, so fio jobs must also specify thread=1
  67 when using the SPDK fio plugin.
  68
  69 fio also currently has a race condition on shutdown if dynamically loading the ioengine by specifying the
  70 engine's full path via the ioengine parameter - LD_PRELOAD is recommended to avoid this race condition.
  71
  72 When testing random workloads, it is recommended to set norandommap=1.  fio's random map
  73 processing consumes extra CPU cycles which will degrade performance over time with
  74 the fio_plugin since all I/O are submitted and completed on a single CPU core.