X-Git-Url: https://git.kernel.dk/?a=blobdiff_plain;f=HOWTO.rst;h=1cea16c4be5de8fafc4102f936bdeca4cd412d19;hb=b1bd09b593ddd4043c6217321c7135c0c580edc0;hp=bcc3da3a9c77160f41234bff9927656038c35218;hpb=6fb31a012cf383cac698ac046eda31c787cc9f2f;p=fio.git diff --git a/HOWTO.rst b/HOWTO.rst index bcc3da3a..1cea16c4 100644 --- a/HOWTO.rst +++ b/HOWTO.rst @@ -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. @@ -1446,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**. @@ -1875,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 @@ -2192,6 +2195,15 @@ I/O engine the SPDK NVMe driver, or your own custom NVMe driver. The xnvme engine includes engine specific options. (See https://xnvme.io). + **libblkio** + Use the libblkio library + (https://gitlab.com/libblkio/libblkio). The specific + *driver* to use must be set using + :option:`libblkio_driver`. If + :option:`mem`/:option:`iomem` is not specified, memory + allocation is delegated to libblkio (and so is + guaranteed to work with the selected *driver*). + I/O engine specific parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2299,7 +2311,9 @@ 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=int : [io_uring] [io_uring_cmd] @@ -2321,6 +2335,12 @@ with the caveat that when used on the command line, they must come after the by the application. The benefits are more efficient IO for high IOPS scenarios, and lower latencies for low queue depth IO. + [libblkio] + + Use poll queues. This is incompatible with + :option:`libblkio_wait_mode=eventfd ` and + :option:`libblkio_force_enable_completion_eventfd`. + [pvsync2] Set RWF_HIPRI on I/O, indicating to the kernel that it's of higher priority @@ -2842,6 +2862,58 @@ with the caveat that when used on the command line, they must come after the If this option is set. xnvme will use vectored read/write commands. +.. option:: libblkio_driver=str : [libblkio] + + The libblkio *driver* to use. Different drivers access devices through + different underlying interfaces. Available drivers depend on the + libblkio version in use and are listed at + https://libblkio.gitlab.io/libblkio/blkio.html#drivers + +.. option:: libblkio_pre_connect_props=str : [libblkio] + + A colon-separated list of libblkio properties to be set after creating + but before connecting the libblkio instance. Each property must have the + format ``=``. Colons can be escaped as ``\:``. These are + set after the engine sets any other properties, so those can be + overriden. Available properties depend on the libblkio version in use + and are listed at + https://libblkio.gitlab.io/libblkio/blkio.html#properties + +.. option:: libblkio_pre_start_props=str : [libblkio] + + A colon-separated list of libblkio properties to be set after connecting + but before starting the libblkio instance. Each property must have the + format ``=``. Colons can be escaped as ``\:``. These are + set after the engine sets any other properties, so those can be + overriden. Available properties depend on the libblkio version in use + and are listed at + https://libblkio.gitlab.io/libblkio/blkio.html#properties + +.. option:: libblkio_vectored : [libblkio] + + Submit vectored read and write requests. + +.. option:: libblkio_write_zeroes_on_trim : [libblkio] + + Submit trims as "write zeroes" requests instead of discard requests. + +.. option:: libblkio_wait_mode=str : [libblkio] + + How to wait for completions: + + **block** (default) + Use a blocking call to ``blkioq_do_io()``. + **eventfd** + Use a blocking call to ``read()`` on the completion eventfd. + **loop** + Use a busy loop with a non-blocking call to ``blkioq_do_io()``. + +.. option:: libblkio_force_enable_completion_eventfd : [libblkio] + + Enable the queue's completion eventfd even when unused. This may impact + performance. The default is to enable it only if + :option:`libblkio_wait_mode=eventfd `. + I/O depth ~~~~~~~~~ @@ -3610,7 +3682,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 ~~~~~~~~~~~~ @@ -4501,7 +4576,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 than 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::