X-Git-Url: https://git.kernel.dk/?a=blobdiff_plain;f=HOWTO.rst;h=0aaf033a707d331ea44be60a17c6d6a9f301f5b9;hb=942d66c85ee8f007ea5f1097d097cf9a44b662a0;hp=470777e2ebd8f85ca74bf78dbdf608d7b4613f58;hpb=13ddd98b2a70c55657f952096785ccc64479f0eb;p=fio.git diff --git a/HOWTO.rst b/HOWTO.rst index 470777e2..0aaf033a 100644 --- a/HOWTO.rst +++ b/HOWTO.rst @@ -167,9 +167,9 @@ Command line options defined by `ioengine`. If no `ioengine` is given, list all available ioengines. -.. option:: --showcmd=jobfile +.. option:: --showcmd - Convert `jobfile` to a set of command-line options. + Convert given job files to a set of command-line options. .. option:: --readonly @@ -1054,7 +1054,7 @@ Target file/device When running a random write test across an entire drive many more zones will be open than in a typical application workload. Hence this - command line option that allows to limit the number of open zones. The + command line option that allows one to limit the number of open zones. The number of open zones is defined as the number of zones to which write commands are issued. @@ -1129,7 +1129,14 @@ I/O type Random mixed reads and writes. **trimwrite** Sequential trim+write sequences. Blocks will be trimmed first, - then the same blocks will be written to. + then the same blocks will be written to. So if ``io_size=64K`` + is specified, Fio will trim a total of 64K bytes and also + write 64K bytes on the same trimmed blocks. This behaviour + will be consistent with ``number_ios`` or other Fio options + limiting the total bytes or number of I/O's. + **randtrimwrite** + Like trimwrite, but uses random offsets rather + than sequential writes. Fio defaults to read if the option is not specified. For the mixed I/O types, the default is to split them 50/50. For certain types of I/O the @@ -1301,7 +1308,7 @@ I/O type 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. A percentage can be specified by a number between 1 and 100 followed by '%', - for example, ``offset=20%`` to specify 20%. In ZBD mode, value can be set as + for example, ``offset=20%`` to specify 20%. In ZBD mode, value can be set as number of zones using 'z'. .. option:: offset_align=int @@ -1439,7 +1446,7 @@ I/O type supplied as a value between 0 and 100. The second, optional float is allowed for **pareto**, **zipf** and **normal** distributions. - It allows to set base of distribution in non-default place, giving more control + It allows one to set base of distribution in non-default place, giving more control over most probable outcome. This value is in range [0-1] which maps linearly to range of possible random values. Defaults are: random for **pareto** and **zipf**, and 0.5 for **normal**. @@ -1868,8 +1875,11 @@ I/O size .. option:: size=int The total size of file I/O for each thread of this job. Fio will run until - this many bytes has been transferred, unless runtime is limited by other options - (such as :option:`runtime`, for instance, or increased/decreased by :option:`io_size`). + this many bytes has been transferred, unless runtime is altered by other means + such as (1) :option:`runtime`, (2) :option:`io_size` (3) :option:`number_ios`, + (4) gaps/holes while doing I/O's such as ``rw=read:16K``, or (5) sequential + I/O reaching end of the file which is possible when :option:`percentage_random` + is less than 100. Fio will divide this size between the available files determined by options such as :option:`nrfiles`, :option:`filename`, unless :option:`filesize` is specified by the job. If the result of division happens to be 0, the size is @@ -1877,7 +1887,7 @@ I/O size If this option is not specified, fio will use the full size of the given files or devices. If the files do not exist, size must be given. It is also possible to give size as a percentage between 1 and 100. If ``size=20%`` is - given, fio will use 20% of the full size of the given files or devices. + given, fio will use 20% of the full size of the given files or devices. In ZBD mode, value can also be set as number of zones using 'z'. Can be combined with :option:`offset` to constrain the start and end range that I/O will be done within. @@ -2267,7 +2277,7 @@ with the caveat that when used on the command line, they must come after the map and release for each IO. This is more efficient, and reduces the IO latency as well. -.. option:: nonvectored : [io_uring] [io_uring_cmd] +.. option:: nonvectored=int : [io_uring] [io_uring_cmd] With this option, fio will use non-vectored read/write commands, where address must contain the address directly. Default is -1. @@ -2292,9 +2302,11 @@ with the caveat that when used on the command line, they must come after the kernel of available items in the SQ ring. If this option is set, the act of submitting IO will be done by a polling thread in the kernel. This frees up cycles for fio, at the cost of using more CPU in the - system. + system. As submission is just the time it takes to fill in the sqe + entries and any syscall required to wake up the idle kernel thread, + fio will not report submission latencies. -.. option:: sqthread_poll_cpu : [io_uring] [io_uring_cmd] +.. option:: sqthread_poll_cpu=int : [io_uring] [io_uring_cmd] When :option:`sqthread_poll` is set, this option provides a way to define which CPU should be used for the polling thread. @@ -2344,7 +2356,7 @@ with the caveat that when used on the command line, they must come after the When hipri is set this determines the probability of a pvsync2 I/O being high priority. The default is 100%. -.. option:: nowait : [pvsync2] [libaio] [io_uring] +.. option:: nowait=bool : [pvsync2] [libaio] [io_uring] [io_uring_cmd] By default if a request cannot be executed immediately (e.g. resource starvation, waiting on locks) it is queued and the initiating process will be blocked until @@ -2550,7 +2562,7 @@ with the caveat that when used on the command line, they must come after the [dfs] - Specificy a different chunk size (in bytes) for the dfs file. + Specify a different chunk size (in bytes) for the dfs file. Use DAOS container's chunk size by default. [libhdfs] @@ -2559,7 +2571,7 @@ with the caveat that when used on the command line, they must come after the .. option:: object_class=str : [dfs] - Specificy a different object class for the dfs file. + Specify a different object class for the dfs file. Use DAOS container's object class by default. .. option:: skip_bad=bool : [mtd] @@ -2692,6 +2704,20 @@ with the caveat that when used on the command line, they must come after the The S3 key/access id. +.. option:: http_s3_sse_customer_key=str : [http] + + The encryption customer key in SSE server side. + +.. option:: http_s3_sse_customer_algorithm=str : [http] + + The encryption customer algorithm in SSE server side. + Default is **AES256** + +.. option:: http_s3_storage_class=str : [http] + + Which storage class to access. User-customizable settings. + Default is **STANDARD** + .. option:: http_swift_auth_token=str : [http] The Swift auth token. See the example configuration file on how @@ -2766,41 +2792,56 @@ with the caveat that when used on the command line, they must come after the Select the xnvme async command interface. This can take these values. **emu** - This is default and used to emulate asynchronous I/O. + This is default and use to emulate asynchronous I/O by using a + single thread to create a queue pair on top of a synchronous + I/O interface using the NVMe driver IOCTL. **thrpool** - Use thread pool for Asynchronous I/O. + Emulate an asynchronous I/O interface with a pool of userspace + threads on top of a synchronous I/O interface using the NVMe + driver IOCTL. By default four threads are used. **io_uring** - Use Linux io_uring/liburing for Asynchronous I/O. + Linux native asynchronous I/O interface which supports both + direct and buffered I/O. + **io_uring_cmd** + Fast Linux native asynchronous I/O interface for NVMe pass + through commands. This only works with NVMe character device + (/dev/ngXnY). **libaio** Use Linux aio for Asynchronous I/O. **posix** - Use POSIX aio for Asynchronous I/O. + Use the posix asynchronous I/O interface to perform one or + more I/O operations asynchronously. **nil** - Use nil-io; For introspective perf. evaluation + Do not transfer any data; just pretend to. This is mainly used + for introspective performance evaluation. .. option:: xnvme_sync=str : [xnvme] Select the xnvme synchronous command interface. This can take these values. **nvme** - This is default and uses Linux NVMe Driver ioctl() for synchronous I/O. + This is default and uses Linux NVMe Driver ioctl() for + synchronous I/O. **psync** - Use pread()/write() for synchronous I/O. + This supports regular as well as vectored pread() and pwrite() + commands. + **block** + This is the same as psync except that it also supports zone + management commands using Linux block layer IOCTLs. .. option:: xnvme_admin=str : [xnvme] Select the xnvme admin command interface. This can take these values. **nvme** - This is default and uses linux NVMe Driver ioctl() for admin commands. + This is default and uses linux NVMe Driver ioctl() for admin + commands. **block** Use Linux Block Layer ioctl() and sysfs for admin commands. - **file_as_ns** - Use file-stat to construct NVMe idfy responses. .. option:: xnvme_dev_nsid=int : [xnvme] - xnvme namespace identifier, for userspace NVMe driver. + xnvme namespace identifier for userspace NVMe driver, such as SPDK. .. option:: xnvme_iovec=int : [xnvme] @@ -3049,7 +3090,8 @@ I/O replay Write the issued I/O patterns to the specified file. See :option:`read_iolog`. Specify a separate file for each job, otherwise the - iologs will be interspersed and the file may be corrupt. + iologs will be interspersed and the file may be corrupt. This file will + be opened in append mode. .. option:: read_iolog=str @@ -3292,13 +3334,13 @@ Threads, processes and job synchronization .. option:: flow=int - Weight in token-based flow control. If this value is used, then there is a - 'flow counter' which is used to regulate the proportion of activity between - two or more jobs. Fio attempts to keep this flow counter near zero. The - ``flow`` parameter stands for how much should be added or subtracted to the - flow counter on each iteration of the main I/O loop. That is, if one job has - ``flow=8`` and another job has ``flow=-1``, then there will be a roughly 1:8 - ratio in how much one runs vs the other. + Weight in token-based flow control. If this value is used, then fio + regulates the activity between two or more jobs sharing the same + flow_id. Fio attempts to keep each job activity proportional to other + jobs' activities in the same flow_id group, with respect to requested + weight per job. That is, if one job has `flow=3', another job has + `flow=2' and another with `flow=1`, then there will be a roughly 3:2:1 + ratio in how much one runs vs the others. .. option:: flow_sleep=int @@ -3319,10 +3361,10 @@ Threads, processes and job synchronization make fio terminate all jobs in the same group, as soon as one job of that group finishes. -.. option:: exit_what +.. option:: exit_what=str By default, fio will continue running all other jobs when one job finishes. - Sometimes this is not the desired action. Setting ``exit_all`` will + Sometimes this is not the desired action. Setting ``exitall`` will instead make fio terminate all jobs in the same group. The option ``exit_what`` allows to control which jobs get terminated when ``exitall`` is enabled. The default is ``group`` and does not change the behaviour of @@ -3573,7 +3615,10 @@ Verification .. option:: experimental_verify=bool - Enable experimental verification. + Enable experimental verification. Standard verify records I/O metadata + for later use during the verification phase. Experimental verify + instead resets the file after the write phase and then replays I/Os for + the verification phase. Steady state ~~~~~~~~~~~~ @@ -3897,6 +3942,13 @@ Error handling appended, the total error count and the first error. The error field given in the stats is the first error that was hit during the run. + Note: a write error from the device may go unnoticed by fio when using + buffered IO, as the write() (or similar) system call merely dirties the + kernel pages, unless :option:`sync` or :option:`direct` is used. Device IO + errors occur when the dirty data is actually written out to disk. If fully + sync writes aren't desirable, :option:`fsync` or :option:`fdatasync` can be + used as well. This is specific to writes, as reads are always synchronous. + The allowed values are: **none** @@ -4457,7 +4509,7 @@ 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 +allows one to access more than one file per trace and has a bigger set of possible file actions. The first line of the trace file has to be::