HOWTO: use proper (or drop wrong usage of) option type =bool

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index f62a517004a1dfff3e049e544299b4a2cccad5bf..b535177c9abb13848346af93bc24b8a186ede983 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -505,19 +505,19 @@ Parameter types
        prefixes.  To specify power-of-10 decimal values defined in the
        International System of Units (SI):
 
        prefixes.  To specify power-of-10 decimal values defined in the
        International System of Units (SI):
 

-               * *Ki* -- means kilo (K) or 1000
-               * *Mi* -- means mega (M) or 1000**2
-               * *Gi* -- means giga (G) or 1000**3
-               * *Ti* -- means tera (T) or 1000**4
-               * *Pi* -- means peta (P) or 1000**5
+               * *ki* -- means kilo (K) or 1000
+               * *mi* -- means mega (M) or 1000**2
+               * *gi* -- means giga (G) or 1000**3
+               * *ti* -- means tera (T) or 1000**4
+               * *pi* -- means peta (P) or 1000**5

 
        To specify power-of-2 binary values defined in IEC 80000-13:
 
                * *k* -- means kibi (Ki) or 1024
 
        To specify power-of-2 binary values defined in IEC 80000-13:
 
                * *k* -- means kibi (Ki) or 1024

-               * *M* -- means mebi (Mi) or 1024**2
-               * *G* -- means gibi (Gi) or 1024**3
-               * *T* -- means tebi (Ti) or 1024**4
-               * *P* -- means pebi (Pi) or 1024**5
+               * *m* -- means mebi (Mi) or 1024**2
+               * *g* -- means gibi (Gi) or 1024**3
+               * *t* -- means tebi (Ti) or 1024**4
+               * *p* -- means pebi (Pi) or 1024**5

 
        With :option:`kb_base`\=1024 (the default), the unit prefixes are opposite
        from those specified in the SI and IEC 80000-13 standards to provide
 
        With :option:`kb_base`\=1024 (the default), the unit prefixes are opposite
        from those specified in the SI and IEC 80000-13 standards to provide


@@ -576,6 +576,8 @@ Parameter types
 **float_list**
        A list of floating point numbers, separated by a ':' character.
 
 **float_list**
        A list of floating point numbers, separated by a ':' character.
 

+With the above in mind, here follows the complete list of fio job parameters.
+

 
 Units
 ~~~~~
 
 Units
 ~~~~~


@@ -622,9 +624,6 @@ Units
                Bit based.
 
 
                Bit based.
 
 

-With the above in mind, here follows the complete list of fio job parameters.
-
-

 Job description
 ~~~~~~~~~~~~~~~
 
 Job description
 ~~~~~~~~~~~~~~~
 


@@ -1015,8 +1014,8 @@ I/O type
 
        ``sequential`` is only useful for random I/O, where fio would normally
        generate a new random offset for every I/O. If you append e.g. 8 to randread,
 
        ``sequential`` is only useful for random I/O, where fio would normally
        generate a new random offset for every I/O. If you append e.g. 8 to randread,

-       you would get a new random offset for every 8 I/O's. The result would be a
-       seek for only every 8 I/O's, instead of for every I/O. Use ``rw=randread:8``
+       you would get a new random offset for every 8 I/Os. The result would be a
+       seek for only every 8 I/Os, instead of for every I/O. Use ``rw=randread:8``

        to specify that. As sequential I/O is already sequential, setting
        ``sequential`` for that would not result in any differences.  ``identical``
        behaves in a similar fashion, except it sends the same offset 8 number of
        to specify that. As sequential I/O is already sequential, setting
        ``sequential`` for that would not result in any differences.  ``identical``
        behaves in a similar fashion, except it sends the same offset 8 number of


@@ -1393,7 +1392,7 @@ Block size
        typically won't work with direct I/O, as that normally requires sector
        alignment.
 
        typically won't work with direct I/O, as that normally requires sector
        alignment.
 

-.. option:: bs_is_seq_rand
+.. option:: bs_is_seq_rand=bool

 
        If this option is set, fio will use the normal read,write blocksize settings
        as sequential,random blocksize settings instead. Any random read or write
 
        If this option is set, fio will use the normal read,write blocksize settings
        as sequential,random blocksize settings instead. Any random read or write


