1 Overview and history 2 -------------------- 3 4 Fio was originally written to save me the hassle of writing special test case 5 programs when I wanted to test a specific workload, either for performance 6 reasons or to find/reproduce a bug. The process of writing such a test app can 7 be tiresome, especially if you have to do it often. Hence I needed a tool that 8 would be able to simulate a given I/O workload without resorting to writing a 9 tailored test case again and again. 10 11 A test work load is difficult to define, though. There can be any number of 12 processes or threads involved, and they can each be using their own way of 13 generating I/O. You could have someone dirtying large amounts of memory in an 14 memory mapped file, or maybe several threads issuing reads using asynchronous 15 I/O. fio needed to be flexible enough to simulate both of these cases, and many 16 more. 17 18 Fio spawns a number of threads or processes doing a particular type of I/O 19 action as specified by the user. fio takes a number of global parameters, each 20 inherited by the thread unless otherwise parameters given to them overriding 21 that setting is given. The typical use of fio is to write a job file matching 22 the I/O load one wants to simulate. 23 24 25 Source 26 ------ 27 28 Fio resides in a git repo, the canonical place is: 29 30 git://git.kernel.dk/fio.git 31 32 When inside a corporate firewall, git:// URL sometimes does not work. 33 If git:// does not work, use the http protocol instead: 34 35 http://git.kernel.dk/fio.git 36 37 Snapshots are frequently generated and :file:`fio-git-*.tar.gz` include the git 38 meta data as well. Other tarballs are archives of official fio releases. 39 Snapshots can download from: 40 41 http://brick.kernel.dk/snaps/ 42 43 There are also two official mirrors. Both of these are automatically synced with 44 the main repository, when changes are pushed. If the main repo is down for some 45 reason, either one of these is safe to use as a backup: 46 47 git://git.kernel.org/pub/scm/linux/kernel/git/axboe/fio.git 48 49 https://git.kernel.org/pub/scm/linux/kernel/git/axboe/fio.git 50 51 or 52 53 git://github.com/axboe/fio.git 54 55 https://github.com/axboe/fio.git 56 57 58 Mailing list 59 ------------ 60 61 The fio project mailing list is meant for anything related to fio including 62 general discussion, bug reporting, questions, and development. 63 64 An automated mail detailing recent commits is automatically sent to the list at 65 most daily. The list address is fio (a] vger.kernel.org, subscribe by sending an 66 email to majordomo (a] vger.kernel.org with 67 68 subscribe fio 69 70 in the body of the email. Archives can be found here: 71 72 http://www.spinics.net/lists/fio/ 73 74 and archives for the old list can be found here: 75 76 http://maillist.kernel.dk/fio-devel/ 77 78 79 Author 80 ------ 81 82 Fio was written by Jens Axboe <axboe (a] kernel.dk> to enable flexible testing of 83 the Linux I/O subsystem and schedulers. He got tired of writing specific test 84 applications to simulate a given workload, and found that the existing I/O 85 benchmark/test tools out there weren't flexible enough to do what he wanted. 86 87 Jens Axboe <axboe (a] kernel.dk> 20060905 88 89 90 Binary packages 91 --------------- 92 93 Debian: 94 Starting with Debian "Squeeze", fio packages are part of the official 95 Debian repository. http://packages.debian.org/search?keywords=fio . 96 97 Ubuntu: 98 Starting with Ubuntu 10.04 LTS (aka "Lucid Lynx"), fio packages are part 99 of the Ubuntu "universe" repository. 100 http://packages.ubuntu.com/search?keywords=fio . 101 102 Red Hat, Fedora, CentOS & Co: 103 Starting with Fedora 9/Extra Packages for Enterprise Linux 4, fio 104 packages are part of the Fedora/EPEL repositories. 105 https://admin.fedoraproject.org/pkgdb/package/rpms/fio/ . 106 107 Mandriva: 108 Mandriva has integrated fio into their package repository, so installing 109 on that distro should be as easy as typing ``urpmi fio``. 110 111 Solaris: 112 Packages for Solaris are available from OpenCSW. Install their pkgutil 113 tool (http://www.opencsw.org/get-it/pkgutil/) and then install fio via 114 ``pkgutil -i fio``. 115 116 Windows: 117 Rebecca Cran <rebecca+fio (a] bluestop.org> has fio packages for Windows at 118 http://www.bluestop.org/fio/ . 119 120 BSDs: 121 Packages for BSDs may be available from their binary package repositories. 122 Look for a package "fio" using their binary package managers. 123 124 125 Building 126 -------- 127 128 Just type:: 129 130 $ ./configure 131 $ make 132 $ make install 133 134 Note that GNU make is required. On BSDs it's available from devel/gmake within 135 ports directory; on Solaris it's in the SUNWgmake package. On platforms where 136 GNU make isn't the default, type ``gmake`` instead of ``make``. 137 138 Configure will print the enabled options. Note that on Linux based platforms, 139 the libaio development packages must be installed to use the libaio 140 engine. Depending on distro, it is usually called libaio-devel or libaio-dev. 141 142 For gfio, gtk 2.18 (or newer), associated glib threads, and cairo are required 143 to be installed. gfio isn't built automatically and can be enabled with a 144 ``--enable-gfio`` option to configure. 145 146 To build fio with a cross-compiler:: 147 148 $ make clean 149 $ make CROSS_COMPILE=/path/to/toolchain/prefix 150 151 Configure will attempt to determine the target platform automatically. 152 153 It's possible to build fio for ESX as well, use the ``--esx`` switch to 154 configure. 155 156 157 Windows 158 ~~~~~~~ 159 160 On Windows, Cygwin (http://www.cygwin.com/) is required in order to build 161 fio. To create an MSI installer package install WiX 3.8 from 162 http://wixtoolset.org and run :file:`dobuild.cmd` from the :file:`os/windows` 163 directory. 164 165 How to compile fio on 64-bit Windows: 166 167 1. Install Cygwin (http://www.cygwin.com/). Install **make** and all 168 packages starting with **mingw64-i686** and **mingw64-x86_64**. 169 2. Open the Cygwin Terminal. 170 3. Go to the fio directory (source files). 171 4. Run ``make clean && make -j``. 172 173 To build fio on 32-bit Windows, run ``./configure --build-32bit-win`` before 174 ``make``. 175 176 It's recommended that once built or installed, fio be run in a Command Prompt or 177 other 'native' console such as console2, since there are known to be display and 178 signal issues when running it under a Cygwin shell (see 179 http://code.google.com/p/mintty/issues/detail?id=56 for details). 180 181 182 Documentation 183 ~~~~~~~~~~~~~ 184 185 Fio uses Sphinx_ to generate documentation from the reStructuredText_ files. 186 To build HTML formatted documentation run ``make -C doc html`` and direct your 187 browser to :file:`./doc/output/html/index.html`. To build manual page run 188 ``make -C doc man`` and then ``man doc/output/man/fio.1``. To see what other 189 output formats are supported run ``make -C doc help``. 190 191 .. _reStructuredText: http://www.sphinx-doc.org/rest.html 192 .. _Sphinx: http://www.sphinx-doc.org 193 194 195 Platforms 196 --------- 197 198 Fio works on (at least) Linux, Solaris, AIX, HP-UX, OSX, NetBSD, OpenBSD, 199 Windows, FreeBSD, and DragonFly. Some features and/or options may only be 200 available on some of the platforms, typically because those features only apply 201 to that platform (like the solarisaio engine, or the splice engine on Linux). 202 203 Some features are not available on FreeBSD/Solaris even if they could be 204 implemented, I'd be happy to take patches for that. An example of that is disk 205 utility statistics and (I think) huge page support, support for that does exist 206 in FreeBSD/Solaris. 207 208 Fio uses pthread mutexes for signalling and locking and some platforms do not 209 support process shared pthread mutexes. As a result, on such platforms only 210 threads are supported. This could be fixed with sysv ipc locking or other 211 locking alternatives. 212 213 Other \*BSD platforms are untested, but fio should work there almost out of the 214 box. Since I don't do test runs or even compiles on those platforms, your 215 mileage may vary. Sending me patches for other platforms is greatly 216 appreciated. There's a lot of value in having the same test/benchmark tool 217 available on all platforms. 218 219 Note that POSIX aio is not enabled by default on AIX. Messages like these:: 220 221 Symbol resolution failed for /usr/lib/libc.a(posix_aio.o) because: 222 Symbol _posix_kaio_rdwr (number 2) is not exported from dependent module /unix. 223 224 indicate one needs to enable POSIX aio. Run the following commands as root:: 225 226 # lsdev -C -l posix_aio0 227 posix_aio0 Defined Posix Asynchronous I/O 228 # cfgmgr -l posix_aio0 229 # lsdev -C -l posix_aio0 230 posix_aio0 Available Posix Asynchronous I/O 231 232 POSIX aio should work now. To make the change permanent:: 233 234 # chdev -l posix_aio0 -P -a autoconfig='available' 235 posix_aio0 changed 236 237 238 Running fio 239 ----------- 240 241 Running fio is normally the easiest part - you just give it the job file 242 (or job files) as parameters:: 243 244 $ fio [options] [jobfile] ... 245 246 and it will start doing what the *jobfile* tells it to do. You can give more 247 than one job file on the command line, fio will serialize the running of those 248 files. Internally that is the same as using the :option:`stonewall` parameter 249 described in the parameter section. 250 251 If the job file contains only one job, you may as well just give the parameters 252 on the command line. The command line parameters are identical to the job 253 parameters, with a few extra that control global parameters. For example, for 254 the job file parameter :option:`iodepth=2 <iodepth>`, the mirror command line 255 option would be :option:`--iodepth 2 <iodepth>` or :option:`--iodepth=2 256 <iodepth>`. You can also use the command line for giving more than one job 257 entry. For each :option:`--name <name>` option that fio sees, it will start a 258 new job with that name. Command line entries following a 259 :option:`--name <name>` entry will apply to that job, until there are no more 260 entries or a new :option:`--name <name>` entry is seen. This is similar to the 261 job file options, where each option applies to the current job until a new [] 262 job entry is seen. 263 264 fio does not need to run as root, except if the files or devices specified in 265 the job section requires that. Some other options may also be restricted, such 266 as memory locking, I/O scheduler switching, and decreasing the nice value. 267 268 If *jobfile* is specified as ``-``, the job file will be read from standard 269 input. 270
