fio
---

fio is a tool that will spawn a number of thread doing a particular
type of io 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.

Options
-------

$ fio
	-s IO is sequential
	-b block size in KiB for each io
	-t <sec> Runtime in seconds
	-r For random io, sequence must be repeatable
	-R <on> If one thread fails to meet rate, quit all
	-o <on> Use direct IO is 1, buffered if 0
	-l Generate per-job latency logs
	-w Generate per-job bandwidth logs
	-f <file> Read <file> for job descriptions

The <jobs> format is as follows:

	directory=x	Use 'x' as the top level directory for storing files
	rw=0/1		0 is read, 1 is write
	prio=x		Run io at prio X, 0-7 is the kernel allowed range
	prioclass=x	Run io at prio class X
	file=foo	Do the io to file foo
	bs=x		Thread blocksize is x bytes
	bsrange=x-y	Mix thread block sizes randomly between x and y
	direct=x	1 for direct IO, 0 for buffered IO
	thinktime=x	"Think" x usec after each io
	random		IO is randomized
	sequential	IO is sequential
	rate=x		Throttle rate to x KiB/sec
	ratemin=x	Quit if rate of x KiB/sec can't be met
	ratecycle=x	ratemin averaged over x msecs
	cpumask=x	Allow job to run on CPUs defined by mask
	fsync=x		If writing, fsync after every x blocks have been written
	startdelay=x	Start this thread x seconds after startup
	timeout=x	Terminate x seconds after startup
	aio		Use Linux async io
	aio_depth=x	Allow x iocbs in flight
	size=x		Set file size to x bytes (x string can include k/m/g)
	offset=x	Start io at offset x (x string can include k/m/g)
	invalidate=x	Invalidate page cache for file prior to doing io
	sync=x		Use sync writes if x and writing
	mem=x		If x == malloc, use malloc for buffers. If x == shm,
			use shm for buffers.
	exitall		When one thread quits, terminate the others
	bwavgtime=x	Average bandwidth stats over x msec
	create_serialize=x	If 'x', serialize file creation.
	create_fsync=x	If 'x', run fsync() after file creation.
	loops=x		Run the job 'x' number of times.
	verify=x	If 'x' and writing, verify data written.
	stonewall	Wait for preceeding jobs to end before running.
	numjobs=x	Create 'x' similar entries for this job


Examples using a job file
-------------------------

A sample job file doing the same as above would look like this:

[read_file]
rw=0
bs=4096

[write_file]
rw=1
bs=16384

And fio would be invoked as:

$ fio -o1 -s -f file_with_above

The second example would look like this:

[rf1]
rw=0
prio=6

[rf2]
rw=0
prio=3

[rf3]
rw=0
prio=0
direct=1

And fio would be invoked as:

$ fio -o0 -s -b4096 -f file_with_above

'global' is a reserved keyword. When used as the filename, it sets the
default options for the threads following that section. It is possible
to have more than one global section in the file, as it only affects
subsequent jobs.

Also see the examples/ dir for sample job files.