Merge branch 'master' into gfio

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index ea8730caea033ec4fce10d00ceef7256170bfd8e..7dc7d4827e340dba61c3d67e53e78c1d83a973aa 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -9,6 +9,7 @@ Table of contents
 6. Normal output
 7. Terse output
 8. Trace file format
+9. CPU idleness profiling
 
 1.0 Overview and history
 ------------------------
@@ -284,6 +285,32 @@ filename=str       Fio normally makes up a filename based on the job name,
                stdin or stdout. Which of the two depends on the read/write
                direction set.
 
+filename_format=str
+               If sharing multiple files between jobs, it is usually necessary
+               to  have fio generate the exact names that you want. By default,
+               fio will name a file based on the default file format
+               specification of jobname.jobnumber.filenumber. With this
+               option, that can be customized. Fio will recognize and replace
+               the following keywords in this string:
+
+               $jobname
+                       The name of the worker thread or process.
+
+               $jobnum
+                       The incremental number of the worker thread or
+                       process.
+
+               $filenum
+                       The incremental number of the file for that worker
+                       thread or process.
+
+               To have dependent jobs share a set of files, this option can
+               be set to have fio generate filenames that are shared between
+               the two. For instance, if testfiles.$filenum is specified,
+               file number 4 for any job will be named testfiles.4. The
+               default of $jobname.$jobnum.$filenum will be used if
+               no other format specifier is given.
+
 opendir=str    Tell fio to recursively add any file it can find in this
                directory and down the file system tree.
 
@@ -301,11 +328,6 @@ lockfile=str       Fio defaults to not locking any files before it does
                                        same time, but writes get exclusive
                                        access.
 
-               The option may be post-fixed with a lock batch number. If
-               set, then each thread/process may do that amount of IOs to
-               the file before giving up the lock. Since lock acquisition is
-               expensive, batching the lock/unlocks will speed up IO.
-
 readwrite=str
 rw=str         Type of io pattern. Accepted values are:
 
@@ -409,7 +431,7 @@ filesize=int        Individual file sizes. May be a range, in which case fio
 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
-                sense with sequential write. For a read workload, the mount
+               sense with sequential write. For a read workload, the mount
                point will be filled first then IO started on the result. This
                option doesn't make sense if operating on a raw device node,
                since the size of that is already known by the file system.
@@ -775,7 +797,7 @@ random_generator=str        Fio supports the following engines for generating
                block sizes, not with workloads that use multiple block
                sizes. If used with such a workload, fio may read or write
                some blocks multiple times.
-               
+
 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
@@ -1229,12 +1251,6 @@ exec_postrun=str After the job completes, issue the command specified
 ioscheduler=str        Attempt to switch the device hosting the file to the specified
                io scheduler before running.
 
-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 microseconds.
-
 disk_util=bool Generate disk utilization statistics, if the platform
                supports it. Defaults to on.
 
@@ -1394,6 +1410,11 @@ that defines them is selected.
                enabled when polling for a minimum of 0 events (eg when
                iodepth_batch_complete=0).
 
+[cpu] cpuload=int Attempt to use the specified percentage of CPU cycles.
+
+[cpu] cpuchunks=int Split the load into cycles of the given time. In
+               microseconds.
+
 [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