Add sample job file showing how to read backwards

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index 1f523d384ad85f64b38889aa364a4b0f150fec66..ab25cb2796ddafeec8b375fe832c61825238fe81 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -53,8 +53,8 @@ bottom, it contains the following basic parameters:
 
        IO engine       How do we issue io? We could be memory mapping the
                        file, we could be using regular read/write, we
 
        IO engine       How do we issue io? We could be memory mapping the
                        file, we could be using regular read/write, we

-                       could be using splice, async io, syslet, or even
-                       SG (SCSI generic sg).
+                       could be using splice, async io, or even SG
+                       (SCSI generic sg).

 
        IO depth        If the io engine is async, how large a queuing
                        depth do we want to maintain?
 
        IO depth        If the io engine is async, how large a queuing
                        depth do we want to maintain?


@@ -329,18 +329,15 @@ directory=str     Prefix filenames with this directory. Used to place files
 filename=str   Fio normally makes up a filename based on the job name,
                thread number, and file number. If you want to share
                files between threads in a job or several jobs, specify
 filename=str   Fio normally makes up a filename based on the job name,
                thread number, and file number. If you want to share
                files between threads in a job or several jobs, specify

-               a filename for each of them to override the default. If
-               the ioengine used is 'net', the filename is the host, port,
-               and protocol to use in the format of =host,port,protocol.
-               See ioengine=net for more. If the ioengine is file based, you
-               can specify a number of files by separating the names with a
-               ':' colon. So if you wanted a job to open /dev/sda and /dev/sdb
-               as the two working files, you would use
-               filename=/dev/sda:/dev/sdb. On Windows, disk devices are
-               accessed as \\.\PhysicalDrive0 for the first device,
-               \\.\PhysicalDrive1 for the second etc. Note: Windows and
-               FreeBSD prevent write access to areas of the disk containing
-               in-use data (e.g. filesystems).
+               a filename for each of them to override the default.
+               If the ioengine is file based, you can specify a number of
+               files by separating the names with a ':' colon. So if you
+               wanted a job to open /dev/sda and /dev/sdb as the two working
+               files, you would use filename=/dev/sda:/dev/sdb. On Windows,
+               disk devices are accessed as \\.\PhysicalDrive0 for the first
+               device, \\.\PhysicalDrive1 for the second etc. Note: Windows
+               and FreeBSD prevent write access to areas of the disk
+               containing in-use data (e.g. filesystems).

                If the wanted filename does need to include a colon, then
                escape that with a '\' character. For instance, if the filename
                is "/dev/dsk/foo@3,0:c", then you would use
                If the wanted filename does need to include a colon, then
                escape that with a '\' character. For instance, if the filename
                is "/dev/dsk/foo@3,0:c", then you would use


@@ -374,6 +371,11 @@ filename_format=str
                default of $jobname.$jobnum.$filenum will be used if
                no other format specifier is given.
 
                default of $jobname.$jobnum.$filenum will be used if
                no other format specifier is given.
 

+unique_filename=bool   To avoid collisions between networked clients, fio
+               defaults to prefixing any generated filenames (with a directory
+               specified) with the source of the client connecting. To disable
+               this behavior, set this option to 0.
+

 opendir=str    Tell fio to recursively add any file it can find in this
                directory and down the file system tree.
 
 opendir=str    Tell fio to recursively add any file it can find in this
                directory and down the file system tree.
 


@@ -673,10 +675,23 @@ file_service_type=str  Defines how fio decides which file from a job to
                                the next. Multiple files can still be
                                open depending on 'openfiles'.
 
                                the next. Multiple files can still be
                                open depending on 'openfiles'.
 

-               The string can have a number appended, indicating how
-               often to switch to a new file. So if option random:4 is
-               given, fio will switch to a new random file after 4 ios
-               have been issued.
+                       zipf    Use a zipfian distribution to decide what file
+                               to access.
+
+                       pareto  Use a pareto distribution to decide what file
+                               to access.
+
+                       gauss   Use a gaussian (normal) distribution to decide
+                               what file to access.
+
+               For random, roundrobin, and sequential, a postfix can be
+               appended to tell fio how many I/Os to issue before switching
+               to a new file. For example, specifying
+               'file_service_type=random:8' would cause fio to issue 8 I/Os
+               before selecting a new file at random. For the non-uniform
+               distributions, a floating point postfix can be given to
+               influence how the distribution is skewed. See
+               'random_distribution' for a description of how that would work.

 
 ioengine=str   Defines how the job issues io to the file. The following
                types are defined:
 
 ioengine=str   Defines how the job issues io to the file. The following
                types are defined:


