Flexible I/O Tester
C Roff C++ Makefile Python Yacc Other
Latest commit f678f8d Mar 21, 2017 @vapier vapier committed with configure: add a --disable-rdma flag to control rdma deps
Signed-off-by: Mike Frysinger <vapier@gentoo.org>
Signed-off-by: Jens Axboe <axboe@fb.com>
Permalink
Failed to load latest commit information.
arch Add arm64 hardware assisted crc32c support Jan 5, 2017
compiler configure: disable compile time asserts for !opt and !static_assert Feb 22, 2017
crc crc: add support for sha3 variants Mar 8, 2017
doc fix manpage heading issue Jan 21, 2017
engines rbd: don't log version to stdout Mar 13, 2017
examples fio: add additional support for dev-dax ioengine Dec 16, 2016
exp Fixup some of the time (usec) based conversions Nov 11, 2014
lib is_power_of_2() should return bool Mar 17, 2017
os configure: add generic pshared mutex test Mar 14, 2017
oslib Fix memory leak on tmp_buf Nov 14, 2016
profiles tests, profiles: Use IEC prefixes for binary multiples Jan 3, 2017
t Fix the return type of log_err and log_info functions Feb 13, 2017
tools Python style/portability fix Jan 10, 2017
unit_tests Avoid using units in option defaults Jan 3, 2017
.gitignore ignore documentation output directory Jan 20, 2017
.travis.yml travis: add OS X builds Feb 16, 2017
COPYING Move fio to seperate repo Dec 8, 2005
FIO-VERSION-GEN Fio 2.18 Feb 23, 2017
GFIO-TODO gfio: update TODO Mar 13, 2012
HOWTO HOWTO: Mention fsync=/fsyncdata= are set to 0 by default Mar 21, 2017
MORAL-LICENSE Moral license update Feb 6, 2015
Makefile Makefile: make test target use thread Mar 13, 2017
README configure: add generic pshared mutex test Mar 14, 2017
REPORTING-BUGS Update REPORTING-BUGS Oct 14, 2016
SERVER-TODO Add disk utilization to terse format output Oct 13, 2011
STEADYSTATE-TODO steadystate: rename TODO to STEADYSTATE-TODO Dec 7, 2016
appveyor.yml appveyor: add CI building of the Windows version of fio Feb 20, 2017
backend.c Make check_mount_writes() test appropriate device types Mar 13, 2017
blktrace.c iolog: add support for replay_scale option Dec 12, 2016
blktrace_api.h Add support for replaying blktrace trim/discard Aug 25, 2010
cairo_text_helpers.c cairo_text_helpers: fix left justified text Mar 28, 2012
cairo_text_helpers.h White space spring cleaning Mar 27, 2012
cconv.c Add 'stats' option Mar 16, 2017
cgroup.c Use in-place path separator "/" for Linux specific code Jul 29, 2016
cgroup.h Fix typo Feb 15, 2012
client.c Add missing trailing \n in log_err/info() Jan 3, 2017
client.h Various cleanups Aug 16, 2016
configure configure: add a --disable-rdma flag to control rdma deps Mar 21, 2017
debug.c debug: ensure that __dprint() is also logged over the network Sep 11, 2013
debug.h Split helper thread debug logging away from steadystate debug logging Aug 15, 2016
diskutil.c Drop conditional declaration of disk_list Feb 14, 2017
diskutil.h Add a comment to clarify 941bda9 Feb 13, 2017
err.h Make err.h a bit more Windows friendly Feb 12, 2014
eta.c Use 0 instead of DDIR_READ to iterate from 0 to DDIR_RWDIR_CNT Feb 14, 2017
fifo.c Fix a few other static code checker spotted "issues" Feb 9, 2012
fifo.h fifo: use minmax.h instead of rolling its own min/max Sep 23, 2014
file.h Use union for per file engine private data storage Mar 10, 2017
filehash.c filehash: move to separate allocation Sep 26, 2016
filehash.h filehash: move to separate allocation Sep 26, 2016
filelock.c filelock: bool conversion Aug 29, 2016
filelock.h filelock: bool conversion Aug 29, 2016
filesetup.c Fix a comment after f227e2b Mar 21, 2017
fio.1 Add 'stats' option Mar 16, 2017
fio.c fio: inherit IO engine flags to 'td' Aug 15, 2016
fio.h Define struct sk_out in server.h (not server.c) Mar 21, 2017
fio_time.h Option for changing log files to use Unix epoch instead of being Aug 18, 2016
flist.h flist: add flist_last_entry() May 19, 2016
flow.c smalloc: OOM fixups Sep 25, 2016
flow.h Token-based flow control Feb 20, 2012
gclient.c Use ARRAY_SIZE() Jan 23, 2017
gclient.h gfio: add and colorize graphs on main page, too Sep 25, 2012
gcompat.c gcompat: gtk_widget_set_can_focus() for below 2.18 Mar 26, 2012
gcompat.h White space spring cleaning Mar 27, 2012
gerror.c gerror: mixed code/data section Apr 18, 2013
gerror.h gfio: split some parts into gclient.c Mar 21, 2012
gettime-thread.c pthread: bump min stack size Jul 14, 2016
gettime.c fio: Fix (unsigned) integer overflow issues Nov 27, 2016
gettime.h gettime.h: use time_t instead of size_t for copy of tv_sec Feb 16, 2015
gfio.c gfio: fix git location for fio Feb 13, 2017
gfio.h gfio: add trim UI support Sep 24, 2012
ghelpers.c gfio: add and colorize graphs on main page, too Sep 25, 2012
ghelpers.h gfio: add and colorize graphs on main page, too Sep 25, 2012
goptions.c Clean up unit prefixes for binary multiples in comments and prints Jan 3, 2017
goptions.h gfio: add per-job option view Mar 24, 2012
graph.c flist: add flist_first_entry() Jul 4, 2014
graph.h gfio: clear graphs for repeated runs on same connection Sep 26, 2012
hash.h hash: make 64-bit even on 32-bit May 25, 2016
helper_thread.c steadystate: rename 'steadystate' to 'steadystate_enabled' Aug 15, 2016
helper_thread.h helper_thread: split into separate file May 6, 2016
helpers.c helpers: fixup bad fadvise check May 22, 2013
helpers.h Add configure script Jan 10, 2013
idletime.c Spelling fix. May 24, 2016
idletime.h Enable the use of multiple output formats Oct 27, 2015
init.c Replace redundant TD_F_NOIO flag with td->io_ops_init Mar 21, 2017
io_ddir.h Add missing "rand"/"trimwrite" strings to corresponding ddir slots Feb 14, 2017
io_u.c Test fsync/fdatasync/sync_file_range for the next i/o only if should_… Mar 21, 2017
io_u_queue.c io_u_queue: add debug assert check on adding too many elements Mar 20, 2015
io_u_queue.h io_u_queue: add debug assert check on adding too many elements Mar 20, 2015
ioengine.h Remove unused io_u's priv union field Jan 23, 2017
ioengines.c Replace redundant TD_F_NOIO flag with td->io_ops_init Mar 21, 2017
iolog.c Add missing trailing \n in dprint() Jan 10, 2017
iolog.h fix to replay_align on iolog Feb 2, 2017
json.c use type double in creating floating point JSON values Dec 16, 2016
json.h Enable the use of multiple output formats Oct 27, 2015
libfio.c Replace redundant TD_F_NOIO flag with td->io_ops_init Mar 21, 2017
log.c log: remove log_local_buf() Dec 10, 2015
log.h log: remove log_local_buf() Dec 10, 2015
memory.c Clean up unit prefixes for binary multiples in comments and prints Jan 3, 2017
minmax.h A few min/max cleanups Nov 23, 2015
mutex.c configure: add generic pshared mutex test Mar 14, 2017
mutex.h mutex: abstract out cond/lock pshared init May 25, 2016
optgroup.c Add missing opt/cat group entries Jan 20, 2017
optgroup.h options: split out option grouping code Dec 30, 2015
options.c Add 'stats' option Mar 16, 2017
options.h Various cleanups Aug 16, 2016
parse.c fio: fix overflow trying to use 'd' suffix Feb 24, 2017
parse.h Change td_var() to take void* for the first arg Jan 19, 2017
printing.c White space spring cleaning Mar 27, 2012
printing.h gfio: Add "print" option for results page. Mar 27, 2012
profile.c parse: get rid of raw option offsets Feb 11, 2014
profile.h parse: get rid of raw option offsets Feb 11, 2014
rate-submit.c Remove unassigned fio_unused variable Mar 10, 2017
rate-submit.h Fixup and improve per-thread data Dec 11, 2015
server.c Define struct sk_out in server.h (not server.c) Mar 21, 2017
server.h Define struct sk_out in server.h (not server.c) Mar 21, 2017
smalloc.c Define pointer alignment macro in fio.h Jan 23, 2017
smalloc.h smalloc: add zeroing scalloc() variant Nov 6, 2014
stat.c Add 'stats' option Mar 16, 2017
stat.h Convert group_run_stats to use bytes instead of KiB/KB Jan 3, 2017
steadystate.c Use 0 instead of DDIR_READ to iterate from 0 to DDIR_RWDIR_CNT Feb 14, 2017
steadystate.h steadystate: use uint64_t for storing bw and iops calculations and re… Dec 7, 2016
td_error.c Split out td error handling code Apr 17, 2013
td_error.h Split out td error handling code Apr 17, 2013
thread_options.h Add 'stats' option Mar 16, 2017
tickmarks.c White space spring cleaning Mar 27, 2012
tickmarks.h gfio: graphing updates Mar 14, 2012
time.c Option for changing log files to use Unix epoch instead of being Aug 18, 2016
trim.c trim: convert to bool Aug 29, 2016
trim.h trim: convert to bool Aug 29, 2016
verify-state.h verify: use proper include for PATH_MAX Aug 20, 2016
verify.c Drop redundant td_rw(td) tests Mar 10, 2017
verify.h verify: add support for the sha3 variants Mar 8, 2017
workqueue.c smalloc: OOM fixups Sep 25, 2016
workqueue.h workqueue: rename private to priv for compiling as c++ Jul 11, 2016

