Merge branch 'master' into gfio

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index a1e659008b38b82e98ba86d0d5d07b4b35b35897..6a880a7fc1053dc31b109fd15cc492767c1e977f 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -9,6 +9,7 @@ Table of contents
 6. Normal output
 7. Terse output
 8. Trace file format
 6. Normal output
 7. Terse output
 8. Trace file format

+9. CPU idleness profiling

 
 1.0 Overview and history
 ------------------------
 
 1.0 Overview and history
 ------------------------


@@ -272,17 +273,17 @@ filename=str      Fio normally makes up a filename based on the job name,
                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
                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 filename="/dev/dsk/foo@3,0\:c".
-               '-' is a reserved name, meaning stdin or stdout. Which of the
-               two depends on the read/write direction set.
+               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
+               filename="/dev/dsk/foo@3,0\:c". '-' is a reserved name, meaning
+               stdin or stdout. Which of the two depends on the read/write
+               direction set.

 
 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.


@@ -301,11 +302,6 @@ lockfile=str       Fio defaults to not locking any files before it does
                                        same time, but writes get exclusive
                                        access.
 
                                        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:
 
 readwrite=str
 rw=str         Type of io pattern. Accepted values are:
 


@@ -353,6 +349,12 @@ kb_base=int        The base unit for a kilobyte. The defacto base is 2^10, 1024.
                ten unit instead, for obvious reasons. Allow values are
                1024 or 1000, with 1024 being the default.
 
                ten unit instead, for obvious reasons. Allow values are
                1024 or 1000, with 1024 being the default.
 

+unified_rw_reporting=bool      Fio normally reports statistics on a per
+               data direction basis, meaning that read, write, and trim are
+               accounted and reported separately. If this option is set,
+               the fio will sum the results and report them as "mixed"
+               instead.
+

 randrepeat=bool        For random IO workloads, seed the generator in a predictable
                way so that results are repeatable across repetitions.
 
 randrepeat=bool        For random IO workloads, seed the generator in a predictable
                way so that results are repeatable across repetitions.
 


@@ -704,7 +706,7 @@ overwrite=bool      If true, writes to a file will always overwrite existing
                and is large enough for the specified write phase, nothing
                will be done.
 
                and is large enough for the specified write phase, nothing
                will be done.
 

-end_fsync=bool If true, fsync file contents when the job exits.
+end_fsync=bool If true, fsync file contents when a write stage has completed.

 
 fsync_on_close=bool    If true, fio will fsync() a dirty file on close.
                This differs from end_fsync in that it will happen on every
 
 fsync_on_close=bool    If true, fio will fsync() a dirty file on close.
                This differs from end_fsync in that it will happen on every


@@ -769,7 +771,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.
                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
 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


@@ -844,9 +846,7 @@ cpus_allowed=str Controls the same options as cpumask, but it allows a text
 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,

-               export the following environment variables,
-                       export EXTFLAGS+=" -DFIO_HAVE_LIBNUMA "
-                       export EXTLIBS+=" -lnuma "
+               fio must be built on a system with libnuma-dev(el) installed.

 
 numa_mem_policy=str Set this job's memory policy and corresponding NUMA
                nodes. Format of the argements:
 
 numa_mem_policy=str Set this job's memory policy and corresponding NUMA
                nodes. Format of the argements:


@@ -1397,6 +1397,9 @@ that defines them is selected.
 [netsplice] port=int
 [net] port=int The TCP or UDP port to bind to or connect to.
 
 [netsplice] port=int
 [net] port=int The TCP or UDP port to bind to or connect to.
 

+[netsplice] nodelay=bool
+[net] nodelay=bool     Set TCP_NODELAY on TCP connections.
+

 [netsplice] protocol=str
 [netsplice] proto=str
 [net] protocol=str
 [netsplice] protocol=str
 [netsplice] proto=str
 [net] protocol=str


@@ -1688,3 +1691,18 @@ write      Write 'length' bytes beginning from 'offset'
 sync       fsync() the file
 datasync   fdatasync() the file
 trim       trim the given file from the given 'offset' for 'length' bytes
 sync       fsync() the file
 datasync   fdatasync() the file
 trim       trim the given file from the given 'offset' for 'length' bytes

+
+
+9.0 CPU idleness profiling
+
+In some cases, we want to understand CPU overhead in a test. For example,
+we test patches for the specific goodness of whether they reduce CPU usage.
+fio implements a balloon approach to create a thread per CPU that runs at
+idle priority, meaning that it only runs when nobody else needs the cpu.
+By measuring the amount of work completed by the thread, idleness of each
+CPU can be derived accordingly.
+
+An unit work is defined as touching a full page of unsigned characters. Mean
+and standard deviation of time to complete an unit work is reported in "unit
+work" section. Options can be chosen to report detailed percpu idleness or
+overall system idleness by aggregating percpu stats.