blob: 3ef13eaa1a36d1453561ebd1dc330948637eb8b1 [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 Axboe724e4432007-09-11 20:02:05 +020074 --readonly Turn on safety read-only checks
Aaron Carrolle592a062007-09-14 09:49:41 +020075 --eta=when When ETA estimate should be printed
76 May be "always", "never" or "auto"
77
Jens Axboeebac4652005-12-08 15:25:21 +010078
Jens Axboeb4692822006-10-27 13:43:22 +020079Any parameters following the options will be assumed to be job files,
80unless they match a job file parameter. You can add as many as you want,
81each job file will be regarded as a separate group and fio will stonewall
82its execution.
Jens Axboe972cfd22006-06-09 11:08:56 +020083
Jens Axboe724e4432007-09-11 20:02:05 +020084The --readonly switch is an extra safety guard to prevent accidentically
85turning on a write setting when that is not desired. Fio will only write
86if rw=write/randwrite/rw/randrw is given, but this extra safety net can
87be used as an extra precaution. It will also enable a write check in the
88io engine core to prevent an accidental write due to a fio bug.
89
Jens Axboe79809112006-06-09 10:14:54 +020090
91Job file
92--------
93
Jens Axboe71bfa162006-10-25 11:08:19 +020094See the HOWTO file for a more detailed description of parameters and what
Jens Axboe4661f3d2007-08-15 09:32:21 +020095they mean. This file contains the terse version. You can describe big and
96complex setups with the command line, but generally it's a lot easier to
Jens Axboe71bfa162006-10-25 11:08:19 +020097just write a simple job file to describe the workload. The job file format
Jens Axboe4661f3d2007-08-15 09:32:21 +020098is in the ini style format, as that is easy to read and write for the user.
Jens Axboe79809112006-06-09 10:14:54 +020099
100The job file parameters are:
Jens Axboeebac4652005-12-08 15:25:21 +0100101
Jens Axboe01452052006-06-07 10:29:47 +0200102 name=x Use 'x' as the identifier for this job.
Jens Axboe61697c32007-02-05 15:04:46 +0100103 description=x 'x' is a text description of the job.
Jens Axboeebac4652005-12-08 15:25:21 +0100104 directory=x Use 'x' as the top level directory for storing files
Jens Axboeb50b8752006-10-24 19:05:53 +0200105 filename=x Force the use of 'x' as the filename for all files
106 in this thread. If not given, fio will make up
107 a suitable filename based on the thread and file
108 number.
Jens Axboe3d60d1e2006-05-25 06:31:06 +0200109 rw=x 'x' may be: read, randread, write, randwrite,
110 rw (read-write mix), randrw (read-write random mix)
Jens Axboea6ccc7b2006-06-02 10:14:15 +0200111 rwmixcycle=x Base cycle for switching between read and write
112 in msecs.
113 rwmixread=x 'x' percentage of rw mix ios will be reads. If
114 rwmixwrite is also given, the last of the two will
115 be used if they don't add up to 100%.
116 rwmixwrite=x 'x' percentage of rw mix ios will be writes. See
117 rwmixread.
Jens Axboe9ebc27e2006-06-12 10:21:50 +0200118 rand_repeatable=x The sequence of random io blocks can be repeatable
119 across runs, if 'x' is 1.
Jens Axboeebac4652005-12-08 15:25:21 +0100120 size=x Set file size to x bytes (x string can include k/m/g)
121 ioengine=x 'x' may be: aio/libaio/linuxaio for Linux aio,
122 posixaio for POSIX aio, sync for regular read/write io,
gurudas paia31041e2007-10-23 15:12:30 +0200123 psync for regular pread/pwrite io, mmap for mmap'ed io,
124 syslet-rw for syslet driven read/write, splice for using
125 splice/vmsplice, sgio for direct SG_IO io, net for
126 network io, or cpuio for a cycler burner load. sgio only
127 works on Linux on SCSI (or SCSI-like devices, such as
128 usb-storage or sata/libata driven) devices. Fio also has
129 a null io engine, which is mainly used for testing fio
130 itself.
Jens Axboeebac4652005-12-08 15:25:21 +0100131 iodepth=x For async io, allow 'x' ios in flight
132 overwrite=x If 'x', layout a write file first.
Jens Axboe53cdc682006-10-18 11:50:58 +0200133 nrfiles=x Spread io load over 'x' number of files per job,
134 if possible.
Jens Axboeebac4652005-12-08 15:25:21 +0100135 prio=x Run io at prio X, 0-7 is the kernel allowed range
136 prioclass=x Run io at prio class X
137 bs=x Use 'x' for thread blocksize. May include k/m postfix.
138 bsrange=x-y Mix thread block sizes randomly between x and y. May
139 also include k/m postfix.
140 direct=x 1 for direct IO, 0 for buffered IO
141 thinktime=x "Think" x usec after each io
142 rate=x Throttle rate to x KiB/sec
143 ratemin=x Quit if rate of x KiB/sec can't be met
144 ratecycle=x ratemin averaged over x msecs
145 cpumask=x Only allow job to run on CPUs defined by mask.
Jens Axboed2e268b2007-06-15 10:33:49 +0200146 cpus_allowed=x Like 'cpumask', but allow text setting of CPU affinity.
Jens Axboe795407c2006-10-24 19:42:44 +0200147 fsync=x If writing with buffered IO, fsync after every
148 'x' blocks have been written.
149 end_fsync=x If 'x', run fsync() after end-of-job.
Jens Axboeebac4652005-12-08 15:25:21 +0100150 startdelay=x Start this thread x seconds after startup
Jens Axboe03b74b32007-01-11 11:04:31 +0100151 runtime=x Terminate x seconds after startup. Can include a
Jens Axboe906c8d72006-06-13 09:37:56 +0200152 normal time suffix if not given in seconds, such as
153 'm' for minutes, 'h' for hours, and 'd' for days.
Jens Axboeebac4652005-12-08 15:25:21 +0100154 offset=x Start io at offset x (x string can include k/m/g)
155 invalidate=x Invalidate page cache for file prior to doing io
Jens Axboe795407c2006-10-24 19:42:44 +0200156 sync=x Use sync writes if x and writing buffered IO.
Jens Axboeebac4652005-12-08 15:25:21 +0100157 mem=x If x == malloc, use malloc for buffers. If x == shm,
Jens Axboe795407c2006-10-24 19:42:44 +0200158 use shared memory for buffers. If x == mmap, use
159 anonymous mmap.
Jens Axboeebac4652005-12-08 15:25:21 +0100160 exitall When one thread quits, terminate the others
161 bwavgtime=x Average bandwidth stats over an x msec window.
162 create_serialize=x If 'x', serialize file creation.
163 create_fsync=x If 'x', run fsync() after file creation.
Jens Axboef6cbb262006-10-18 14:16:42 +0200164 unlink If set, unlink files when done.
Jens Axboeebac4652005-12-08 15:25:21 +0100165 loops=x Run the job 'x' number of times.
166 verify=x If 'x' == md5, use md5 for verifies. If 'x' == crc32,
167 use crc32 for verifies. md5 is 'safer', but crc32 is
168 a lot faster. Only makes sense for writing to a file.
169 stonewall Wait for preceeding jobs to end before running.
170 numjobs=x Create 'x' similar entries for this job
171 thread Use pthreads instead of forked jobs
Jens Axboe20dc95c2005-12-09 10:29:35 +0100172 zonesize=x
173 zoneskip=y Zone options must be paired. If given, the job
174 will skip y bytes for every x read/written. This
175 can be used to gauge hard drive speed over the entire
176 platter, without reading everything. Both x/y can
177 include k/m/g suffix.
Jens Axboeaea47d42006-05-26 19:27:29 +0200178 iolog=x Open and read io pattern from file 'x'. The file must
179 contain one io action per line in the following format:
180 rw, offset, length
181 where with rw=0/1 for read/write, and the offset
182 and length entries being in bytes.
Jens Axboe843a7412006-06-01 21:14:21 -0700183 write_iolog=x Write an iolog to file 'x' in the same format as iolog.
184 The iolog options are exclusive, if both given the
185 read iolog will be performed.
Jens Axboeec94ec52006-10-20 10:59:19 +0200186 write_bw_log Write a bandwidth log.
187 write_lat_log Write a latency log.
Jens Axboec04f7ec2006-05-31 10:13:16 +0200188 lockmem=x Lock down x amount of memory on the machine, to
189 simulate a machine with less memory available. x can
190 include k/m/g suffix.
Jens Axboeb6f4d882006-06-02 10:32:51 +0200191 nice=x Run job at given nice value.
Jens Axboe4e0ba8a2006-06-06 09:36:28 +0200192 exec_prerun=x Run 'x' before job io is begun.
193 exec_postrun=x Run 'x' after job io has finished.
Jens Axboeda867742006-06-06 10:39:10 -0700194 ioscheduler=x Use ioscheduler 'x' for this job.
Jens Axboeb990b5c2006-09-14 09:48:22 +0200195 cpuload=x For a CPU io thread, percentage of CPU time to attempt
196 to burn.
Jens Axboeba0fbe12007-03-09 14:34:23 +0100197 cpuchunks=x Split burn cycles into pieces of x usecs.
Jens Axboeebac4652005-12-08 15:25:21 +0100198
Jens Axboe79809112006-06-09 10:14:54 +0200199
Jens Axboe79809112006-06-09 10:14:54 +0200200Author
201------
202
Jens Axboeaae22ca2006-09-05 10:46:22 +0200203Fio was written by Jens Axboe <axboe@kernel.dk> to enable flexible testing
Jens Axboe79809112006-06-09 10:14:54 +0200204of the Linux IO subsystem and schedulers. He got tired of writing
205specific test applications to simulate a given workload, and found that
206the existing io benchmark/test tools out there weren't flexible enough
207to do what he wanted.
208
Jens Axboeaae22ca2006-09-05 10:46:22 +0200209Jens Axboe <axboe@kernel.dk> 20060905
Jens Axboe79809112006-06-09 10:14:54 +0200210