README

Overview and history
--------------------

Fio was originally written to save me the hassle of writing special test case
programs when I wanted to test a specific workload, either for performance
reasons or to find/reproduce a bug. The process of writing such a test app can
be tiresome, especially if you have to do it often.  Hence I needed a tool that
would be able to simulate a given I/O workload without resorting to writing a
tailored test case again and again.

A test work load is difficult to define, though. There can be any number of
processes or threads involved, and they can each be using their own way of
generating I/O. You could have someone dirtying large amounts of memory in an
memory mapped file, or maybe several threads issuing reads using asynchronous
I/O. fio needed to be flexible enough to simulate both of these cases, and many
more.

Fio spawns a number of threads or processes doing a particular type of I/O
action as specified by the user. fio takes a number of global parameters, each
inherited by the thread unless otherwise parameters given to them overriding
that setting is given.  The typical use of fio is to write a job file matching
the I/O load one wants to simulate.


Source
------

Fio resides in a git repo, the canonical place is:

	git://git.kernel.dk/fio.git

When inside a corporate firewall, git:// URL sometimes does not work.
If git:// does not work, use the http protocol instead:

	http://git.kernel.dk/fio.git

Snapshots are frequently generated and :file:`fio-git-*.tar.gz` include the git
meta data as well. Other tarballs are archives of official fio releases.
Snapshots can download from:

	http://brick.kernel.dk/snaps/