@@ -1530,6 +1529,7 @@ Buffers and memory
 
                **cudamalloc**
                        Use GPU memory as the buffers for GPUDirect RDMA benchmark.
 
                **cudamalloc**
                        Use GPU memory as the buffers for GPUDirect RDMA benchmark.

+                       The ioengine must be rdma.

 
        The area allocated is a function of the maximum allowed bs size for the job,
        multiplied by the I/O depth given. Note that for **shmhuge** and
 
        The area allocated is a function of the maximum allowed bs size for the job,
        multiplied by the I/O depth given. Note that for **shmhuge** and


@@ -1819,6 +1819,11 @@ caveat that when used on the command line, they must come after the
        Set RWF_HIPRI on I/O, indicating to the kernel that it's of higher priority
        than normal.
 
        Set RWF_HIPRI on I/O, indicating to the kernel that it's of higher priority
        than normal.
 

+.. option:: hipri_percentage : [pvsync2]
+
+       When hipri is set this determines the probability of a pvsync2 IO being high
+       priority. The default is 100%.
+

 .. option:: cpuload=int : [cpuio]
 
        Attempt to use the specified percentage of CPU cycles. This is a mandatory
 .. option:: cpuload=int : [cpuio]
 
        Attempt to use the specified percentage of CPU cycles. This is a mandatory


@@ -1853,7 +1858,7 @@ caveat that when used on the command line, they must come after the
 
    [libhdfs]
 
 
    [libhdfs]
 

-               the listening port of the HFDS cluster namenode.
+               The listening port of the HFDS cluster namenode.

 
 .. option:: interface=str : [netsplice] [net]
 
 
 .. option:: interface=str : [netsplice] [net]
 


@@ -1926,7 +1931,7 @@ caveat that when used on the command line, they must come after the
        **0**
                Default. Preallocate donor's file on init.
        **1**
        **0**
                Default. Preallocate donor's file on init.
        **1**

-               Allocate space immediately inside defragment event,     and free right
+               Allocate space immediately inside defragment event, and free right

                after event.
 
 .. option:: clustername=str : [rbd]
                after event.
 
 .. option:: clustername=str : [rbd]


@@ -1958,7 +1963,7 @@ caveat that when used on the command line, they must come after the
 
 .. option:: chunk_size : [libhdfs]
 
 
 .. option:: chunk_size : [libhdfs]
 

-       the size of the chunk to use for each file.
+       The size of the chunk to use for each file.

 
 
 I/O depth
 
 
 I/O depth


@@ -2161,7 +2166,7 @@ I/O replay
        replay, the file needs to be turned into a blkparse binary data file first
        (``blkparse <device> -o /dev/null -d file_for_fio.bin``).
 
        replay, the file needs to be turned into a blkparse binary data file first
        (``blkparse <device> -o /dev/null -d file_for_fio.bin``).
 

-.. option:: replay_no_stall=int
+.. option:: replay_no_stall=bool

 
        When replaying I/O with :option:`read_iolog` the default behavior is to
        attempt to respect the timestamps within the log and replay them with the
 
        When replaying I/O with :option:`read_iolog` the default behavior is to
        attempt to respect the timestamps within the log and replay them with the


@@ -2482,7 +2487,7 @@ Verification
 
 .. option:: verifysort_nr=int
 
 
 .. option:: verifysort_nr=int
 

-   Pre-load and sort verify blocks for a read workload.
+       Pre-load and sort verify blocks for a read workload.

 
 .. option:: verify_offset=int
 
 
 .. option:: verify_offset=int
 


@@ -2590,7 +2595,7 @@ Verification
 
 .. option:: trim_backlog=int
 
 
 .. option:: trim_backlog=int
 

-       Verify that trim/discarded blocks are returned as zeros.
+       Trim after this number of blocks are written.

 
 .. option:: trim_backlog_batch=int
 
 
 .. option:: trim_backlog_batch=int
 


