X-Git-Url: https://git.kernel.dk/?a=blobdiff_plain;f=HOWTO.rst;h=bbd9496eefb37f952e3dea1f76adbd2df54a2e76;hb=HEAD;hp=c404d724aa8e92906f713108ddc76fc5376e1795;hpb=5b7565b0b236f77761126d728f085a965f3e61bc;p=fio.git diff --git a/HOWTO.rst b/HOWTO.rst index c404d724..0b39a892 100644 --- a/HOWTO.rst +++ b/HOWTO.rst @@ -971,13 +971,13 @@ Target file/device .. option:: unlink=bool - Unlink the job files when done. Not the default, as repeated runs of that + Unlink (delete) the job files when done. Not the default, as repeated runs of that job would then waste time recreating the file set again and again. Default: false. .. option:: unlink_each_loop=bool - Unlink job files after each iteration or loop. Default: false. + Unlink (delete) job files after each iteration or loop. Default: false. .. option:: zonemode=str @@ -985,14 +985,14 @@ Target file/device **none** The :option:`zonerange`, :option:`zonesize`, - :option `zonecapacity` and option:`zoneskip` + :option:`zonecapacity` and :option:`zoneskip` parameters are ignored. **strided** I/O happens in a single zone until :option:`zonesize` bytes have been transferred. After that number of bytes has been transferred processing of the next zone - starts. :option `zonecapacity` is ignored. + starts. :option:`zonecapacity` is ignored. **zbd** Zoned block device mode. I/O happens sequentially in each zone, even if random I/O @@ -1631,7 +1631,7 @@ Block size Comma-separated ranges may be specified for reads, writes, and trims as described in :option:`blocksize`. - Example: ``bsrange=1k-4k,2k-8k``. + Example: ``bsrange=1k-4k,2k-8k`` also the ':' delimiter ``bsrange=1k:4k,2k:8k``. .. option:: bssplit=str[,str][,str] @@ -1992,7 +1992,9 @@ I/O engine .. option:: ioengine=str - Defines how the job issues I/O to the file. The following types are defined: + fio supports 2 kinds of performance measurement: I/O and file/directory operation. + + I/O engines define how the job issues I/O to the file. The following types are defined: **sync** Basic :manpage:`read(2)` or :manpage:`write(2)` @@ -2177,21 +2179,6 @@ I/O engine absolute or relative. See :file:`engines/skeleton_external.c` for details of writing an external I/O engine. - **filecreate** - Simply create the files and do no I/O to them. You still need to - set `filesize` so that all the accounting still occurs, but no - actual I/O will be done other than creating the file. - - **filestat** - Simply do stat() and do no I/O to the file. You need to set 'filesize' - and 'nrfiles', so that files will be created. - This engine is to measure file lookup and meta data access. - - **filedelete** - Simply delete the files by unlink() and do no I/O to them. You need to set 'filesize' - and 'nrfiles', so that the files will be created. - This engine is to measure file delete. - **libpmem** Read and write using mmap I/O to a file on a filesystem mounted with DAX on a persistent memory device through the PMDK @@ -2261,6 +2248,50 @@ I/O engine several instances to access the same device or file simultaneously, but allow it for threads. + File/directory operation engines define how the job operates file or directory. The + following types are defined: + + **filecreate** + Simply create the files and do no I/O to them. You still need to + set `filesize` so that all the accounting still occurs, but no + actual I/O will be done other than creating the file. + Example job file: filecreate-ioengine.fio. + + **filestat** + Simply do stat() and do no I/O to the file. You need to set 'filesize' + and 'nrfiles', so that files will be created. + This engine is to measure file lookup and meta data access. + Example job file: filestat-ioengine.fio. + + **filedelete** + Simply delete the files by unlink() and do no I/O to them. You need to set 'filesize' + and 'nrfiles', so that the files will be created. + This engine is to measure file delete. + Example job file: filedelete-ioengine.fio. + + **dircreate** + Simply create the directories and do no I/O to them. You still need to + set `filesize` so that all the accounting still occurs, but no + actual I/O will be done other than creating the directories. + Example job file: dircreate-ioengine.fio. + + **dirstat** + Simply do stat() and do no I/O to the directories. You need to set 'filesize' + and 'nrfiles', so that directories will be created. + This engine is to measure directory lookup and meta data access. + Example job file: dirstat-ioengine.fio. + + **dirdelete** + Simply delete the directories by rmdir() and do no I/O to them. You need to set 'filesize' + and 'nrfiles', so that the directories will be created. + This engine is to measure directory delete. + Example job file: dirdelete-ioengine.fio. + + For file and directory operation engines, there is no I/O throughput, then the + statistics data in report have different meanings. The meaningful output indexes are: 'iops' and 'clat'. + 'bw' is meaningless. Refer to section: "Interpreting the output" for more details. + + I/O engine specific parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2469,7 +2500,24 @@ with the caveat that when used on the command line, they must come after the Enable Flexible Data Placement mode for write commands. -.. option:: fdp_pli_select=str : [io_uring_cmd] [xnvme] +.. option:: dataplacement=str : [io_uring_cmd] [xnvme] + + Specifies the data placement directive type to use for write commands. + The following types are supported: + + **none** + Do not use a data placement directive. This is the + default. + + **fdp** + Use Flexible Data Placement directives for write + commands. This is equivalent to specifying + :option:`fdp` =1. + + **streams** + Use Streams directives for write commands. + +.. option:: plid_select=str, fdp_pli_select=str : [io_uring_cmd] [xnvme] Defines how fio decides which placement ID to use next. The following types are defined: @@ -2481,16 +2529,41 @@ with the caveat that when used on the command line, they must come after the Round robin over available placement IDs. This is the default. - The available placement ID index/indices is defined by the option - :option:`fdp_pli`. + **scheme** + Choose a placement ID (index) based on the scheme file defined by + the option :option:`dp_scheme`. + + The available placement ID (indices) are defined by the option :option:`fdp_pli` + or :option:`plids` except for the case of **scheme**. + +.. option:: plids=str, fdp_pli=str : [io_uring_cmd] [xnvme] + + Select which Placement IDs (streams) or Placement ID Indices (FDP) this + job is allowed to use for writes. For FDP by default, the job will + cycle through all available Placement IDs, so use this to isolate these + identifiers to specific jobs. If you want fio to use FDP placement + identifiers only at indices 0, 2 and 5 specify ``plids=0,2,5``. For + streams this should be a comma-separated list of Stream IDs. + +.. option:: dp_scheme=str : [io_uring_cmd] [xnvme] + + Defines which placement ID (index) to be selected based on offset(LBA) range. + The file should contains one or more scheme entries in the following format: -.. option:: fdp_pli=str : [io_uring_cmd] [xnvme] + 0, 10737418240, 0 + 10737418240, 21474836480, 1 + 21474836480, 32212254720, 2 + ... - Select which Placement ID Index/Indicies this job is allowed to use for - writes. By default, the job will cycle through all available Placement - IDs, so use this to isolate these identifiers to specific jobs. If you - want fio to use placement identifier only at indices 0, 2 and 5 specify - ``fdp_pli=0,2,5``. + Each line, a scheme entry, contains start offset, end offset, and placement ID + (index) separated by comma(,). If the write offset is within the range of a certain + scheme entry(start offset ≤ offset < end offset), the corresponding placement ID + (index) will be selected. If the write offset belongs to multiple scheme entries, + the first matched scheme entry will be applied. If the offset is not within any range + of scheme entry, dspec field will be set to 0, default RUH. (Caution: In case of + multiple devices in a job, all devices of the job will be affected by the scheme. If + this option is specified, the option :option:`plids` or :option:`fdp_pli` will be + ignored.) .. option:: md_per_io_size=int : [io_uring_cmd] [xnvme] @@ -2774,12 +2847,12 @@ with the caveat that when used on the command line, they must come after the Specify stat system call type to measure lookup/getattr performance. Default is **stat** for :manpage:`stat(2)`. -.. option:: readfua=bool : [sg] +.. option:: readfua=bool : [sg] [io_uring_cmd] With readfua option set to 1, read operations include the force unit access (fua) flag. Default is 0. -.. option:: writefua=bool : [sg] +.. option:: writefua=bool : [sg] [io_uring_cmd] With writefua option set to 1, write operations include the force unit access (fua) flag. Default is 0. @@ -3323,8 +3396,8 @@ I/O rate .. option:: rate_cycle=int - Average bandwidth for :option:`rate` and :option:`rate_min` over this number - of milliseconds. Defaults to 1000. + Average bandwidth for :option:`rate_min` and :option:`rate_iops_min` + over this number of milliseconds. Defaults to 1000. I/O latency @@ -4568,6 +4641,21 @@ writes in the example above). In the order listed, they denote: commit if available) functions were completed to when the I/O's completion was reaped by fio. + For file and directory operation engines, **clat** denotes the time + to complete one file or directory operation. + + **filecreate engine**:the time cost to create a new file + + **filestat engine**: the time cost to look up an existing file + + **filedelete engine**:the time cost to delete a file + + **dircreate engine**: the time cost to create a new directory + + **dirstat engine**: the time cost to look up an existing directory + + **dirdelete engine**: the time cost to delete a directory + **lat** Total latency. Same names as slat and clat, this denotes the time from when fio created the I/O unit to completion of the I/O operation. @@ -4586,12 +4674,30 @@ writes in the example above). In the order listed, they denote: are on the same disk, since they are then competing for disk access. + For file and directory operation engines, **bw** is meaningless. + **iops** IOPS statistics based on measurements from discrete intervals. For details see the description for bw above. See :option:`iopsavgtime` to control the duration of the intervals. Same values reported here as for bw except for percentage. + For file and directory operation engines, **iops** is the most + fundamental index to denote the performance. + It means how many files or directories can be operated per second. + + **filecreate engine**:number of files can be created per second + + **filestat engine**: number of files can be looked up per second + + **filedelete engine**:number of files can be deleted per second + + **dircreate engine**: number of directories can be created per second + + **dirstat engine**: number of directories can be looked up per second + + **dirdelete engine**: number of directories can be deleted per second + **lat (nsec/usec/msec)** The distribution of I/O completion latencies. This is the time from when I/O leaves fio and when it gets completed. Unlike the separate