X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=HOWTO;h=12974f3f4dcc563cd143a1084aaff17116d70d48;hp=4d103c846a4d7945f5cdb19d18a27c8b4139760c;hb=44c47feb9edc7854bf3cfa2e3d843e90fc969b3a;hpb=8a35c71ea954894b26cb1af52f4089a228e1e68e diff --git a/HOWTO b/HOWTO index 4d103c84..12974f3f 100644 --- a/HOWTO +++ b/HOWTO @@ -170,7 +170,8 @@ Some parameters take an option of a given type, such as an integer or a string. The following types are used: str String. This is a sequence of alpha characters. -int Integer. A whole number value, can be negative. +int Integer. A whole number value, can be negative. If prefixed with + 0x, the integer is assumed to be of base 16 (hexidecimal). siint SI integer. A whole number value, which may contain a postfix describing the base of the number. Accepted postfixes are k/m/g, meaning kilo, mega, and giga. So if you want to specify 4096, @@ -218,6 +219,25 @@ filename=str Fio normally makes up a filename based on the job name, opendir=str Tell fio to recursively add any file it can find in this directory and down the file system tree. +lockfile=str Fio defaults to not doing any locking files before it does + IO to them. If a file or file descriptor is shared, fio + can serialize IO to that file to make the end result + consistent. This is usual for emulating real workloads that + share files. The lock modes are: + + none No locking. The default. + exclusive Only one thread/process may do IO, + excluding all others. + readwrite Read-write locking on the file. Many + readers may access the file at the + same time, but writes get exclusive + access. + + The option may be post-fixed with a lock batch number. If + set, then each thread/process may do that amount of IOs to + the file before giving up the lock. Since lock acqusition is + expensive, batching the lock/unlocks will speed up IO. + readwrite=str rw=str Type of io pattern. Accepted values are: @@ -261,6 +281,10 @@ filesize=siint Individual file sizes. May be a range, in which case fio and limited to 'size' in total (if that is given). If not given, each created file is the same size. +fill_device=bool Sets size to something really large and waits for ENOSPC (no + space left on device) as the terminating condition. Only makes + sense with sequential write. + blocksize=siint bs=siint The block size used for the io units. Defaults to 4k. Values can be given for both read and writes. If a single siint is @@ -280,6 +304,30 @@ bsrange=irange Instead of giving a single block size, specify a range writes, however a second range can be given after a comma. See bs=. +bssplit=str Sometimes you want even finer grained control of the + block sizes issued, not just an even split between them. + This option allows you to weight various block sizes, + so that you are able to define a specific amount of + block sizes issued. The format for this option is: + + bssplit=blocksize/percentage:blocksize/percentage + + for as many block sizes as needed. So if you want to define + a workload that has 50% 64k blocks, 10% 4k blocks, and + 40% 32k blocks, you would write: + + bssplit=4k/10:64k/50:32k/40 + + Ordering does not matter. If the percentage is left blank, + fio will fill in the remaining values evenly. So a bssplit + option like this one: + + bssplit=4k/50:1k/:32k/ + + would have 50% 4k ios, and 25% 1k and 32k ios. The percentages + always add up to 100, if bssplit is given a range that adds + up to more, it will error out. + blocksize_unaligned bs_unaligned If this option is given, any byte size value within bsrange may be used as a block range. This typically wont work with @@ -288,6 +336,12 @@ bs_unaligned If this option is given, any byte size value within bsrange zero_buffers If this option is given, fio will init the IO buffers to all zeroes. The default is to fill them with random data. +refill_buffers If this option is given, fio will refill the IO buffers + on every submit. The default is to only fill it at init + time and reuse that data. Only makes sense if zero_buffers + isn't specified, naturally. If data verification is enabled, + refill_buffers is also automatically enabled. + nrfiles=int Number of files to use for this job. Defaults to 1. openfiles=int Number of files to keep open at the same time. Defaults to @@ -313,10 +367,16 @@ ioengine=str Defines how the job issues io to the file. The following sync Basic read(2) or write(2) io. lseek(2) is used to position the io location. + psync Basic pread(2) or pwrite(2) io. + + vsync Basic readv(2) or writev(2) IO. + libaio Linux native asynchronous io. posixaio glibc posix asynchronous io. + solarisaio Solaris native asynchronous io. + mmap File is memory mapped and data copied to/from using memcpy(3). @@ -343,11 +403,17 @@ ioengine=str Defines how the job issues io to the file. The following or receive, if the latter only the port argument is used. - cpu Doesn't transfer any data, but burns CPU + netsplice Like net, but uses splice/vmsplice to + map data and send/receive. + + cpuio Doesn't transfer any data, but burns CPU cycles according to the cpuload= and cpucycle= options. Setting cpuload=85 will cause that job to do nothing but burn - 85% of the CPU. + 85% of the CPU. In case of SMP machines, + use numjobs= to get desired CPU + usage, as the cpuload only loads a single + CPU at the desired rate. guasi The GUASI IO engine is the Generic Userspace Asyncronous Syscall Interface approach @@ -368,8 +434,9 @@ iodepth=int This defines how many io units to keep in flight against concurrency. iodepth_batch=int This defines how many pieces of IO to submit at once. - It defaults to the same as iodepth, but can be set lower - if one so desires. + It defaults to 1 which means that we submit each IO + as soon as it is available, but can be raised to submit + bigger batches of IO at the time. iodepth_low=int The low water mark indicating when to start filling the queue again. Defaults to the same as iodepth, meaning @@ -395,7 +462,11 @@ fsync=int If writing to a file, issue a sync of the dirty data not sync the file. The exception is the sg io engine, which synchronizes the disk cache anyway. -overwrite=bool If writing to a file, setup the file first and do overwrites. +overwrite=bool If true, writes to a file will always overwrite existing + data. If the file doesn't already exist, it will be + created before the write phase begins. If the file exists + and is large enough for the specified write phase, nothing + will be done. end_fsync=bool If true, fsync file contents when the job exits. @@ -403,10 +474,6 @@ fsync_on_close=bool If true, fio will fsync() a dirty file on close. This differs from end_fsync in that it will happen on every file close, not just at the end of the job. -rwmixcycle=int Value in milliseconds describing how often to switch between - reads and writes for a mixed workload. The default is - 500 msecs. - rwmixread=int How large a percentage of the mix should be reads. rwmixwrite=int How large a percentage of the mix should be writes. If both @@ -423,6 +490,12 @@ norandommap Normally fio will cover every block of the file when doing fio doesn't track potential block rewrites which may alter the calculated checksum for that block. +softrandommap See norandommap. If fio runs with the random block map enabled + and it fails to allocate the map, if this option is set it + will continue without a random block map. As coverage will + not be as complete as with random maps, this option is + disabled by default. + nice=int Run the job with the given nice value. See man nice(2). prio=int Set the io priority value of this job. Linux limits us to @@ -565,15 +638,36 @@ loops=int Run the specified number of iterations of this job. Used to repeat the same workload a given number of times. Defaults to 1. +do_verify=bool Run the verify phase after a write phase. Only makes sense if + verify is set. Defaults to 1. + verify=str If writing to a file, fio can verify the file contents after each iteration of the job. The allowed values are: md5 Use an md5 sum of the data area and store it in the header of each block. + crc64 Use an experimental crc64 sum of the data + area and store it in the header of each + block. + crc32 Use a crc32 sum of the data area and store it in the header of each block. + crc16 Use a crc16 sum of the data area and store + it in the header of each block. + + crc7 Use a crc7 sum of the data area and store + it in the header of each block. + + sha512 Use sha512 as the checksum function. + + sha256 Use sha256 as the checksum function. + + meta Write extra information about each io + (timestamp, block number etc.). The block + number is verified. + null Only pretend to verify. Useful for testing internals with ioengine=null, not for much else. @@ -589,6 +683,28 @@ verifysort=bool If set, fio will sort written verify blocks when it deems can ignore this option unless doing huge amounts of really fast IO where the red-black tree sorting CPU time becomes significant. + +verify_offset=siint Swap the verification header with data somewhere else + in the block before writing. Its swapped back before + verifying. + +verify_interval=siint Write the verification header at a finer granularity + than the blocksize. It will be written for chunks the + size of header_interval. blocksize should divide this + evenly. + +verify_pattern=int If set, fio will fill the io buffers with this + pattern. Fio defaults to filling with totally random + bytes, but sometimes it's interesting to fill with a known + pattern for io verification purposes. Depending on the + width of the pattern, fio will fill 1/2/3/4 bytes of the + buffer at the time. The verify_pattern cannot be larger than + a 32-bit quantity. + +verify_fatal=bool Normally fio will keep checking the entire contents + before quitting on a block verification failure. If this + option is set, fio will exit the job on the first observed + failure. stonewall Wait for preceeding jobs in the job file to exit, before starting this one. Can be used to insert serialization @@ -694,9 +810,10 @@ E Thread exited, not reaped by main thread yet. _ Thread reaped. The other values are fairly self explanatory - number of threads -currently running and doing io, rate of io since last check, and the estimated -completion percentage and time for the running group. It's impossible to -estimate runtime of the following groups (if any). +currently running and doing io, rate of io since last check (read speed +listed first, then write speed), and the estimated completion percentage +and time for the running group. It's impossible to estimate runtime of +the following groups (if any). 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 @@ -707,8 +824,10 @@ Client1 (g=0): err= 0: slat (msec): min= 0, max= 136, avg= 0.03, stdev= 1.92 clat (msec): min= 0, max= 631, avg=48.50, stdev=86.82 bw (KiB/s) : min= 0, max= 1196, per=51.00%, avg=664.02, stdev=681.68 - cpu : usr=1.49%, sys=0.25%, ctx=7969 + cpu : usr=1.49%, sys=0.25%, ctx=7969, majf=0, minf=17 IO depths : 1=0.1%, 2=0.3%, 4=0.5%, 8=99.0%, 16=0.0%, 32=0.0%, >32=0.0% + submit : 0=0.0%, 4=100.0%, 8=0.0%, 16=0.0%, 32=0.0%, 64=0.0%, >=64=0.0% + complete : 0=0.0%, 4=100.0%, 8=0.0%, 16=0.0%, 32=0.0%, 64=0.0%, >=64=0.0% issued r/w: total=0/32768, short=0/0 lat (msec): 2=1.6%, 4=0.0%, 10=3.2%, 20=12.8%, 50=38.4%, 100=24.8%, lat (msec): 250=15.2%, 500=0.0%, 750=0.0%, 1000=0.0%, >=2048=0.0% @@ -738,12 +857,19 @@ runt= The runtime of that thread only really useful if the threads in this group are on the same disk, since they are then competing for disk access. cpu= CPU usage. User and system time, along with the number - of context switches this thread went through. + of context switches this thread went through, usage of + system and user time, and finally the number of major + and minor page faults. IO depths= The distribution of io depths over the job life time. The numbers are divided into powers of 2, so for example the 16= entries includes depths up to that value but higher than the previous entry. In other words, it covers the range from 16 to 31. +IO submit= How many pieces of IO were submitting in a single submit + call. Each entry denotes that amount and below, until + the previous entry - eg, 8=100% mean that we submitted + anywhere in between 5-8 ios per submit call. +IO complete= Like the above submit number, but for completions instead. IO issued= The number of read/write requests issued, and how many of them were short. IO latencies= The distribution of IO completion latencies. This is the @@ -808,7 +934,7 @@ Split up, the format is as follows: Submission latency: min, max, mean, deviation Completion latency: min, max, mean, deviation Bw: min, max, aggregate percentage of total, mean, deviation - CPU usage: user, system, context switches + CPU usage: user, system, context switches, major faults, minor faults IO depths: <=1, 2, 4, 8, 16, 32, >=64 IO latencies: <=2, 4, 10, 20, 50, 100, 250, 500, 750, 1000, >=2000 Text description