Make pre_read imply invalidate=0

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index 4e52e6509c18a6efb2350071d15b4899fb0be759..494b3e64d722597405e6a82191f776c1b8bc35d7 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -230,7 +230,7 @@ description=str     Text description of the job. Doesn't do anything except
                dump this text description when this job is run. It's
                not parsed.
 
-directory=str  Prefix filenames with this directory. Used to places files
+directory=str  Prefix filenames with this directory. Used to place files
                in a different location than "./".
 
 filename=str   Fio normally makes up a filename based on the job name,
@@ -250,7 +250,7 @@ filename=str        Fio normally makes up a filename based on the job name,
 opendir=str    Tell fio to recursively add any file it can find in this
                directory and down the file system tree.
 
-lockfile=str   Fio defaults to not doing any locking files before it does
+lockfile=str   Fio defaults to not locking any files before it does
                IO to them. If a file or file descriptor is shared, fio
                can serialize IO to that file to make the end result
                consistent. This is usual for emulating real workloads that
@@ -303,7 +303,7 @@ fadvise_hint=bool By default, fio will use fadvise() to advise the kernel
 size=int       The total size of file io for this job. Fio will run until
                this many bytes has been transferred, unless runtime is
                limited by other options (such as 'runtime', for instance).
-               Unless specific nr_files and filesize options are given,
+               Unless specific nrfiles and filesize options are given,
                fio will divide this size between the available files
                specified by the job.
 
@@ -327,6 +327,14 @@ bs=int             The block size used for the io units. Defaults to 4k. Values
                can do so by passing an empty read size - bs=,8k will set
                8k for writes and leave the read default value.
 
+blockalign=int
+ba=int         At what boundary to align random IO offsets. Defaults to
+               the same as 'blocksize' the minimum blocksize given.
+               Minimum alignment is typically 512b for using direct IO,
+               though it usually depends on the hardware block size. This
+               option is mutually exclusive with using a random map for
+               files, so it will turn off that option.
+
 blocksize_range=irange
 bsrange=irange Instead of giving a single block size, specify a range
                and fio will mix the issued io block sizes. The issued
@@ -359,6 +367,15 @@ bssplit=str        Sometimes you want even finer grained control of the
                always add up to 100, if bssplit is given a range that adds
                up to more, it will error out.
 
+               bssplit also supports giving separate splits to reads and
+               writes. The format is identical to what bs= accepts. You
+               have to separate the read and write parts with a comma. So
+               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
+
 blocksize_unaligned
 bs_unaligned   If this option is given, any byte size value within bsrange
                may be used as a block range. This typically wont work with
@@ -696,6 +713,11 @@ create_fsync=bool  fsync the data file after creation. This is the
 create_on_open=bool    Don't pre-setup the files for IO, just create open()
                        when it's time to do IO to that file.
 
+pre_read=bool  If this is given, files will be pre-read into memory before
+               starting the given IO operation. This will also clear
+               the 'invalidate' flag, since it is pointless to pre-read
+               and then drop the cache.
+
 unlink=bool    Unlink the job files when done. Not the default, as repeated
                runs of that job would then waste time recreating the file
                set again and again.
@@ -857,7 +879,7 @@ cpuload=int If the job is a CPU cycle eater, attempt to use the specified
                percentage of CPU cycles.
 
 cpuchunks=int  If the job is a CPU cycle eater, split the load into
-               cycles of the given time. In milliseconds.
+               cycles of the given time. In microseconds.
 
 disk_util=bool Generate disk utilization statistics, if the platform
                supports it. Defaults to on.
@@ -911,6 +933,7 @@ Idle        Run
 P              Thread setup, but not started.
 C              Thread created.
 I              Thread initialized, waiting.
+       p       Thread running pre-reading file(s).
        R       Running, doing sequential reads.
        r       Running, doing random reads.
        W       Running, doing sequential writes.
@@ -918,7 +941,7 @@ I           Thread initialized, waiting.
        M       Running, doing mixed sequential reads/writes.
        m       Running, doing mixed random reads/writes.
        F       Running, currently waiting for fsync()
-V              Running, doing verification of written data.
+       V       Running, doing verification of written data.
 E              Thread exited, not reaped by main thread yet.
 _              Thread reaped.