@@ -2675,7 +2680,7 @@ Measurements and reporting
        all jobs in a file will be part of the same reporting group, unless
        separated by a :option:`stonewall`.
 
        all jobs in a file will be part of the same reporting group, unless
        separated by a :option:`stonewall`.
 

-.. option:: stats
+.. option:: stats=bool

 
        By default, fio collects and shows final output results for all jobs
        that run. If this option is set to 0, then fio will ignore it in
 
        By default, fio collects and shows final output results for all jobs
        that run. If this option is set to 0, then fio will ignore it in


@@ -2758,10 +2763,11 @@ Measurements and reporting
        you instead want to log the maximum value, set this option to 1. Defaults to
        0, meaning that averaged values are logged.
 
        you instead want to log the maximum value, set this option to 1. Defaults to
        0, meaning that averaged values are logged.
 

-.. option:: log_offset=int
+.. option:: log_offset=bool

 
        If this is set, the iolog options will include the byte offset for the I/O
 
        If this is set, the iolog options will include the byte offset for the I/O

-       entry as well as the other data values.
+       entry as well as the other data values. Defaults to 0 meaning that
+       offsets are not present in logs. Also see `Log File Formats`_.

 
 .. option:: log_compression=int
 
 
 .. option:: log_compression=int
 


@@ -3242,7 +3248,7 @@ numbers denote:
 **ios**
                Number of I/Os performed by all groups.
 **merge**
 **ios**
                Number of I/Os performed by all groups.
 **merge**

-               Number of merges I/O the I/O scheduler.
+               Number of merges performed by the I/O scheduler.

 **ticks**
                Number of ticks we kept the disk busy.
 **in_queue**
 **ticks**
                Number of ticks we kept the disk busy.
 **in_queue**


@@ -3278,7 +3284,7 @@ changed for some reason, this number will be incremented by 1 to signify that
 change.
 
 Split up, the format is as follows (comments in brackets denote when a
 change.
 
 Split up, the format is as follows (comments in brackets denote when a

-field was introduced or whether its specific to some terse version):
+field was introduced or whether it's specific to some terse version):

 
     ::
 
 
     ::
 


@@ -3531,9 +3537,10 @@ Log File Formats
 Fio supports a variety of log file formats, for logging latencies, bandwidth,
 and IOPS. The logs share a common format, which looks like this:
 
 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*, *offset*
+    *time* (`msec`), *value*, *data direction*, *block size* (`bytes`),
+    *offset* (`bytes`)

 
 

-Time for the log entry is always in milliseconds. The *value* logged depends
+*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:
 
     **Latency log**
 on the type of log, it will be one of the following:
 
     **Latency log**


@@ -3552,16 +3559,17 @@ on the type of log, it will be one of the following:
        **2**
                I/O is a TRIM
 
        **2**
                I/O is a TRIM
 

-The *offset* is the offset, in bytes, from the start of the file, for that
-particular I/O. The logging of the offset can be toggled with
-:option:`log_offset`.
+The entry's *block size* is always in bytes. The *offset* is the offset, in bytes,
+from the start of the file, for that particular I/O. The logging of the offset can be
+toggled with :option:`log_offset`.

 
 Fio defaults to logging every individual I/O.  When IOPS are logged for individual
 
 Fio defaults to logging every individual I/O.  When IOPS are logged for individual

-I/Os the value entry will always be 1.  If windowed logging is enabled through
+I/Os the *value* entry will always be 1. If windowed logging is enabled through

 :option:`log_avg_msec`, fio logs the average values over the specified period of time.
 If windowed logging is enabled and :option:`log_max_value` is set, then fio logs
 :option:`log_avg_msec`, fio logs the average values over the specified period of time.
 If windowed logging is enabled and :option:`log_max_value` is set, then fio logs

-maximum values in that window instead of averages.  Since 'data direction' and
-'offset' are per-I/O values, they aren't applicable if windowed logging is enabled.
+maximum values in that window instead of averages. Since *data direction*, *block
+size* and *offset* are per-I/O values, if windowed logging is enabled they
+aren't applicable and will be 0.

 
 Client/Server
 -------------
 
 Client/Server
 -------------