doc: improve readonly option description
[fio.git] / HOWTO
diff --git a/HOWTO b/HOWTO
index acb9e97fc35bf6ca790d45bb93b7be0260509a8f..e1399b4a101925d94527542e4c5f8f696668912b 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -163,12 +163,12 @@ Command line options
 
 .. option:: --readonly
 
-       Turn on safety read-only checks, preventing writes.  The ``--readonly``
-       option is an extra safety guard to prevent users from accidentally starting
-       a write workload when that is not desired.  Fio will only write if
-       `rw=write/randwrite/rw/randrw` is given.  This extra safety net can be used
-       as an extra precaution as ``--readonly`` will also enable a write check in
-       the I/O engine core to prevent writes due to unknown user space bug(s).
+       Turn on safety read-only checks, preventing writes and trims.  The
+       ``--readonly`` option is an extra safety guard to prevent users from
+       accidentally starting a write or trim workload when that is not desired.
+       Fio will only modify the device under test if
+       `rw=write/randwrite/rw/randrw/trim/randtrim/trimwrite` is given.  This
+       safety net can be used as an extra precaution.
 
 .. option:: --eta=when
 
@@ -1429,7 +1429,7 @@ Block size
        If you want a workload that has 50% 2k reads and 50% 4k reads, while
        having 90% 4k writes and 10% 8k writes, you would specify::
 
-               bssplit=2k/50:4k/50,4k/90,8k/10
+               bssplit=2k/50:4k/50,4k/90:8k/10
 
        Fio supports defining up to 64 different weights for each data
        direction.
@@ -1747,6 +1747,7 @@ I/O engine
                        :manpage:`read(2)` and :manpage:`write(2)` for asynchronous
                        I/O. Requires :option:`filename` option to specify either block or
                        character devices.
+                       The sg engine includes engine specific options.
 
                **null**
                        Doesn't transfer any data, just pretends to.  This is mainly used to
@@ -1853,12 +1854,12 @@ I/O engine
 
                **pmemblk**
                        Read and write using filesystem DAX to a file on a filesystem
-                       mounted with DAX on a persistent memory device through the NVML
+                       mounted with DAX on a persistent memory device through the PMDK
                        libpmemblk library.
 
                **dev-dax**
                        Read and write using device DAX to a persistent memory device (e.g.,
-                       /dev/dax0.0) through the NVML libpmem library.
+                       /dev/dax0.0) through the PMDK libpmem library.
 
                **external**
                        Prefix to specify loading an external I/O engine object file. Append
@@ -1874,7 +1875,7 @@ I/O engine
 
                **libpmem**
                        Read and write using mmap I/O to a file on a filesystem
-                       mounted with DAX on a persistent memory device through the NVML
+                       mounted with DAX on a persistent memory device through the PMDK
                        libpmem library.
 
 I/O engine specific parameters
@@ -2068,6 +2069,37 @@ with the caveat that when used on the command line, they must come after the
        multiple paths exist between the client and the server or in certain loopback
        configurations.
 
+.. option:: readfua=bool : [sg]
+
+       With readfua option set to 1, read operations include
+       the force unit access (fua) flag. Default is 0.
+
+.. option:: writefua=bool : [sg]
+
+       With writefua option set to 1, write operations include
+       the force unit access (fua) flag. Default is 0.
+
+.. option:: sg_write_mode=str : [sg]
+       Specify the type of write commands to issue. This option can take three values:
+
+       **write**
+               This is the default where write opcodes are issued as usual.
+       **verify**
+               Issue WRITE AND VERIFY commands. The BYTCHK bit is set to 0. This
+               directs the device to carry out a medium verification with no data
+               comparison. The writefua option is ignored with this selection.
+       **same**
+               Issue WRITE SAME commands. This transfers a single block to the device
+               and writes this same block of data to a contiguous sequence of LBAs
+               beginning at the specified offset. fio's block size parameter specifies
+               the amount of data written with each command. However, the amount of data
+               actually transferred to the device is equal to the device's block
+               (sector) size. For a device with 512 byte sectors, blocksize=8k will
+               write 16 sectors with each command. fio will still generate 8k of data
+               for each command but only the first 512 bytes will be used and
+               transferred to the device. The writefua option is ignored with this
+               selection.
+
 I/O depth
 ~~~~~~~~~
 
@@ -2299,6 +2331,14 @@ I/O replay
        still respecting ordering. The result is the same I/O pattern to a given
        device, but different timings.
 
+.. option:: replay_time_scale=int
+
+       When replaying I/O with :option:`read_iolog`, fio will honor the
+       original timing in the trace. With this option, it's possible to scale
+       the time. It's a percentage option, if set to 50 it means run at 50%
+       the original IO rate in the trace. If set to 200, run at twice the
+       original IO rate. Defaults to 100.
+
 .. option:: replay_redirect=str
 
        While replaying I/O patterns using :option:`read_iolog` the default behavior
