Add string condensing for the ETA output

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index 4dacd98965ea1d12ecb86d9d3998e57404edfd28..cad175c6fb59fed73407afe48ffc9cf43e6759f6 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -262,7 +262,8 @@ description=str     Text description of the job. Doesn't do anything except
                not parsed.
 
 directory=str  Prefix filenames with this directory. Used to place files
                not parsed.
 
 directory=str  Prefix filenames with this directory. Used to place files

-               in a different location than "./".
+               in a different location than "./". See the 'filename' option
+               for escaping certain characters.

 
 filename=str   Fio normally makes up a filename based on the job name,
                thread number, and file number. If you want to share
 
 filename=str   Fio normally makes up a filename based on the job name,
                thread number, and file number. If you want to share


@@ -429,11 +430,25 @@ size=int  The total size of file io for this job. Fio will run until
                is given, fio will use 20% of the full size of the given
                files or devices.
 
                is given, fio will use 20% of the full size of the given
                files or devices.
 

+io_limit=int   Normally fio operates within the region set by 'size', which
+               means that the 'size' option sets both the region and size of
+               IO to be performed. Sometimes that is not what you want. With
+               this option, it is possible to define just the amount of IO
+               that fio should do. For instance, if 'size' is set to 20G and
+               'io_limit' is set to 5G, fio will perform IO within the first
+               20G but exit when 5G have been done.
+

 filesize=int   Individual file sizes. May be a range, in which case fio
                will select sizes for files at random within the given range
                and limited to 'size' in total (if that is given). If not
                given, each created file is the same size.
 
 filesize=int   Individual file sizes. May be a range, in which case fio
                will select sizes for files at random within the given range
                and limited to 'size' in total (if that is given). If not
                given, each created file is the same size.
 

+file_append=bool       Perform IO after the end of the file. Normally fio will
+               operate within the size of a file. If this option is set, then
+               fio will append to the file instead. This has identical
+               behavior to setting offset to the size of a file. This option
+               is ignored on non-regular files.
+

 fill_device=bool
 fill_fs=bool   Sets size to something really large and waits for ENOSPC (no
                space left on device) as the terminating condition. Only makes
 fill_device=bool
 fill_fs=bool   Sets size to something really large and waits for ENOSPC (no
                space left on device) as the terminating condition. Only makes


@@ -518,6 +533,8 @@ bs_is_seq_rand      If this option is set, fio will use the normal read,write
 
 zero_buffers   If this option is given, fio will init the IO buffers to
                all zeroes. The default is to fill them with random data.
 
 zero_buffers   If this option is given, fio will init the IO buffers to
                all zeroes. The default is to fill them with random data.

+               The resulting IO buffers will not be completely zeroed,
+               unless scramble_buffers is also turned off.

 
 refill_buffers If this option is given, fio will refill the IO buffers
                on every submit. The default is to only fill it at init
 
 refill_buffers If this option is given, fio will refill the IO buffers
                on every submit. The default is to only fill it at init


@@ -928,6 +945,18 @@ cpus_allowed=str Controls the same options as cpumask, but it allows a text
                allows a range of CPUs. Say you wanted a binding to CPUs
                1, 5, and 8-15, you would set cpus_allowed=1,5,8-15.
 
                allows a range of CPUs. Say you wanted a binding to CPUs
                1, 5, and 8-15, you would set cpus_allowed=1,5,8-15.
 

+cpus_allowed_policy=str Set the policy of how fio distributes the CPUs
+               specified by cpus_allowed or cpumask. Two policies are
+               supported:
+
+               shared  All jobs will share the CPU set specified.
+               split   Each job will get a unique CPU from the CPU set.
+
+               'shared' is the default behaviour, if the option isn't
+               specified. If split is specified, then fio will will assign
+               one cpu per job. If not enough CPUs are given for the jobs
+               listed, then fio will roundrobin the CPUs in the set.
+

 numa_cpu_nodes=str Set this job running on spcified NUMA nodes' CPUs. The
                arguments allow comma delimited list of cpu numbers,
                A-B ranges, or 'all'. Note, to enable numa options support,
 numa_cpu_nodes=str Set this job running on spcified NUMA nodes' CPUs. The
                arguments allow comma delimited list of cpu numbers,
                A-B ranges, or 'all'. Note, to enable numa options support,


@@ -1484,6 +1513,8 @@ that defines them is selected.
 [cpu] cpuchunks=int Split the load into cycles of the given time. In
                microseconds.
 
 [cpu] cpuchunks=int Split the load into cycles of the given time. In
                microseconds.
 

+[cpu] exit_on_io_done=bool Detect when IO threads are done, then exit.
+

 [netsplice] hostname=str
 [net] hostname=str The host name or IP address to use for TCP or UDP based IO.
                If the job is a TCP listener or UDP reader, the hostname is not
 [netsplice] hostname=str
 [net] hostname=str The host name or IP address to use for TCP or UDP based IO.
                If the job is a TCP listener or UDP reader, the hostname is not


@@ -1569,12 +1600,22 @@ I               Thread initialized, waiting or generating necessary data.
        M       Running, doing mixed sequential reads/writes.
        m       Running, doing mixed random reads/writes.
        F       Running, currently waiting for fsync()
        M       Running, doing mixed sequential reads/writes.
        m       Running, doing mixed random reads/writes.
        F       Running, currently waiting for fsync()

+       f       Running, finishing up (writing IO logs, etc)

        V       Running, doing verification of written data.
 E              Thread exited, not reaped by main thread yet.
 _              Thread reaped, or
 X              Thread reaped, exited with an error.
 K              Thread reaped, exited due to signal.
 
        V       Running, doing verification of written data.
 E              Thread exited, not reaped by main thread yet.
 _              Thread reaped, or
 X              Thread reaped, exited with an error.
 K              Thread reaped, exited due to signal.
 

+Fio will condense the thread string as not to take up more space on the
+command line as is needed. For instance, if you have 10 readers and 10
+writers running, the output would look like this:
+
+Jobs: 20 (f=20): [R(10),W(10)] [4.0% done] [2103MB/0KB/0KB /s] [538K/0/0 iops] [eta 57m:36s]
+
+Fio will still maintain the ordering, though. So the above means that jobs
+1..10 are readers, and 11..20 are writers.
+

 The other values are fairly self explanatory - number of threads
 currently running and doing io, rate of io since last check (read speed
 listed first, then write speed), and the estimated completion percentage
 The other values are fairly self explanatory - number of threads
 currently running and doing io, rate of io since last check (read speed
 listed first, then write speed), and the estimated completion percentage