X-Git-Url: https://git.kernel.dk/?a=blobdiff_plain;f=HOWTO;h=7e46cee0eceac9f8d85c5b6191b3335dd72c2e14;hb=dee9b29bef5bc344815d7a53dda6bb21426f2bfa;hp=cd6285524f392c0a911a2e133dd3d4b6b40aa371;hpb=0e21f5c6f64a73bcede20e1a29a885845e453b8e;p=fio.git diff --git a/HOWTO b/HOWTO index cd628552..7e46cee0 100644 --- a/HOWTO +++ b/HOWTO @@ -970,14 +970,15 @@ Target file/device Accepted values are: **none** - The :option:`zonerange`, :option:`zonesize` and - :option:`zoneskip` parameters are ignored. + The :option:`zonerange`, :option:`zonesize`, + :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. + starts. :option `zonecapacity` is ignored. **zbd** Zoned block device mode. I/O happens sequentially in each zone, even if random I/O @@ -1004,6 +1005,17 @@ Target file/device For :option:`zonemode` =zbd, this is the size of a single zone. The :option:`zonerange` parameter is ignored in this mode. + +.. option:: zonecapacity=int + + For :option:`zonemode` =zbd, this defines the capacity of a single zone, + which is the accessible area starting from the zone start address. + This parameter only applies when using :option:`zonemode` =zbd in + combination with regular block devices. If not specified it defaults to + the zone size. If the target device is a zoned block device, the zone + capacity is obtained from the device information and this option is + ignored. + .. option:: zoneskip=int For :option:`zonemode` =strided, the number of bytes to skip after @@ -1665,10 +1677,28 @@ Buffers and memory This will be ignored if :option:`pre_read` is also specified for the same job. -.. option:: sync=bool +.. option:: sync=str + + Whether, and what type, of synchronous I/O to use for writes. The allowed + values are: + + **none** + Do not use synchronous IO, the default. + + **0** + Same as **none**. + + **sync** + Use synchronous file IO. For the majority of I/O engines, + this means using O_SYNC. + + **1** + Same as **sync**. + + **dsync** + Use synchronous data IO. For the majority of I/O engines, + this means using O_DSYNC. - Use synchronous I/O for buffered writes. For the majority of I/O engines, - this means using O_SYNC. Default: false. .. option:: iomem=str, mem=str @@ -1889,14 +1919,6 @@ I/O engine single CPU at the desired rate. A job never finishes unless there is at least one non-cpuio job. - **guasi** - The GUASI I/O engine is the Generic Userspace Asynchronous Syscall - Interface approach to async I/O. See - - http://www.xmailserver.org/guasi-lib.html - - 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 @@ -2026,6 +2048,14 @@ I/O engine **nbd** Read and write a Network Block Device (NBD). + **libcufile** + I/O engine supporting libcufile synchronous access to nvidia-fs and a + GPUDirect Storage-supported filesystem. This engine performs + I/O without transferring buffers between user-space and the kernel, + unless :option:`verify` is set or :option:`cuda_io` is `posix`. + :option:`iomem` must not be `cudamalloc`. This ioengine defines + engine specific options. + I/O engine specific parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2097,6 +2127,26 @@ 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] + + 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 + the required resource becomes free. + + This option sets the RWF_NOWAIT flag (supported from the 4.14 Linux kernel) and + the call will return instantly with EAGAIN or a partial result rather than waiting. + + It is useful to also use ignore_error=EAGAIN when using this option. + + Note: glibc 2.27, 2.28 have a bug in syscall wrappers preadv2, pwritev2. + They return EOPNOTSUP instead of EAGAIN. + + For cached I/O, using this option usually means a request operates only with + cached data. Currently the RWF_NOWAIT flag does not supported for cached write. + + For direct I/O, requests will only succeed if cache invalidation isn't required, + file blocks are fully allocated and the disk request could be issued immediately. + .. option:: cpuload=int : [cpuio] Attempt to use the specified percentage of CPU cycles. This is a mandatory @@ -2356,6 +2406,28 @@ with the caveat that when used on the command line, they must come after the nbd+unix:///?socket=/tmp/socket nbds://tlshost/exportname +.. option:: gpu_dev_ids=str : [libcufile] + + Specify the GPU IDs to use with CUDA. This is a colon-separated list of + int. GPUs are assigned to workers roundrobin. Default is 0. + +.. option:: cuda_io=str : [libcufile] + + Specify the type of I/O to use with CUDA. Default is **cufile**. + + **cufile** + Use libcufile and nvidia-fs. This option performs I/O directly + between a GPUDirect Storage filesystem and GPU buffers, + avoiding use of a bounce buffer. If :option:`verify` is set, + cudaMemcpy is used to copy verificaton data between RAM and GPU. + Verification data is copied from RAM to GPU before a write + and from GPU to RAM after a read. :option:`direct` must be 1. + **posix** + Use POSIX to perform I/O with a RAM buffer, and use cudaMemcpy + to transfer data between RAM and the GPUs. Data is copied from + GPU to RAM before a write and copied from RAM to GPU after a + read. :option:`verify` does not affect use of cudaMemcpy. + I/O depth ~~~~~~~~~ @@ -2450,7 +2522,8 @@ I/O depth can increase latencies. The benefit is that fio can manage submission rates independently of the device completion rates. This avoids skewed latency reporting if I/O gets backed up on the device side (the coordinated omission - problem). + problem). Note that this option cannot reliably be used with async IO + engines. I/O rate @@ -2552,6 +2625,13 @@ I/O latency defaults to 100.0, meaning that all I/Os must be equal or below to the value set by :option:`latency_target`. +.. option:: latency_run=bool + + Used with :option:`latency_target`. If false (default), fio will find + the highest queue depth that meets :option:`latency_target` and exit. If + true, fio will continue running and try to meet :option:`latency_target` + by adjusting queue depth. + .. option:: max_latency=time If set, fio will exit the job with an ETIMEDOUT error if it exceeds this @@ -2586,6 +2666,9 @@ I/O replay character. See the :option:`filename` option for information on how to escape ':' characters within the file names. These files will be sequentially assigned to job clones created by :option:`numjobs`. + '-' is a reserved name, meaning read from stdin, notably if + :option:`filename` is set to '-' which means stdin as well, then + this flag can't be set to '-'. .. option:: read_iolog_chunked=bool @@ -2819,15 +2902,10 @@ Threads, processes and job synchronization ``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. -.. option:: flow_watermark=int - - The maximum value that the absolute value of the flow counter is allowed to - reach before the job must wait for a lower value of the counter. - .. option:: flow_sleep=int - The period of time, in microseconds, to wait after the flow watermark has - been exceeded before retrying operations. + The period of time, in microseconds, to wait after the flow counter + has exceeded its proportion before retrying operations. .. option:: stonewall, wait_for_previous @@ -4138,7 +4216,7 @@ Fio supports a variety of log file formats, for logging latencies, bandwidth, and IOPS. The logs share a common format, which looks like this: *time* (`msec`), *value*, *data direction*, *block size* (`bytes`), - *offset* (`bytes`) + *offset* (`bytes`), *command priority* *Time* for the log entry is always in milliseconds. The *value* logged depends on the type of log, it will be one of the following: @@ -4163,6 +4241,9 @@ The entry's *block size* is always in bytes. The *offset* is the position in byt from the start of the file for that particular I/O. The logging of the offset can be toggled with :option:`log_offset`. +*Command priority* is 0 for normal priority and 1 for high priority. This is controlled +by the ioengine specific :option:`cmdprio_percentage`. + Fio defaults to logging every individual I/O but when windowed logging is set through :option:`log_avg_msec`, either the average (by default) or the maximum (:option:`log_max_value` is set) *value* seen over the specified period of time