[disktools.git] / README.fio

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

	<jobs>

The <jobs> format is as follows:

	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
	delay=x		Delay x useconds before 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


Examples using cmd line jobs
----------------------------

Spawn 2 threads, one read and one writer. Both threads want direct and
sequential io, set these as global options. The reader wants a 4kb block
size and the writer a 16kb block size, set those as thread options.

$ fio -o1 -s "{rw=0,file=read_file,bs=4096}" "{rw=1,file=write_file,bs=16384}"

Spawn 3 reader threads doing io at priorities 0, 3, and 6. The highest
prio thread wants direct io, the others buffered. All want a 4kb block
size.

$ fio -o0 -s -b4096 "{rw=0,file=rf1,prio=6}" "{rw=0,file=rf2,prio=3}" "{rw=0,file=rf3,prio=0,direct=1}"

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.
Commit	Line	Data
e709787c JA	1	fio
	2	---
	3
	4	fio is a tool that will spawn a number of thread doing a particular
	5	type of io action as specified by the user. fio takes a number of
	6	global parameters, each inherited by the thread unless otherwise
	7	parameters given to them overriding that setting is given.
	8
	9	Options
	10	-------
	11
	12	$ fio
	13	-s IO is sequential
86184d14	14	-b block size in KiB for each io
e709787c	15	-t <sec> Runtime in seconds
e709787c	16	-r For random io, sequence must be repeatable
02bdd9ba	17	-R <on> If one thread fails to meet rate, quit all
e709787c	18	-o <on> Use direct IO is 1, buffered if 0
a0a9b35b JA	19	-l Generate per-job latency logs
a0a9b35b JA	20	-w Generate per-job bandwidth logs
7dd1389e	21	-f <file> Read <file> for job descriptions
e709787c JA	22
	23	<jobs>
	24
	25	The <jobs> format is as follows:
	26
	27	rw=0/1 0 is read, 1 is write
	28	prio=x Run io at prio X, 0-7 is the kernel allowed range
	29	prioclass=x Run io at prio class X
	30	file=foo Do the io to file foo
8c033f93	31	bs=x Thread blocksize is x bytes
7889f07b	32	bsrange=x-y Mix thread block sizes randomly between x and y
e709787c JA	33	direct=x 1 for direct IO, 0 for buffered IO
	34	delay=x Delay x useconds before each io
	35	random IO is randomized
	36	sequential IO is sequential
86184d14	37	rate=x Throttle rate to x KiB/sec
4240cfa1 JA	38	ratemin=x Quit if rate of x KiB/sec can't be met
4240cfa1 JA	39	ratecycle=x ratemin averaged over x msecs
18e0b78c	40	cpumask=x Allow job to run on CPUs defined by mask
4240cfa1	41	fsync=x If writing, fsync after every x blocks have been written
fc24389f	42	startdelay=x Start this thread x seconds after startup
67903a2e	43	timeout=x Terminate x seconds after startup
43000118 JA	44	aio Use Linux async io
43000118 JA	45	aio_depth=x Allow x iocbs in flight
02983297 JA	46	size=x Set file size to x bytes (x string can include k/m/g)
02983297 JA	47	offset=x Start io at offset x (x string can include k/m/g)
b95799ca	48	invalidate=x Invalidate page cache for file prior to doing io
74b4b5fb	49	sync=x Use sync writes if x and writing
99c6704f JA	50	mem=x If x == malloc, use malloc for buffers. If x == shm,
99c6704f JA	51	use shm for buffers.
98dd52d6	52	exitall When one thread quits, terminate the others
e709787c JA	53
e709787c JA	54
7dd1389e JA	55	Examples using cmd line jobs
7dd1389e JA	56	----------------------------
e709787c JA	57
	58	Spawn 2 threads, one read and one writer. Both threads want direct and
	59	sequential io, set these as global options. The reader wants a 4kb block
	60	size and the writer a 16kb block size, set those as thread options.
	61
	62	$ fio -o1 -s "{rw=0,file=read_file,bs=4096}" "{rw=1,file=write_file,bs=16384}"
	63
	64	Spawn 3 reader threads doing io at priorities 0, 3, and 6. The highest
	65	prio thread wants direct io, the others buffered. All want a 4kb block
	66	size.
	67
	68	$ fio -o0 -s -b4096 "{rw=0,file=rf1,prio=6}" "{rw=0,file=rf2,prio=3}" "{rw=0,file=rf3,prio=0,direct=1}"
	69
7dd1389e JA	70	Examples using a job file
	71	-------------------------
	72
	73	A sample job file doing the same as above would look like this:
	74
	75	[read_file]
	76	rw=0
	77	bs=4096
	78
	79	[write_file]
	80	rw=1
	81	bs=16384
	82
	83	And fio would be invoked as:
	84
	85	$ fio -o1 -s -f file_with_above
	86
	87	The second example would look like this:
	88
	89	[rf1]
	90	rw=0
	91	prio=6
	92
	93	[rf2]
	94	rw=0
	95	prio=3
	96
	97	[rf3]
	98	rw=0
	99	prio=0
	100	direct=1
	101
	102	And fio would be invoked as:
	103
	104	$ fio -o0 -s -b4096 -f file_with_above
	105
47d45203 JA	106	'global' is a reserved keyword. When used as the filename, it sets the
	107	default options for the threads following that section. It is possible
	108	to have more than one global section in the file, as it only affects
	109	subsequent jobs.
ed864e24 JA	110
ed864e24 JA	111	Also see the examples/ dir for sample job files.
47d45203	112