From 798091133938db311ceb6946ee86f548ed2b3aaa Mon Sep 17 00:00:00 2001 From: Jens Axboe Date: Fri, 9 Jun 2006 10:14:54 +0200 Subject: [PATCH] [PATCH] Documentation updates --- README | 126 +++++++++++++++++++++++---------- examples/1mbs_clients | 160 +++++++++--------------------------------- examples/aio-read | 9 +-- fio.c | 5 +- 4 files changed, 130 insertions(+), 170 deletions(-) diff --git a/README b/README index 94a1b408..fccb92f4 100644 --- a/README +++ b/README @@ -1,10 +1,12 @@ 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. +fio is a tool that will spawn a number of threads or processes 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. +The typical use of fio is to write a job file matching the io load +one wants to simulate. Source @@ -14,8 +16,8 @@ fio resides in a git repo, the canonical place is: git://brick.kernel.dk/data/git/fio.git -Snapshots are frequently generated as well and they include the git -meta data as well. You can download them here: +Snapshots are frequently generated and they include the git meta data as +well. You can download them here: http://brick.kernel.dk/snaps/ @@ -54,7 +56,16 @@ $ fio -h Print help info -v Print version information and exit -The format is as follows: + +Job file +-------- + +Only a few options can be controlled with command line parameters, +generally it's a lot easier to just write a simple job file to describe +the workload. The job file format is in the ini style format, as it's +easy to read and write for the user. + +The job file parameters are: name=x Use 'x' as the identifier for this job. directory=x Use 'x' as the top level directory for storing files @@ -129,48 +140,67 @@ The format is as follows: exec_postrun=x Run 'x' after job io has finished. ioscheduler=x Use ioscheduler 'x' for this job. + Examples using a job file ------------------------- -A sample job file doing the same as above would look like this: +Example 1) Two random readers -[read_file] -rw=0 -bs=4096 +Lets say we want to simulate two threads reading randomly from a file +each. They will be doing IO in 4KiB chunks, using raw (O_DIRECT) IO. +Since they share most parameters, we'll put those in the [global] +section. Job 1 will use a 128MiB file, job 2 will use a 256MiB file. -[write_file] -rw=1 -bs=16384 +; ---snip--- -And fio would be invoked as: +[global] +ioengine=sync ; regular read/write(2), the default +rw=randread +bs=4k +direct=1 -$ fio -o1 -s -f file_with_above +[file1] +size=128m -The second example would look like this: +[file2] +size=256m -[rf1] -rw=0 -prio=6 +; ---snip--- -[rf2] -rw=0 -prio=3 +Generally the [] bracketed name specifies a file name, but the "global" +keyword is reserved for setting options that are inherited by each +subsequent job description. It's possible to have several [global] +sections in the job file, each one adds options that are inherited by +jobs defined below it. The name can also point to a block device, such +as /dev/sda. To run the above job file, simply do: -[rf3] -rw=0 -prio=0 -direct=1 +$ fio jobfile + +Example 2) Many random writers + +Say we want to exercise the IO subsystem some more. We'll define 64 +threads doing random buffered writes. We'll let each thread use async io +with a depth of 4 ios in flight. A job file would then look like this: -And fio would be invoked as: +; ---snip--- -$ fio -o0 -s -b4096 -f file_with_above +[global] +ioengine=libaio +iodepth=4 +rw=randwrite +bs=32k +direct=0 +size=64m -'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. +[files] +numjobs=64 -Also see the examples/ dir for sample job files. +; ---snip--- + +This will create files.[0-63] and perform the random writes to them. + +There are endless ways to define jobs, the examples/ directory contains +a few more examples. Interpreting the output @@ -187,17 +217,22 @@ each thread. The possible values (in typical life cycle order) are: Idle Run ---- --- P Thread setup, but not started. -C Thread created and running, but not doing anything yet +C Thread created. +I Thread initialized, waiting. R Running, doing sequential reads. r Running, doing random reads. W Running, doing sequential writes. w Running, doing random writes. + M Running, doing mixed sequential reads/writes. + m Running, doing mixed random reads/writes. + F Running, currently waiting for fsync() V Running, doing verification of written data. E Thread exited, not reaped by main thread yet. _ Thread reaped. -The other values are fairly self explanatory - number of thread currently -running and doing io, and the estimated completion percentage. +The other values are fairly self explanatory - number of threads +currently running and doing io, and the estimated completion percentage +and time. When fio is done (or interrupted by ctrl-c), it will show the data for each thread, group of threads, and disks in that order. For each data @@ -247,8 +282,8 @@ io= Number of megabytes io performed. aggrb= Aggregate bandwidth of threads in this group. minb= The minimum average bandwidth a thread saw. maxb= The maximum average bandwidth a thread saw. -mint= The minimum runtime of a thread. -maxt= The maximum runtime of a thread. +mint= The smallest runtime of the threads in that group. +maxt= The longest runtime of the threads in that group. And finally, the disk statistics are printed. They will look like this: @@ -264,3 +299,16 @@ ticks= Number of ticks we kept the disk busy. io_queue= Total time spent in the disk queue. util= The disk utilization. A value of 100% means we kept the disk busy constantly, 50% would be a disk idling half of the time. + + +Author +------ + +Fio was written by Jens Axboe to enable flexible testing +of the Linux IO subsystem and schedulers. He got tired of writing +specific test applications to simulate a given workload, and found that +the existing io benchmark/test tools out there weren't flexible enough +to do what he wanted. + +Jens Axboe 20060609 + diff --git a/examples/1mbs_clients b/examples/1mbs_clients index f9a228ee..505cd879 100644 --- a/examples/1mbs_clients +++ b/examples/1mbs_clients @@ -1,196 +1,104 @@ ; Keep adding 1024kb/s reading clients at 4 seconds [global] size=32m - -[/tmp/file1] rw=read +directory=tmp rate=1250 ratemin=1024 + +[file1] startdelay=0 -[/tmp/file2] -rw=read -rate=1250 -ratemin=1024 +[file2] startdelay=4 -[/tmp/file3] -rw=read -rate=1250 -ratemin=1024 +[file3] startdelay=8 -[/tmp/file4] -rw=read -rate=1250 -ratemin=1024 +[file4] startdelay=12 -[/tmp/file5] -rw=read -rate=1250 -ratemin=1024 +[file5] startdelay=16 -[/tmp/file6] -rw=read -rate=1250 -ratemin=1024 +[file6] startdelay=20 -[/tmp/file7] -rw=read -rate=1250 -ratemin=1024 +[file7] startdelay=24 -[/tmp/file8] -rw=read -rate=1250 -ratemin=1024 +[file8] startdelay=28 -[/tmp/file9] -rw=read -rate=1250 -ratemin=1024 +[file9] startdelay=32 -[/tmp/file10] -rw=read -rate=1250 -ratemin=1024 +[file10] startdelay=36 -[/tmp/file11] -rw=read -rate=1250 -ratemin=1024 +[file11] startdelay=40 -[/tmp/file12] -rw=read -rate=1250 -ratemin=1024 +[file12] startdelay=44 -[/tmp/file13] -rw=read -rate=1250 -ratemin=1024 +[file13] startdelay=48 -[/tmp/file14] -rw=read -rate=1250 -ratemin=1024 +[file14] startdelay=52 -[/tmp/file15] -rw=read -rate=1250 -ratemin=1024 +[file15] startdelay=56 -[/tmp/file16] -rw=read -rate=1250 -ratemin=1024 +[file16] startdelay=60 -[/tmp/file17] -rw=read -rate=1250 -ratemin=1024 +[file17] startdelay=64 -[/tmp/file18] -rw=read -rate=1250 -ratemin=1024 +[file18] startdelay=68 -[/tmp/file19] -rw=read -rate=1250 -ratemin=1024 +[file19] startdelay=72 -[/tmp/file20] -rw=read -rate=1250 -ratemin=1024 +[file20] startdelay=76 -[/tmp/file21] -rw=read -rate=1250 -ratemin=1024 +[file21] startdelay=80 -[/tmp/file22] -rw=read -rate=1250 -ratemin=1024 +[file22] startdelay=84 -[/tmp/file23] -rw=read -rate=1250 -ratemin=1024 +[file23] startdelay=88 -[/tmp/file24] -rw=read -rate=1250 -ratemin=1024 +[file24] startdelay=92 -[/tmp/file25] -rw=read -rate=1250 -ratemin=1024 +[file25] startdelay=96 -[/tmp/file26] -rw=read -rate=1250 -ratemin=1024 +[file26] startdelay=100 -[/tmp/file27] -rw=read -rate=1250 -ratemin=1024 +[file27] startdelay=104 -[/tmp/file28] -rw=read -rate=1250 -ratemin=1024 +[file28] startdelay=108 -[/tmp/file29] -rw=read -rate=1250 -ratemin=1024 +[file29] startdelay=112 -[/tmp/file30] -rw=read -rate=1250 -ratemin=1024 +[file30] startdelay=116 -[/tmp/file31] -rw=read -rate=1250 -ratemin=1024 +[file31] startdelay=120 -[/tmp/file32] -rw=read -rate=1250 -ratemin=1024 +[file32] startdelay=124 diff --git a/examples/aio-read b/examples/aio-read index ed8cb2c4..7300c334 100644 --- a/examples/aio-read +++ b/examples/aio-read @@ -4,15 +4,16 @@ ioengine=libaio rw=randread bs=128k size=512m +directory=/data1 -[/data1/file1] +[file1] iodepth=4 -[/data1/file2] +[file2] iodepth=32 -[/data1/file3] +[file3] iodepth=8 -[/data1/file4] +[file4] iodepth=16 diff --git a/fio.c b/fio.c index b452c5f0..65d94980 100644 --- a/fio.c +++ b/fio.c @@ -49,7 +49,10 @@ static void print_thread_status(void); extern unsigned long long mlock_size; /* - * thread life cycle + * Thread life cycle. Once a thread has a runstate beyond TD_INITIALIZED, it + * will never back again. It may cycle between running/verififying/fsyncing. + * Once the thread reaches TD_EXITED, it is just waiting for the core to + * reap it. */ enum { TD_NOT_CREATED = 0, -- 2.25.1