Commit | Line | Data |
---|---|---|
3e6c7afb VF |
1 | Overview and history |
2 | -------------------- | |
f80dba8d MT |
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 | |
bd781986 | 13 | generating I/O. You could have someone dirtying large amounts of memory in a |
f80dba8d MT |
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. | |
ebac4655 | 23 | |
2b02b546 | 24 | |
3e6c7afb VF |
25 | Source |
26 | ------ | |
2b02b546 | 27 | |
f80dba8d | 28 | Fio resides in a git repo, the canonical place is: |
2b02b546 | 29 | |
d6225c15 | 30 | https://git.kernel.dk/cgit/fio/ |
2b02b546 | 31 | |
f80dba8d | 32 | Snapshots are frequently generated and :file:`fio-git-*.tar.gz` include the git |
88d398d0 | 33 | meta data as well. Other tarballs are archives of official fio releases. |
4649b352 | 34 | Snapshots can download from: |
2b02b546 | 35 | |
d6225c15 | 36 | https://brick.kernel.dk/snaps/ |
2b02b546 | 37 | |
f80dba8d MT |
38 | There are also two official mirrors. Both of these are automatically synced with |
39 | the main repository, when changes are pushed. If the main repo is down for some | |
40 | reason, either one of these is safe to use as a backup: | |
01fa84d5 | 41 | |
01fa84d5 JA |
42 | https://git.kernel.org/pub/scm/linux/kernel/git/axboe/fio.git |
43 | ||
f80dba8d | 44 | https://github.com/axboe/fio.git |
a71844ff | 45 | |
2b02b546 | 46 | |
3e6c7afb VF |
47 | Mailing list |
48 | ------------ | |
726f6ff0 | 49 | |
4649b352 | 50 | The fio project mailing list is meant for anything related to fio including |
6468020d TK |
51 | general discussion, bug reporting, questions, and development. For bug reporting, |
52 | see REPORTING-BUGS. | |
2e8552b0 | 53 | |
f80dba8d MT |
54 | An automated mail detailing recent commits is automatically sent to the list at |
55 | most daily. The list address is fio@vger.kernel.org, subscribe by sending an | |
56 | email to majordomo@vger.kernel.org with | |
4649b352 GG |
57 | |
58 | subscribe fio | |
2e8552b0 | 59 | |
4f5d1526 EIB |
60 | in the body of the email. Archives can be found here: |
61 | ||
d6225c15 | 62 | https://www.spinics.net/lists/fio/ |
4f5d1526 | 63 | |
d7521682 JA |
64 | or here: |
65 | ||
66 | https://lore.kernel.org/fio/ | |
67 | ||
4f5d1526 | 68 | and archives for the old list can be found here: |
2e8552b0 | 69 | |
4649b352 | 70 | http://maillist.kernel.dk/fio-devel/ |
726f6ff0 JA |
71 | |
72 | ||
3e6c7afb VF |
73 | Author |
74 | ------ | |
bbfd6b00 | 75 | |
f80dba8d MT |
76 | Fio was written by Jens Axboe <axboe@kernel.dk> to enable flexible testing of |
77 | the Linux I/O subsystem and schedulers. He got tired of writing specific test | |
78 | applications to simulate a given workload, and found that the existing I/O | |
79 | benchmark/test tools out there weren't flexible enough to do what he wanted. | |
6de43c1b | 80 | |
f80dba8d | 81 | Jens Axboe <axboe@kernel.dk> 20060905 |
2382dca7 | 82 | |
c8931876 | 83 | |
5b991967 JA |
84 | Maintainers |
85 | ----------- | |
86 | ||
87 | Fio is maintained by Jens Axboe <axboe@kernel.dk and | |
88 | Vincent Fu <vincentfu@gmail.com> - however, for reporting bugs please use | |
89 | the fio reflector or the GitHub page rather than email any of them | |
90 | directly. By using the public resources, others will be able to learn from | |
91 | the responses too. Chances are also good that other members will be able to | |
92 | help with your inquiry as well. | |
93 | ||
94 | ||
3e6c7afb VF |
95 | Binary packages |
96 | --------------- | |
bbfd6b00 | 97 | |
3e6c7afb | 98 | Debian: |
f80dba8d | 99 | Starting with Debian "Squeeze", fio packages are part of the official |
d6225c15 | 100 | Debian repository. https://packages.debian.org/search?keywords=fio . |
53adf64f | 101 | |
3e6c7afb | 102 | Ubuntu: |
f80dba8d MT |
103 | Starting with Ubuntu 10.04 LTS (aka "Lucid Lynx"), fio packages are part |
104 | of the Ubuntu "universe" repository. | |
d6225c15 | 105 | https://packages.ubuntu.com/search?keywords=fio . |
53adf64f | 106 | |
3e6c7afb | 107 | Red Hat, Fedora, CentOS & Co: |
a881438b SW |
108 | Starting with Fedora 9/Extra Packages for Enterprise Linux 4, fio |
109 | packages are part of the Fedora/EPEL repositories. | |
981ad73a | 110 | https://packages.fedoraproject.org/pkgs/fio/ . |
f41862f7 | 111 | |
3e6c7afb | 112 | Mandriva: |
f80dba8d MT |
113 | Mandriva has integrated fio into their package repository, so installing |
114 | on that distro should be as easy as typing ``urpmi fio``. | |
9aa5fe32 | 115 | |
3e6c7afb | 116 | Arch Linux: |
a6415d76 QB |
117 | An Arch Linux package is provided under the Community sub-repository: |
118 | https://www.archlinux.org/packages/?sort=&q=fio | |
119 | ||
3e6c7afb | 120 | Solaris: |
f80dba8d MT |
121 | Packages for Solaris are available from OpenCSW. Install their pkgutil |
122 | tool (http://www.opencsw.org/get-it/pkgutil/) and then install fio via | |
123 | ``pkgutil -i fio``. | |
7409711b | 124 | |
3e6c7afb | 125 | Windows: |
4eba0c6e JA |
126 | Beginning with fio 3.31 Windows installers are available on GitHub at |
127 | https://github.com/axboe/fio/releases. The latest builds for Windows | |
128 | can also be grabbed from https://ci.appveyor.com/project/axboe/fio by | |
129 | clicking the latest x86 or x64 build and then selecting the Artifacts | |
130 | tab. | |
78080867 | 131 | |
3e6c7afb | 132 | BSDs: |
f80dba8d MT |
133 | Packages for BSDs may be available from their binary package repositories. |
134 | Look for a package "fio" using their binary package managers. | |
53adf64f | 135 | |
ebac4655 | 136 | |
3e6c7afb VF |
137 | Building |
138 | -------- | |
bebe6398 | 139 | |
82250ffc | 140 | Just type:: |
3e6c7afb VF |
141 | |
142 | $ ./configure | |
143 | $ make | |
144 | $ make install | |
145 | ||
f80dba8d MT |
146 | Note that GNU make is required. On BSDs it's available from devel/gmake within |
147 | ports directory; on Solaris it's in the SUNWgmake package. On platforms where | |
148 | GNU make isn't the default, type ``gmake`` instead of ``make``. | |
811826be | 149 | |
f80dba8d MT |
150 | Configure will print the enabled options. Note that on Linux based platforms, |
151 | the libaio development packages must be installed to use the libaio | |
705c3780 | 152 | engine. Depending on the distro, it is usually called libaio-devel or libaio-dev. |
811826be | 153 | |
f80dba8d MT |
154 | For gfio, gtk 2.18 (or newer), associated glib threads, and cairo are required |
155 | to be installed. gfio isn't built automatically and can be enabled with a | |
156 | ``--enable-gfio`` option to configure. | |
bebe6398 | 157 | |
f80dba8d | 158 | To build fio with a cross-compiler:: |
3e6c7afb VF |
159 | |
160 | $ make clean | |
161 | $ make CROSS_COMPILE=/path/to/toolchain/prefix | |
162 | ||
f80dba8d | 163 | Configure will attempt to determine the target platform automatically. |
bebe6398 | 164 | |
f80dba8d MT |
165 | It's possible to build fio for ESX as well, use the ``--esx`` switch to |
166 | configure. | |
4649b352 | 167 | |
bebe6398 | 168 | |
3e6c7afb VF |
169 | Windows |
170 | ~~~~~~~ | |
323255cc | 171 | |
705c3780 | 172 | The minimum versions of Windows for building/running fio are Windows 7/Windows |
26dcc084 SW |
173 | Server 2008 R2. On Windows, Cygwin (https://www.cygwin.com/) is required in |
174 | order to build fio. To create an MSI installer package install WiX from | |
13e9c0b0 | 175 | https://wixtoolset.org and run :file:`dobuild.cmd` from the :file:`os/windows` |
f80dba8d | 176 | directory. |
323255cc | 177 | |
3e6c7afb | 178 | How to compile fio on 64-bit Windows: |
323255cc | 179 | |
d6225c15 | 180 | 1. Install Cygwin (https://www.cygwin.com/). Install **make** and all |
b570e037 SW |
181 | packages starting with **mingw64-x86_64**. Ensure |
182 | **mingw64-x86_64-zlib** are installed if you wish | |
b86770c6 | 183 | to enable fio's log compression functionality. |
f80dba8d MT |
184 | 2. Open the Cygwin Terminal. |
185 | 3. Go to the fio directory (source files). | |
186 | 4. Run ``make clean && make -j``. | |
39b5f61e | 187 | |
b570e037 SW |
188 | To build fio for 32-bit Windows, ensure the -i686 versions of the previously |
189 | mentioned -x86_64 packages are installed and run ``./configure | |
26dcc084 | 190 | --build-32bit-win`` before ``make``. |
39b5f61e | 191 | |
f80dba8d MT |
192 | It's recommended that once built or installed, fio be run in a Command Prompt or |
193 | other 'native' console such as console2, since there are known to be display and | |
194 | signal issues when running it under a Cygwin shell (see | |
f5c5f869 SW |
195 | https://github.com/mintty/mintty/issues/56 and |
196 | https://github.com/mintty/mintty/wiki/Tips#inputoutput-interaction-with-alien-programs | |
197 | for details). | |
39b5f61e | 198 | |
39b5f61e | 199 | |
3e6c7afb VF |
200 | Documentation |
201 | ~~~~~~~~~~~~~ | |
39b5f61e | 202 | |
f80dba8d MT |
203 | Fio uses Sphinx_ to generate documentation from the reStructuredText_ files. |
204 | To build HTML formatted documentation run ``make -C doc html`` and direct your | |
205 | browser to :file:`./doc/output/html/index.html`. To build manual page run | |
206 | ``make -C doc man`` and then ``man doc/output/man/fio.1``. To see what other | |
207 | output formats are supported run ``make -C doc help``. | |
3e6c7afb | 208 | |
d6225c15 RC |
209 | .. _reStructuredText: https://www.sphinx-doc.org/rest.html |
210 | .. _Sphinx: https://www.sphinx-doc.org | |
39b5f61e | 211 | |
bebe6398 | 212 | |
3e6c7afb VF |
213 | Platforms |
214 | --------- | |
217bc04b | 215 | |
1b8c5af7 | 216 | Fio works on (at least) Linux, Solaris, AIX, HP-UX, OSX, NetBSD, OpenBSD, |
2af5bd99 | 217 | Windows, FreeBSD, and DragonFly. Some features and/or options may only be |
f80dba8d MT |
218 | available on some of the platforms, typically because those features only apply |
219 | to that platform (like the solarisaio engine, or the splice engine on Linux). | |
217bc04b JA |
220 | |
221 | Some features are not available on FreeBSD/Solaris even if they could be | |
f80dba8d MT |
222 | implemented, I'd be happy to take patches for that. An example of that is disk |
223 | utility statistics and (I think) huge page support, support for that does exist | |
224 | in FreeBSD/Solaris. | |
217bc04b | 225 | |
705c3780 | 226 | Fio uses pthread mutexes for signaling and locking and some platforms do not |
06eac6b2 SW |
227 | support process shared pthread mutexes. As a result, on such platforms only |
228 | threads are supported. This could be fixed with sysv ipc locking or other | |
229 | locking alternatives. | |
217bc04b | 230 | |
f80dba8d MT |
231 | Other \*BSD platforms are untested, but fio should work there almost out of the |
232 | box. Since I don't do test runs or even compiles on those platforms, your | |
233 | mileage may vary. Sending me patches for other platforms is greatly | |
217bc04b JA |
234 | appreciated. There's a lot of value in having the same test/benchmark tool |
235 | available on all platforms. | |
236 | ||
f80dba8d | 237 | Note that POSIX aio is not enabled by default on AIX. Messages like these:: |
bf2e821a CC |
238 | |
239 | Symbol resolution failed for /usr/lib/libc.a(posix_aio.o) because: | |
240 | Symbol _posix_kaio_rdwr (number 2) is not exported from dependent module /unix. | |
241 | ||
f80dba8d | 242 | indicate one needs to enable POSIX aio. Run the following commands as root:: |
bf2e821a CC |
243 | |
244 | # lsdev -C -l posix_aio0 | |
245 | posix_aio0 Defined Posix Asynchronous I/O | |
246 | # cfgmgr -l posix_aio0 | |
247 | # lsdev -C -l posix_aio0 | |
248 | posix_aio0 Available Posix Asynchronous I/O | |
249 | ||
f80dba8d | 250 | POSIX aio should work now. To make the change permanent:: |
bf2e821a CC |
251 | |
252 | # chdev -l posix_aio0 -P -a autoconfig='available' | |
253 | posix_aio0 changed | |
217bc04b JA |
254 | |
255 | ||
3e6c7afb VF |
256 | Running fio |
257 | ----------- | |
79809113 | 258 | |
f80dba8d MT |
259 | Running fio is normally the easiest part - you just give it the job file |
260 | (or job files) as parameters:: | |
79809113 | 261 | |
f80dba8d MT |
262 | $ fio [options] [jobfile] ... |
263 | ||
264 | and it will start doing what the *jobfile* tells it to do. You can give more | |
265 | than one job file on the command line, fio will serialize the running of those | |
266 | files. Internally that is the same as using the :option:`stonewall` parameter | |
267 | described in the parameter section. | |
268 | ||
269 | If the job file contains only one job, you may as well just give the parameters | |
270 | on the command line. The command line parameters are identical to the job | |
271 | parameters, with a few extra that control global parameters. For example, for | |
272 | the job file parameter :option:`iodepth=2 <iodepth>`, the mirror command line | |
273 | option would be :option:`--iodepth 2 <iodepth>` or :option:`--iodepth=2 | |
274 | <iodepth>`. You can also use the command line for giving more than one job | |
275 | entry. For each :option:`--name <name>` option that fio sees, it will start a | |
276 | new job with that name. Command line entries following a | |
277 | :option:`--name <name>` entry will apply to that job, until there are no more | |
278 | entries or a new :option:`--name <name>` entry is seen. This is similar to the | |
279 | job file options, where each option applies to the current job until a new [] | |
280 | job entry is seen. | |
281 | ||
282 | fio does not need to run as root, except if the files or devices specified in | |
283 | the job section requires that. Some other options may also be restricted, such | |
284 | as memory locking, I/O scheduler switching, and decreasing the nice value. | |
79809113 | 285 | |
f80dba8d MT |
286 | If *jobfile* is specified as ``-``, the job file will be read from standard |
287 | input. |