blob: 7e87c47b8ef8ea52940b0757884d4cf9164b2435 [file] [log] [blame]
Jens Axboeebac4652005-12-08 15:25:21 +01001fio
2---
3
Jens Axboe79809112006-06-09 10:14:54 +02004fio is a tool that will spawn a number of threads or processes doing a
5particular type of io action as specified by the user. fio takes a
6number of global parameters, each inherited by the thread unless
7otherwise parameters given to them overriding that setting is given.
8The typical use of fio is to write a job file matching the io load
9one wants to simulate.
Jens Axboeebac4652005-12-08 15:25:21 +010010
Jens Axboe2b02b542005-12-08 15:29:14 +010011
12Source
13------
14
15fio resides in a git repo, the canonical place is:
16
Jens Axboe6b3eccb2007-07-18 13:51:19 +020017git://git.kernel.dk/fio.git
Jens Axboe97f049c2007-04-23 18:54:55 +020018
19The http protocol also works, path is the same.
Jens Axboe2b02b542005-12-08 15:29:14 +010020
Jens Axboe79809112006-06-09 10:14:54 +020021Snapshots are frequently generated and they include the git meta data as
22well. You can download them here:
Jens Axboe2b02b542005-12-08 15:29:14 +010023
24http://brick.kernel.dk/snaps/
25
Jens Axboea68594c2007-03-05 12:37:54 +010026Pascal Bleser <guru@unixtech.be> has fio RPMs in his repository for
27SUSE variants, you can find them here:
Jens Axboe1053a102006-06-06 09:23:13 +020028
29http://linux01.gwdg.de/~pbleser/rpm-navigation.php?cat=System/fio
30
Jens Axboea68594c2007-03-05 12:37:54 +010031Dag Wieërs has RPMs for Red Hat related distros, find them here:
32
33http://dag.wieers.com/rpm/packages/fio/
34
Jens Axboe244e1702007-07-19 14:21:08 +020035Mandriva has integrated fio into their package repository, so installing
36on that distro should be as easy as typing 'urpmi fio'.
37
Jens Axboe2b02b542005-12-08 15:29:14 +010038
Jens Axboe726f6ff2007-01-03 21:02:41 +010039Mailing list
40------------
41
42There's a mailing list associated with fio. It's meant for general
43discussion, bug reporting, questions - basically anything that has to
44do with fio. An automated mail detailing recent commits is automatically
45sent to the list at most daily. The list address is fio-devel@kernel.dk,
46subscribe by sending an empty email to fio-devel+subscribe@kernel.dk.
47
48
Jens Axboebbfd6b02006-06-07 19:42:54 +020049Building
50--------
51
52Just type 'make' and 'make install'. If on FreeBSD, for now you have to
53specify the FreeBSD Makefile with -f, eg:
54
55$ make -f Makefile.Freebsd && make -f Makefile.FreeBSD install
56
Jens Axboeedffcb92006-06-08 13:40:18 +020057Likewise with OpenSolaris, use the Makefile.solaris to compile there.
Jens Axboebbfd6b02006-06-07 19:42:54 +020058This might change in the future if I opt for an autoconf type setup.
59
60
Jens Axboe972cfd22006-06-09 11:08:56 +020061Command line
62------------
Jens Axboeebac4652005-12-08 15:25:21 +010063
64$ fio
Jens Axboeb4692822006-10-27 13:43:22 +020065 --output Write output to file
Jens Axboe03b74b32007-01-11 11:04:31 +010066 --runtime Runtime in seconds
Jens Axboeb4692822006-10-27 13:43:22 +020067 --latency-log Generate per-job latency logs
68 --bandwidth-log Generate per-job bandwidth logs
69 --minimal Minimal (terse) output
70 --version Print version info and exit
Jens Axboefd28ca42007-01-09 21:20:13 +010071 --help Print this page
72 --cmdhelp=cmd Print command help, "all" for all of them
Jens Axboecca73aa2007-04-04 11:09:19 +020073 --showcmd Turn a job file into command line options
Jens Axboeebac4652005-12-08 15:25:21 +010074
Jens Axboeb4692822006-10-27 13:43:22 +020075Any parameters following the options will be assumed to be job files,
76unless they match a job file parameter. You can add as many as you want,
77each job file will be regarded as a separate group and fio will stonewall
78its execution.
Jens Axboe972cfd22006-06-09 11:08:56 +020079
Jens Axboe79809112006-06-09 10:14:54 +020080
81Job file
82--------
83
Jens Axboe71bfa162006-10-25 11:08:19 +020084See the HOWTO file for a more detailed description of parameters and what
85they mean. This file contains the terse version. Only a few options can
86be controlled with command line parameters, generally it's a lot easier to
87just write a simple job file to describe the workload. The job file format
88is in the ini style format, as it's easy to read and write for the user.
Jens Axboe79809112006-06-09 10:14:54 +020089
90The job file parameters are:
Jens Axboeebac4652005-12-08 15:25:21 +010091
Jens Axboe01452052006-06-07 10:29:47 +020092 name=x Use 'x' as the identifier for this job.
Jens Axboe61697c32007-02-05 15:04:46 +010093 description=x 'x' is a text description of the job.
Jens Axboeebac4652005-12-08 15:25:21 +010094 directory=x Use 'x' as the top level directory for storing files
Jens Axboeb50b8752006-10-24 19:05:53 +020095 filename=x Force the use of 'x' as the filename for all files
96 in this thread. If not given, fio will make up
97 a suitable filename based on the thread and file
98 number.
Jens Axboe3d60d1e2006-05-25 06:31:06 +020099 rw=x 'x' may be: read, randread, write, randwrite,
100 rw (read-write mix), randrw (read-write random mix)
Jens Axboea6ccc7b2006-06-02 10:14:15 +0200101 rwmixcycle=x Base cycle for switching between read and write
102 in msecs.
103 rwmixread=x 'x' percentage of rw mix ios will be reads. If
104 rwmixwrite is also given, the last of the two will
105 be used if they don't add up to 100%.
106 rwmixwrite=x 'x' percentage of rw mix ios will be writes. See
107 rwmixread.
Jens Axboe9ebc27e2006-06-12 10:21:50 +0200108 rand_repeatable=x The sequence of random io blocks can be repeatable
109 across runs, if 'x' is 1.
Jens Axboeebac4652005-12-08 15:25:21 +0100110 size=x Set file size to x bytes (x string can include k/m/g)
111 ioengine=x 'x' may be: aio/libaio/linuxaio for Linux aio,
112 posixaio for POSIX aio, sync for regular read/write io,
Jens Axboed0ff85d2007-02-14 01:19:41 +0100113 mmap for mmap'ed io, syslet-rw for syslet driven
114 read/write, splice for using splice/vmsplice,
Jens Axboeba0fbe12007-03-09 14:34:23 +0100115 sgio for direct SG_IO io, net for network io, or cpuio
116 for a cycler burner load. sgio only works on Linux on
117 SCSI (or SCSI-like devices, such as usb-storage or
118 sata/libata driven) devices. Fio also has a null io
119 engine, which is mainly used for testing fio itself.
Jens Axboeebac4652005-12-08 15:25:21 +0100120 iodepth=x For async io, allow 'x' ios in flight
121 overwrite=x If 'x', layout a write file first.
Jens Axboe53cdc682006-10-18 11:50:58 +0200122 nrfiles=x Spread io load over 'x' number of files per job,
123 if possible.
Jens Axboeebac4652005-12-08 15:25:21 +0100124 prio=x Run io at prio X, 0-7 is the kernel allowed range
125 prioclass=x Run io at prio class X
126 bs=x Use 'x' for thread blocksize. May include k/m postfix.
127 bsrange=x-y Mix thread block sizes randomly between x and y. May
128 also include k/m postfix.
129 direct=x 1 for direct IO, 0 for buffered IO
130 thinktime=x "Think" x usec after each io
131 rate=x Throttle rate to x KiB/sec
132 ratemin=x Quit if rate of x KiB/sec can't be met
133 ratecycle=x ratemin averaged over x msecs
134 cpumask=x Only allow job to run on CPUs defined by mask.
Jens Axboed2e268b2007-06-15 10:33:49 +0200135 cpus_allowed=x Like 'cpumask', but allow text setting of CPU affinity.
Jens Axboe795407c2006-10-24 19:42:44 +0200136 fsync=x If writing with buffered IO, fsync after every
137 'x' blocks have been written.
138 end_fsync=x If 'x', run fsync() after end-of-job.
Jens Axboeebac4652005-12-08 15:25:21 +0100139 startdelay=x Start this thread x seconds after startup
Jens Axboe03b74b32007-01-11 11:04:31 +0100140 runtime=x Terminate x seconds after startup. Can include a
Jens Axboe906c8d72006-06-13 09:37:56 +0200141 normal time suffix if not given in seconds, such as
142 'm' for minutes, 'h' for hours, and 'd' for days.
Jens Axboeebac4652005-12-08 15:25:21 +0100143 offset=x Start io at offset x (x string can include k/m/g)
144 invalidate=x Invalidate page cache for file prior to doing io
Jens Axboe795407c2006-10-24 19:42:44 +0200145 sync=x Use sync writes if x and writing buffered IO.
Jens Axboeebac4652005-12-08 15:25:21 +0100146 mem=x If x == malloc, use malloc for buffers. If x == shm,
Jens Axboe795407c2006-10-24 19:42:44 +0200147 use shared memory for buffers. If x == mmap, use
148 anonymous mmap.
Jens Axboeebac4652005-12-08 15:25:21 +0100149 exitall When one thread quits, terminate the others
150 bwavgtime=x Average bandwidth stats over an x msec window.
151 create_serialize=x If 'x', serialize file creation.
152 create_fsync=x If 'x', run fsync() after file creation.
Jens Axboef6cbb262006-10-18 14:16:42 +0200153 unlink If set, unlink files when done.
Jens Axboeebac4652005-12-08 15:25:21 +0100154 loops=x Run the job 'x' number of times.
155 verify=x If 'x' == md5, use md5 for verifies. If 'x' == crc32,
156 use crc32 for verifies. md5 is 'safer', but crc32 is
157 a lot faster. Only makes sense for writing to a file.
158 stonewall Wait for preceeding jobs to end before running.
159 numjobs=x Create 'x' similar entries for this job
160 thread Use pthreads instead of forked jobs
Jens Axboe20dc95c2005-12-09 10:29:35 +0100161 zonesize=x
162 zoneskip=y Zone options must be paired. If given, the job
163 will skip y bytes for every x read/written. This
164 can be used to gauge hard drive speed over the entire
165 platter, without reading everything. Both x/y can
166 include k/m/g suffix.
Jens Axboeaea47d42006-05-26 19:27:29 +0200167 iolog=x Open and read io pattern from file 'x'. The file must
168 contain one io action per line in the following format:
169 rw, offset, length
170 where with rw=0/1 for read/write, and the offset
171 and length entries being in bytes.
Jens Axboe843a7412006-06-01 21:14:21 -0700172 write_iolog=x Write an iolog to file 'x' in the same format as iolog.
173 The iolog options are exclusive, if both given the
174 read iolog will be performed.
Jens Axboeec94ec52006-10-20 10:59:19 +0200175 write_bw_log Write a bandwidth log.
176 write_lat_log Write a latency log.
Jens Axboec04f7ec2006-05-31 10:13:16 +0200177 lockmem=x Lock down x amount of memory on the machine, to
178 simulate a machine with less memory available. x can
179 include k/m/g suffix.
Jens Axboeb6f4d882006-06-02 10:32:51 +0200180 nice=x Run job at given nice value.
Jens Axboe4e0ba8a2006-06-06 09:36:28 +0200181 exec_prerun=x Run 'x' before job io is begun.
182 exec_postrun=x Run 'x' after job io has finished.
Jens Axboeda867742006-06-06 10:39:10 -0700183 ioscheduler=x Use ioscheduler 'x' for this job.
Jens Axboeb990b5c2006-09-14 09:48:22 +0200184 cpuload=x For a CPU io thread, percentage of CPU time to attempt
185 to burn.
Jens Axboeba0fbe12007-03-09 14:34:23 +0100186 cpuchunks=x Split burn cycles into pieces of x usecs.
Jens Axboeebac4652005-12-08 15:25:21 +0100187
Jens Axboe79809112006-06-09 10:14:54 +0200188
Jens Axboe79809112006-06-09 10:14:54 +0200189Author
190------
191
Jens Axboeaae22ca2006-09-05 10:46:22 +0200192Fio was written by Jens Axboe <axboe@kernel.dk> to enable flexible testing
Jens Axboe79809112006-06-09 10:14:54 +0200193of the Linux IO subsystem and schedulers. He got tired of writing
194specific test applications to simulate a given workload, and found that
195the existing io benchmark/test tools out there weren't flexible enough
196to do what he wanted.
197
Jens Axboeaae22ca2006-09-05 10:46:22 +0200198Jens Axboe <axboe@kernel.dk> 20060905
Jens Axboe79809112006-06-09 10:14:54 +0200199