Flexible I/O Tester
C Roff Python Shell Makefile C++ Other
Clone or download
axboe axmap: optimize ulog64 usage in axmap_handler()
We can do this incrementally, no need to compute from scratch
for every iteration.

Signed-off-by: Jens Axboe <axboe@kernel.dk>
Latest commit edfca25 Jul 12, 2018
Permalink
Failed to load latest commit information.
arch x86: don't need 'level' passed to amd/intel init functions Jun 5, 2018
compiler compiler: set minimum compiler version to GCC 4.1.0 Mar 22, 2018
crc Minor style changes Mar 30, 2018
doc make fio scripts python3-ready May 16, 2018
engines glusterfs: capable to test with one single glfs instance Jun 20, 2018
examples Add support for Ceph Rados benchmarking. Feb 14, 2018
exp fio: update FSF address Oct 29, 2017
lib axmap: optimize ulog64 usage in axmap_handler() Jul 12, 2018
os fallocate: use 'offset' parameter Jun 5, 2018
oslib configure: use proper CONFIG_ prefix for asprintf/vasprintf Apr 21, 2018
profiles Rename fio_mutex into fio_sem Mar 15, 2018
t t/axmap: add longer overlap test case Jul 11, 2018
tools make fio scripts python3-ready (part 2) May 24, 2018
unit_tests make fio scripts python3-ready May 16, 2018
.appveyor.yml Rename appveyor.yml into .appveyor.yml Jun 5, 2018
.gitignore .gitignore: ignore tags files and additional output binaries Dec 14, 2017
.travis.yml travis: add 32 bit build, minor updates and cleanups Sep 3, 2017
COPYING COPYING: update license file Oct 29, 2017
FIO-VERSION-GEN Fio 3.7 Jun 1, 2018
GFIO-TODO gfio: update TODO Mar 13, 2012
HOWTO doc: add text about possibly verify errors with norandommap Jun 21, 2018
MORAL-LICENSE Moral license update Feb 6, 2015
Makefile Makefile: lib/axmap no longer needs hweight Jul 10, 2018
README doc: add Windows processor group behaviour and Windows target option Mar 27, 2018
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
backend.c fio: work with cgroup2 as well Jun 29, 2018
blktrace.c blktrace: just ignore zero byte traces Jul 4, 2018
blktrace.h iolog/blktrace: boolean conversion Apr 27, 2018
blktrace_api.h blktrace: change barrier to a flush Apr 26, 2018
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 blktrace: add 'reply_skip' option Apr 26, 2018
cgroup.c fio: work with cgroup2 as well Jun 29, 2018
cgroup.h Fix compilation without cgroups Jun 29, 2018
client.c client: close dup'ed descriptor if fdopen() fails Jun 15, 2018
client.h client: remove 'cmd' argument to stop handler Jun 5, 2018
configure configure: use proper CONFIG_ prefix for asprintf/vasprintf Apr 21, 2018
debug.c Refactor #includes and headers Mar 21, 2018
debug.h blktrace: just ignore zero byte traces Jul 4, 2018
diskutil.c Suppress gcc 8 compiler warnings Jun 5, 2018
diskutil.h Refactor #includes and headers Mar 21, 2018
err.h Make err.h a bit more Windows friendly Feb 12, 2014
eta.c eta: fix dead variable assignments Apr 8, 2018
fifo.c Refactor #includes and headers Mar 21, 2018
fifo.h Refactor #includes and headers Mar 21, 2018
file.h Rename fio_mutex into fio_sem Mar 15, 2018
filehash.c Rename fio_mutex into fio_sem Mar 15, 2018
filehash.h filehash: move to separate allocation Sep 26, 2016
filelock.c Rename fio_mutex into fio_sem Mar 15, 2018
filelock.h filelock: bool conversion Aug 29, 2016
filesetup.c filesetup: make trim jobs respect --readonly during file open Jun 18, 2018
fio.1 doc: add text about possibly verify errors with norandommap Jun 21, 2018
fio.c Refactor #includes and headers Mar 21, 2018
fio.h fio: should_fsync() returns bool Jul 11, 2018
fio_sem.c Refactor #includes and headers Mar 21, 2018
fio_sem.h Rename fio_mutex into fio_sem Mar 15, 2018
fio_time.h Add include-what-you-use pragmas Mar 21, 2018
flist.h flist.h: replace offsetof macros by stddef.h include May 20, 2017
flow.c Rename fio_mutex into fio_sem Mar 15, 2018
flow.h Token-based flow control Feb 20, 2012
gclient.c client: remove 'cmd' argument to stop handler Jun 5, 2018
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 smalloc: oom cleanups Mar 22, 2018
gettime.c gettime: remove 'is_thread' variable to local clock init Jun 5, 2018
gettime.h gettime: remove 'is_thread' variable to local clock init Jun 5, 2018
gfio.c fio: update FSF address Oct 29, 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 fio: update FSF address Oct 29, 2017
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 Suppress uninteresting data race reports Mar 15, 2018
helper_thread.h Rename fio_mutex into fio_sem Mar 15, 2018
helpers.c Refactor #includes and headers Mar 21, 2018
helpers.h Refactor #includes and headers Mar 21, 2018
idletime.c idle-prof: Fix segment fault issue when run with '--idle-prof' and mu… Jun 8, 2018
idletime.h idle-prof: Fix segment fault issue when run with '--idle-prof' and mu… Jun 8, 2018
init.c init: abort write and trim jobs when --readonly option is present Jun 18, 2018
io_ddir.h io_ddir: revert separate ddir count change Jan 25, 2018
io_u.c io_u: ensure we generate the full length of block sizes Jul 10, 2018
io_u.h Remove binject engine Apr 8, 2018
io_u_queue.c io_u_queue: convert rings to bool Nov 2, 2017
io_u_queue.h Refactor #includes and headers Mar 21, 2018
ioengines.c This partly revert 97bb54c(add __load_ioengine() to separate ioengine… May 15, 2018
ioengines.h Introduce enum fio_q_status Apr 18, 2018
iolog.c Fix variable shadowing Jun 5, 2018
iolog.h iolog: remove 'td' from trim_io_piece() Jun 5, 2018
json.c Refactor #includes and headers Mar 21, 2018
json.h Refactor #includes and headers Mar 21, 2018
libfio.c Fix issue with rate_process=poisson and ramp time Jun 4, 2018
log.c log: fix signedness issue Jun 5, 2018
log.h log: fix signedness issue Jun 5, 2018
memory.c Refactor #includes and headers Mar 21, 2018
minmax.h A few min/max cleanups Nov 23, 2015
optgroup.c optgroup: move debug code into function Mar 20, 2018
optgroup.h sg: add read/write FUA options Mar 19, 2018
options.c options: check for conflict between trims and readonly option Jun 18, 2018
options.h option parsing: Mark arguments that are not modified as 'const' Apr 4, 2018
parse.c log: fix signedness issue Jun 5, 2018
parse.h parse: add support for soft deprecated options Apr 18, 2018
printing.c printing: use bigger on-stack buffer Aug 16, 2017
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 Remove prof_io_ops.fill_io_u_off(), .fill_io_u_size() and .get_next_f… Mar 9, 2018
pshared.c Split mutex.c and .h each into three files Mar 15, 2018
pshared.h Split mutex.c and .h each into three files Mar 15, 2018
rate-submit.c Deprecate verifysort and verifysort_nr Apr 18, 2018
rate-submit.h Fixup and improve per-thread data Dec 11, 2015
rwlock.c Improve Valgrind instrumentation of memory allocations Mar 15, 2018
rwlock.h Split mutex.c and .h each into three files Mar 15, 2018
server.c Fix variable shadowing Jun 5, 2018
server.h blktrace: add 'reply_skip' option Apr 26, 2018
smalloc.c smalloc: Remove Valgrind instrumentation Mar 23, 2018
smalloc.h Refactor #includes and headers Mar 21, 2018
stat.c fio: add job_runtime to the thread json output Jun 29, 2018
stat.h Remove show_run_stats() because it has no callers Jun 5, 2018
steadystate.c steadystate: check for division by zero in mean calculation Apr 8, 2018
steadystate.h Refactor #includes and headers Mar 21, 2018
td_error.c use ARRAY_SIZE() for ignore_error_nr[etype] Jun 7, 2017
td_error.h Refactor #includes and headers Mar 21, 2018
thread_options.h Fix start delay being the same across threads Jun 12, 2018
tickmarks.c White space spring cleaning Mar 27, 2012
tickmarks.h gfio: graphing updates Mar 14, 2012
time.c time: use bool for ramp time Sep 13, 2017
trim.c Refactor #includes and headers Mar 21, 2018
trim.h Refactor #includes and headers Mar 21, 2018
verify-state.h Move nowarn_snprintf.h to lib/ Jun 5, 2018
verify.c Deprecate verifysort and verifysort_nr Apr 18, 2018
verify.h Refactor #includes and headers Mar 21, 2018
workqueue.c Split mutex.c and .h each into three files Mar 15, 2018
workqueue.h Refactor #includes and headers Mar 21, 2018

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. For bug reporting,
see REPORTING-BUGS.

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://apps.fedoraproject.org/packages/fio .

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

Arch Linux:
        An Arch Linux package is provided under the Community sub-repository:
        https://www.archlinux.org/packages/?sort=&q=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
	https://www.bluestop.org/fio/ . The latest builds for Windows can also
	be grabbed from https://ci.appveyor.com/project/axboe/fio by clicking
	the latest x86 or x64 build, then selecting the ARTIFACTS tab.

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-x86_64**. Ensure
    **mingw64-x86_64-zlib** are installed if you wish
    to enable fio's log compression functionality.
 2. Open the Cygwin Terminal.
 3. Go to the fio directory (source files).
 4. Run ``make clean && make -j``.

To build fio for 32-bit Windows, ensure the -i686 versions of the previously
mentioned -x86_64 packages are installed and run ``./configure
--build-32bit-win`` before ``make``. To build an fio that supports versions of
Windows below Windows 7/Windows Server 2008 R2 also add ``--target-win-ver=xp``
to the end of the configure line that you run before doing ``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
https://github.com/mintty/mintty/issues/56 and
https://github.com/mintty/mintty/wiki/Tips#inputoutput-interaction-with-alien-programs
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.