X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=HOWTO;h=724b604b19c1116b87f32cc4b385e36e92dcd445;hp=8b17610dd4a457438f56233d2ff5dfde80e63a61;hb=f20485ad77872d6c5084dead547420386a6ecd5e;hpb=35649e58042da4beefefc2678c09e4625ec2155e diff --git a/HOWTO b/HOWTO index 8b17610d..724b604b 100644 --- a/HOWTO +++ b/HOWTO @@ -8,7 +8,7 @@ Table of contents 5. Detailed list of parameters 6. Normal output 7. Terse output - +8. Trace file format 1.0 Overview and history ------------------------ @@ -244,6 +244,7 @@ irange Integer range with suffix. Allows value range to be given, such 1k:4k. If the option allows two sets of ranges, they can be specified with a ',' or '/' delimiter: 1k-4k/8k-32k. Also see int. +float_list A list of floating numbers, separated by a ':' character. With the above in mind, here follows the complete list of fio job parameters. @@ -318,8 +319,12 @@ rw=str Type of io pattern. Accepted values are: a number of IO's to do before getting a new offset, this is one by appending a ':' to the end of the string given. For a random read, it would look like 'rw=randread:8' for - passing in an offset modifier with a value of 8. See the - 'rw_sequencer' option. + passing in an offset modifier with a value of 8. If the + postfix is used with a sequential IO pattern, then the value + specified will be added to the generated offset for each IO. + For instance, using rw=write:4k will skip 4k for every + write. It turns sequential IO into sequential IO with holes. + See the 'rw_sequencer' option. rw_sequencer=str If an offset modifier is given by appending a number to the rw= line, then this option controls how that @@ -512,6 +517,16 @@ ioengine=str Defines how the job issues io to the file. The following libaio Linux native asynchronous io. Note that Linux may only support queued behaviour with non-buffered IO (set direct=1 or buffered=0). + This engine also has a sub-option, + userspace_reap. To set it, use + ioengine=libaio:userspace_reap. Normally, with + the libaio engine in use, fio will use the + io_getevents system call to reap newly returned + events. With this flag turned on, the AIO ring + will be read directly from user-space to reap + events. The reaping mode is only enabled when + polling for a minimum of 0 events (eg when + iodepth_batch_complete=0). posixaio glibc posix asynchronous io. @@ -568,6 +583,11 @@ ioengine=str Defines how the job issues io to the file. The following for more info on GUASI. + rdma The RDMA I/O engine supports both RDMA + memory semantics (RDMA_WRITE/RDMA_READ) and + channel semantics (Send/Recv) for the + InfiniBand, RoCE and iWARP protocols. + external Prefix to specify loading an external IO engine object file. Append the engine filename, eg ioengine=external:/tmp/foo.o @@ -673,10 +693,10 @@ norandommap Normally fio will cover every block of the file when doing blocksizes (via bsrange=) are used, since fio only tracks complete rewrites of blocks. -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 +softrandommap=bool 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). @@ -987,7 +1007,8 @@ verify_backlog_batch=int Control how many blocks fio will verify if verify_backlog_batch is larger than verify_backlog, some blocks will be verified more than once. -stonewall Wait for preceeding jobs in the job file to exit, before +stonewall +wait_for_previous Wait for preceeding jobs in the job file to exit, before starting this one. Can be used to insert serialization points in the job file. A stone wall also implies starting a new reporting group. @@ -1114,6 +1135,18 @@ disable_slat=bool Disable measurements of submission latency numbers. See disable_bw=bool Disable measurements of throughput/bandwidth numbers. See disable_lat. +clat_percentiles=bool Enable the reporting of percentiles of + completion latencies. + +percentile_list=float_list Overwrite the default list of percentiles + for completion latencies. Each number is a floating + number in the range (0,100], and the maximum length of + the list is 20. Use ':' to separate the numbers, and + list the numbers in ascending order. For example, + --percentile_list=99.5:99.9 will cause fio to report + the values of completion latency below which 99.5% and + 99.9% of the observed latencies fell, respectively. + gtod_reduce=bool Enable all of the gettimeofday() reducing options (disable_clat, disable_slat, disable_bw) plus reduce precision of the timeout somewhat to really shrink @@ -1334,3 +1367,64 @@ Split up, the format is as follows: Additional Info (dependant on continue_on_error, default off): total # errors, first error code Additional Info (dependant on description being set): Text description + + +8.0 Trace file format +--------------------- +There are two trace file format that you can encounter. The older (v1) format +is unsupported since version 1.20-rc3 (March 2008). It will still be described +below in case that you get an old trace and want to understand it. + +In any case the trace is a simple text file with a single action per line. + + +8.1 Trace file format v1 +------------------------ +Each line represents a single io action in the following format: + +rw, offset, length + +where rw=0/1 for read/write, and the offset and length entries being in bytes. + +This format is not supported in Fio versions => 1.20-rc3. + + +8.2 Trace file format v2 +------------------------ +The second version of the trace file format was added in Fio version 1.17. +It allows to access more then one file per trace and has a bigger set of +possible file actions. + +The first line of the trace file has to be: + +fio version 2 iolog + +Following this can be lines in two different formats, which are described below. + +The file management format: + +filename action + +The filename is given as an absolute path. The action can be one of these: + +add Add the given filename to the trace +open Open the file with the given filename. The filename has to have + been added with the add action before. +close Close the file with the given filename. The file has to have been + opened before. + + +The file io action format: + +filename action offset length + +The filename is given as an absolute path, and has to have been added and opened +before it can be used with this format. The offset and length are given in +bytes. The action can be one of these: + +wait Wait for 'offset' microseconds. Everything below 100 is discarded. +read Read 'length' bytes beginning from 'offset' +write Write 'length' bytes beginning from 'offset' +sync fsync() the file +datasync fdatasync() the file +trim trim the given file from the given 'offset' for 'length' bytes