Update documentation for filename/directory

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index 044b57221f3d18c431e4840bfcbdb21bbab31b2e..725214fb4d14a0b2d0099f0106a8e2ad6822e7eb 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -223,7 +223,8 @@ a string. The following types are used:
 str    String. This is a sequence of alpha characters.
 time   Integer with possible time suffix. In seconds unless otherwise
        specified, use eg 10m for 10 minutes. Accepts s/m/h for seconds,
-       minutes, and hours.
+       minutes, and hours, and accepts 'ms' (or 'msec') for milliseconds,
+       and 'us' (or 'usec') for microseconds.
 int    SI integer. A whole number value, which may contain a suffix
        describing the base of the number. Accepted suffixes are k/m/g/t/p,
        meaning kilo, mega, giga, tera, and peta. The suffix is not case
@@ -261,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
-               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
@@ -384,6 +386,11 @@ unified_rw_reporting=bool  Fio normally reports statistics on a per
 randrepeat=bool        For random IO workloads, seed the generator in a predictable
                way so that results are repeatable across repetitions.
 
+randseed=int   Seed the random number generators based on this seed value, to
+               be able to control what sequence of output is being generated.
+               If not set, the random sequence depends on the randrepeat
+               setting.
+
 use_os_rand=bool Fio can either use the random generator supplied by the OS
                to generator random offsets, or it can use it's own internal
                generator (based on Tausworthe). Default is to use the
@@ -542,6 +549,11 @@ buffer_compress_chunk=int  See buffer_compress_percentage. This
                alternate random and zeroed data throughout the IO
                buffer.
 
+buffer_pattern=str     If set, fio will fill the io buffers with this pattern.
+               If not set, the contents of io buffers is defined by the other
+               options related to buffer contents. The setting can be any
+               pattern of bytes, and can be prefixed with 0x for hex values.
+
 nrfiles=int    Number of files to use for this job. Defaults to 1.
 
 openfiles=int  Number of files to keep open at the same time. Defaults to
@@ -917,6 +929,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.
 
+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,
@@ -1058,6 +1082,13 @@ loops=int        Run the specified number of iterations of this job. Used
                to repeat the same workload a given number of times. Defaults
                to 1.
 
+verify_only    Do not perform specified workload---only verify data still
+               matches previous invocation of this workload. This option
+               allows one to check data multiple times at a later date
+               without overwriting it. This option makes sense only for
+               workloads that write data, and does not support workloads
+               with the time_based option set.
+
 do_verify=bool Run the verify phase after a write phase. Only makes sense if
                verify is set. Defaults to 1.
 
@@ -1088,6 +1119,10 @@ verify=str       If writing to a file, fio can verify the file contents
                        crc7    Use a crc7 sum of the data area and store
                                it in the header of each block.
 
+                       xxhash  Use xxhash as the checksum function. Generally
+                               the fastest software checksum that fio
+                               supports.
+
                        sha512  Use sha512 as the checksum function.
 
                        sha256  Use sha256 as the checksum function.
@@ -1096,7 +1131,9 @@ verify=str        If writing to a file, fio can verify the file contents
 
                        meta    Write extra information about each io
                                (timestamp, block number etc.). The block
-                               number is verified. See also verify_pattern.
+                               number is verified. The io sequence number is
+                               verified for workloads that write data.
+                               See also verify_pattern.
 
                        null    Only pretend to verify. Useful for testing
                                internals with ioengine=null, not for much
@@ -1486,7 +1523,9 @@ that defines them is selected.
 [net] proto=str        The network protocol to use. Accepted values are:
 
                        tcp     Transmission control protocol
+                       tcpv6   Transmission control protocol V6
                        udp     User datagram protocol
+                       udpv6   User datagram protocol V6
                        unix    UNIX domain socket
 
                When the protocol is TCP or UDP, the port must also be given,