@@ -688,7 +703,9 @@ ioengine=str        Defines how the job issues io to the file. The following
 
                        vsync   Basic readv(2) or writev(2) IO.
 
 
                        vsync   Basic readv(2) or writev(2) IO.
 

-                       psyncv  Basic preadv(2) or pwritev(2) IO.
+                       pvsync  Basic preadv(2) or pwritev(2) IO.
+
+                       pvsync2 Basic preadv2(2) or pwritev2(2) IO.

 
                        libaio  Linux native asynchronous io. Note that Linux
                                may only support queued behaviour with
 
                        libaio  Linux native asynchronous io. Note that Linux
                                may only support queued behaviour with


@@ -708,9 +725,6 @@ ioengine=str        Defines how the job issues io to the file. The following
                                vmsplice(2) to transfer data from user
                                space to the kernel.
 
                                vmsplice(2) to transfer data from user
                                space to the kernel.
 

-                       syslet-rw Use the syslet system calls to make
-                               regular read/write async.
-

                        sg      SCSI generic sg v3 io. May either be
                                synchronous using the SG_IO ioctl, or if
                                the target is an sg character device
                        sg      SCSI generic sg v3 io. May either be
                                synchronous using the SG_IO ioctl, or if
                                the target is an sg character device


@@ -735,7 +749,7 @@ ioengine=str        Defines how the job issues io to the file. The following
 
                        cpuio   Doesn't transfer any data, but burns CPU
                                cycles according to the cpuload= and
 
                        cpuio   Doesn't transfer any data, but burns CPU
                                cycles according to the cpuload= and

-                               cpucycle= options. Setting cpuload=85
+                               cpuchunks= options. Setting cpuload=85

                                will cause that job to do nothing but burn
                                85% of the CPU. In case of SMP machines,
                                use numjobs=<no_of_cpu> to get desired CPU
                                will cause that job to do nothing but burn
                                85% of the CPU. In case of SMP machines,
                                use numjobs=<no_of_cpu> to get desired CPU


@@ -798,6 +812,9 @@ ioengine=str        Defines how the job issues io to the file. The following
                                overwriting. The writetrim mode works well
                                for this constraint.
 
                                overwriting. The writetrim mode works well
                                for this constraint.
 

+                       pmemblk Read and write through the NVML libpmemblk
+                               interface.
+

                        external Prefix to specify loading an external
                                IO engine object file. Append the engine
                                filename, eg ioengine=external:/tmp/foo.o
                        external Prefix to specify loading an external
                                IO engine object file. Append the engine
                                filename, eg ioengine=external:/tmp/foo.o


@@ -1047,7 +1064,8 @@ nice=int  Run the job with the given nice value. See man nice(2).
 
 prio=int       Set the io priority value of this job. Linux limits us to
                a positive value between 0 and 7, with 0 being the highest.
 
 prio=int       Set the io priority value of this job. Linux limits us to
                a positive value between 0 and 7, with 0 being the highest.

-               See man ionice(1).
+               See man ionice(1). Refer to an appropriate manpage for
+               other operating systems since meaning of priority may differ.

 
 prioclass=int  Set the io priority class. See man ionice(1).
 
 
 prioclass=int  Set the io priority class. See man ionice(1).
 


@@ -1263,10 +1281,14 @@ exitall_on_error        When one job finishes in error, terminate the rest. The
                default is to wait for each job to finish.
 
 bwavgtime=int  Average the calculated bandwidth over the given time. Value
                default is to wait for each job to finish.
 
 bwavgtime=int  Average the calculated bandwidth over the given time. Value

-               is specified in milliseconds.
+               is specified in milliseconds. If the job also does bandwidth
+               logging through 'write_bw_log', then the minimum of this option
+               and 'log_avg_msec' will be used.  Default: 500ms.

 
 iopsavgtime=int        Average the calculated IOPS over the given time. Value
 
 iopsavgtime=int        Average the calculated IOPS over the given time. Value

-               is specified in milliseconds.
+               is specified in milliseconds. If the job also does IOPS logging
+               through 'write_iops_log', then the minimum of this option and
+               'log_avg_msec' will be used.  Default: 500ms.

 
 create_serialize=bool  If true, serialize the file creating for the jobs.
                        This may be handy to avoid interleaving of data
 
 create_serialize=bool  If true, serialize the file creating for the jobs.
                        This may be handy to avoid interleaving of data