There are also two official mirrors. Both of these are automatically synced with
the main repository, when changes are pushed. If the main repo is down for some
reason, either one of these is safe to use as a backup:

	git://git.kernel.org/pub/scm/linux/kernel/git/axboe/fio.git

	https://git.kernel.org/pub/scm/linux/kernel/git/axboe/fio.git

or

	git://github.com/axboe/fio.git

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


Mailing list
------------

The fio project mailing list is meant for anything related to fio including
general discussion, bug reporting, questions, and development.

An automated mail detailing recent commits is automatically sent to the list at
most daily. The list address is fio@vger.kernel.org, subscribe by sending an
email to majordomo@vger.kernel.org with

	subscribe fio

in the body of the email. Archives can be found here:

	http://www.spinics.net/lists/fio/

and archives for the old list can be found here:

	http://maillist.kernel.dk/fio-devel/


Author
------

Fio was written by Jens Axboe <axboe@kernel.dk> to enable flexible testing of
the Linux I/O subsystem and schedulers. He got tired of writing specific test
applications to simulate a given workload, and found that the existing I/O
benchmark/test tools out there weren't flexible enough to do what he wanted.

Jens Axboe <axboe@kernel.dk> 20060905


Binary packages
---------------

Debian:
	Starting with Debian "Squeeze", fio packages are part of the official
	Debian repository. http://packages.debian.org/search?keywords=fio .

