Add gtod_cpu option for pinning gettimeofday() to a single CPU

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index f4efd281bbc72e2a4a54dfc233aab2310fa0643d..731684cb9d62c7766155ba050ee66178ea19c428 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -583,11 +583,16 @@ cpumask=int       Set the CPU affinity of this job. The parameter given is a
                the allowed CPUs to be 1 and 5, you would pass the decimal
                value of (1 << 1 | 1 << 5), or 34. See man
                sched_setaffinity(2). This may not work on all supported
-               operating systems or kernel versions.
+               operating systems or kernel versions. This option doesn't
+               work well for a higher CPU count than what you can store in
+               an integer mask, so it can only control cpus 1-32. For
+               boxes with larger CPU counts, use cpus_allowed.
 
 cpus_allowed=str Controls the same options as cpumask, but it allows a text
                setting of the permitted CPUs instead. So to use CPUs 1 and
-               5, you would specify cpus_allowed=1,5.
+               5, you would specify cpus_allowed=1,5. This options also
+               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.
 
 startdelay=time        Start this job the specified number of seconds after fio
                has started. Only useful if the job file contains several
@@ -804,14 +809,23 @@ read_iolog=str    Open an iolog with the specified file name and replay the
                the file needs to be turned into a blkparse binary data
                file first (blktrace <device> -d file_for_fio.bin).
 
-write_bw_log   If given, write a bandwidth log of the jobs in this job
+write_bw_log=str If given, write a bandwidth log of the jobs in this job
                file. Can be used to store data of the bandwidth of the
                jobs in their lifetime. The included fio_generate_plots
                script uses gnuplot to turn these text files into nice
-               graphs.
+               graphs. See write_log_log for behaviour of given
+               filename. For this option, the postfix is _bw.log.
 
-write_lat_log  Same as write_bw_log, except that this option stores io
-               completion latencies instead.
+write_lat_log=str Same as write_bw_log, except that this option stores io
+               completion latencies instead. If no filename is given
+               with this option, the default filename of "jobname_type.log"
+               is used. Even if the filename is given, fio will still
+               append the type of log. So if one specifies
+
+               write_lat_log=foo
+
+               The actual log names will be foo_clat.log and foo_slat.log.
+               This helps fio_generate_plot fine the logs automatically.
 
 lockmem=siint  Pin down the specified amount of memory with mlock(2). Can
                potentially be used instead of removing memory or booting
@@ -855,6 +869,18 @@ gtod_reduce=bool Enable all of the gettimeofday() reducing options
                we only do about 0.4% of the gtod() calls we would have
                done if all time keeping was enabled.
 
+gtod_cpu=int   Sometimes it's cheaper to dedicate a single thread of
+               execution to just getting the current time. Fio (and
+               databases, for instance) are very intensive on gettimeofday()
+               calls. With this option, you can set one CPU aside for
+               doing nothing but logging current time to a shared memory
+               location. Then the other threads/processes that run IO
+               workloads need only copy that segment, instead of entering
+               the kernel with a gettimeofday() call. The CPU set aside
+               for doing these time calls will be excluded from other
+               uses. Fio will manually clear it from the CPU mask of other
+               jobs.
+
 
 6.0 Interpreting the output
 ---------------------------