@@ -2326,6 +2366,14 @@ I/O replay
 
        Scale sector offsets down by this factor when replaying traces.
 
+.. option:: replay_skip=str
+
+       Sometimes it's useful to skip certain IO types in a replay trace.
+       This could be, for instance, eliminating the writes in the trace.
+       Or not replaying the trims/discards, if you are redirecting to
+       a device that doesn't support them. This option takes a comma
+       separated list of read, write, trim, sync.
+
 
 Threads, processes and job synchronization
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2365,24 +2413,27 @@ Threads, processes and job synchronization
 
        Set the I/O priority class. See man :manpage:`ionice(1)`.
 
-.. option:: cpumask=int
-
-       Set the CPU affinity of this job. The parameter given is a bit mask of
-       allowed CPUs the job may run on. So if you want the allowed CPUs to be 1
-       and 5, you would pass the decimal value of (1 << 1 | 1 << 5), or 34. See man
-       :manpage:`sched_setaffinity(2)`. This may not work on all supported
-       operating systems or kernel versions. This option doesn't work well for a
-       higher CPU count than what you can store in an integer mask, so it can only
-       control cpus 1-32. For boxes with larger CPU counts, use
-       :option:`cpus_allowed`.
-
 .. option:: cpus_allowed=str
 
        Controls the same options as :option:`cpumask`, but accepts a textual
-       specification of the permitted CPUs instead. So to use CPUs 1 and 5 you
-       would specify ``cpus_allowed=1,5``. This option also allows a range of CPUs
-       to be specified -- say you wanted a binding to CPUs 1, 5, and 8 to 15, you
-       would set ``cpus_allowed=1,5,8-15``.
+       specification of the permitted CPUs instead and CPUs are indexed from 0. So
+       to use CPUs 0 and 5 you would specify ``cpus_allowed=0,5``. This option also
+       allows a range of CPUs to be specified -- say you wanted a binding to CPUs
+       0, 5, and 8 to 15, you would set ``cpus_allowed=0,5,8-15``.
+
+       On Windows, when ``cpus_allowed`` is unset only CPUs from fio's current
+       processor group will be used and affinity settings are inherited from the
+       system. An fio build configured to target Windows 7 makes options that set
+       CPUs processor group aware and values will set both the processor group
+       and a CPU from within that group. For example, on a system where processor
+       group 0 has 40 CPUs and processor group 1 has 32 CPUs, ``cpus_allowed``
+       values between 0 and 39 will bind CPUs from processor group 0 and
+       ``cpus_allowed`` values between 40 and 71 will bind CPUs from processor
+       group 1. When using ``cpus_allowed_policy=shared`` all CPUs specified by a
+       single ``cpus_allowed`` option must be from the same processor group. For
+       Windows fio builds not built for Windows 7, CPUs will only be selected from
+       (and be relative to) whatever processor group fio happens to be running in
+       and CPUs from other processor groups cannot be used.
 
 .. option:: cpus_allowed_policy=str
 
@@ -2399,6 +2450,17 @@ Threads, processes and job synchronization
        enough CPUs are given for the jobs listed, then fio will roundrobin the CPUs
        in the set.
 
+.. option:: cpumask=int
+
+       Set the CPU affinity of this job. The parameter given is a bit mask of
+       allowed CPUs the job may run on. So if you want the allowed CPUs to be 1
+       and 5, you would pass the decimal value of (1 << 1 | 1 << 5), or 34. See man
+       :manpage:`sched_setaffinity(2)`. This may not work on all supported
+       operating systems or kernel versions. This option doesn't work well for a
+       higher CPU count than what you can store in an integer mask, so it can only
+       control cpus 1-32. For boxes with larger CPU counts, use
+       :option:`cpus_allowed`.
+
 .. option:: numa_cpu_nodes=str
 
        Set this job running on specified NUMA nodes' CPUs. The arguments allow
@@ -2601,18 +2663,6 @@ Verification
        previously written file. If the data direction includes any form of write,
        the verify will be of the newly written data.
 
-.. option:: verifysort=bool
-
-       If true, fio will sort written verify blocks when it deems it faster to read
-       them back in a sorted manner. This is often the case when overwriting an
-       existing file, since the blocks are already laid out in the file system. You
-       can ignore this option unless doing huge amounts of really fast I/O where
-       the red-black tree sorting CPU time becomes significant. Default: true.
-
-.. option:: verifysort_nr=int
-
-       Pre-load and sort verify blocks for a read workload.
-
 .. option:: verify_offset=int
 
        Swap the verification header with data somewhere else in the block before
@@ -2909,7 +2959,8 @@ Measurements and reporting
 
        Define the set of CPUs that are allowed to handle online log compression for
        the I/O jobs. This can provide better isolation between performance
-       sensitive jobs, and background compression work.
+       sensitive jobs, and background compression work. See
+       :option:`cpus_allowed` for the format used.
 
 .. option:: log_store_compressed=bool