Ubuntu:
	Starting with Ubuntu 10.04 LTS (aka "Lucid Lynx"), fio packages are part
	of the Ubuntu "universe" repository.
	http://packages.ubuntu.com/search?keywords=fio .

Red Hat, Fedora, CentOS & Co:
	Starting with Fedora 9/Extra Packages for Enterprise Linux 4, fio
	packages are part of the Fedora/EPEL repositories.
	https://admin.fedoraproject.org/pkgdb/package/rpms/fio/ .

Mandriva:
	Mandriva has integrated fio into their package repository, so installing
	on that distro should be as easy as typing ``urpmi fio``.

Solaris:
	Packages for Solaris are available from OpenCSW. Install their pkgutil
	tool (http://www.opencsw.org/get-it/pkgutil/) and then install fio via
	``pkgutil -i fio``.

Windows:
	Rebecca Cran <rebecca+fio@bluestop.org> has fio packages for Windows at
	http://www.bluestop.org/fio/ .

BSDs:
	Packages for BSDs may be available from their binary package repositories.
	Look for a package "fio" using their binary package managers.


Building
--------

Just type::

 $ ./configure
 $ make
 $ make install

Note that GNU make is required. On BSDs it's available from devel/gmake within
ports directory; on Solaris it's in the SUNWgmake package.  On platforms where
GNU make isn't the default, type ``gmake`` instead of ``make``.

Configure will print the enabled options. Note that on Linux based platforms,
the libaio development packages must be installed to use the libaio
engine. Depending on distro, it is usually called libaio-devel or libaio-dev.

For gfio, gtk 2.18 (or newer), associated glib threads, and cairo are required
to be installed.  gfio isn't built automatically and can be enabled with a
``--enable-gfio`` option to configure.

To build fio with a cross-compiler::

 $ make clean
 $ make CROSS_COMPILE=/path/to/toolchain/prefix

Configure will attempt to determine the target platform automatically.

It's possible to build fio for ESX as well, use the ``--esx`` switch to
configure.


Windows
~~~~~~~

On Windows, Cygwin (http://www.cygwin.com/) is required in order to build
fio. To create an MSI installer package install WiX 3.8 from
http://wixtoolset.org and run :file:`dobuild.cmd` from the :file:`os/windows`
directory.

How to compile fio on 64-bit Windows:

 1. Install Cygwin (http://www.cygwin.com/). Install **make** and all
    packages starting with **mingw64-i686** and **mingw64-x86_64**.
 2. Open the Cygwin Terminal.
 3. Go to the fio directory (source files).
 4. Run ``make clean && make -j``.

To build fio on 32-bit Windows, run ``./configure --build-32bit-win`` before
``make``.

It's recommended that once built or installed, fio be run in a Command Prompt or
other 'native' console such as console2, since there are known to be display and
signal issues when running it under a Cygwin shell (see
http://code.google.com/p/mintty/issues/detail?id=56 for details).


Documentation
~~~~~~~~~~~~~

Fio uses Sphinx_ to generate documentation from the reStructuredText_ files.
To build HTML formatted documentation run ``make -C doc html`` and direct your
browser to :file:`./doc/output/html/index.html`.  To build manual page run
``make -C doc man`` and then ``man doc/output/man/fio.1``.  To see what other
output formats are supported run ``make -C doc help``.

.. _reStructuredText: http://www.sphinx-doc.org/rest.html
.. _Sphinx: http://www.sphinx-doc.org


Platforms
---------

Fio works on (at least) Linux, Solaris, AIX, HP-UX, OSX, NetBSD, OpenBSD,
Windows, FreeBSD, and DragonFly. Some features and/or options may only be
available on some of the platforms, typically because those features only apply
to that platform (like the solarisaio engine, or the splice engine on Linux).

Some features are not available on FreeBSD/Solaris even if they could be
implemented, I'd be happy to take patches for that. An example of that is disk
utility statistics and (I think) huge page support, support for that does exist
in FreeBSD/Solaris.

Fio uses pthread mutexes for signalling and locking and some platforms do not
support process shared pthread mutexes. As a result, on such platforms only
threads are supported. This could be fixed with sysv ipc locking or other
locking alternatives.

Other \*BSD platforms are untested, but fio should work there almost out of the
box. Since I don't do test runs or even compiles on those platforms, your
mileage may vary. Sending me patches for other platforms is greatly
appreciated. There's a lot of value in having the same test/benchmark tool
available on all platforms.

Note that POSIX aio is not enabled by default on AIX. Messages like these::

    Symbol resolution failed for /usr/lib/libc.a(posix_aio.o) because:
        Symbol _posix_kaio_rdwr (number 2) is not exported from dependent module /unix.

indicate one needs to enable POSIX aio. Run the following commands as root::

    # lsdev -C -l posix_aio0
        posix_aio0 Defined  Posix Asynchronous I/O
    # cfgmgr -l posix_aio0
    # lsdev -C -l posix_aio0
        posix_aio0 Available  Posix Asynchronous I/O

POSIX aio should work now. To make the change permanent::

    # chdev -l posix_aio0 -P -a autoconfig='available'
        posix_aio0 changed


Running fio
-----------

Running fio is normally the easiest part - you just give it the job file
(or job files) as parameters::

	$ fio [options] [jobfile] ...

and it will start doing what the *jobfile* tells it to do. You can give more
than one job file on the command line, fio will serialize the running of those
files. Internally that is the same as using the :option:`stonewall` parameter
described in the parameter section.

If the job file contains only one job, you may as well just give the parameters
on the command line. The command line parameters are identical to the job
parameters, with a few extra that control global parameters.  For example, for
the job file parameter :option:`iodepth=2 <iodepth>`, the mirror command line
option would be :option:`--iodepth 2 <iodepth>` or :option:`--iodepth=2
<iodepth>`. You can also use the command line for giving more than one job
entry. For each :option:`--name <name>` option that fio sees, it will start a
new job with that name.  Command line entries following a
:option:`--name <name>` entry will apply to that job, until there are no more
entries or a new :option:`--name <name>` entry is seen. This is similar to the
job file options, where each option applies to the current job until a new []
job entry is seen.

fio does not need to run as root, except if the files or devices specified in
the job section requires that. Some other options may also be restricted, such
as memory locking, I/O scheduler switching, and decreasing the nice value.

If *jobfile* is specified as ``-``, the job file will be read from standard
input.