X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=HOWTO;h=22c5a5b8e1d845b726a2e860f5446057ff19c42e;hp=6d903bba0cb372745767ca7f81afcd19aefbc544;hb=247823cc9f4032eaa5f75c9883727c91401bee44;hpb=c4aa2d0825c180dd96ffff8ce1d74b967f3a0f4a diff --git a/HOWTO b/HOWTO index 6d903bba..22c5a5b8 100644 --- a/HOWTO +++ b/HOWTO @@ -543,6 +543,8 @@ Parameter types If the option accepts an upper and lower range, use a colon ':' or minus '-' to separate such values. See :ref:`irange `. + If the lower value specified happens to be larger than the upper value, + two values are swapped. .. _bool: @@ -886,7 +888,8 @@ Target file/device If this isn't set, fio will abort jobs that are destructive (e.g. that write) to what appears to be a mounted device or partition. This should help catch creating inadvertently destructive tests, not realizing that the test will - destroy data on the mounted file system. Default: false. + destroy data on the mounted file system. Note that some platforms don't allow + writing against a mounted device regardless of this option. Default: false. .. option:: pre_read=bool @@ -1069,10 +1072,11 @@ I/O type .. option:: offset=int - Start I/O at the given offset in the file. The data before the given offset - will not be touched. This effectively caps the file size at `real_size - - offset`. Can be combined with :option:`size` to constrain the start and - end range that I/O will be done within. + Start I/O at the provided offset in the file, given as either a fixed size or + a percentage. If a percentage is given, the next ``blockalign``-ed offset + will be used. Data before the given offset will not be touched. This + effectively caps the file size at `real_size - offset`. Can be combined with + :option:`size` to constrain the start and end range of the I/O workload. .. option:: offset_increment=int @@ -1099,13 +1103,15 @@ I/O type blocks given. For example, if you give 32 as a parameter, fio will sync the file for every 32 writes issued. If fio is using non-buffered I/O, we may not sync the file. The exception is the sg I/O engine, which synchronizes - the disk cache anyway. + the disk cache anyway. Defaults to 0, which means no sync every certain + number of writes. .. option:: fdatasync=int Like :option:`fsync` but uses :manpage:`fdatasync(2)` to only sync data and not metadata blocks. In Windows, FreeBSD, and DragonFlyBSD there is no :manpage:`fdatasync(2)`, this falls back to using :manpage:`fsync(2)`. + Defaults to 0, which means no sync data every certain number of writes. .. option:: write_barrier=int @@ -1285,7 +1291,7 @@ Block size means default for reads, 8k for writes and trims. **bs=,8k,** - means default for reads, 8k for writes, and default for writes. + means default for reads, 8k for writes, and default for trims. .. option:: blocksize_range=irange[,irange][,irange], bsrange=irange[,irange][,irange] @@ -1395,11 +1401,18 @@ Buffers and memory .. option:: buffer_pattern=str - If set, fio will fill the I/O buffers with this pattern. If not set, the - contents of I/O buffers is defined by the other options related to buffer - contents. The setting can be any pattern of bytes, and can be prefixed with - 0x for hex values. It may also be a string, where the string must then be - wrapped with ``""``, e.g.:: + If set, fio will fill the I/O buffers with this pattern or with the contents + of a file. If not set, the contents of I/O buffers are defined by the other + options related to buffer contents. The setting can be any pattern of bytes, + and can be prefixed with 0x for hex values. It may also be a string, where + the string must then be wrapped with ``""``. Or it may also be a filename, + where the filename must be wrapped with ``''`` in which case the file is + opened and read. Note that not all the file contents will be read if that + would cause the buffers to overflow. So, for example:: + + buffer_pattern='filename' + + or:: buffer_pattern="abcd" @@ -1413,7 +1426,7 @@ Buffers and memory Also you can combine everything together in any order:: - buffer_pattern=0xdeadface"abcd"-12 + buffer_pattern=0xdeadface"abcd"-12'filename' .. option:: dedupe_percentage=int @@ -1426,7 +1439,9 @@ Buffers and memory .. option:: invalidate=bool Invalidate the buffer/page cache parts for this file prior to starting - I/O. Defaults to true. + I/O if the platform and file type support it. Defaults to true. + This will be ignored if :option:`pre_read` is also specified for the + same job. .. option:: sync=bool @@ -1461,6 +1476,9 @@ Buffers and memory **mmapshared** Same as mmap, but use a MMAP_SHARED mapping. + **cudamalloc** + Use GPU memory as the buffers for GPUDirect RDMA benchmark. + The area allocated is a function of the maximum allowed bs size for the job, multiplied by the I/O depth given. Note that for **shmhuge** and **mmaphuge** to work, the system must have free huge pages allocated. This @@ -1568,6 +1586,7 @@ I/O engine **sync** Basic :manpage:`read(2)` or :manpage:`write(2)` I/O. :manpage:`lseek(2)` is used to position the I/O location. + See :option:`fsync` and :option:`fdatasync` for syncing write I/Os. **psync** Basic :manpage:`pread(2)` or :manpage:`pwrite(2)` I/O. Default on @@ -1667,6 +1686,11 @@ I/O engine DDIR_TRIM does fallocate(,mode = FALLOC_FL_KEEP_SIZE|FALLOC_FL_PUNCH_HOLE). + **ftruncate** + I/O engine that sends :manpage:`ftruncate(2)` operations in response + to write (DDIR_WRITE) events. Each ftruncate issued sets the file's + size to the current block offset. Block size is ignored. + **e4defrag** I/O engine that does regular EXT4_IOC_MOVE_EXT ioctls to simulate defragment activity in request to DDIR_WRITE event. @@ -1745,7 +1769,8 @@ caveat that when used on the command line, they must come after the .. option:: cpuload=int : [cpuio] - Attempt to use the specified percentage of CPU cycles. + Attempt to use the specified percentage of CPU cycles. This is a mandatory + option when using cpuio I/O engine. .. option:: cpuchunks=int : [cpuio] @@ -2450,6 +2475,7 @@ Verification contents to one or more separate threads. If using this offload option, even sync I/O engines can benefit from using an :option:`iodepth` setting higher than 1, as it allows them to have I/O in flight while verifies are running. + Defaults to 0 async threads, i.e. verification is not asynchronous. .. option:: verify_async_cpus=str @@ -2486,7 +2512,7 @@ Verification is "local" for a local run, "sock" for a client/server socket connection, and "ip" (192.168.0.1, for instance) for a networked - client/server connection. + client/server connection. Defaults to true. .. option:: verify_state_load=bool @@ -2590,6 +2616,12 @@ Measurements and reporting all jobs in a file will be part of the same reporting group, unless separated by a :option:`stonewall`. +.. option:: stats + + By default, fio collects and shows final output results for all jobs + that run. If this option is set to 0, then fio will ignore it in + the final stat output. + .. option:: write_bw_log=str If given, write a bandwidth log for this job. Can be used to store data of @@ -2811,7 +2843,8 @@ Error handling .. option:: ignore_error=str Sometimes you want to ignore some errors during test in that case you can - specify error list for each error type. + specify error list for each error type, instead of only being able to + ignore the default 'non-fatal error' using :option:`continue_on_error`. ``ignore_error=READ_ERR_LIST,WRITE_ERR_LIST,VERIFY_ERR_LIST`` errors for given error type is separated with ':'. Error may be symbol ('ENOSPC', 'ENOMEM') or integer. Example:: @@ -2819,7 +2852,8 @@ Error handling ignore_error=EAGAIN,ENOSPC:122 This option will ignore EAGAIN from READ, and ENOSPC and 122(EDQUOT) from - WRITE. + WRITE. This option works by overriding :option:`continue_on_error` with + the list of errors for each error type if any. .. option:: error_dump=bool @@ -3155,7 +3189,7 @@ Split up, the format is as follows: Total IO (KiB), bandwidth (KiB/sec), IOPS, runtime (msec) Submission latency: min, max, mean, stdev (usec) - Completion latency: min, max, mean, stdev(usec) + Completion latency: min, max, mean, stdev (usec) Completion latency percentiles: 20 fields (see below) Total latency: min, max, mean, stdev (usec) Bw (KiB/s): min, max, aggregate percentage of total, mean, stdev @@ -3201,6 +3235,11 @@ which is the Xth percentile, and the `usec` latency associated with it. For disk utilization, all disks used by fio are shown. So for each disk there will be a disk utilization section. +Below is a single line containing short names for each of the fields in the +minimal output v3, separated by semicolons: + +terse_version_3;fio_version;jobname;groupid;error;read_kb;read_bandwidth;read_iops;read_runtime_ms;read_slat_min;read_slat_max;read_slat_mean;read_slat_dev;read_clat_max;read_clat_min;read_clat_mean;read_clat_dev;read_clat_pct01;read_clat_pct02;read_clat_pct03;read_clat_pct04;read_clat_pct05;read_clat_pct06;read_clat_pct07;read_clat_pct08;read_clat_pct09;read_clat_pct10;read_clat_pct11;read_clat_pct12;read_clat_pct13;read_clat_pct14;read_clat_pct15;read_clat_pct16;read_clat_pct17;read_clat_pct18;read_clat_pct19;read_clat_pct20;read_tlat_min;read_lat_max;read_lat_mean;read_lat_dev;read_bw_min;read_bw_max;read_bw_agg_pct;read_bw_mean;read_bw_dev;write_kb;write_bandwidth;write_iops;write_runtime_ms;write_slat_min;write_slat_max;write_slat_mean;write_slat_dev;write_clat_max;write_clat_min;write_clat_mean;write_clat_dev;write_clat_pct01;write_clat_pct02;write_clat_pct03;write_clat_pct04;write_clat_pct05;write_clat_pct06;write_clat_pct07;write_clat_pct08;write_clat_pct09;write_clat_pct10;write_clat_pct11;write_clat_pct12;write_clat_pct13;write_clat_pct14;write_clat_pct15;write_clat_pct16;write_clat_pct17;write_clat_pct18;write_clat_pct19;write_clat_pct20;write_tlat_min;write_lat_max;write_lat_mean;write_lat_dev;write_bw_min;write_bw_max;write_bw_agg_pct;write_bw_mean;write_bw_dev;cpu_user;cpu_sys;cpu_csw;cpu_mjf;pu_minf;iodepth_1;iodepth_2;iodepth_4;iodepth_8;iodepth_16;iodepth_32;iodepth_64;lat_2us;lat_4us;lat_10us;lat_20us;lat_50us;lat_100us;lat_250us;lat_500us;lat_750us;lat_1000us;lat_2ms;lat_4ms;lat_10ms;lat_20ms;lat_50ms;lat_100ms;lat_250ms;lat_500ms;lat_750ms;lat_1000ms;lat_2000ms;lat_over_2000ms;disk_name;disk_read_iops;disk_write_iops;disk_read_merges;disk_write_merges;disk_read_ticks;write_ticks;disk_queue_time;disk_util + Trace file format -----------------